Docs v1.1.0  /  Settings panel HTML5 Angular Vue.js Laravel Laravel + Vue.js Rails ASP.NET Core 2 ASP.NET MVC
OTHER
Layout helpers

ThemeSettings plugin allow you to dynamically configure layout options and theme appearance.

Usage

To use ThemeSettings plugin, first of all, you need to:

  1. Include layout-helpers.js and theme-settings.js scripts in the <head> section.
  2. Initialize ThemeSettings plugin in the <script> block in the <head> section. It's important to initialize the plugin in the <head> to prevent style blinking.
  3. Add theme-settings-bootstrap-css, theme-settings-appwork-css, theme-settings-theme-css and theme-settings-colors-css classes to bootstrap, appwork, theme-* and colors stylesheets. Please note that ThemeSettings plugin initialization code must be after core stylesheets. 
<!-- Core stylesheets -->
<link rel="stylesheet" href="path/to/css/bootstrap.css" class="theme-settings-bootstrap-css">
<link rel="stylesheet" href="assets/vendor/css/appwork.css" class="theme-settings-appwork-css">
<link rel="stylesheet" href="path/to/theme-css/theme-corporate.css" class="theme-settings-theme-css">
<link rel="stylesheet" href="path/to/css/colors.css" class="theme-settings-colors-css">
<link rel="stylesheet" href="path/to/css/uikit.css">

    <!-- Layout helpers -->
<script src="path/to/layout-helpers.js"></script>

<!-- Theme settings -->
<script src="path/to/theme-settings.js"></script>
<script>
  window.themeSettings = new ThemeSettings({
    cssPath: 'path/to/css/',
    themesPath: 'path/to/theme-css/'
  });
</script>
// Get current settings. Do not change it directly, use methods instead.
console.log(window.themeSettings.settings);

/*
{
  "cssPath": "path/to/css/",
  "themesPath": "path/to/theme-css/",
  "cssFilenamePattern": "%name%.css",
  "navbarBgs": [ ... ],
  "defaultNavbarBg": "navbar-theme",
  "sidenavBgs": [ ... ],
  "defaultSidenavBg": "sidenav-theme",
  "footerBgs": [ ... ],
  "defaultFooterBg": "footer-theme",
  "availableThemes": [ ... ],
  "defaultTheme": { ... },
  "controls": [ ... ],
  "rtl": false,
  "material": false,
  "layoutPosition": "static",
  "layoutReversed": false,
  "layoutNavbarFixed": false,
  "layoutFooterFixed": false,
  "navbarBg": "navbar-theme",
  "sidenavBg": "sidenav-theme",
  "footerBg": "footer-theme",
  "theme": { ... }
}
*/

Options

Option Description
cssPath Core stylesheets path. Must ends with a slash. Required
themesPath Theme stylesheets path. Must ends with a slash. Required
cssFilenamePattern

Filename pattern.

Default: %name%.css

For example, if you set this option to %name%.minified.css, the plugin will load the next paths:

  • path/to/css/bootstrap.minified.css
  • path/to/css/bootstrap-material.minified.css
  • path/to/css/appwork.minified.css
  • path/to/css/appwork-material.minified.css
  • path/to/css/colors.minified.css
  • path/to/css/colors-material.minified.css
  • path/to/theme-css/theme-corporate.minified.css
  • ...
controls

Using this option you can disable ThemeSettings controls. Just pass an array of the required controls.

Default: ['rtl', 'material', 'layoutPosition', 'layoutNavbarFixed', 'layoutFooterFixed', 'layoutReversed', 'navbarBg', 'sidenavBg', 'footerBg', 'themes']

For example, if you set this option to ['rtl', 'material'], ThemeSettings panel will contain only RTL and material switchers.
sidenavBgs

Available layout sidenav backgrounds.

Default: ['sidenav-theme', 'primary', 'primary-dark sidenav-dark', 'primary-darker sidenav-dark', 'secondary', 'secondary-dark sidenav-dark', 'secondary-darker sidenav-dark', 'success', 'success-dark sidenav-dark', 'success-darker sidenav-dark', 'info', 'info-dark sidenav-dark', 'info-darker sidenav-dark', 'warning', 'warning-dark sidenav-light', 'warning-darker sidenav-light', 'danger', 'danger-dark sidenav-dark', 'danger-darker sidenav-dark', 'dark', 'white', 'light', 'lighter']
defaultSidenavBg

Default layout sidenav background. The plugin uses this value if no sidenav background value found in the localStorage or its value is incorrect.

Default: sidenav-theme
navbarBgs

Available layout navbar backgrounds.

Default: ['navbar-theme', 'primary', 'primary-dark navbar-dark', 'primary-darker navbar-dark', 'secondary', 'secondary-dark navbar-dark', 'secondary-darker navbar-dark', 'success', 'success-dark navbar-dark', 'success-darker navbar-dark', 'info', 'info-dark navbar-dark', 'info-darker navbar-dark', 'warning', 'warning-dark navbar-light', 'warning-darker navbar-light', 'danger', 'danger-dark navbar-dark', 'danger-darker navbar-dark', 'dark', 'white', 'light', 'lighter']
defaultNavbarBg

Default layout navbar background. The plugin uses this value if no navbar background value found in the localStorage or its value is incorrect.

Default: navbar-theme
footerBgs

Available layout footer backgrounds.

Default: ['footer-theme', 'primary', 'primary-dark footer-dark', 'primary-darker footer-dark', 'secondary', 'secondary-dark footer-dark', 'secondary-darker footer-dark', 'success', 'success-dark footer-dark', 'success-darker footer-dark', 'info', 'info-dark footer-dark', 'info-darker footer-dark', 'warning', 'warning-dark footer-light', 'warning-darker footer-light', 'danger', 'danger-dark footer-dark', 'danger-darker footer-dark', 'dark', 'white', 'light', 'lighter']
defaultFooterBg

