Getting Started

SmartAdmin v5 – Modern UI Framework

Welcome to SmartAdmin v5, an advanced UI Bootstrap 5 Admin and Dashboard template designed for modern web applications. This guide will walk you through setting up and running the SmartAdmin project, understanding its core components, and customizing it to fit your needs.

Pro Tip: SmartAdmin v5 is built with vanilla JavaScript and Bootstrap 5, eliminating jQuery dependencies for better performance and modern development practices.

Prerequisites

Before you begin, ensure you have the following tools installed on your computer:

Tool Version Purpose Installation
Node.js & npm v14.x or later JavaScript runtime and package manager nodejs.org
Gulp CLI Latest Task automation toolkit npm install gulp-cli -g
Git Latest Version control system git-scm.com
Code Editor Any For editing project files VS Code, Sublime Text, etc.

Verify your installations with these commands:

node --version
npm --version
gulp --version
git --version

Installation

Follow these steps to set up SmartAdmin v5:

Step 1: Extract the Package

# Extract the SmartAdmin.zip file to your preferred location
# Navigate to the extracted directory
cd path/to/smartadmin-package-5.x.x/smartadmin-html-full

Step 2: Install Dependencies

# Install all required npm packages
npm install

# If you encounter Git-related errors, use
npm install --force

Step 3: Build the Project

# Build all assets (CSS, JS, etc.)
gulp build

# Start development server with live reload
gulp
Important: Always run the project through a web server, not by opening HTML files directly, to avoid AJAX and module loading issues.

Project Structure

Understanding the SmartAdmin v5 file organization is crucial for effective development. Click the tree view below to expand and collapse the project structure:

Directory/File Description
/src Source files (SCSS, JS, views)
/dist Compiled and processed files (created by Gulp)
/src/sass SCSS source files for styling
/src/scripts JavaScript source files
/src/views EJS template files for HTML generation
gulpfile.js Gulp configuration and tasks
navigation.json Navigation structure configuration
package.json Project dependencies and scripts

Gulp Build System

SmartAdmin v5 uses Gulp to automate development tasks. The gulpfile.js defines various tasks for building, processing, and serving the application.

Key Gulp Tasks

Here are the main Gulp tasks you'll use during development:

// Default task - builds everything and starts watching for changes
gulp

// Build all assets without watching
gulp build

// Generate CSS only
gulp appCss

// Generate JavaScript only
gulp js

// Generate HTML from EJS templates
gulp html

// Generate navigation from navigation.json
gulp navigation

Gulp Configuration Structure

The gulpfile.js contains configuration for paths, tasks, and build options:

// Configuration object from gulpfile.js
const config = {
    paths: {
        src: {
            // Source file paths
            appSass: './src/sass/**/*.scss',
            vendorCSS: './src/css/*.css',
            views: './src/views/pages/*.ejs',
            scripts: ['./src/scripts/**/*.js', '!./src/scripts/_archive/**/*.js'],
            images: './src/img/**/*.{gif,jpg,png,svg,webp}',
            navigation: './src/navigation.json'
        },
        dist: {
            // Distribution paths
            appCss: 'dist/css',
            html: 'dist',
            scripts: './dist/scripts',
            images: './dist/img',
            navigation: './src/views/partials/generated-navigation.ejs'
        },
        watch: {
            // Watch paths for changes
            appSass: './src/sass/**/*.scss',
            views: ['./src/views/**/*.ejs', './src/views/partials/**/*.ejs'],
            scripts: './src/scripts/**/*.js',
            navigation: './src/navigation.json'
        }
    },
    browserSync: {
        // BrowserSync configuration
        baseDir: './dist'
    }
};

Customizing the Gulp Build Process

You can customize the Gulp build process to fit your project needs:

Customization How to Implement
Adding New Tasks Define new task functions and register them with gulp.task()
Modifying Build Paths Update the config.paths object to change source or destination directories
Adding Preprocessors Install additional Gulp plugins and add them to the appropriate task pipeline
Optimizing for Production Add minification, compression, and optimization steps to the build tasks
Adding Linting Incorporate ESLint, Stylelint, or other linting tools into the build process

Example: Adding a New Gulp Task

Here's how to add a custom task to the Gulp build system:

// Add this to your gulpfile.js
const { src, dest, task } = require('gulp');
const imagemin = require('gulp-imagemin');

// Define a new task for image optimization
function optimizeImages() {
    return src(config.paths.src.images)
        .pipe(imagemin([
            imagemin.gifsicle({interlaced: true}),
            imagemin.mozjpeg({quality: 75, progressive: true}),
            imagemin.optipng({optimizationLevel: 5}),
            imagemin.svgo({
                plugins: [
                    {removeViewBox: false},
                    {cleanupIDs: false}
                ]
            })
        ]))
        .pipe(dest(config.paths.dist.images));
}

