• Template development
  • For Developers

    • Template development

    In this article:

      Attention  This section is aimed at people with experience in coding (webdevelopers and designers). If you're looking for articles about setting up the shop, design etc. have a look here.

      Before embarking on the development of a template, you need a basic understanding of the fundamentals of building templates and the structure of the system. These guides cover the basics:

      System files

      1. meta.json

      The most important file in the template is meta.json. Without meta.json, the template cannot be read. Therefore, meta.json is also the only file that is always located locally in the template and not on the server. The file meta.json contains the most important information about your template, such as name, description, and developer information. But meta.json also lets the system know whether the template is a parent or a child template. This happens via the PARENT parameter. Below, the PARENT parameter for template002, that is a child template of template001 (Rooty), is shown:

      "PARENT": "template001"

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

      2. source/settings/settings.json

      The file settings.json defines which input options should be available in the Customize design section. This means that you can use this file to determine which options the user has in the Design Manager. The file is a JSON file and needs to adhere to that format. Our advice is to start with the existing files and work from there.

      The file is structured as follows:

      • The parameter setting under which it is available in the system is SETTINGS
        • In Smarty: In $template.settings.SETTINGS_NAVN.
        • In SCSS (if TO_SCSS is set to TRUE) with _ replaced by -
           
      • 4 types of SETTINGS are available:
        • DROPDOWN: Dropdown with options in OPTIONS
        • COLOR_PICKER: A color picker
        • TEXT: A regular field for text input
        • IMAGE_PICKER: An image picker (file selector)


      Example of a design setting in settings.json:

      "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" }

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

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

      Access to settings via Smarty in the tpl files:

      {$page.headline}

      3. source/settings/settings_values.json

      The file settings_values.json belongs with settings.json and are the values from Customize. settings_values.json is generated by the system and is used to save the settings for Customize.

      4. source/scss/template.theme.scss

      The file template.theme.scss is one of the many Sass files that the system's templates consist of. However, it's the only one that doesn't compile locally and upload. The file template.theme.scss is compiled on the server by the system each time the user presses "Save" in Customize design. Sass is a precompiler for CSS that you can learn more about on their website sass-lang.com.

      The file template.theme.scss is, along with settings_values.json, the files the system uses when compiling assets/css/theme.css. To compile the file, the shop system uses the PHP library scssphp, a simple PHP version of Sass. The file consists primarily of Sass partials that is located in source/scss/theme/, but the file also contains a few global mixins. The file primarily contains color values to make the compilation as simple as possible.

      Note for developers already familiar with Sass: It is not possible to use Compass in template.theme.scss, as scssphp CAN'T compile Compass. If you need Compass, we suggest doing it in Sass files that you compile locally. In our case, this is source/scss/template.structure.scss.

      When developing a template, you can use source/scss/template.theme.scss to access the colors from Customize design. As mentioned in the section about settings.json, the settings that are set up here will be accessible intemplate.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 is compiled each time the "Save" button is pressed in Customize design and the file is deleted and overwritten by a new file.

      The file theme.css is a regular CSS file that can be viewed in Edit files. If you choose to edit the file, be aware that all settings will be lost as soon as "Save" is pressed in Customize design.

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

      Files containing custom language variables are placed here. The files should be named after the language layers available on the solution. Eg. dk.json. The contents of the file looks like this:

      {    "MY_OWN_TRANSLATION": {        "value": "View offer here!"    },    "MY_OTHER_TRANSLATION": {        "value": "See more offers here!"    } }

      Edit template

      If you want to make changes to an existing template, we suggest that you create a new file. In the dandomain webshop system, we have three types of files in our templates: CSS, Javascript and Smarty template files. All files can be accessed in two ways, either through the Design Manager or via FTP. See how to set up FTP access here: FTP access for developers. As new feature, you can now - through the new Design Manager - add or remove references to CSS or Javascript files from a template, so you can decide which assets you want to load or not load. Would you for example like to design a new way to display variants, or overwrite an already existing variant display, you now have the option to do this by removing the reference to the files.

      You have the option to overwrite a file in the Design Manager. The system is built to look for assets locally in the template folder first before it looks for files on the system server. This means that files added with addScript or addLink are firstly searched for locally in the template folder. Afterwards the system looks in the system folders. Local files is displayed with a (c) in Edit files.

      Create CSS file

      Do you need to edit or make changes in the CSS on a template, we suggest that you create a new CSS file in the folder assets/css and add your modifications to the CSS here. Right now, the easiest way to do this is via the FTP.

      When you have added the CSS file in the folder, you need to reference it. This is done via the Smarty feature we have made available called addLink. addLink makes it possible to add CSS files from all tpl files, but we suggest that you generally do it in index.tpl, as it makes it easier to keep track of all your references. See below how this can be done:

      {*** Example of CSS template CSS ***} {addLink href='assets/css/custom.css'} {*** Example of global CSS file ***} {addLink href='//eksempel.com/style.css' relative='true'}

      Create tpl file

      A Smarty template (*.tpl) file, works the same as CSS and Javascript files in many ways, where the files can be edited via Edit files or via FTP. However, unlike the CSS and Javascript files, we suggest that instead of creating new files each time, you should only create files if you want to add a new function. It could be a new partial, for example a secondary header, a sidebar, or something else entirely.

      To access and edit a Smarty template file through FTP, it may need to be saved in Edit files, so that the file gets a (c) showing that the file is a local template file that has been customized.

      If you want to create a Smarty template file, you currently need to do so via FTP. Where the file is created depends on the context in which you plan to use it. To create a new partial for a module we suggest that you create it in the corresponding folder for that module. If you want to add e.g. a new partial for Products, we suggest that you add it to modules/products/partials. Do you want to create a general partial for the template, e.g. an extension for the header, we suggest that you place it in the partials folder in the root of the template.

      Including templates is done with Smarty's include function where you also have the option to include additional parameters. The parameters can be accessed in the folder as a variable: $parameter. In the examples below, you can see how it can be done:

      {*** Example of inclusion of file in the same folder ***} {include file='eksempel.tpl'} {*** Example of inclusion of file in a different folder ***} {include file='mappe/eksempel.tpl'} {*** Example of inclusion of file and parameters ***} {include file='mappe/eksempel.tpl' parameter1='1' parameter2='2'}

      Build/compile template files locally

      With the new Design Manager, we have chosen to make all files available to you as a developer. We've done this to make it possible for you to build exactly the template you want. Besides the files that make up the template, we have also decided to make all source-files for Javascript and Sass available. This makes it possible to change part of the files instead of having to overwrite or remove existing functionality with other files. When we compile and build CSS and Javascript files from the source files, we use Sass to create CSS, and Grunt to minify and concatinate many Javascript files into one minified file.

      To make it possible for you as a developer to do the same, we have included two project files with all templates. In our case this is:

      • package.js
      • Gruntfile.js -

      With these project files and the right developers' tools, you can build all template files locally from the source files and upload these to your template via FTP. Below, you can read more about what the files are used for.
      Note:
      All files in modules/*/assets/js is compiled into app.js.
      All files in modules/*/includes are used locally by the module, e.g. checkout.js is included by checkout-order.tpl, because that way we can more easily update this file separately from the other files.

      Package.js

      Is a project file for Node.js. Node.js is Javascript on the serverside. In order to be able to compile and build the files, you need to use Grunt. Grunt is built on Node.js, so Node.js needs to be installed in order to build locally. Node.js can be downloaded and installed from their website nodejs.org. After installing Node.js, you can write the below code in the folder where you have the files and source-files located in the console, and all Node.js dependencies will be installed:

      $ npm install

      Gruntfile.js

      The gruntfile is the project file itself. The file is a task file for Grunt (a build tool for Node.js). Grunt needs to be installed along with the other Node.js dependencies, because the programme needs to be located globally and should be run from the console. Grunt is installed with npm after you have installed Node.js by typing the below: 

      $ npm install -g grunt-cli

      After installing Grunt, you can now use the Gruntfile. You do this by navigating to the folder with the developers' and source files in the console. With our Gruntfile, we have created two tasks that you can name:

      $ grunt watch

      Grunt watch monitors all the source files (both Javascript and CSS) and looks for changes, and when a change occurs it rebuilds or compiles the files. The files are built for assets/js and assets/css. The files will not be minified and will contain all comments. The watch task is ideal to use while developing, and you still need to debug and locate errors, as the files are not minified. The task will keep running until you close the terminal or console, or until you press CTRL+C to disconnect it.

      $ grunt build

      Grunt build runs the same tasks as Grunt watch, but runs them only once. All files will be minified and all unnecessary comments will be removed. For Javascript files it is also true that all console.log calls are removed, so they don't cause problems for browsers that do not support console.log. The task is used to finish building the files into completed production files. When your project is finished and everything has been tested, you run Grunt build and all your files will end up in the assets/folder as minified and optimized files.

      If you would like learn more about Grunt, their website has a guide.