Templating

Under construction

With the introduction of the new theming system in LimeSurvey 3.x (planned: July, 2017), the process of templating and creating subtemplates for your surveys has become easier.

This guide functions now (june 2017) as a starter for people trying to understand & explain the system of creating templates in LimeSurvey 3.x. It does not apply to previous versions of LimeSurvey.

What is templating?

Templating is adapting the way your surveys are presented to the respondent. Each survey refers to a template, which holds files that influence the visual appearance of your survey, as well as some aspects of the behaviour of the survey. For example: in a template the font and colors of your survey are defined, as well as the position of elements on the page.

Templating methods

There are three ways for creating a new template:

1. Copy & Adjust: copy a template that works to your /uploads/themes directory and adjust what you want to be different.
2. Build from scratch: build your own template from zero. Sometimes people begin with Copy & Adjust, but they end up building a new template from scratch. Or the other way around.
3. Subtemplating: start with a good working template and override in a subtemplate everything that you want to be different from the "mother" template

And next to all these above methods, there is now also a way of templating individual questions, using the question-templating method.

Copy & Adjust

This is the "classical" way: this was already possible in previous versions of LimeSurvey. This is the easiest for people that only want to change small things in the survey (colors, margins, paddings) and for people that do not have ftp-access to their LimeSurvey installation.

Two ways:

1. Using the template editor For very small changes and for people that do not have ftp-access to their LimeSurvey installation.

2. Uploading via ftp Easier for larger changes, but you need ftp-access to the uploads/templates directory.

Tip

You can mix methods here: for example you can use the template editor to download a template and then install it in a local installation of LimeSurvey where you can experiment with it and adjust it to your needs. Afterwards you can choose to upload it via FTP or to zip it and upload the zip-file through the template editor.

Typical way of working

1. copy the template and give it a new name. For example copy "default" to "my-template".
2. adjust what you want in "my-template"
3. test this on the survey(s) that will refer to "my-template"
4. make online available
5. refer to "my-template" from the surveys that need the changes that are in "my-template"

Build from scratch

This has always been possible, but with the completely rewritten base templates and the new Twig-engine for templating, this will be much easier.

Typical way of working

1. learn from the best templates that you can find
2. use other's code where possible and appropriate
3. write .css, .js and .twig files
4. test & tune
5. and hopefully: make available for the community

Subtemplating

This is a new way of working, introduced in LimeSurvey 3.0: in this method you create a subtemplate that refers to a "mother"-template. You only specify what needs to be different, for the rest all specifications from the mother template are used. This opens up several possibilities (and risks):

• when you use a core template as the mother-template and LimeSurvey updates the core template, this update will also affect your sub-template, except where you have overridden features.
• you can create a subtemplate with very little specification, thereby making this a quick process.
• you can also make sub-subtemplate, whereby you extend a subtemplate. Question for LouisGac: is there a limit to levels of sub-templating?

The way to invoke the subtemplating feature is adapting the config.xml file of your sub-template. For example the following statements are in the config.xml of the ubuntu_orange template, which is a sub-template (it "extends") of default. Question for LouisGac: will this stay like this? That ubuntu_orange is a sub_template of default?

<config>
   <metadatas>
       <name>Ubuntu Orange</name>
       <extends>default</extends>
       ----
       ----
   </metadatas>

Question for LouisGac: will sub-templating also be possible via the template editor or will the developer have to use FTP?

Typical way of working

1. determine which template of the core templates or the custom template is closest to what you want and/or which is the best to use as the basis for your template
2. extend by configuring the config.xml: include/exclude files from the mother template, adapt .twig-, .css- and/or .js-files.
3. test thoroughly

Advantages of subtemplating

• when a mother template (the template that you are referring to) is a core LimeSurvey template, and this core template changes, these changes will also become visible in your sub-template. Unless you have overridden this aspect of the mother template. This may both be an advantage as well as a disadvantage. At each update of the LimeSurvey package, in the relase notes, there will be a note what aspects of the core template have been changed.
• you can make easy subtemplates, only changing a few things, like colors, fonts, and still have all the advantages of the mother template.

Disadvantages of subtemplating

• you have to track what is happening in the mother template (when it is a template that was supplied by LimeSurvey), to see what the impact is on your template.
• you might think that making sub's of sub's can go on for ever, but take care: performance will go down. The best performance will always be to work with mother templates only. (@LouisGac: is this true? It is my assumption..)

Question templating

Hopefully LouisGac can shine his light on this paragraph as a starter....

Template structure

The name of the template as shown in your template list dropdown is the name of the folder/directory the templates files are in.

Your LimeSurvey installation always has at least one core template, which is called default. See picture above. This default template is derived from the Flatly theme of bootswatch. This is the fall back template, for example for when you load a survey from someone else and that template refers to a custom template that is not available in your installation.

Core templates are in: /templates (please note: there is also a map called /themes, but this one holds admin-themes, the themes that are used to render the administration pages of LimeSurvey). Your own custom templates (independent of the way that they are created) will be placed in /upload/templates

In the root directory of your template (for example: /templates/default) you will find the file config.xml. This file defines what your template will using for rendering your survey pages.

You might think that all .twig-, .css- and .js-files reside in your template, but that is not true. Even if you template contains none of these files, LS will supply the following files from core:

Plugins may also serve their own css, javascript or even package.