// Register the task
task('optimizeImages', optimizeImages);

// Add it to the build task
task('build', gulp.series(
    'clean',
    gulp.parallel('appCss', 'vendorCss', 'js', 'navigation', 'optimizeImages'),
    'html'
));

Integrating with Backend Build Systems

When integrating SmartAdmin with a backend framework, you may need to adjust the Gulp workflow:

  • ASP.NET / .NET Core: Configure Gulp to output files to the wwwroot directory and integrate with MSBuild
  • Laravel: Adjust paths to work with Laravel's public directory structure or integrate with Laravel Mix
  • Django: Configure Gulp to output to Django's static files directory and integrate with collectstatic
  • Node.js: Set up Gulp to work alongside Express or other Node.js frameworks
Pro Tip: You can extend the Gulp tasks by modifying gulpfile.js to add custom build steps, optimizations, or deployment processes. Consider creating environment-specific configurations for development, testing, and production.

Customizing index.ejs as Your Application Foundation

The index.ejs file serves as an ideal starting point for building your application. This blank template provides the basic structure while allowing maximum flexibility for integration with various backend frameworks.

Understanding index.ejs

Let's examine the key components of the index.ejs file:

// Example of index.ejs structure (simplified)
// This includes the base.ejs template with configuration parameters
include('../partials/base.ejs', {
    pageTitle: 'Page Title',
    currentPage: 'pageIdentifier', // This should match a navigation item ID in navigation.json
    additionalCSS: ['css/your-custom.css'], // Array of CSS files specific to this page
    additionalJS: ['scripts/your-custom.js'], // Array of JavaScript files specific to this page
    additionalScripts: "console.log('Page loaded');", // Inline JavaScript to be executed on page load
    contentRight: "Right sidebar content here", // Content for the right sidebar (if enabled)
    content: "Main content goes here" // Main content of the page
})

Example of base.ejs Structure

The base.ejs file provides the overall layout structure for your application. It includes:

<!DOCTYPE html>
<html>
    <head>
        < %- include('head.ejs'); % >
    </head>
    <body class="< %= typeof contentRight !== 'undefined' ? 'content-has-right' : '' % >">
        < %- include('saveloadscript.ejs'); % >
        <section class="app-wrap">
            < %- include('app-header.ejs'); % >
            < %- include('app-sidebar.ejs'); % >
            <section class="app-body">
                <main class="app-content">
                    <div class="content-wrapper">
                        < %- content % >
                    </div>
                    < % if (typeof contentRight !== 'undefined') { % >
                    <div class="content-wrapper-right">
                        < %- contentRight % >
                    </div>
                    <% } % >
                </main>
                < %- include('app-footer.ejs'); % >
            </section>
            < %- include('app-drawer.ejs'); % >
            < %- include('app-settings.ejs'); % >
        </section>
        <div class="backdrop" data-action="toggle-swap" data-toggleclass="app-mobile-menu-open"></div>
        < %- include('app-scripts.ejs'); % >
    </body>
</html>

Key Configuration Parameters

Parameter Description Usage
pageTitle Sets the page title in the browser tab String value for the HTML title tag
currentPage Identifies the current page for navigation highlighting Should match a navigation item ID in navigation.json
additionalCSS Array of CSS files specific to this page Paths relative to the dist directory
additionalJS Array of JavaScript files specific to this page Paths relative to the dist directory
additionalScripts Inline JavaScript to be executed on page load Raw JavaScript code as a template literal
contentRight Content for the right sidebar (if enabled) HTML content as a template literal
content Main page content HTML content as a template literal

Example of head.ejs Structure

The head.ejs file provides the base head for the application:

<meta charset="utf-8">
<title>< %= pageTitle % >
<meta name="description" content="Page Description">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no, user-scalable=no, minimal-ui">
<!-- Call App Mode on ios devices -->
<meta name="mobile-web-app-capable" content="yes">
<!-- Remove Tap Highlight on Windows Phone IE -->
<meta name="msapplication-tap-highlight" content="no">
<!-- Vendor css -->
<link rel="stylesheet" media="screen, print" href="css/bootstrap.css">
<link rel="stylesheet" media="screen, print" href="css/waves.css">
<!-- Base css -->
<link rel="stylesheet" media="screen, print" href="css/smartapp.css">
<link rel="stylesheet" media="screen, print" href="css/sa-icons.css">
<!-- Page specific CSS, that comes from the index.ejs file under 'additionalCSS' -->
< % if (typeof additionalCSS !== 'undefined' && additionalCSS) { % >
    < % additionalCSS.forEach(function(css) { % >
        <link rel="stylesheet" media="screen, print" href="< %= css % >">
    <% }); % >
< % } % >

