# Skeleton Template

With Kooomo’s Skeleton template, everything is done on your local machine, which is synched automatically to a Kooomo server using kooomator.

Developers have a local copy of their template, and using NPM, we are able to compile Handlebars, Javascript and CSS files. This gives us a freedom to restructure the files per project as we please and introduce new frontend technologies without any server side change required.

# Structure Overview

The template folder is structured as follows:

• css: contains code for styling your website. Kooomo uses SASS as a CSS pre-processor. Also any specific font files you might want to use

• handlebars: contains template files for front-end interactions through AJAX

• js: contains all the Javascript required to run your website

• images: for storing any images, icons etc.

• media: for storing any other media content like videos

• node_modules: stores all the NPM code for working with Skeleton and kooomator

• tpl: contains the individual HTML template files

  • these are written in Smarty4, a PHP-based templating engine

::: tip

In the following documentation, where we refer to ‘manager', that references the current sub-folder you’re in for the tpl folder, which also references a section of the website a developer can work on. For example, account, cart category etc. are all managers, where you would have e.g. www.beautifulstore.com/eshop/account. The phrase comes from the structure in the backend.

:::

# Editing the Files & “Fallback” Mechanism

In most of the templates root folders (css, js, handlebars, tpl) you’ll see base and custom sub-folders. The base folders contain all the code to get you started off. These base folders shouldn’t be touched, as they will be overwritten any time you run kooomator update. If you want to modify anything, you generally copy the file from base into an equivalent sub-folder in custom, then the system will use your file in custom rather than the version in base. Any files missing from the custom folders will always “fall back” to the equivalent file in base.

For example, let’s say we’re working on the account manager, so we have base/account/index.tpl and I want to customise it:

• Copy the file to custom/account/index.tpl
• Modify this new file
• Observe your changes being loaded

When you run kooomator update, the custom folders won’t be touched, but you’ll get updated versions in your base folders. If you use git or another VCS, you’ll easily be able to see what has changed.

Each of the css, js, handlebars, tpl folders handle the fallback slightly differently, and more detail is given in the relevant sections of this documentation, as well as in the README.md file contained within each folder.

# Compilation

As is standard practice in web development, Kooomo enables its users to “compile” it's static frontend assets into a single file. This process is managed through NPM and the package.json file in the template root. In this file you can find different scripts which you can run:

1. npm run compile Compiles JS, Handlebars and CSS
2. npm run watch Compiles and starts to watch for files changes to recompile JS, Handlebars and CSS as the files are updated
3. npm run js Compiles only JS and Handlebars
4. npm run css Compiles only CSS
5. npm run lint Checks code style of Javascript and CSS

Compiled files will end up in a related compiled subfolder and shouldn’t be touched.

# Structure Detail

# Template Files (tpl)

All the templates are written using Smarty V4 and they use .tpl format

You can find the templates under the tpl folder. index.tpl is usually the default action on website any other template can be included using {include} or is loaded during different actions.

# Customisation

Inside the tpl folder there are 2 main folders:

• base it contains the default templates. Do not edit those templates
• custom it contains the template customisations.

Each of these is further divided into subfolders based on the various managers.

If you want to edit one of the base templates, just copy the file from the base folder into the custom folder, respecting the subfolders.

Therefore if you want to edit tpl/base/account/index.tpl you will need to copy it into tpl/custom/account/index.tpl and edit from there. Smarty will then load the custom file, not the base. The system will automatically load the customisation files if they exists, otherwise it will fallback to the files in the base folder.

::: warning

Do not edit the files on the tpl/base folder.
The base folder can be updated with the newest version using npx kooomator update therefore the files on the base folder are going to be replaced everytime run the update, and the changes will be lost.

:::

# Javascript (js)

We have structured the Javascript files into folders related to the current manager that we are visiting; this allows us to load separate Javascript files per manager. In this way we can reduce the amount of Javascript and handlebars templates that we need to load and parse per request. For example, the JS files in js/base/account and js/custom/account will only be included on pages that manage a customer’s online account.

