Before you begin development of a template, it is important that you have an understanding of these fundemental issues dealing with templates and the structure of the system:

• Smarty Guide 3.1 - An introduction to smarty parameters.
• Template Structure 3.4 - Walkthrough of template building and structure.

 

System Files

SmartWeb saves a line of system files, via the "Edit Design" function in the administration. This function is used to edit the colors, font and language variables and stores these choices in the customers template folder.

There you will find 6 important files for "Edit Design", These files are:

1. meta.json
2. source/settings/settings.json
3. source/settings/settings_values.json
4. source/scss/template.theme.scss
5. assets/css/theme.css
6. source/settings/language/*.json (dk.json etc.)

 

1. meta.json

The most important file for the template is meta.json. Without meta.json the template cannot load. Therefore meta.json is the only file that must always be local in the template and not on the server. The meta.json file contains the most important information about your template, such as: name, description and developer information. It also tells the system if the template is a parent or child. this is done through the PARENT parameter. Below you can see the PARENT Parameter for template002 (Palette), it is a child template of themplate001 (Rooty).

*CODE* *SNIPPIT* "PARENT": "template001"*CODE*

Template001 is a PARENT template and therefore has no PARENT defined.

 

2. source/settings/settings.json

The file settings.json is the file that determines, which input options Edit Design has access to. This means that with this file you can determine what the user has access to in the Design Manager. The file is a JSON file and therefore must follow this format. Our best advice is to take the starting points in the existing files and to work from them.

The files have the following structure:

• Structure is the name of the parameter that is available under the system:

• • In Smarty under $template.settings.SETTINGS_NAVN.
• • In SCSS (If TO_SCSS is set to TRUE) with _ written about the -

• There are 4 types of SETTINGS:

• • DROPDOWN: Dropdown med choices in OPTIONS

• - COLOR_PICKER: A color picker

• - TEXT: A normal text input field

• - IMAGE_PICKER: An image picker (File Selector)

 

Example of Design Settings in settings.json:

*CODE*
*SNIPPIT*"FONT_COLOR_HEADLINE":{
    "TYPE" : "COLOR_PICKER",
    "TITLE" : {
        "DK" : "Overskrift tekst farve",
        "UK" : "Headline text color",
        "SE" : "Textfärg, överskrift",
        "NO" : "Skriftfarge, overskrift"
    },
    "TO_SCSS" : "TRUE"
}
*CODE*

 

Access to setting via SCSS in source/scss/template.theme.scss:

*CODE*
*SNIPPIT*.header h1 {
    color: $font-color-headline;
    font: 2em/1 sans-serif;
}
*CODE*

Access to setting via Smarty in .tpl file:

*CODE*
*SNIPPIT*

    

{$page.headline}

*CODE*

3. source/settings/settings_values.json

The file settings_values.json belongs with settings.json and the values from Edit Design.

settings_value.json is generated and used by the system to save settings to Edit Design.

 

4. source/scss/template.theme.scss

The file template.theme.scss is one of the many Sass files that SmartWeb consists of. However it is the only file that is not compiled locally and uploaded. The file template.theme.scss will actually be compiled on the server-side of the system, every time a userpresses save i Edit Design. If you do not know Sass is a precompiler for CSS that you can read about on their website (sass-lang.com).

The file template.theme.scss together with settings_values.json are files that the system uses as a starting point when it should compile assets/css/theme.css. To compile files SmartWeb uses the PHP library scssphp, a simple PHP version of Sass. The file consists primarily of Sass partials, that are situated in source/scss/theme/, but also contains some of the global mixins. The files contain primarily color values, to make the compilation as simple as possible.

Note for developers that already know SASS: It is not possible to use Compass in template.theme.scss, because scssphp can’t compile Compass. If you need to use Compass, please do so in the Sass files that you compile locally. In our case that is source/scss/template.structure.scss.

When you develop a template, you can use source/scss/template.theme.scss to access colors from Edit Design. As mentioned in connection with settings.json the settings that are set here, will be available in template.theme.scss, if TO_SCSS is set to TRUE.

 

5. assets/css/theme.css

The file theme.css is the compiled result of source/scss/template.theme.scss. The file compiles every time when the "Save" in Edit Design is pressed, the file gets deleted and overwritten with a new file. The file theme.css is a normal CSS file that can be viewed in Edit Files. If you choose to edit a file you need to be aware that all changes will be lost when save is pressed in Edit Design.

 

6. source/settings/language/*.json (dk.json etc.)

The files that are placed here contain their own language variable. It is necessary to name files in accordance with the language layer contained within e.g. dk.json.

The contents of these files are as follows:

*CODE*
*SNIPPIT*
{
    "MY_OWN_TRANSLATION": {
        "value": "See offers here!"
    },
    "MY_OTHER_TRANSLATION": {
        "value": "See more offers here!"
    }
}
*CODE*

 

Edit Template

If you would like to change an existing template, we suggest you create a new file as a starting point. In SmartWeb we have 3 types of files in our templates; CSS, Javascript and Smarty template files. All files can be accessed in two ways, through the Design Manager or via FTP. To see how to access FTP under FTP Access for Developers. With the Design Manager you can create and delete references to CSS or Javascript files from a template, then you can decide which assets you would like to load or not. e.g. You will like to create a new variant view, or overwrite an exisiting variant view, you now have the possibility to do it, by removing references to the files.

You now have the possibility to overwrite a file in the Design Manager. The system is structured so it will look for local assets first in the template folder before looking to the server system to pick up the remaining assets. It will then look for files that are added with addScript or addLink in the local folder before looking in the server folder. You will notice that local files are marked with a © next to their filenames in Edit Files in the Design Manager.

 

Create a CSS File

If you are looking to edit or make changes to the CSS on a template, we suggest, that you open a new CSS file in the folder assets/css and add the CSS corrections here. Right now, it is easiest to do this via FTP.

When you have added the CSS file in the folder, you should insert a reference to this file. This is done via a Smarty function we have made available, called addLink. addlink makes it possible to add CSS files to the from all .tpl files, but as a starting point we suggest you add it to the index.tpl file, this way it is easier to manage all of your references. See the example below on how this can be done:

*CODE*
*SNIPPIT*{*** Example of a template CSS file ***}
{addLink href='assets/css/custom.css'}

{*** Example of a global CSS file ***}
{addLink href='//example.com/style.css' relative='true'}
*CODE*

Create a Javascript File

The things that apply to the CSS files, also appl to Javascript files. As a starting point, we suggest you make a new file and place upload it via FTP to assets/js/. After this, you can add the reference to the Javascript file using the addScript function to index.tpl. See the example below on how this can be done:

*CODE*
*SNIPPIT*{*** Example of a template Javascript file ***}
{addScript href='assets/js/script.js'}

{*** Example of a global Javascript file ***}
{addScript href='//code.jquery.com/jquery-2.1.1.min.js' relative='true'}
*CODE*

Create a Template File

A Smarty template (.tpl) file, in many ways functions like CSS or Javascript files, where you can edit files through *Edit Files or via FTP. Unlike CSS and Javascript files, we suggest, that instead of always creating new files as if it was a new feature. You should create these new files as partials, as a secondary header, a sidebar or someting else.

To get access to edit Smarty templates via FTP, we suggest that you edit the files in Edit Files, so the files have a © after its file name, this will show/save it as a local file that can be accessed via FTP.

If you would like to open a Smarty template file, you should now do it via FTP. How you create the file depends on the context you want to use it. To create a new partial to a module, we suggest that you open a folder in the module. e.g. If you want to open a new partial for the product module, it is our suggestion that you put it in modules/products/partials. If you will create a general partial for a template e.g. an expansion for the header. We suggest that you add it in the partials folderin the templates root folder.

When you include a template using Smarty’s include function, where you also have the option of attaching extra parameters. Parameters will be available in the folder as a variable: $ parameter. See the examples below for how to do it:

*CODE*
*SNIPPIT*{*** Example of include file in the same folder ***}
{include file='example.tpl'}

{*** Example of include file in another folder ***}
{include file='folder/example.tpl'}

{*** Example of include file and sending of parameter ***}
{include file='folder/example.tpl' parameter1='1' parameter2='2'}
*CODE*

Building/Compiling Template File Locally

With the Design Manager, we chose to allow developers full access to all files. We did this to allow you to create the exact template you want. In addition to the files that make up the template, we have also chosen to leave all source files for Javascript and Sass out. So it is possible for you to modify parts of files instead of removing or overwriting functionality with other files. When we compile and build CSS and Javascript files from the source we use Sass til create CSS and Grunt to minify and concatinate many Javascript files together into one minified file.

To make it possible for you to do it together, we have enclosed 3 project files in all templates. In our case they are:

• Gemfile
• package.js
• Gruntfile.js

With these project files and the correct development tools you can build all template files locally from source files and upload them to your template via FTP. Below you can read more about what files should be used.

Note:

• All files in modules/*/assets/js are compiles into app.js.
• All files in modules/*/includes are used locally of the module e.g. ckeckout.js is included in checkout-order.tpl, because it is easier to update this file separately from the other files.

 

Gemfile

Is a project file for Ruby and Bundler, it tells Bundler and Ruby which gems (Existing Libraries) we use in our project. Bundler makes sure that they are installed in their correct versions. If you do not have Ruby installed, you can find it on Ruby’s website. Bundler is a gem for Ruby and you can find more information about it on Bundler’s website. With Ruby and Bundler installed, in the folder where you have development and source files remain in the terminal or console and use the code below. This will install all Ruby dependencies for the project:

*CODE*
*SNIPPIT* $ bundle install
*CODE*

Package.js

This is a project file for Node.js. It works in many ways just like Gemfile, but instead of Ruby, it uses the Node.js file. Node.js, if you don’t know, is server-side Javascript, Just as you probably know PHP can now run Javascript server-side. To compile and build development files it is necessary to have Grunt and Grunt is built on Node.js, so it is important to have it installed so you can build files locally. Node.js can be downloaded and installed from their website nodejs.org. After you have installed Node.js, in the folder where you have development and source files remain in the terminal or console and use the code below. This will install all Node.js dependencies for the project:

*CODE*
*SNIPPIT* $ npm install
*CODE*

Gruntfile.js

Gruntfile.js is a project file that does all the hard work. The file is a task/assignment file for Grunt, it is a build tool for Node.js. Grunt should be installed along side of all other Node.js dependencies, because it is a program that needs to be global and should be run from the terminal or console. Grunt is installed with npm after you have installed Node.js, by using the code below:

*CODE*
*SNIPPIT* $ npm install -g grunt-cli
*CODE*

After you have installed Grunt, you can now use the Gruntfile.js. You do this in the terminal or console, you can then navigate to the folder with the development and source files. With our Gruntfile.js we have created 2 tasks that you can call:

*CODE*
*SNIPPIT* $ grunt watch
*CODE*

Grunt watch monitors all source files (both Javascript and CSS) and watches for changes, when changes are made they are combined or compiled into the files. Files are built into assets/js and assets/css. Files will not be minified and will containall comments. The watch task is ideal to use when you still need to develop, debug and troubleshoot unminified code. The task will be run until you close the terminal or console or until you press CTRL+C to cancel it.

*CODE*
*SNIPPIT* $ grunt build
*CODE*

Grunt build together with sub tasks like Grunt watch, but runs them only once and all files will be minified with all unnecessary comments will be removed. For Javascript files all console.log calls are removed, so it does not cause any problems for browsers that do not support console.log. The task builds all of the final production files. So when you are finished with your project, have tested everything, you should run Grunt build and all of your finished files will end up in the assets/ folder as minified and optimised files.

If you are interested in and would like to know more about Grunt, you can read their guide on their website.