Example of app-scripts.ejs Structure

The app-scripts.ejs file provides the base scripts for the application:

<!-- core scripts  -->
<script>
    //Run loadPanelState() immediately (before DOMContentLoaded)
</script>
<!-- Bootstrap JS Bundle with Popper -->
<script type="text/javascript" src="scripts/bootstrap.bundle.min.js">
<script type="text/javascript" src="scripts/waves.min.js"></script>
<!-- App JS scripts -->
<script type="text/javascript" src="scripts/smartApp.js"></script>
<script type="text/javascript" src="scripts/smartNavigation.js"></script>
<script type="text/javascript" src="scripts/smartFilter.js"></script>   
<script type="text/javascript" src="scripts/sortable.js"></script>
<script type="text/javascript" src="scripts/smartSlimscroll.js"></script>

<!-- Page specific JS -->
< % if (typeof additionalJS !== 'undefined' && additionalJS) { % >
    < % additionalJS.forEach(function(js) { % >
        <script src="< %= js % >"></script>
    < % }); % >
< % } % >

<script>
    // Initialize the navigation Scripts
    // Waves Effect
    
    document.addEventListener('DOMContentLoaded', function() {
        // Initialize the list filter
        // SortableJS
        // Initialize Sortable for each column
        // SmartSlimScroll
    });

    // Initialize tooltips
    // Initialize popovers
    // Set default dropdown behavior
    // Inject additional scripts dynamically
    < % if (typeof additionalScripts !== 'undefined' && additionalScripts) { % >
        < % = additionalScripts % >
    < % } % >
</script>

Integration with Backend Frameworks

SmartAdmin's template structure can be adapted to work with various backend frameworks. Here's how to approach integration with popular platforms:

For .NET integration, convert the EJS templates to Razor views:

  1. Create a _Layout.cshtml based on base.ejs
  2. Convert EJS includes to Razor partial views
  3. Replace EJS variables with Razor model properties
  4. Move CSS/JS references to appropriate Razor sections
// ASP.NET Razor example (simplified)
// _Layout.cshtml
@model YourApp.Models.PageViewModel
@{
    ViewData["Title"] = Model.PageTitle;
}

// Navigation partial
@await Html.PartialAsync("_Navigation")

// Main Content 
<div class="main-content">
    @RenderBody()
</div>

// Scripts section 
@section Scripts {
    // Your scripts here 
}

For PHP frameworks like Laravel or Symfony:

  1. Convert base.ejs to a Blade/Twig layout template
  2. Use framework-specific template inheritance
  3. Implement sections/blocks for content areas

Laravel (Blade) Example:

// Laravel Blade example (simplified)
// layouts/app.blade.php
<!DOCTYPE html>
<html lang="en">
<head>
    <title>{{ $pageTitle ?? 'SmartAdmin' }}</title>
    <!-- CSS includes -->
</head>
<body>
    @include('partials.navigation')
    
    <div class="main-content">
        @yield('content')
        </div>
    
    <!-- Script includes -->
</body>
</html>

For Django or Flask applications:

  1. Convert base.ejs to a Django/Jinja2 base template
  2. Use template inheritance with blocks
  3. Pass context variables from views to templates

Django Example:

// Django template example (simplified)
// templates/base.html
<!DOCTYPE html>
<html lang="en">
<head>
    <title>{% block title %}SmartAdmin{% endblock %}</title>
    <!-- CSS includes -->
</head>
<body>
    {% include 'partials/navigation.html' %}
    
    <div class="main-content">
        {% block content %}{% endblock %}
    </div>
    
    <!-- Script includes -->
</body>
</html>

// templates/index.html
{% extends 'base.html' %}

{% block title %}{{ page_title }}{% endblock %}

{% block content %}
    
{% endblock %}

For modern JavaScript frameworks:

  1. Extract the CSS and JS dependencies
  2. Create component-based layouts
  3. Use props/state to manage dynamic content

React Example:

// React components example (simplified)

// Layout.jsx
import React from 'react';
import Navigation from './components/Navigation';

const Layout = ({ pageTitle, children, additionalCSS = [], additionalJS = [] }) => {
  // Component implementation
  return (
    <>
      <Navigation />
      <div className="main-content">
        {children}
      </div>
    </>
  );
};

// HomePage.jsx
import React from 'react';
import Layout from './Layout';