As mentioned previously, we have 2 main folders on the js folder: base and custom.

• Under base we have all the default Javascript libraries that are shipped with the Skeleton template. You should not edit the files in these subfolders.
• Under custom you will find same structure, and inside each folder there is an index.js file. This index.js files links to the files in the base folder and they will be used to compile when running the compile or watch command.

Read on for details on how to compile and customise your JS.

Example:
When visiting the /eshop/account/ we are using the manager account therefore we are going to load the Javascript files that are linked on js/custom/account/index.js

``

# Compilation

To compile we use a module bundler called Rollup

• When running the command npm run js we are going to trigger a Javascript compilation

• Rollup loads the configuration from the rollup.config.js on the root of the template

• The configuration goes through the js folder and looks for any file called index.js inside all the manager folders

• The index.js files contain import to other files and rollup bundle them into separate files inside the js/compiled folder.

• Rollup also creates a manifest.json JSON file containing a key value object with the modules and the files with a unique version id. This manifest is then loaded by the template to understand that the files have changed and the browser needs to reload them.

• The platform will then load 3 Javascript files

  • core-pre.js?v=xxxxx scripts that needs to be loaded always before the manager’s scripts
  • {currentManager}.js?v=xxxxx manager specific scripts
  • core-post.js?v=xxxxx scripts that need to be loaded always after the manager’s scripts

In this way, using the folders per manager and the index.js we are able to split and load specific Javascript only for a specific manager and use core-pre and core-post to load Javascript that needs to be loaded on all pages.

# Customisation

If you need to customise or add a new change to your website, you should add your files in the custom folder. You should never edit the base folder. The base folder can be updated with the newest version, therefore the files on the folder are going to be replaced every time you update them and the changes will be lost.

Just create a new file on the proper custom folder and link it in the index.js file.

For example, to customise js/base/cart/2900-zg-subscription.js:

1. Copy the file to js/custom/cart/2900-zg-subscription.js

2. Modify it as you wish

3. Update js/custom/cart/index.js

   1. Since this file only contains an import to js/base/cart/base.js, we need to replace the contents of the index.js with those of the base.js, then modify the import for 2900-zg-subscription to come from the custom folder, instead of the base
   2. i.e. import 'js/custom/cart/2900-zg-subscription.js'

# Loading asset files within a template (.tpl) file

• To load the assets simply use the Smarty function:
  {asset type='js' return_cdn=1}

  • This will generate a HTML <script> tag to load the compiled file for your current manager and should already be present in any relevant template base files

• Custom xxx.js
{asset type='js' return_cdn=1 manager=xxx}

  • This will generate a HTML <script> tag to load the compiled JS for the xxx manager. For example,. if for some reason you wanted to include the compiled cart JS on the checkout page, you could do {asset type='js' return_cdn=1 manager=cart}

# Handlebars (handlebars)

Handlebars is structured in a similar way than Javascript. But in this case we are not limited to only folders with the manager’s name, and we are free to set any name that we want.

# Compile

As with Javascript, Handlebars is compiled using a custom Rollup plugin.

We only need to add the proper .handlebars file in an import inside the index.js in the manager's (custom) Javascript folder and Rollup will compile the file and add it into the manager's Javascript file.

# CSS (css)

CSS is free to be structured as you please using SCSS @import in the main.scss

I added an extra feature to load multiple CSS files with Smarty

# Compile

• Run npm run css, this will start the CSS compilation process (compilation, minify and manifest).
• A manifest.json is created using a custom node package. You can find the source code on our private repo. Check Javascript compilation to understand what is the manifest for.

# Loading assets

• To load the default main.scss asset (includes all styles):
  {asset type='css' return_cdn=1}
• Similar to JS, If you want to add another CSS xxx.scss
{asset type='css' return_cdn=1 manager=xxx}