SmartAdmin - 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
# Open the SmartAdmin project folder (Full or Seed) in your preferred code editor (e.g., VS Code, WebStorm, Sublime Text, etc.)
Step 2: Install Dependencies
# Option 1: If Using yarn (https://yarnpkg.com/getting-started)
yarn install
                                                
# --------------------------------------------

# Option 2: If Using npm (https://docs.npmjs.com/)
npm install


# --------------------------------------------

# Option 3: If Using bun (https://bun.sh/docs)
bun install
Step 3: Build the Project
// Default task - builds everything and starts watching for changes
gulp

// Build all assets without watching
gulp build

// RTL (Right-to-Left) support
gulp rtl

// Build RTL all assets without watching
gulp rtlbuild
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
gulpfile.js Gulp configuration and tasks
plugins.config.js Plugins File Path
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

// RTL (Right-to-Left) support
gulp rtl

// Build RTL all assets without watching
gulp rtlbuild
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
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.html as Your Application Foundation

The index.html 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.html

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

Example of index.html Structure

The index.html file provides the overall layout structure for your application. It includes:

<!DOCTYPE html>
@@include('./partials/app-html.html')

<head>
    @@include('./partials/app-meta-title.html', {"pageTitle": 'Blank Page'})

    @@include('./partials/app-head-css.html')
</head>

<body>

    <div class="app-wrap">

        @@include('./partials/app-header.html')

        @@include('./partials/app-sidebar.html')

        <main class="app-body">
            <div class="app-content">

                <div class="content-wrapper">

                    @@include('./partials/app-pagetitle.html', {
                        "pageTitle": "Blank Page",
                        "pageSubTitle1": "Blank Page",
                        "pageSubText": "Blank Page"
                    })

                </div>


            </div>

            @@include('./partials/app-footer.html')

        </main>

        @@include('./partials/app-drawer.html')

        @@include('./partials/app-settings.html')

    </div>

    @@include('./partials/app-scripts.html')

    <script src="scripts/pages/blank.js"></script>

</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 app-head-css.html Structure

The app-head-css.html file provides the base head css for the application:

<!-- Vendor css -->
<link rel="stylesheet" media="screen, print" href="plugins/waves/waves.min.css">

<!-- Base css -->
<link rel="stylesheet" media="screen, print" href="css/smartapp.css">

<!-- Icons css-->
<link rel="stylesheet" media="screen, print" href="webfonts/smartadmin/sa-icons.css">
<link rel="stylesheet" media="screen, print" href="webfonts/fontawesome/fontawesome.css">

<!-- Save/Load functionality JavaScript -->
<script src="scripts/core/saveloadscript.js"></script>
Example of app-scripts.html Structure

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

<!-- Core scripts -->
<script src="plugins/bootstrap/bootstrap.bundle.min.js"></script>
<script src="scripts/core/smartNavigation.js"></script>
<script src="scripts/core/smartFilter.js"></script>
<script src="scripts/core/smartSlimscroll.js"></script>

<!-- Dependable scripts -->
<script src="plugins/sortablejs/Sortable.min.js"></script>
<script src="plugins/waves/waves.min.js"></script>

<!-- App.js -->
<script src="scripts/core/smartApp.js"></script>

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 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

// Build all assets without watching
gulp build

// RTL (Right-to-Left) support
gulp rtl

// Build RTL all assets without watching
gulp rtlbuild
Dark Mode Customization

The dark mode theme is defined in the same file using the [data-bs-theme=dark] selector found in src/sass/app/_darkmode.scss

Inverse Key Variables

The following variables are used to customize the dark mode theme which has the proper inverse effect:

  • --bs-body-color / --bs-body-color-rgb: Inverse Text color
  • --bs-body-bg / --bs-body-bg-rgb: Inverse Background color
  • --bs-emphasis-color / --bs-emphasis-color-rgb: Inverse Emphasis color
  • --bs-border-color / --bs-border-color-rgb: Inverse Border color