const HomePage = () => {
  return (
    <Layout pageTitle="Home Page">
      <h1>Welcome to SmartAdmin</h1>
      <div className="main-content">
        <p>Your content here</p>
      </div>
    </Layout>
  );
};

Best Practices for Customization

Practice Description
Modular Structure Break down the UI into reusable components/partials that can be maintained independently
Configuration-Driven Use configuration objects to control page behavior rather than hardcoding values
Asset Management Implement proper bundling and minification for production environments
Authentication Integration Plan for user authentication UI components and session management
API Communication Establish patterns for frontend-backend communication (REST, GraphQL, etc.)
State Management Implement appropriate state management for your application complexity
Error Handling Create consistent error handling and user feedback mechanisms
Pro Tip: Create a standardized page template early in your development process. This template should include all common elements (navigation, footer, authentication UI) and provide clear extension points for page-specific content.

Theme Colors and Customization

SmartAdmin v5 provides a powerful theming system that allows you to customize the visual appearance of your application. The theme is built using SCSS variables, making it easy to change colors, typography, and other visual elements.

Understanding _variables.scss

The core of the theming system is the src/sass/app/_variables.scss file. This file contains all the color definitions and other visual variables that control the appearance of the template:

// Core theme colors in _variables.scss
$color-primary:                     #2196F3;
$color-success:                     #1dc9b7;
$color-info:                        #a486d1;
$color-warning:                     #ffc241;
$color-danger:                      #fd3995;
$color-fusion:                      darken(desaturate(adjust-hue($color-primary, 5), 80%), 25%);
$color-white:                       #fff;
$color-black:                       #000; 

// Color Maps
$theme-colors: (
  'primary': $color-primary,
  'success': $color-success,
  'info': $color-info,
  'warning': $color-warning,
  'danger': $color-danger,
  'fusion': $color-fusion,
  'dark': $color-black,
  'light': $color-white,
  'secondary': #6c757d
);

Customizing Theme Colors

To change the theme colors of your application:

  1. Locate and open src/sass/app/_variables.scss
  2. Modify the color variables to match your brand or design requirements
  3. Run gulp appCss to compile the SCSS into CSS
  4. Or use gulp to start the watch process for automatic compilation on changes
Color Variable Used For Default Value
$color-primary Primary buttons, links, active states, and brand elements #2196F3 (Blue)
$color-success Success messages, confirmations, and positive actions #1dc9b7 (Teal)
$color-info Information messages, help text, and neutral notifications #a486d1 (Purple)
$color-warning Warning messages, caution indicators, and attention-grabbing elements #ffc241 (Amber)
$color-danger Error messages, destructive actions, and critical alerts #fd3995 (Pink)

CSS Variables System

SmartAdmin v5 converts SCSS variables into CSS custom properties (variables) for runtime theme switching capabilities. This enables features like dark mode and dynamic theming:

// CSS Variables in :root
:root {
    // Theme Colors
    @each $name, $value in $theme-colors {
        // Base color
        --bs-#{$name}: #{$value};
        
        // RGB values for rgba() usage
        --bs-#{$name}-rgb: #{red($value)}, #{green($value)}, #{blue($value)};
        
        // Text emphasis colors
        --bs-#{$name}-text-emphasis: #{darken($value, 30%)};
        
        // Subtle background colors
        --bs-#{$name}-bg-subtle: #{lighten($value, 30%)};
        
        // Subtle border colors
        --bs-#{$name}-border-subtle: #{lighten($value, 20%)};
    }
}

Compiling Theme Changes

After making changes to the SCSS variables, you need to compile them to CSS using Gulp:

// Compile SCSS to CSS (one-time)
gulp appCss

// Watch for changes and automatically recompile (development)
gulp

// Build optimized CSS for production
gulp build

Dark Mode Customization (coming soon)

The dark mode theme is defined in the same file using the [data-bs-theme=dark] selector:

// Dark theme overrides
[data-bs-theme=dark] {
    // Base theme colors
    --bs-body-color: #adb5bd;
    --bs-body-bg: #212529;
    --bs-emphasis-color: var(--bs-white);
    
    // Component specific colors
    --bs-border-color: #495057;
    --bs-border-color-translucent: rgba(255, 255, 255, 0.15);
    
    // Navigation specific
    --app-nav-link-color: #adb5bd;
    --app-nav-link-hover-color: #fff;
    --app-nav-link-active-color: #fff;
}
Important: Always use the Gulp tasks to compile your SCSS changes. Direct edits to CSS files will be overwritten during the next compilation.

