# Getting Started

######

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

    If you have not set up Node.js or are not using Node.js, then skip the below step
    and open the dist folder directly in the editor.
    Run a local server

##### Recommended Extensions

- VS Code – Live Server

## 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 | Toggle Fixed Header
Navigation Full Height | `set-nav-full` | Extends navigation to full page height | Toggle Full Height
Navigation Fixed | `set-nav-fixed` | Fixes the navigation position | Toggle Fixed Nav
Navigation Collapsed | `set-nav-collapsed` | Collapses the navigation to icons only | Toggle Collapsed Nav
Navigation Minified | `set-nav-minified` | Minifies the navigation menu | Toggle Minified Nav
Dark Navigation | `set-nav-dark` | Applies dark theme to navigation | Toggle Dark Nav

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

- Introduction
- Prerequisites
- Installation
- Project Structure
- Gulp Build
- Navigation
- Customizing
- Backend Integration
- Best Practices
- Theme Colors
- Examples
- Theme Settings

#### Hi Sunny,

how can I help you today?
Analyze my data

Create a new report

Summarize my Calendar

App Builder
Unlock limitless design potential with 16+ layout combinations and extensive customization options—tailor your dashboard to fit your exact needs.
Header position fixed
Navigation full height
Navigation position fixed
Navigation collapsed
Navigation Minified
Dark Navigation
Colorblind Mode
High Contrast Mode