// Dark theme overrides 
[data-bs-theme=dark] {
    color-scheme: dark;
    --bs-body-color: #{$body-color-dark};
    --bs-body-color-rgb: #{red($body-color-dark)}, #{green($body-color-dark)}, #{blue($body-color-dark)};
    --bs-body-bg: #{$body-bg-dark};
    --bs-body-bg-rgb: #{red($body-bg-dark)}, #{green($body-bg-dark)}, #{blue($body-bg-dark)};
    --bs-emphasis-color: #{$body-emphasis-color-dark};
    --bs-emphasis-color-rgb: #{red($body-emphasis-color-dark)}, #{green($body-emphasis-color-dark)}, #{blue($body-emphasis-color-dark)};
    --bs-secondary-color: #{$body-secondary-color-dark};
    --bs-secondary-color-rgb: #{red($body-secondary-color-dark)}, #{green($body-secondary-color-dark)}, #{blue($body-secondary-color-dark)};
    --bs-secondary-bg: #{$body-secondary-bg-dark};
    --bs-secondary-bg-rgb: #{red($body-secondary-bg-dark)}, #{green($body-secondary-bg-dark)}, #{blue($body-secondary-bg-dark)};
    --bs-tertiary-color: #{$body-tertiary-color-dark};
    --bs-tertiary-color-rgb: #{red($body-tertiary-color-dark)}, #{green($body-tertiary-color-dark)}, #{blue($body-tertiary-color-dark)};
    --bs-tertiary-bg: #{$body-tertiary-bg-dark};
    --bs-tertiary-bg-rgb: #{red($body-tertiary-bg-dark)}, #{green($body-tertiary-bg-dark)}, #{blue($body-tertiary-bg-dark)};
    --bs-primary-text-emphasis: #{$primary-text-emphasis-dark};
    --bs-secondary-text-emphasis: #{$secondary-text-emphasis-dark};
    --bs-success-text-emphasis: #{$success-text-emphasis-dark};
    --bs-info-text-emphasis: #{$info-text-emphasis-dark};
    --bs-warning-text-emphasis: #{$warning-text-emphasis-dark};
    --bs-danger-text-emphasis: #{$danger-text-emphasis-dark};
    --bs-light-text-emphasis: #{$light-text-emphasis-dark};
    --bs-dark-text-emphasis: #{$dark-text-emphasis-dark};
    --bs-primary-bg-subtle: #{$primary-bg-subtle-dark};
    --bs-secondary-bg-subtle: #{$secondary-bg-subtle-dark};
    --bs-success-bg-subtle: #{$success-bg-subtle-dark};
    --bs-info-bg-subtle: #{$info-bg-subtle-dark};
    --bs-warning-bg-subtle: #{$warning-bg-subtle-dark};
    --bs-danger-bg-subtle: #{$danger-bg-subtle-dark};
    --bs-light-bg-subtle: #{$light-bg-subtle-dark};
    --bs-dark-bg-subtle: #{$dark-bg-subtle-dark};
    --bs-primary-border-subtle: #{$primary-border-subtle-dark};
    --bs-secondary-border-subtle: #{$secondary-border-subtle-dark};
    --bs-success-border-subtle: #{$success-border-subtle-dark};
    --bs-info-border-subtle: #{$info-border-subtle-dark};
    --bs-warning-border-subtle: #{$warning-border-subtle-dark};
    --bs-danger-border-subtle: #{$danger-border-subtle-dark};
    --bs-light-border-subtle: #{$light-border-subtle-dark};
    --bs-dark-border-subtle: #{$dark-border-subtle-dark};
    --bs-border-color: #{$border-color-dark};
    --bs-border-color-translucent: #{$border-color-translucent-dark};
    --bs-headings-color: #{$headings-color-dark};
    --bs-link-color: #{$link-color-dark};
    --bs-link-hover-color: #{$link-hover-color-dark};
    --bs-code-color: #{$code-color-dark};
    --bs-mark-color: #{$mark-color-dark};
    --bs-mark-bg: #{$mark-bg-dark};
    --bs-form-select-indicator-color: #{$form-select-indicator-color-dark};
    --bs-form-select-indicator: #{$form-select-indicator-dark};
    --bs-form-switch-color: #{$form-switch-color-dark};
    --bs-form-switch-bg-image: #{$form-switch-bg-image-dark};
    --bs-form-valid-color: #{$form-valid-color-dark};
    --bs-form-valid-border-color: #{$form-valid-border-color-dark};
    --bs-form-invalid-color: #{$form-invalid-color-dark};
    --bs-form-invalid-border-color: #{$form-invalid-border-color-dark};
    --bs-accordion-icon-color: #{$accordion-icon-color-dark};
    --bs-accordion-icon-active-color: #{$accordion-icon-active-color-dark};
    --bs-accordion-button-icon: #{$accordion-button-icon-dark};
    --bs-accordion-button-active-icon: #{$accordion-button-active-icon-dark};
}
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