Advanced Customization Tips

  • Color Shades: SmartAdmin generates color shades (50-900) for each theme color automatically
  • Typography: Customize fonts by changing the --font-family variable
  • Layout: Adjust layout dimensions with variables like --app-header-height and --menu-width
  • Custom Themes: Create multiple theme files by extending the base variables
Pro Tip: For large projects, create a separate _custom-variables.scss file that imports and overrides the default variables. This approach makes it easier to update the template while preserving your customizations.

Examples and Usage

Toggle Actions

Toggle actions are used to switch classes on and off elements:

<!-- Basic Toggle Example -->
<button data-action="toggle" data-class="my-class">Toggle Class</button>

<!-- Toggle with Dependencies -->
<button data-action="toggle" 
        data-class="primary-theme"
        data-dependency="dark-mode light-mode">Toggle Theme</button>

<!-- Toggle with Co-dependencies -->
<button data-action="toggle" 
        data-class="menu-expanded"
        data-codependence="menu-collapsed">Toggle Menu</button>

Panel Actions

SmartApp.js includes comprehensive panel management features:

<!-- Panel Controls -->
<div class="panel">
    <div class="panel-hdr">
        <h2>Example Panel</h2>
        <div class="panel-toolbar">
            <button class="btn btn-panel" data-action="panel-collapse">
                <i class="fa fa-minus"></i>
            </button>
            <button class="btn btn-panel" data-action="panel-fullscreen">
                <i class="fa fa-expand"></i>
            </button>
            <button class="btn btn-panel" data-action="panel-close">
                <i class="fa fa-times"></i>
            </button>
        </div>
    </div>
    <div class="panel-container">
        <div class="panel-content">
            Panel content here
        </div>
    </div>
</div>

Sound Controls

SmartApp.js provides audio playback functionality:

<!-- Play Sound Example -->
<button data-action="playsound" 
        data-soundfile="notification.mp3">
    Play Notification
</button>

<!-- Play Sound with Path -->
<button data-action="playsound" 
        data-soundpath="media/sound/" 
        data-soundfile="alert.mp3">
    Play Alert
</button>

Class Management

Direct class manipulation on target elements:

<!-- Add Class Example -->
<button data-action="add-class" 
        data-target="#myElement" 
        data-classname="active">
    Activate Element
</button>

<!-- Remove Class Example -->
<button data-action="remove-class" 
        data-target="#myElement" 
        data-classname="disabled">
    Enable Element
</button>

<!-- Toggle Replace Example -->
<button data-action="toggle-replace" 
        data-target="#myElement"
        data-removeclass="light-theme"
        data-addclass="dark-theme">
    Switch Theme
</button>

Working Examples

Here are some live examples you can try:

Demo Panel

This is a working example of a panel with all controls enabled. Tip:Remember to use the btn-has-sound class when adding a sound to a button.

Adds the class "demo-active" to the HTML element and saves the settings

Adds/Remove the class "highlight" to the #demoElement element

Theme Settings and Customization

SmartAdmin provides a comprehensive theme settings system that allows you to customize the layout and appearance of your application. These settings can be controlled through data attributes and are automatically saved to local storage.

Available Theme Settings

Setting Class Description Example
Header Fixed set-header-fixed Fixes the header position at the top of the page
Navigation Full Height set-nav-full Extends navigation to full page height
Navigation Fixed set-nav-fixed Fixes the navigation position
Navigation Collapsed set-nav-collapsed Collapses the navigation to icons only
Navigation Minified set-nav-minified Minifies the navigation menu
Dark Navigation set-nav-dark Applies dark theme to navigation

Implementation Example

Here's how to implement theme settings in your application:

<!-- Theme Setting Toggle -->
<div class="form-check">
    <input class="form-check-input" 
           type="checkbox" 
           id="actionNavFull" 
           data-action="toggle" 
           data-class="set-nav-full"
           data-codependence="set-nav-collapsed">
    <label class="form-check-label" for="actionNavFull">
        Navigation full height
    </label>
</div>

<!-- Theme Setting with Dependencies -->
<div class="form-check">
    <input class="form-check-input" 
           type="checkbox" 
           id="actionNavCollapsed" 
           data-action="toggle" 
           data-class="set-nav-collapsed"
           data-dependency="set-nav-full">
    <label class="form-check-label" for="actionNavCollapsed">
        Navigation collapsed
    </label>
</div>

Understanding Dependencies

Theme settings can have dependencies and co-dependencies:

  • data-dependency: Classes that must be added when this setting is enabled
  • data-codependence: Classes that must be removed when this setting is enabled
Pro Tip: Theme settings are automatically saved to local storage and restored on page reload. You can reset all settings using the appDOM.resetStyle() method.
On This Page