What is the expert starter?
It is a blank directory to make a copy of and start a new project with. It includes the required JS and CSS files from TheSaaS as well as icon fonts, PHP files and some images.
The expert starter has several features which is not included in the basic starter. Those features give you more freedom in customizing your template and writing extra codes. It includes a gulpfile with necessary tasks to start a web server, watch files for changes and compile SCSS and JS files. Finally, you can run a command to have all the required files for production copied to a directory.
How to get started?
Follow the below steps to create a project directory with all the required plugins and tools installed.
Step 1
Make a copy of expert/ directory to your desire workspace.
Step 2
- Download and install Node.js if it's not installed on your machine
- Install the Gulp command line tools, gulp-cli, with
npm install gulp-cli -g - Navigate to the root directory of your project and run
npm installto install dependencies - Run
gulp serve.
With the above command, a static web server starts in your browser which points to /src directory. It watch your files to reload the browser upon change to the HTML files, or JS and CSS files. Also, it watch your SCSS and JS files to compile them to page.min.css and page.min.js upon each change.
Step 3
Now it's time to configure your website.
- Script: Open
/assets/js/src/config.jsand change the desire values. - Style: Open
/assets/scss/_theme.scssand change the SCSS variables.
Step 4
Time for development. Now you're ready to create your HTML files and writing your custom CSS and JS codes.
- HTML
Since most of the websites have a global layout for whole of the application, you might want to start modifying index.html file and create a global layout for your website. Check available layout features such as navbar, header, cover, footer, etc. as well as all the blocks and UI Kit.
- SCSS
Write your additional styles inside /assets/scss/_style.scss. Feel free to create more scss files and even subdirectories inside /scss folder to split your code to smaller chunks and import them inside /scss/page.scss file. Our Gulp task is watching all of the scss files inside /scss directory and recompile the page.min.css upon each change.
- JavaScript
Your additional JavaScript codes should be write inside /assets/js/src/script.js. Again, if you need to split your code to several JS files, simply create them inside /js/src directory and require them inside the /js/src/page.js. Our Gulp task is watching all of the JS files inside /js/src directory and recompile page.min.js after each change using Webpack.
Step 5
Done with development? Run gulp dist to deploy your code inside /dist directory. This task simply remove unnecessary files (scss files, scss folder, unminified css and js files, etc.) in the /dist folder. Now you can use the /dist folder in your server side coding or upload to your web server.
What is the available gulp tasks?
Our Gulpfile includes the following commands and tasks:
| Task | Description |
gulp serve |
Running a server and start watching for change on html, scss and js files to compile and reload the browser |
gulp dist |
Create a /dist folder, compile scss and js files, and copy all the project's files inside the /dist directory except unnecessary ones |
gulp img |
Uses the imagemin plugin to minify the images inside /assets/img directory |
How to update to a new version?
Usually, you only need to update the following files and directories in assets/ folder for minor updates. If any extra changes were required, we'll write it in the changelog. For major releases (i.e. from 2.x to 3.x), you probably need to update your HTML code as well.
/fonts/php/plugin/thesaas
Sometimes, you might need to update some parts of the following files if we state it in the changelog description. We do our best to reduce these changes.
/scss/_theme.scss/scss/_page.scss/js/src/config.js/js/src/page.js
Please note that after updating the above files and directories, you need to run gulp dist to recompile the page.min.css and page.min.js once again and upload them to your server.
Also, time to time, we update the NPM packages and plugins. So it's a good practice to update your package.json and gulpfile.js regularly (even better with each update) and run npm install once again to make sure all the npm packages are up to date.
How to add a 3rd-party plugin?
If the plugin has CDN and you're willing to use it, simply include the plugin into your HTML pages by adding css and js files of the plugin from CDN. If you want to host the plugin on your own server, put the plugin inside /assets/plugin and import it into your HTML pages.
To configure and initialize the plugin, write the required JS code inside /assets/js/src/script.js file with the help of the plugin's documentation.
How to remove some vendors to decrease CSS and JS files size?
Please take a look at /assets/js/src/page.js and /assets/scss/page.scss files. Both of them have a Vendors section which is responsible for importing vendors' assets. Simply comment the import line that you'd like to remove the vendor from final CSS or JS file.