SOW : Introduction
SOW = Step Of Web
www.stepofweb.com
1. Smarty Core
src/js/sow_core/sow.js
Everything related to javascript is starting with this single file! Is just an object! Just one! But this is the root of all evil goodness!
At the very end of this page you can find the structure! Core sructure where everything is happening inside Smarty!
Despite the fact than right now, Smarty Core has over 25 plugins written from scratch, is incredibily lightweight: under 130Kb minified, all plugins together. 223Kb including jQuery! ~60Kb gzipped!
Smarty is working like a framework. All core plugins (SOW) are linked together, so all of them are working together. You can remove any plugin but is highly recommended to keep the most used ones: toast, bootstrap validation, dropdowns + deep navigation (required by header main navigation), scroll to, button toggle. Of course, because the total size is so small, you can keep all of them! Vendors are the only issue BUT solved by Smarty in an elegant way. Picture this: only, and only datatable PDF export function is using a plugin that is OVER 1Mb in size, MINIFIED! Can you imagine? 10 times larger than entire Smarty Core and is just one single little option! So how Smarty solved these kind of issues without you writing a single line of javascript code?
Each plugin is described in this documentation in this format/order:
1. Short plugin description / vendor link, if available
2. How the plugin is installed (vendors mostly)
3. How the plugin is loaded/initialized + showing the default config/settings so you can change the defaults later, if needed
4. HTML attributes and examples of how you can use the plugin! – this is what you really need!
Because Smarty is now using GULP and you are able to bundle only some vendors in a single JS file (most lightweight/most used), the so supposed "GULP - a single easy script file that automates SCSS/JS" becomes a framework because things got too complicated (not for you, for me, the author). Don't worry, you just type a single word: gulp and Voila! All CSS/JS are compiled for you/your project!
So Smarty has 2 config files used by GULP to build the project:
A. SOW Core Plugins:
gulp.config__core.jsB. Vendors Plugins:
gulp.config__vendors.jsNothing is mixed, everything is well separated and organized, like this documentation is - plugins are very well separated!
From these two config files used by GULP, each plugin can be enabled or disabled! You might don't want all plugins so you can simply disable and will completely be excluded, including the controller for that specific plugin.
Another option you'll see in both config files is to bundle Vendors in a single large JS file (which is not recommended, unless is the end of the world). If are not bundled (as you already figured out), Smarty will load them in a dynamic way, only when/if needed! And you don't need to do a thing! You can simply forget about - just use the examples with copy paste and Smarty will handle everything!
In the end, GULP will compile all you need but there are only 4 important JS files included in each HTML (all other files must stay where they are - each one of them in its CSS/JS folder):
1. core.min.js
2. core.min.css
3. vendor_bundle.js
4. vendor_bundle.css
This is how all your HTML files should looks like (all demos already are like this):
1. CSS Files – Inside <head>:
<link rel="stylesheet" href="assets/css/core.min.css">
<link rel="stylesheet" href="assets/css/vendor_bundle.min.css">
2. JS Files – At the bottom of page, just before </body>:
<script src="assets/js/core.min.js"></script>
<script src="assets/js/vendor_bundle.min.js"></script>
vendor_bundle.min.js and vendor_bundle.min.css contains the most used vendors packed together - like bootstrap javascript, AOS, etc.
Please note: there is no absolute requirement to include vendor_bundle.min.js (only the css)!
Smarty Core (core.min.js) will load it dinamically before starting to init anything else! You don't need to do anything!
The page render/paint speed will be a bit better but all vendor functionalities are starting after the file is loaded and initialized (example: swiper slider).
You can play and do tests (simply by removing/adding it to html).
If your project is simple, there might be a noticeable difference - depends on many, many factors - so you can test - what can be easier than removing and adding back a single HTML line, isn't it? :)
So please remember, only these 4 mentioned files (2css + 2js) are included in each HTML page!
All other files are not! Not a single one! Only and only the green ones above!
All other aditional files compiled by GULP (js and css), are loaded by Smarty in a dynamic way, only if/when needed!
Looks complicated but actually is very-very simple, isn't it?
You do not have to deal with any javascript code, if is not said to (which is rare)! You can, if you want to (that's why is there, of course) but you can also 100% ignore it!
To understand better, let's take the GDPR plugin as example. In the image below (click it to enlarge) you see:
1. plugin source file location - used by GULP only
2. Basic initialization of this plugin (all of them are similar, as you will see)
3. How the plugin is used - the default params passed to init function, you can change (if you want/need to) in gulp.config__core.js before compiling the project!
So anything below this kind of introduction (some are a lot longer, explained in detail but basically same thing) are the examples ready to copy/paste into your own HTML file! Smarty is based on ready to use, just copy/paste!
Wait, there is more! You don't even need to edit any JS/GULP files to change the defaults! Most controllers are build in such way so you can pass the variables using HTML Attributes. Like: data-cookie-name="rocketMan"
2. Vendors
Vendors are actually plugins, but we call them "vendors" because are third party files, and are not part of Smarty Core. Each vendor has it's own controller written from scratch for Smarty - that's why there is no need for 95% of plugins to write a single line of javascript code. Everything works in seconds!
Vendor controllers are working like this:
1. Check if there is a need for the plugin on that specific page
2. If the plugin is needed, load it! Load also the CSS if there is any asociated with the plugin!
3. Initialize the plugin!
4. Done!
Did you catch the trick? Instead of loading over 5Mb of vendor javascript files, is loaded only and only the vendor is needed for that specific page! Is like you add manually on each page, only the javascript you need! So that's why Smarty is fast and lightweight! Oh, and unique - no other template in any marketplace has this feature (not yet, but is never too late ).
Smarty has many plugins you can use but of course, you might want to add a new plugin.
You can do it in 2 ways:
1. Creating a Smarty Controller for that plugin - there is a boilerplate or you can inspire from all others.
2. Using it like you always did. That was easy, isn't it?
Smarty is adding new features on each update but any feature request is more than welcome! Oh, not only requests, also suggestions and/or bad things are welcome! We all know that there is no such thing "perfect" but I am willing to fix and improve my work!
Down below is the Smarty Core Structure I promised in the beggining.
Smarty is sold only and only on wrapbootstrap! Thank you for reading this!
/**
src/js/sow_core/sow.js
**/
;(function ($) {
'use strict';
$.SOW = {
/**
*
* @init
*
*
**/
init: function () {}
/**
*
* @globals
* SOW Config
*
**/
globals: {
direction : $('body').css('direction'), /* rtl | ltr */
width : $(window).width(), /* window width, updated on resize */
height : $(window).height(), /* window height, updated on resize */
is_modern_browser : ('querySelector' in document && 'localStorage' in window && 'addEventListener' in window), /* `true` if modern */
is_mobile : ($(window).width() < 993) ? true : false,
is_admin : $('body').hasClass('layout-admin') ? true : false,
}
/**
*
* @core
* SOW Core Plugins
*
**/
core: {},
/**
*
* @vendor
* Vendor Plugins [separated by SOW]
*
**/
vendor: {},
/**
*
* @helper
* SOW Helpers
*
**/
helper: {},
/**
*
* @custom
* My Custom [optional]
*
**/
custom: {},
/**
*
* @reinit
* Ajax Callable
*
**/
reinit: function(ajax_container) {}
/**
*
* Init this
*
*
**/
$.SOW.init();
})(jQuery);
/*
Globals you can get
if you need in your js code
*/
@globals
$.SOW.globals.direction 'ltr|rtl'
$.SOW.globals.width actual width (updated on resize)
$.SOW.globals.height actual height (updated on resize)
$.SOW.globals.is_mobile true|false
$.SOW.globals.is_modern_browser true if modern
$.SOW.globals.is_admin true|false (admin layout)
$.SOW.globals.breakpoints.[sm|ms|lg|xl] bootstrap default breakpoints
$.SOW.globals.elBody body element
$.SOW.globals.elHeader header element
$.SOW.globals.elAside main sidebar element
@functions
$.SOW.reinit('#container') reinit plugins for a specific ajax container; see also:
/**
HELPERS YOU CAN USE IN YOUR JS CODE
src/js/sow_core/helpers.js
Please do not modify them, SOW plugins are using them!
**/
@loadScript
$.SOW.helper.loadScript(script_arr, async[true|false], cache[true|false]).done(function() {
// all scripts loaded... do something
// * async = false by default (scripts are loaded in order)
// * cache = true by default
});
*
@loadCSS
$.SOW.helper.loadCSS("/path/to/file.css", "append|prepend|remove"); "append" is default, if no option passed
*
@loadingSpinner
$.SOW.helper.loadingSpinner('show|hide', "#mycontainer", 'overlay|icon');
*
@overlay
$.SOW.helper.overlay('show|hide|toggle');
*
@randomStr
$.SOW.helper.randomStr(8, 'empty|L|N');
*
@byte2size
$.SOW.helper.byte2size(bytes, precision=2, int_only=false);
$.SOW.helper.byte2kb(bytes);
*
@scrollAnimate
$.SOW.helper.scrollAnimate(_el, _offset, _hash_change, _speed);
_el = element to scroll to. #top = page top
_offset = top offset (0 default)
_hash_change = update url hash on click
_speed = scroll speed (400 default)
$.SOW.helper.scrollAnimate('#top', 0, false, 400);
*
@removeUrlHash
$.SOW.helper.removeUrlHash('https://domain.com/url#hash');
*
@playSound
$.SOW.helper.playSound('path/to/audio.mp3');
*
@time_from_ms
$.SOW.helper.time_from_ms(miliseconds, 's|m|h|d|empty for all');
*
@get_browser (unfinished, need improvement, do not use)
$.SOW.helper.get_browser();
*
@params_parse
var params = $.SOW.helper.params_parse(params_from_post); // return: array
var ajax_params_arr = $.SOW.helper.params_parse(ajax_params);
for (var i = 0; i < ajax_params_arr.length; ++i) {
formDataDel.append(ajax_params_arr[i][0], ajax_params_arr[i][1]);
}
*
@indexedDB (local database)
$.SOW.helper.indexedDB(.. see function ..);
*
@currencyFormat
$.SOW.helper.currencyFormat(1000000); // output: 1,234,567.89
// 1,234,567.89
$.SOW.helper.currencyFormat(1000000, [
2, ',', '.' // en
// 2, '.', ',' // de
// 2, ' ', ',' // fr
]);
*
@consoleLog (output - only if debug is enabled!)
$.SOW.helper.consoleLog('Lorem Ipsum', 'color: #ff0000;');
<!-- Classic Smarty Preloader
Smarty Reborn is not using it anymore but you can, if you want to ;)
-->
<!-- preloader -->
<div id="page_preload" class="d-middle fixed-full z-index-9999 bg-white">
<span class="p-3 shadow-xs rounded">
<i class="fi fi-circle-spin fi-spin text-muted float-start"></i>
loading...
</span>
</div>
<!-- /preloader -->