JavaScript

Learn more about Materio's core js and usage of third-party plugins.

Folder structure

Important: Make sure you have followed the steps from the Installation & Build tools page. You should have already installed the Node, Gulp and setup the template. Check available tasks to transpile/compile JavaScript.

Below is the folder structure which contain the JS/ES6 files.

📦
├── 📂 js                                   > Template core JS(ES6) folder
│   ├── 📂 _template-customizer               > Contains template customizer markup & styles
│   ├── 📄 bootstrap.js                       > Extends bootstrap JS from node_modules/
│   ├── 📄 dropdown-hover.js                  > Add onHover event for bootstrap dropdowns
│   ├── 📄 helpers.js                         > Contains reusable helper functions
│   ├── 📄 mega-dropdown.js                   > Mega menu JS
│   ├── 📄 menu.js                            > Core menu JS (vertical & horizontal)
│   └── 📄 template-customizer.js             > Customizer Plugin JS
│
├── 📂 assets                               > Templates assets
│   └── 📂 js                                 > Contains main, config, pages, apps and third-party plugins JS
│       ├── 📄 main.js                        > Initialize the template core components, plugins and contain common JS.
│       ├── 📄 config.js                      > Contains JS global variables and TemplateCustomizer settings
│       └── ...
│
├── 📂 libs                                 > Third-party libraries(plugins)
│   ├── 📂 datatables-bs5                     > DataTables plugins JS extends from node_modules
│   │   └── 📄 datatables-bootstrap5.js
│   └── ...
│
├── 📄 build-config.js                      > Template build config file
├── 📄 gulpfile.js                          > Gulpfile
└── ...

Important:

It is not recommend to make any changes in the to the js/ (core JS) folder.
If you modify any JavaScript files from assets/js/ folder, make sure you keep an eye on those edited changes as Materio will be constantly updated and you need to merge those changes manually.

js/ Folder contains template core JS (ES6) files. Materio uses Webpack to transpile those files and generate js in assets/vendor/js/ folder. Read more. It is not recommend to make any changes in this folder.

bootstrap.js File extend core bootstrap js from node_modules. You can also import required only plugins of bootstrap.
helpers.js File contains reusable helper functions. Read more
menu.js Core menu JS file, contain vertical & horizontal menu (navigation) code.
template-customizer.js Template Customizer Plugin JS file. Read more

assets/js Folder contains template static JavaScript files of each pages, apps and third-party plugins usage. If you modify any JavaScript files from this folder, make sure you keep an eye on those you edited changes as it will be constantly updated and you need to merge those changes manually.

main.js This the main file which initialize the template core components, plugins and contain common JS.
config.js Contains JS global variables and TemplateCustomizer settings which are used in this templates. Read more

libs/ Folder also contains third-party libraries (plugins) JavaScript files which is extended from node_modules/. You can easily add/remover plugins as per your choice. For more details refer Third Party Plugin Guide.

Tip:

Materio import most of all bootstrap plugins from node_modules. If you don't want to use all bootstrap plugin, then you can import specific plugin also in bootstrap.js file as per your preference.
Easily add/remover third-party plugins as per your choice. For more details refer Third Party Plugin Guide.

Customizing JS

Materio provide almost all possible options to customize it easily using config.js file. Apart from that it also provides useful helper methods to customize it easily.

You can also modify any pages, apps or third-party plugin JavaScript files from assets/js folder. Just make sure you keep an eye on those you edited changes as it will be constantly updated and you need to merge those changes manually.

Where should I write my custom JavaScript?

To avoid file loss, overrides of your custom JavaScript or any other conflicts during the upgrade process, create your custom javascript file assets/js/scripts.js. Just don't forget to include it in your HTML file.

Methods

Helpers

Useful JavaScript helpers methods to customize Materio easily. For example, To use helpers methods, Open browser developer tool and in console tab run Helpers.isRtl()

Method	Description
`isLightStyle()`	Returns `true` if the current style is light, else returns `false`.
`isDarkStyle()`	Returns `true` if the current style is dark, else returns `false`.
`isRtl()`	Returns `true` if the current layout is in RTL direction, else returns `false`.
`isCollapsed()`	Returns `true` if the current layout is collapsed, else returns `false`.
`isFixed()`	Returns `true` if the current layout is fixed, else returns `false`.
`isNavbarFixed()`	Returns `true` if the Navbar is fixed, else returns `false`.
`isFooterFixed()`	Returns `true` if the Footer is fixed, else returns `false`.
`setCollapsed()`	Set to `true` to collapsed vertical menu, `false` to expand it. For example, `setCollapsed(true)`
`toggleCollapsed()`	Set to `true` to collapsed vertical menu, `false` to expand it.
`isSmallScreen()`	Returns `true` if the window width is less than 1200px, else returns `false`.
`isMobileDevice()`	Returns `true` if the current devices is mobile, else returns `false`.