Default layout footer background. The plugin uses this value if no footer background value found in the localStorage or its value is incorrect.

Default: footer-theme
availableThemes

Available themes. Theme item has the next structure: 

{
  name: '{theme_filename_without_extension}',
  title: '{theme_name}',
  colors: {
    primary: '{primary_color}',
    navbar: '{bg_navbar_theme}',
    sidenav: '{bg_sidenav_theme}'
  }
}

Default: 

[
  { name: 'theme-air', title: 'Air', colors: { primary: '#3c97fe', navbar: '#f8f8f8', sidenav: '#f8f8f8' } },
  { name: 'theme-corporate', title: 'Corporate', colors: { primary: '#26B4FF', navbar: '#fff', sidenav: '#2e323a' } },
  { name: 'theme-cotton', title: 'Сotton', colors: { primary: '#e84c64', navbar: '#ffffff', sidenav: '#ffffff' } },
  { name: 'theme-gradient', title: 'Gradient', colors: { primary: '#775cdc', navbar: '#ffffff', sidenav: 'linear-gradient(to top, #4e54c8, #8c55e4)' } },
  { name: 'theme-paper', title: 'Paper', colors: { primary: '#17b3a3', navbar: '#ffffff', sidenav: '#ffffff' } },
  { name: 'theme-shadow', title: 'Shadow', colors: { primary: '#7b83ff', navbar: '#f8f8f8', sidenav: '#ececf9' } },
  { name: 'theme-soft', title: 'Soft', colors: { primary: '#1cbb84', navbar: '#39517b', sidenav: '#ffffff' } },
  { name: 'theme-sunrise', title: 'Sunrise', colors: { primary: '#fc5a5c', navbar: '#222222', sidenav: '#ffffff' } },
  { name: 'theme-twitlight', title: 'Twitlight', colors: { primary: '#4c84ff', navbar: '#343c44', sidenav: '#3f4853' } },
  { name: 'theme-vibrant', title: 'Vibrant', colors: { primary: '#fc5a5c', navbar: '#f8f8f8', sidenav: '#222222' } },
]
defaultTheme

Default theme index. The plugin uses this value if no theme value found in the localStorage or its value is incorrect.

Default: 1
pathResolver

A callback function that lets you change the stylesheet url on the fly. Accepts stylesheet url. Must return stylesheet url.

This function is useful when you're using hashes in filenames - just load the manifest and return the correct path.

Example:

window.themeSettings = new ThemeSettings({
  cssPath: 'css/',
  themesPath: 'theme-css/'
  cssFilenamePattern: '%name%',
  pathResolver: function(path) {
    var pathMap = {
      'css/bootstrap': 'css/bootstrap_some-hash-1',
      'css/bootstrap-material': 'css/bootstrap-material_some-hash-2',
      'css/appwork': 'css/appwork_some-hash-3',
      'css/appwork-material': 'css/appwork-material_some-hash-4',
      'css/colors': 'css/colors_some-hash-5',
      'css/colors-material': 'css/colors-material_some-hash-6',

      'theme-css/theme-air': 'css/theme-air_some-hash-7',
      'theme-css/theme-air-material': 'css/theme-air-material_some-hash-8',
      ...
    };

    return 'http://example.com/assets/' + (pathMap[path] || path) + '.css';
  },
  ...
});
onSettingsChange

A callback function which invoked after settings changed and stored in the localStorage. Accepts ThemeSettings.settings object.

Example:

window.themeSettings = new ThemeSettings({
  ...

  onSettingsChange: function(currentSettings) {
    ...
  },

  ...
});

Methods

Method Description
setRtl(rtl) Set to true to enable RTL direction, false to disable. Will reload page.
setMaterial(material) Set to true to enable material styling, false to disable. Will reload page.
setTheme(themeName, updateStorage = true, cb = null) Set the current theme by name, must be in the settings.availableThemes array. The cb function will be invoked after the theme is loaded. Set updateStorage to false to not update localStorage.
setLayoutPosition(pos, updateStorage = true)

Set layout position. Available values:

  • static
  • static-offcanvas
  • fixed
  • fixed-offcanvas

Set updateStorage to false to not update localStorage.
setLayoutNavbarFixed(fixed, updateStorage = true) Set to true to make the layout navbar fixed, false to make it static. Set updateStorage to false to not update localStorage.
setLayoutFooterFixed(fixed, updateStorage = true) Set to true to make the layout footer fixed, false to make it static. Set updateStorage to false to not update localStorage.
setLayoutReversed(reversed, updateStorage = true) Set to true to make the layout reversed, false to reset. Set updateStorage to false to not update localStorage.
setNavbarBg(bg, updateStorage = true) Set the layout navbar background. The value must be in the settings.navbarBgs array. Set updateStorage to false to not update localStorage.
setSidenavBg(bg, updateStorage = true) Set the layout sidenav background. The value must be in the settings.sidenavBgs array. Set updateStorage to false to not update localStorage.
setFooterBg(bg, updateStorage = true) Set the layout footer background. The value must be in the settings.footerBgs array. Set updateStorage to false to not update localStorage.
update() Update settings panel.
updateNavbarBg() Update the layout navbar background.
updateSidenavBg() Update the layout sidenav background.
updateFooterBg() Update the layout footer background.
clearLocalStorage() Clear localStorage values.
destroy() Destroy ThemeSettings instance.

Configuration generator

Use ThemeSettings configuration generator to simplify the initial setup.

Open in new tab