This template was developed to use Gulp as the main tool of the development workflow.
Gulp provides plugins to serve the app, perform automatic browser reloading after any change and build of assets for distribution. It also allows to work with agile languages like PUG/SCSS/etc and modular JavaScript (concatenated).
Beyond that, if you are not convinced about build tools, the current setup has a basic support to work with static files (html, css) without needing build tools.
We encourage you to use build tools, the benefits greatly outweigh the costs of learning.
Static files organization (no Gulp)
The most simple usage is by pointing the server root the 'app' folder of the package. Note that the index.html included in the root of the project is just a redirect to dashboard.html.
This allows to work directly with raw files like CSS, HTML and JS without worrying about build tools.
Now, to edit files, focus on the following locations:
- Styles are accessible in folder /app/css
- Markup is accessible in folder /app (raw html)
- Scripts are accessible in folder /app/js
Important if you change something on this folder and then switch to use Gulp, all previous changes may be lost because Gulp uses this folder as destination to place compiled files.
Compiled files organization
As a quick reference, the current setup does the following compilations:
| Language |
Produces |
| PUG |
HTML |
| SCSS |
CSS |
| Javascript |
Javascript (concatenation) |
Styles
For styles we use two files
sass/bootstrap.scss This files will be compile to bootstrap.css with the framework rules modified to match the template styles.
sass/app.scss This file contains template rules for different components and plugins. This file also @imports some files from Bootstrap like variables and mixin to easy the development.
Scripts
All scripts are concatenated into one single file app.js
The order of concatenation is the following:
app.init.js
modules/**/*.js
custom/**/*.js
Layout
One of the main benefits of using PUG is that we can use partials templates to write common parts of a page only once and reuse such template many times. This happens also for layout, similar to templates but allows to define 'blocks' where we will add later markup for a specific page.
Behavior classes
As you can see in the index, there are some classes related to the sidebar that are used to change the layout behavior.
This classes are:
| Classname |
Description |
.layout-fixed |
Makes navbars become fixed while the user can scroll only content |
.layout-boxed |
Limits the width of the main wrapper element |
.aside-collapsed |
Condenses the sidebar showing only icons |
.aside-collapsed-text |
Condenses the sidebar showing icons and Text |
.aside-toggle |
used internally for mobiles to hide the sidebar off screen |
.offsidebar-open |
used internally to display the offsidebar component (formally the right sidebar) |
The following markup representation is in fact divided into views but this code will give a good perspective of the final organization after the app is rendered:
<html>
<head>
#metas and css
</head>
<body>
<section class="wrapper">
<nav class="navbar topnavbar">
#top navbar content
</nav>
<aside class="aside">
#sidebar content (left)
</aside>
<aside class="offsidebar">
#offsidebar content (right)
</aside>
<section>
<div class="content-wrapper">
#page content
</div>
</section>
</section>
#scripts
</body>
</html>
The file *sidebar.json *contains the sidebar menu items configuration for easy customization. Using PUG you need only to edit this file in order to change the sidebar items
Vendor
Vendor script dependencies are managed by npm. Just run npm install in folder master/ and all dependencies will be installed.
Vendor folder
To avoid unnecessary files that comes with each package there’s a Gulp task that will copy all files required by the template from the node_modules folder to the app/vendor folder.
This files are listed in *vendor.json * which contains the paths of all files required.
Vendor Updates
To update vendor files via NPM you can edit the package.json file by adding the last version you want to download. Please note that each version of the template is developed and tested with the versions included, if you update plugins is not guaranteed they will work "out of the box".
RTL
RTL support uses the a tool called "rtlcss" which inverts most the css properties to change the page orientation.
To use the rtl version just include the rtl version of the stylesheets in your html files
<link rel="stylesheet" href="css/bootstrap-rtl.css">
<link rel="stylesheet" href="css/app-rtl.css">
Translation
The translation system uses jQuery Localize
This modules simplifies the translation system by loading translate references from a JSON file and replacing the content where the reference has been used.
Examples
<small data-localize="dashboard.WELCOME"></small>
The JSON files with translation references are located in the folder app/i18n
See also dashboard.html to find example on how to change the language manually
Themes
To change the color scheme you have 2 options:
From SCSS files
Edit the SCSS files in folder master/scss/ to use the color you want. Like Bootstrap, most of the colors are based on variables.
You can also edit the files in master/scss/theme folder to create your own set of color schemes. This files must be included after the app.css in order to override the default color set.
Changing the theme colors from SCSS files helps you to avoid bloating your css by not double declaring your color rules.
From CSS files
This template support color schemes including a css file. You can find the color options in the folder app/css/ files are named theme-*.css
If you want to change or add a new component color, just inspect the color using your favorite browser devtool and then replace the value in the file.
This files are prepared to change the basic color scheme (both sidebars and top navbar) but if you want to make a more deep change, check the SCSS source files which is more simple for multiple component changes.
Default Theme
To set a default just include in your HTML files the stylesheet of the theme of your choice right after the main stylesheet (app.css)
Custom code
To add your own code you can follow this instructions:
Working with css and js
- Create a file app/css/custom.css and add your own styles
- Create a file app/js/custom.js and add your own javascript
Edit the HTML files and include custom.css after all other css files and custom.js after all other js files.
Working with source files
For JS, go to folder master/js/custom and start editing the file custom.js. After compile the source again with Gulp, your own code will included at th bottom of file app/js/app.js.
For SCSS, go to folder master/scss and create a folder named custom and add your own files. Then edit file app.scss and @import all your stylesheets at the bottom (overrides all app default styles)
A note on updating The premise is, the less you change the downloaded code, the easier will be to apply any updates. Try always to keep your own code the most separated as possible from the package code to easily apply new updates when necessary.
jQuery and Wrapper script
Starting from version 4.1, this template doesn't need jQuery as a mandatory dependency for core files, this means it is only required when using jQuery based plugins for some features included.
Seed project versions no more include jQuery by default..
The wrapper.js (~ 7k minified) is a new script introduced to emulate some specific jQuery functions used in the template. This made possible to significantly cut the refactoring changes in the code, keeping it readable in a jQuery way and avoiding extra bytes, mainly when loops are repeatedly used to work with multiple elements.
Important The Wrapper script is NOT a replacement for jQuery. All methods were designed for an adequate and specific use and they don't do a deep validation on the arguments provided. It's suggested NOT to use this library extensively. Instead, use pure JS or you might even need jQuery.