Customizer

Useful customizer JavaScript helper methods to customize Materio easily. For example, To use customizer helper methods, Open browser developer tool and in console tab run templateCustomizer.setRtl(true)

Method	Description
`setRtl()`	Set to `true` to enable RTL direction (mode), `false` to disable it.
`setStyle()`	Set the current style light/dark. Accepts the following values: 'light' 'dark'
`setTheme()`	Set the current theme. Accepts the following values: 'theme-default' 'theme-semi-dark' 'theme-bordered'
`setLayoutType()`	Set the current layout type static/fixed. Accepts the following values: 'static' 'fixed'
`setLayoutNavbarFixed()`	Set to `true` to make layout navbar fixed, `false` to make it static.
`setLayoutFooterFixed()`	Set to `true` to make layout footer fixed, `false` to make it static.
`setLang()`	Set current language. The value must be in the `TemplateCustomizer.LANGUAGES`, otherwise an error will be thrown. Read more
`update()`	Update customizer settings panel.
`clearLocalStorage()`	Clear localStorage.
`destroy()`	Destroy TemplateCustomizer instance.

FAQs

Can I remove jQuery?

Yes. Before you remove it, confirm the following important points.

Many third-party plugins (For example, Select2, Block UI, jQuery-idletimer, Typeahead etc..) are still using jQuery and they are very useful. Due to that we can't remove it. But if you are not using those libraries you can remove jQuery.
The navbar search functionality also depends on jQuery plugin (Typeahead), it will stop working if you remove jQuery.

If you are fine with the above points, then proceed with removing jquery.js from HTML.
Also, remove jQuery plugin usage from main.js. Search for the Removed following code if you don't wish to use jQuery and remove the code.

Info: We also love to remove jQuery dependency from this template, once the important libraries removes the jQuery dependencies we will also remove it.

How can I use Translation (Internationalization)?

Materio Use i18next as internationalization-framework. For demo purposes in this template, we're just translating the menu (navigation), but you can use translation anyware in this template.

Add/update language option to the navbar dropdown easily.
To add the Arabic language, refer the following code. Don't forget to set language to data-language attribute.
```
<li>
  <a class="dropdown-item" href="javascript:void(0);" data-language="ar" data-text-direction="rtl">
    <span class="align-middle">Arabic</span>
  </a>
</li>
```
assets/json/locales/ folder contain different languages translation files. It contains Key, Value pairs for each word to translate. You can add more Key, Value pairs or create a new language file.
Also, add that Key to data-i18n attribute to HTML tag. For example, <span data-i18n="Apple">Apple</span>
Search lang in config.js and set the default language here. For ex: 'en'.

if (typeof TemplateCustomizer !== 'undefined') {
  window.templateCustomizer = new TemplateCustomizer({
    cssPath: assetsPath + 'vendor/css' + (rtlSupport ? '/rtl' : '') + '/',
    themesPath: assetsPath + 'vendor/css' + (rtlSupport ? '/rtl' : '') + '/',
    displayCustomizer: true,
    lang: localStorage.getItem('templateCustomizer-' + templateName + '--Lang') || 'en', // Set default language here
    // defaultTheme: 2,
    // defaultStyle: 'system',
    // defaultTextDir: 'rtl',
    // defaultContentLayout: 'wide',
    // defaultHeaderType: 'static',
    // defaultMenuCollapsed: true,
    // defaultNavbarType: 'sticky',
    // defaultFooterFixed: false,
    // defaultShowDropdownOnHover: false,
    controls: ['rtl', 'style', 'headerType', 'contentLayout', 'layoutCollapsed', 'layoutNavbarOptions', 'themes']
  });
}

Internationalization section in main.js. It contains the following code.

if (typeof i18next !== 'undefined' && typeof i18NextHttpBackend !== 'undefined') {
i18next
  .use(i18NextHttpBackend)
  .init({
    lng: window.templateCustomizer ? window.templateCustomizer.settings.lang : 'en',
    debug: false,
    fallbackLng: 'en',
    backend: {
      loadPath: assetsPath + 'json/locales/{{lang}}.json'
    },
    returnObjects: true
  })
  .then(function (t) {
    localize();
  });
}

lang: use this parameter to set default language In our case we're using window.templateCustomizer.settings.lang from config.js file. If the default translation language file is not available then it will use fallbackLng automatically.
loadPath: Set the language JSON file path.