Templating

Under construction

With the introduction of the new theming system in LimeSurvey 3.x (planned: July, 2017), the process of creating subthemes 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 themes.

Theming methods

There are three ways for creating a new theme:

1. Copy & Adjust: copy a theme that works to your /uploads/themes directory and adjust what you want to be different.
2. Subtheme: start with a good working theme and override in a subtheme everything that you want to be different from the "mother" theme
3. Build: build your own theme from zero

and next to all these methods, there is now also a way of theming individual questions, using the question-theming 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 theme 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.

But important: since small changes to your template can have big effects (sometimes unwanted) to all your surveys that refer to the changed template, it is advisable to download and work on a local installation or on an online development installation.

Subtheme

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

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

The way to invoke the subtheming 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.

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

Build

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

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. This is the fall back theme, for example 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.