LimeSurvey Manual - User contributions [en]

New Template System in LS3.x

2018-12-20T10:30:30Z

LouisGac: /* The manifest config.xml */

<languages />
<translate>

__TOC__
=Introduction= 


On this page you'll learn how to:


* Use the new theme system of LimeSurvey 3.0.
* Use inheritance to manage your own themes.
* Add a picture to your theme
* Manage theme options for your surveys and survey groups


<hr/>


LimeSurvey 3 introduces a complete new theme engine system, based on Twig 1.29, Bootstrap, and allowing theme inheritance and theme options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old theme system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A theme designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new theme engine.


<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Theme Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface= 
==theme list==
On the admin dashboard, there is now a box to access the theme list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The theme list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the theme: it’s just a picture file called “preview.png” at the root of the theme
* the “title” of the theme as specified in the manifest (config.xml in the root of the theme)
* the description of the theme: a string set in its manifest
* the type of theme: Core theme (provided with LimeSurvey), User theme (added in upload directory), XML theme (not loaded in database)
* Extends: if the theme extends another theme, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a theme to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a theme in the database
** Theme editor: it will redirect you to the theme editor
** Theme option: it will lead you the global configuration of theme options

==Theme Editor== 
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' theme'']]

====A quick overview of the concept of theme inheritance==== 


In LS3, a theme can now inherit from another theme, it can “extend” another theme. This means that the theme directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of themes for your different users without having to maintain a lot of different themes. For example: you can have your own home-made theme, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom theme, all the themes that inherit from it will be updated automatically. Note that the inheritance is recursive: a theme can extend a theme that extends another one etc.


<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core themes of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface==== 


To extend the Monochrome theme of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome theme. Then, click on “extend” and validate the new name “extends_monochrome”.


If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/themes/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this theme as a normal one from a survey and it will look exactly like the monochrome theme.


[[File:Extends monochrome empty.jpg|center|baseline|border|''The theme tree (directory and files) just after its creation. It's practically empty'']]


<div class="simplebox">[[File:help.png]] The resources (jpg, png etc.) from the original theme are copied when extending a theme. This is because if you copy a CSS file from the original theme locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current theme path. </div>


The theme editor for the extends_monochrome theme looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome theme'']]
<br /><br />
There is no big difference with the old theme editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the theme directory and that the file from the original theme will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to theme views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local theme and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ==== 


The button '''Copy to local theme and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the theme you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button'']]
<br>
If you open a file explorer and go to the directory upload/themes/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your theme'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).


<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the theme to find the image. If the theme you’re working on is extended to another theme, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local theme, it will loop through the theme inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your theme. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/


<div class="simplebox">
So, to add a picture to your theme:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''


* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}


* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list==== 
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which theme the current one extends (if any)

==Template options== 
Another novelty of LS3 is the theme option page. As we’ll see later, theme creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the theme options at global level: click on “theme options” in the theme list
===Advanced options===


{{QS:Theme editor - advanced options}}

===Simple options=== 


The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the theme's /options directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options (Broken link)
<div class="simplebox">[[File:help.png]] This page can be completely different from a theme to another, and theme providers are strongly encouraged to create their own look & feel. </div>


[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from


{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core themes:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a theme provider could add his own animation library or no animation library at all.


<div class="simplebox">[[File:help.png]] The monochrome themes use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for theme providers.</div>

===Inheritance system=== 


In the previous part, we’ve seen that a theme can extend another theme. A theme configuration can also inherit from another theme configuration. It means that for a given theme, you can have a configuration at


* global level (the one we’ve just seen accessible from the theme list)
* at survey group level
* a last one at survey level.


Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

====At survey group level==== 


Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of themes than in the theme list, except that here only the option button is visible (theme editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]


<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

====At survey level==== 
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example== 
Let’s say you’re using a single theme for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core theme. But of course, if you are a theme provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization = 


You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS/JS: deal with the asset manager ("why are my changes not applied?") == 
<br />


If you're trying to update the CSS/JS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.


<br />


Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />


It moves the CSS/JS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css/js file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css/js. Else, they would have to clean their browser cache.


<br />


Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.


<br />


Here the CSS links in header when asset manager is off:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.


<br />


<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>


So, when you're editing CSS/JS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache


[[File:Clearassets-ls3 3.png]]


<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>


Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme == 
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how it works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css


<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>


Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>


You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font === 
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>


You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.


Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options === 
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>


* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %} //Shouldn't this be "theme" in stead of "template"?
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>


<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector === 
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">


'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}


</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79


<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>


Of course, the XML file only contains the default values for your theme configuration. But indeed, those values are defined and read inside the database (table "template_configuration" (Question: "template_" of "theme_"?) as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174


So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

== Adding theme options to control positioning and display of survey elements == 
This tutorial will show how to add options to an extended theme to display survey elements in various locations. In this case, we will create theme options to show the survey title in two different locations.
<div class="simplebox">[[File:help.png]] For the sake of simplicity, we will base the tutorial on an extension of the "bootswatch" theme in LimeSurvey version 3.4.3.</div>
=== Create a custom theme ===
#Extend the "bootswatch" theme as described above.
#Copy <span style="color: #BA2121;">custom.css</span> to the local theme as described above.
===Create new theme options===
#Copy the contents of <span style="color: #BA2121;">/themes/survey/bootswatch/options/</span> to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/</span>.
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/options.twig</span> in an editor and find "{# Bootstrap Bootswatch theme #}". Directly before its parent <nowiki><div class='row'></nowiki> element, add this:<syntaxhighlight lang="html" enclose="div">
{# Custom survey name in navbar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div>


{# Custom survey name below progress bar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div></syntaxhighlight>
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/config.xml</span> and add two items to the "options" block so it looks like this:<syntaxhighlight lang="xml" enclose="div"> <options>
<ajaxmode>on</ajaxmode>
...
<surveyname1>on</surveyname1>
<surveyname2>on</surveyname2>
</options></syntaxhighlight>
#This should give you two new options in the Theme Options screen like this:<br />[[File:Tutorial_tp_1_1.png]]

===Modifed view for Survey Title in the navbar=== 
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/header/</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> and find "{# Logo option #}". Under that, modify the IF statement for the logo/survey-name, so it looks like this:<syntaxhighlight lang="html" enclose="div">
{# Logo option #}
{% if( aSurveyInfo.options.brandlogo == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }} logo-container" {{ aSurveyInfo.attr.navbarbrand }} >
{{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
</div>
{% endif %}
{% if( aSurveyInfo.options.surveyname1 == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }}" {{ aSurveyInfo.attr.navbarbrand }} >
{{ aSurveyInfo.name }}
</div>
{% endif %}</syntaxhighlight>
#Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60px;
font-size: 32px;
}</syntaxhighlight>
#Toggle the "Survey name in navbar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_2.png]]
===Modifed view for Survey Title under progress bar===
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> and add an <nowiki><h1></nowiki> element for the survey name. So it looks like this:<syntaxhighlight lang="html" enclose="div"><div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>

{# Custom survey name #}
{% if( aSurveyInfo.options.surveyname2 == "on") %}
<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
{% endif %}

{# Group Name #}
{{ include('./subviews/survey/group_subviews/group_name.twig') }}

{# Group Description #}
{{ include('./subviews/survey/group_subviews/group_desc.twig') }}

{#
PRESENT THE QUESTIONS

This is the main part. It will render each question for this group
#}


{% for aQuestion in aGroup.aQuestions %}
{{ include('./subviews/survey/question_container.twig') }}
{% endfor %}


{% if aGroup.show_last_group == true %}
<input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
{% endif %}

{% if aGroup.show_last_answer == true %}
<input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
{% endif %}
</div></syntaxhighlight>
# Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60ph1.custom-survey-name {
margin: 0;
text-align: center;
}</syntaxhighlight>
#Toggle the "Survey name below progress bar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_3.png]]

===Downloads=== 
* Sample extended theme: [[Media:Test_survey_names.zip]]

=Creating a theme from scratch= 
Documentation coming soon.

For now, just giving few tips.

==theme structure==

=== Files and directories ===
When you create a Theme from scratch, you don't need to respect the file/directory structure/css/js from Vanilla.
The mandatory css/js is added by core (you can still remove it if needed)

The only files your theme must have are the layout files:

* '''layout_global.twig''' : render the pages for survey taking
* '''layout_survey_list.twig''' : render the survey list (if this theme is set as default)
* '''layout_errors.twig''' : used to render errors that block survey rendering. ( wrong survey id, empty group in preview group, etc.)
* '''layout_user_forms.twig''': renders the user forms such as: token (survey participant), and register.
* '''layout_print.twig''' : used to print the survey to pdf
* '''layout_printanswers.twig''': print the answers

The content of those files, the files they include or not, is entirely up to you.
All the other files and directories that you find on Vanilla are purely optional, feel free to organize your code the way you want.

<div class="simplebox">[[File:help.png]] If you read the frontend rendering code, you'll see that those files names appear directly in it. That's why they are mandatory.
Eg: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/helpers/SurveyRuntimeHelper.php#L462
</div>

=== Content ===

In Vanilla's layout_global.twig, you'll see we use a variable called "include_content" to decide what to show
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/layout_global.twig#L114-L115

<syntaxhighlight lang="php" enclose="div">
{% set sViewContent = './subviews/content/' ~ aSurveyInfo.include_content ~ '.twig' %}
{% include './subviews/content/outerframe.twig' with {'include_content': sViewContent } %}
</syntaxhighlight>

aSurveyInfo.include_content tell you what action is currently going on: showing questions? showing submit result? showing clear all? etc
As you can see, in vanilla, we create one file to include by action. So if you want to know the list of actions, just check the vanilla's directory '''views/subviews/content''', and remove the "twig" extension :
https://github.com/LimeSurvey/LimeSurvey/tree/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/subviews/content

* '''clearall.twig'''
* '''firstpage.twig'''
* '''load.twig'''
* '''mainrow.twig'''
* '''main.twig'''
* '''optin.twig'''
* '''optout.twig'''
* '''outerframe.twig'''
* '''printanswers.twig'''
* '''quotas.twig'''
* '''register.twig'''
* '''save.twig'''
* '''submit_preview.twig'''
* '''submit.twig'''
* '''userforms.twig'''

If you already created a them for 2.x versions of LimeSurvey, you'll notice that most of them corresponds to the old pstpl files for limesurvey 2.x.
Again, there is no obligation for you in your theme to create those files, with those names, in this directory. You could for example just add a giant switch in layout_global.twig with the wanted HTML for each action.

=== The manifest config.xml ===

The manifest of the theme contains the main informations about your theme. When you install a theme, the content of the manifest will be loaded in the database, in two different tables: template and template_configuration. So each time you modify the manifest of a theme, you must uninstall and reinstall it (or just reset it). Because this process is annoying while developing a theme you can force the direct usage of the XML file rather than the DB entries. To do so, in config.phpn turn on debug mode and 'force_xmlsettings_for_survey_rendering' to true.

==== The metadata section ====

Nothing complex: just the main infos about your theme. It will be pushed in the table templates_configuration

<syntaxhighlight lang="xml" enclose="div">
<metadata>
<name>the_name_of_your_theme</name>
<title>The Title of your theme</title>
<creationDate>16/10/2017</creationDate>
<author>Your Name</author>
<authorEmail>your@email.org</authorEmail>
<authorUrl>http://www.yourwebsite.org</authorUrl>
<copyright>Your Copyright </copyright>
<license>Licence of your theme</license>
<version>version of your theme</version>
<apiVersion>3</apiVersion>
<description>Description of your theme</description>
<extends>parent_theme</extends>
</metadata>
</syntaxhighlight>

Few remarks:
* '''name''': will be used as a key in the db. So it must be unique, and it should not have any special chars (no spaces). Note that cases will not be taken in account
* '''Title''': will be used to display your theme name in the different lists. It can have special chars
* '''description''': will be used in the main list of survey theme. It can contains special chars, and even HTML code by using
* '''extends''': optional, it defines the parent themes. So if any file is not present in this theme (twig/js/css/jpg, etc) it will look for it in the parent theme

<div class="simplebox">[[File:help.png]] If you extended one of the the 3 core themes (Vanilla, Bootswatch, Fruity), you can change the "extends" value from one parent theme to the other. Of course, you'll have to reset the theme. </div>

==== The files section ====

This one is an important one. It will be pushed in the table template_configuration, in the field files_css, files_js, files_print_css as json arrays.

Eg: the files section of the Material Premium Theme:

<syntaxhighlight lang="xml" enclose="div">
<files>
<css>
<add>css/bootstrap-material-design.css</add>
<add>css/ripples.min.css</add>
<replace>css/ajaxify.css</replace>
<replace>css/theme.css</replace>
<replace>css/custom.css</replace>
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</css>
<js>
<replace>scripts/theme.js</replace>
<replace>scripts/ajaxify.js</replace>
<add>scripts/material.js</add>
<add>scripts/ripples.min.js</add>
<replace>scripts/custom.js</replace>
</js>
<print_css>
<add>css/print_theme.css</add>
</print_css>
</files>
</syntaxhighlight>

All the CSS/JS files present in this section will be loaded at the launch of the survey (in ajax mode. If ajax mode is off, then of course all the files are reloaded at each page).

They will be added to a Yii Asset Packet based on the name of the theme. So when Asset Manager is on (debug mode being off), those files will be copied to the tmp directory with the rest of the theme (so you can use relative path in the CSS and JS to reach the image files).
About the Asset manager in Yii: https://www.yiiframework.com/wiki/148/understanding-assets
About packages in Yii: http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail

They will use the inheritance system. It means that if you add a CSS/JS file to a theme, but it's not present in the theme, then the engine will look into all the mother themes of this theme and will use the first one it finds. So if a user extends your theme via the theme editor, all those files will be inherited in his theme. The keywords refer to this inheritance system.

* '''add''' : it will add the file to the theme, and to all its inherited theme
* '''replace''': it will replace the the file of its mother theme
* '''remove''': it will remove the file from '''any''' package, even the core package (since 3.14)

<div class="simplebox">[[File:help.png]] Remember you can set in config.php 'force_xmlsettings_for_survey_rendering' so configuration is read from XML instead of DB (no reset needed). This will make easier to test the modifications of the XML files, and will avoid you to uninstall/reinstall theme at each modification of the XML </div>

Few remarks on those keywords:

===== Inheritance tips =====
As explained before, the "add" keyword can refer to a file being in one of the mother theme. So you can "add" a file in this section, and still not having this file in your theme, but in one of its parents theme. The engine will look into all its parent themes and will use the first one it finds. If it can't find the file, and debug mode is on in config, and js frontend debug mode is on in global setting, a message in console will warn you. Eg: if we add in a my_theme: <add>css/unexisting.css</add>, in the console we'll see:

<syntaxhighlight lang="" enclose="div">
(¯`·._.·(¯`·._.· Theme Configuration Error ·._.·´¯)·._.·´¯)

Can't find file 'css/unexisting.css' defined in theme 'my_theme'
</syntaxhighlight>

If the debug mode is off, then no error at all will be seen. The engine will just ignore the wrong add statements.

===== When to use add, when to use replace, when can I just leave it to the parent theme? =====

First: add and replace are the very same keyword. You can use the one or the other, the engine will just do the same. They are distinct for human readers, so they understand what was your intention.

You can't add a file with the same name as the mother theme: it will always replace it. eg: If you have a file called "my_mother_theme/foo.css" and you add a file called "foo.cs" in the daughter theme, only "daughter_theme/foo.css" will be added to the theme. If you want to keep "my_mother_theme/foo.css", just choose another name for "daughter_theme/foo.css", like "daughter_theme/bar.css". So the keyword "add" can be used as a "replace" keyword.

If you wonder why: this make much easier the automatic generation of inherited theme, copying the file section works out of the box (no need to rename "add" to "replace" when extending one the file).

To make it clear, let's take the Fruity example. Here its css file section:

<syntaxhighlight lang="xml" enclose="div">
<css>
<add>css/variations/sea_green.css</add>
<replace>css/animate.css</replace>
<replace>css/theme.css</replace>
<replace>css/custom.css</replace>
</css>
</syntaxhighlight>

If you look to the custom.css file in fruity, it is exactly the same as the vanilla one. We could delete the custom.css file inside fruity, the one of vanilla would loaded. We could remove the statement <replace>custom.css</replace> from the Fruity manifest, the statement from vanilla will be used, and the vanilla custom.css would be loaded.

So why do we use the statement <replace>custom.css</replace> inside the fruity manifest? The answer is easy: because we want the end user to be able to extend the fruity theme, to modify the file in his local theme, and to load this modified file from his inherited theme. To understand, just extend fruity and have a look to the extended theme. THe extended theme doesn't even have the file custom.css. So the one of fruity will be used. But: if the user create this file in the extended theme (by clicking on "extend" in the theme editor), then this file will be loaded from his theme.

So in general:
if you create a theme from scratch not extending any theme, just use the add statement to add your css/js files. Easy peasy.
if you create a theme extending another theme, and you don't want the users to be able to extends the css/js file from the mother theme: don't use the add statement in your manifest. THe files will still be loaded from the mother theme configuration.
if you create a theme extending another theme, and you want to replace a file from the mother theme: use the replace keyword (the add keyword will have the same result)
if you create a theme extending another theme, if you don't replace a given file from css/js, but you want the users to be able to extend this file: then use the "replace" statement in your manifest for this file. Even if you don't replace the file, by using the keyword replace in the manifest: you allow the user to do it if he wants to do it.

Only this very last case needs a bit of mental gymnastic ot understand, all the other cases are trivial.

<div class="simplebox">[[File:help.png]]
You can also register CSS and JS files directly from the twig code. Those files will be loaded only when the twig file is asked. If you want the users to be able to inherit those JS/Css files from the theme editor, remember to use the functions {{registerTemplateCssFile('my_style.css')}} and {{registerTemplateScript('my_script.js')}}. If you don't use those functions, your theme may work, but inheritance on it will be broken. It is the same logic as the {{image('my_picture.jpg')}} function
</div>

===== The remove keyword =====

The remove keyword is available only since 3.14. With this one, you can remove any css/file from any package, even the core ones. It is used in Material Premium Theme to remove the Awseome Bootstrap Checkbox's files:

<syntaxhighlight lang="xml" enclose="div">
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</syntaxhighlight>

so you should use the very same syntax as the package's file (eg: "awesome-bootstrap-checkbox.css" alone without it's folder path would not work). You'll find the complete list of core packages and their files in /application/config/packages.php and config/third_party.php. For example, for awesome-bootstrap-checkbox.css:
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/config/packages.php#L54-L56

<syntaxhighlight lang="php" enclose="div">
'css'=> array(
'awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css',
),
</syntaxhighlight>

Another way to find the exact name to use in the remove tag is to turn asset manager on (turning debug mode off or setting 'use_asset_manager'=>true in the config). Then, the path to use will be the one just after the random directory in the tmp directory. For example, for awesome-bootstrap-checkbox.css:
<syntaxhighlight lang="html" enclose="div">
<link rel="stylesheet" type="text/css" href="/tmp/assets/cbc4e3cb/awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css" />
</syntaxhighlight>

Files you should not remove:

'''jquery-3.1.1.min.js''' : needed

'''jquery-migrate-3.0.0.min.js''' : needed

'''survey.js''' : needed

'''moment-with-locales.min.js''' : needed for date question type (and some other i think)

'''em_javascript.js''' : needed for all Expression Manager javascript

==== The options section ====

This section is relative to the option of your theme. It will be used to feed the filed "options" of the table template_configuration as a json array.

== Some notes ==


'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.


'''NOTE''': to avoid that, you can force the use to the XML rather than DB. In config.php turn debug mode on and uncommment:


'force_xmlsettings_for_survey_rendering' => true, // Uncomment if you want to force the use of the XML file rather than DB (for easy theme development)


Becareful: everything will be loaded from the XML (included options, etc)


'''NOTE''': if you manually edit the CSS/JS files (without using the Theme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache".


'''NOTE''': if you remove the section

</translate>

New Template System in LS3.x

2018-12-20T10:30:19Z

LouisGac: /* The manifest config.xml */

<languages />
<translate>

__TOC__
=Introduction= 


On this page you'll learn how to:


* Use the new theme system of LimeSurvey 3.0.
* Use inheritance to manage your own themes.
* Add a picture to your theme
* Manage theme options for your surveys and survey groups


<hr/>


LimeSurvey 3 introduces a complete new theme engine system, based on Twig 1.29, Bootstrap, and allowing theme inheritance and theme options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old theme system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A theme designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new theme engine.


<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Theme Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface= 
==theme list==
On the admin dashboard, there is now a box to access the theme list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The theme list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the theme: it’s just a picture file called “preview.png” at the root of the theme
* the “title” of the theme as specified in the manifest (config.xml in the root of the theme)
* the description of the theme: a string set in its manifest
* the type of theme: Core theme (provided with LimeSurvey), User theme (added in upload directory), XML theme (not loaded in database)
* Extends: if the theme extends another theme, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a theme to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a theme in the database
** Theme editor: it will redirect you to the theme editor
** Theme option: it will lead you the global configuration of theme options

==Theme Editor== 
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' theme'']]

====A quick overview of the concept of theme inheritance==== 


In LS3, a theme can now inherit from another theme, it can “extend” another theme. This means that the theme directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of themes for your different users without having to maintain a lot of different themes. For example: you can have your own home-made theme, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom theme, all the themes that inherit from it will be updated automatically. Note that the inheritance is recursive: a theme can extend a theme that extends another one etc.


<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core themes of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface==== 


To extend the Monochrome theme of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome theme. Then, click on “extend” and validate the new name “extends_monochrome”.


If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/themes/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this theme as a normal one from a survey and it will look exactly like the monochrome theme.


[[File:Extends monochrome empty.jpg|center|baseline|border|''The theme tree (directory and files) just after its creation. It's practically empty'']]


<div class="simplebox">[[File:help.png]] The resources (jpg, png etc.) from the original theme are copied when extending a theme. This is because if you copy a CSS file from the original theme locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current theme path. </div>


The theme editor for the extends_monochrome theme looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome theme'']]
<br /><br />
There is no big difference with the old theme editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the theme directory and that the file from the original theme will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to theme views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local theme and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ==== 


The button '''Copy to local theme and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the theme you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button'']]
<br>
If you open a file explorer and go to the directory upload/themes/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your theme'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).


<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the theme to find the image. If the theme you’re working on is extended to another theme, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local theme, it will loop through the theme inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your theme. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/


<div class="simplebox">
So, to add a picture to your theme:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''


* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}


* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list==== 
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which theme the current one extends (if any)

==Template options== 
Another novelty of LS3 is the theme option page. As we’ll see later, theme creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the theme options at global level: click on “theme options” in the theme list
===Advanced options===


{{QS:Theme editor - advanced options}}

===Simple options=== 


The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the theme's /options directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options (Broken link)
<div class="simplebox">[[File:help.png]] This page can be completely different from a theme to another, and theme providers are strongly encouraged to create their own look & feel. </div>


[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from


{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core themes:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a theme provider could add his own animation library or no animation library at all.


<div class="simplebox">[[File:help.png]] The monochrome themes use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for theme providers.</div>

===Inheritance system=== 


In the previous part, we’ve seen that a theme can extend another theme. A theme configuration can also inherit from another theme configuration. It means that for a given theme, you can have a configuration at


* global level (the one we’ve just seen accessible from the theme list)
* at survey group level
* a last one at survey level.


Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

====At survey group level==== 


Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of themes than in the theme list, except that here only the option button is visible (theme editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]


<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

====At survey level==== 
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example== 
Let’s say you’re using a single theme for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core theme. But of course, if you are a theme provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization = 


You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS/JS: deal with the asset manager ("why are my changes not applied?") == 
<br />


If you're trying to update the CSS/JS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.


<br />


Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />


It moves the CSS/JS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css/js file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css/js. Else, they would have to clean their browser cache.


<br />


Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.


<br />


Here the CSS links in header when asset manager is off:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.


<br />


<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>


So, when you're editing CSS/JS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache


[[File:Clearassets-ls3 3.png]]


<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>


Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme == 
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how it works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css


<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>


Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>


You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font === 
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>


You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.


Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options === 
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>


* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %} //Shouldn't this be "theme" in stead of "template"?
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>


<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector === 
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">


'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}


</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79


<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>


Of course, the XML file only contains the default values for your theme configuration. But indeed, those values are defined and read inside the database (table "template_configuration" (Question: "template_" of "theme_"?) as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174


So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

== Adding theme options to control positioning and display of survey elements == 
This tutorial will show how to add options to an extended theme to display survey elements in various locations. In this case, we will create theme options to show the survey title in two different locations.
<div class="simplebox">[[File:help.png]] For the sake of simplicity, we will base the tutorial on an extension of the "bootswatch" theme in LimeSurvey version 3.4.3.</div>
=== Create a custom theme ===
#Extend the "bootswatch" theme as described above.
#Copy <span style="color: #BA2121;">custom.css</span> to the local theme as described above.
===Create new theme options===
#Copy the contents of <span style="color: #BA2121;">/themes/survey/bootswatch/options/</span> to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/</span>.
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/options.twig</span> in an editor and find "{# Bootstrap Bootswatch theme #}". Directly before its parent <nowiki><div class='row'></nowiki> element, add this:<syntaxhighlight lang="html" enclose="div">
{# Custom survey name in navbar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div>


{# Custom survey name below progress bar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div></syntaxhighlight>
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/config.xml</span> and add two items to the "options" block so it looks like this:<syntaxhighlight lang="xml" enclose="div"> <options>
<ajaxmode>on</ajaxmode>
...
<surveyname1>on</surveyname1>
<surveyname2>on</surveyname2>
</options></syntaxhighlight>
#This should give you two new options in the Theme Options screen like this:<br />[[File:Tutorial_tp_1_1.png]]

===Modifed view for Survey Title in the navbar=== 
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/header/</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> and find "{# Logo option #}". Under that, modify the IF statement for the logo/survey-name, so it looks like this:<syntaxhighlight lang="html" enclose="div">
{# Logo option #}
{% if( aSurveyInfo.options.brandlogo == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }} logo-container" {{ aSurveyInfo.attr.navbarbrand }} >
{{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
</div>
{% endif %}
{% if( aSurveyInfo.options.surveyname1 == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }}" {{ aSurveyInfo.attr.navbarbrand }} >
{{ aSurveyInfo.name }}
</div>
{% endif %}</syntaxhighlight>
#Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60px;
font-size: 32px;
}</syntaxhighlight>
#Toggle the "Survey name in navbar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_2.png]]
===Modifed view for Survey Title under progress bar===
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> and add an <nowiki><h1></nowiki> element for the survey name. So it looks like this:<syntaxhighlight lang="html" enclose="div"><div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>

{# Custom survey name #}
{% if( aSurveyInfo.options.surveyname2 == "on") %}
<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
{% endif %}

{# Group Name #}
{{ include('./subviews/survey/group_subviews/group_name.twig') }}

{# Group Description #}
{{ include('./subviews/survey/group_subviews/group_desc.twig') }}

{#
PRESENT THE QUESTIONS

This is the main part. It will render each question for this group
#}


{% for aQuestion in aGroup.aQuestions %}
{{ include('./subviews/survey/question_container.twig') }}
{% endfor %}


{% if aGroup.show_last_group == true %}
<input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
{% endif %}

{% if aGroup.show_last_answer == true %}
<input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
{% endif %}
</div></syntaxhighlight>
# Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60ph1.custom-survey-name {
margin: 0;
text-align: center;
}</syntaxhighlight>
#Toggle the "Survey name below progress bar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_3.png]]

===Downloads=== 
* Sample extended theme: [[Media:Test_survey_names.zip]]

=Creating a theme from scratch= 
Documentation coming soon.

For now, just giving few tips.

==theme structure==

=== Files and directories ===
When you create a Theme from scratch, you don't need to respect the file/directory structure/css/js from Vanilla.
The mandatory css/js is added by core (you can still remove it if needed)

The only files your theme must have are the layout files:

* '''layout_global.twig''' : render the pages for survey taking
* '''layout_survey_list.twig''' : render the survey list (if this theme is set as default)
* '''layout_errors.twig''' : used to render errors that block survey rendering. ( wrong survey id, empty group in preview group, etc.)
* '''layout_user_forms.twig''': renders the user forms such as: token (survey participant), and register.
* '''layout_print.twig''' : used to print the survey to pdf
* '''layout_printanswers.twig''': print the answers

The content of those files, the files they include or not, is entirely up to you.
All the other files and directories that you find on Vanilla are purely optional, feel free to organize your code the way you want.

<div class="simplebox">[[File:help.png]] If you read the frontend rendering code, you'll see that those files names appear directly in it. That's why they are mandatory.
Eg: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/helpers/SurveyRuntimeHelper.php#L462
</div>

=== Content ===

In Vanilla's layout_global.twig, you'll see we use a variable called "include_content" to decide what to show
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/layout_global.twig#L114-L115

<syntaxhighlight lang="php" enclose="div">
{% set sViewContent = './subviews/content/' ~ aSurveyInfo.include_content ~ '.twig' %}
{% include './subviews/content/outerframe.twig' with {'include_content': sViewContent } %}
</syntaxhighlight>

aSurveyInfo.include_content tell you what action is currently going on: showing questions? showing submit result? showing clear all? etc
As you can see, in vanilla, we create one file to include by action. So if you want to know the list of actions, just check the vanilla's directory '''views/subviews/content''', and remove the "twig" extension :
https://github.com/LimeSurvey/LimeSurvey/tree/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/subviews/content

* '''clearall.twig'''
* '''firstpage.twig'''
* '''load.twig'''
* '''mainrow.twig'''
* '''main.twig'''
* '''optin.twig'''
* '''optout.twig'''
* '''outerframe.twig'''
* '''printanswers.twig'''
* '''quotas.twig'''
* '''register.twig'''
* '''save.twig'''
* '''submit_preview.twig'''
* '''submit.twig'''
* '''userforms.twig'''

If you already created a them for 2.x versions of LimeSurvey, you'll notice that most of them corresponds to the old pstpl files for limesurvey 2.x.
Again, there is no obligation for you in your theme to create those files, with those names, in this directory. You could for example just add a giant switch in layout_global.twig with the wanted HTML for each action.

=== The manifest config.xml ===

The manifest of the theme contains the main informations about your theme. When you install a theme, the content of the manifest will be loaded in the database, in two different tables: template and template_configuration. So each time you modify the manifest of a theme, you must uninstall and reinstall it (or just reset it). Because this process is annoying while developing a theme you can force the direct usage of the XML file rather than the DB entries. To do so, in config.phpn turn on debug mode and 'force_xmlsettings_for_survey_rendering' to true.

==== The metadata section ====

Nothing complex: just the main infos about your theme. It will be pushed in the table templates_configuration

<syntaxhighlight lang="xml" enclose="div">
<metadata>
<name>the_name_of_your_theme</name>
<title>The Title of your theme</title>
<creationDate>16/10/2017</creationDate>
<author>Your Name</author>
<authorEmail>your@email.org</authorEmail>
<authorUrl>http://www.yourwebsite.org</authorUrl>
<copyright>Your Copyright </copyright>
<license>Licence of your theme</license>
<version>version of your theme</version>
<apiVersion>3</apiVersion>
<description>Description of your theme</description>
<extends>parent_theme</extends>
</metadata>
</syntaxhighlight>

Few remarks:
* '''name''': will be used as a key in the db. So it must be unique, and it should not have any special chars (no spaces). Note that cases will not be taken in account
* '''Title''': will be used to display your theme name in the different lists. It can have special chars
* '''description''': will be used in the main list of survey theme. It can contains special chars, and even HTML code by using
* '''extends''': optional, it defines the parent themes. So if any file is not present in this theme (twig/js/css/jpg, etc) it will look for it in the parent theme

<div class="simplebox">[[File:help.png]] If you extended one of the the 3 core themes (Vanilla, Bootswatch, Fruity), you can change the "extends" value from one parent theme to the other. Of course, you'll have to reset the theme. </div>

<![CDATA[

==== The files section ====

This one is an important one. It will be pushed in the table template_configuration, in the field files_css, files_js, files_print_css as json arrays.

Eg: the files section of the Material Premium Theme:

<syntaxhighlight lang="xml" enclose="div">
<files>
<css>
<add>css/bootstrap-material-design.css</add>
<add>css/ripples.min.css</add>
<replace>css/ajaxify.css</replace>
<replace>css/theme.css</replace>
<replace>css/custom.css</replace>
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</css>
<js>
<replace>scripts/theme.js</replace>
<replace>scripts/ajaxify.js</replace>
<add>scripts/material.js</add>
<add>scripts/ripples.min.js</add>
<replace>scripts/custom.js</replace>
</js>
<print_css>
<add>css/print_theme.css</add>
</print_css>
</files>
</syntaxhighlight>

All the CSS/JS files present in this section will be loaded at the launch of the survey (in ajax mode. If ajax mode is off, then of course all the files are reloaded at each page).

They will be added to a Yii Asset Packet based on the name of the theme. So when Asset Manager is on (debug mode being off), those files will be copied to the tmp directory with the rest of the theme (so you can use relative path in the CSS and JS to reach the image files).
About the Asset manager in Yii: https://www.yiiframework.com/wiki/148/understanding-assets
About packages in Yii: http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail

They will use the inheritance system. It means that if you add a CSS/JS file to a theme, but it's not present in the theme, then the engine will look into all the mother themes of this theme and will use the first one it finds. So if a user extends your theme via the theme editor, all those files will be inherited in his theme. The keywords refer to this inheritance system.

* '''add''' : it will add the file to the theme, and to all its inherited theme
* '''replace''': it will replace the the file of its mother theme
* '''remove''': it will remove the file from '''any''' package, even the core package (since 3.14)

<div class="simplebox">[[File:help.png]] Remember you can set in config.php 'force_xmlsettings_for_survey_rendering' so configuration is read from XML instead of DB (no reset needed). This will make easier to test the modifications of the XML files, and will avoid you to uninstall/reinstall theme at each modification of the XML </div>

Few remarks on those keywords:

===== Inheritance tips =====
As explained before, the "add" keyword can refer to a file being in one of the mother theme. So you can "add" a file in this section, and still not having this file in your theme, but in one of its parents theme. The engine will look into all its parent themes and will use the first one it finds. If it can't find the file, and debug mode is on in config, and js frontend debug mode is on in global setting, a message in console will warn you. Eg: if we add in a my_theme: <add>css/unexisting.css</add>, in the console we'll see:

<syntaxhighlight lang="" enclose="div">
(¯`·._.·(¯`·._.· Theme Configuration Error ·._.·´¯)·._.·´¯)

Can't find file 'css/unexisting.css' defined in theme 'my_theme'
</syntaxhighlight>

If the debug mode is off, then no error at all will be seen. The engine will just ignore the wrong add statements.

===== When to use add, when to use replace, when can I just leave it to the parent theme? =====

First: add and replace are the very same keyword. You can use the one or the other, the engine will just do the same. They are distinct for human readers, so they understand what was your intention.

You can't add a file with the same name as the mother theme: it will always replace it. eg: If you have a file called "my_mother_theme/foo.css" and you add a file called "foo.cs" in the daughter theme, only "daughter_theme/foo.css" will be added to the theme. If you want to keep "my_mother_theme/foo.css", just choose another name for "daughter_theme/foo.css", like "daughter_theme/bar.css". So the keyword "add" can be used as a "replace" keyword.

If you wonder why: this make much easier the automatic generation of inherited theme, copying the file section works out of the box (no need to rename "add" to "replace" when extending one the file).

To make it clear, let's take the Fruity example. Here its css file section:

<syntaxhighlight lang="xml" enclose="div">
<css>
<add>css/variations/sea_green.css</add>
<replace>css/animate.css</replace>
<replace>css/theme.css</replace>
<replace>css/custom.css</replace>
</css>
</syntaxhighlight>

If you look to the custom.css file in fruity, it is exactly the same as the vanilla one. We could delete the custom.css file inside fruity, the one of vanilla would loaded. We could remove the statement <replace>custom.css</replace> from the Fruity manifest, the statement from vanilla will be used, and the vanilla custom.css would be loaded.

So why do we use the statement <replace>custom.css</replace> inside the fruity manifest? The answer is easy: because we want the end user to be able to extend the fruity theme, to modify the file in his local theme, and to load this modified file from his inherited theme. To understand, just extend fruity and have a look to the extended theme. THe extended theme doesn't even have the file custom.css. So the one of fruity will be used. But: if the user create this file in the extended theme (by clicking on "extend" in the theme editor), then this file will be loaded from his theme.

So in general:
if you create a theme from scratch not extending any theme, just use the add statement to add your css/js files. Easy peasy.
if you create a theme extending another theme, and you don't want the users to be able to extends the css/js file from the mother theme: don't use the add statement in your manifest. THe files will still be loaded from the mother theme configuration.
if you create a theme extending another theme, and you want to replace a file from the mother theme: use the replace keyword (the add keyword will have the same result)
if you create a theme extending another theme, if you don't replace a given file from css/js, but you want the users to be able to extend this file: then use the "replace" statement in your manifest for this file. Even if you don't replace the file, by using the keyword replace in the manifest: you allow the user to do it if he wants to do it.

Only this very last case needs a bit of mental gymnastic ot understand, all the other cases are trivial.

<div class="simplebox">[[File:help.png]]
You can also register CSS and JS files directly from the twig code. Those files will be loaded only when the twig file is asked. If you want the users to be able to inherit those JS/Css files from the theme editor, remember to use the functions {{registerTemplateCssFile('my_style.css')}} and {{registerTemplateScript('my_script.js')}}. If you don't use those functions, your theme may work, but inheritance on it will be broken. It is the same logic as the {{image('my_picture.jpg')}} function
</div>

===== The remove keyword =====

The remove keyword is available only since 3.14. With this one, you can remove any css/file from any package, even the core ones. It is used in Material Premium Theme to remove the Awseome Bootstrap Checkbox's files:

<syntaxhighlight lang="xml" enclose="div">
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</syntaxhighlight>

so you should use the very same syntax as the package's file (eg: "awesome-bootstrap-checkbox.css" alone without it's folder path would not work). You'll find the complete list of core packages and their files in /application/config/packages.php and config/third_party.php. For example, for awesome-bootstrap-checkbox.css:
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/config/packages.php#L54-L56

<syntaxhighlight lang="php" enclose="div">
'css'=> array(
'awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css',
),
</syntaxhighlight>

Another way to find the exact name to use in the remove tag is to turn asset manager on (turning debug mode off or setting 'use_asset_manager'=>true in the config). Then, the path to use will be the one just after the random directory in the tmp directory. For example, for awesome-bootstrap-checkbox.css:
<syntaxhighlight lang="html" enclose="div">
<link rel="stylesheet" type="text/css" href="/tmp/assets/cbc4e3cb/awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css" />
</syntaxhighlight>

Files you should not remove:

'''jquery-3.1.1.min.js''' : needed

'''jquery-migrate-3.0.0.min.js''' : needed

'''survey.js''' : needed

'''moment-with-locales.min.js''' : needed for date question type (and some other i think)

'''em_javascript.js''' : needed for all Expression Manager javascript

==== The options section ====

This section is relative to the option of your theme. It will be used to feed the filed "options" of the table template_configuration as a json array.

== Some notes ==


'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.


'''NOTE''': to avoid that, you can force the use to the XML rather than DB. In config.php turn debug mode on and uncommment:


'force_xmlsettings_for_survey_rendering' => true, // Uncomment if you want to force the use of the XML file rather than DB (for easy theme development)


Becareful: everything will be loaded from the XML (included options, etc)


'''NOTE''': if you manually edit the CSS/JS files (without using the Theme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache".


'''NOTE''': if you remove the section

</translate>

New Template System in LS3.x

2018-12-20T10:24:41Z

LouisGac: /* The metadata section */

<languages />
<translate>

__TOC__
=Introduction= 


On this page you'll learn how to:


* Use the new theme system of LimeSurvey 3.0.
* Use inheritance to manage your own themes.
* Add a picture to your theme
* Manage theme options for your surveys and survey groups


<hr/>


LimeSurvey 3 introduces a complete new theme engine system, based on Twig 1.29, Bootstrap, and allowing theme inheritance and theme options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old theme system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A theme designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new theme engine.


<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Theme Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface= 
==theme list==
On the admin dashboard, there is now a box to access the theme list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The theme list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the theme: it’s just a picture file called “preview.png” at the root of the theme
* the “title” of the theme as specified in the manifest (config.xml in the root of the theme)
* the description of the theme: a string set in its manifest
* the type of theme: Core theme (provided with LimeSurvey), User theme (added in upload directory), XML theme (not loaded in database)
* Extends: if the theme extends another theme, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a theme to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a theme in the database
** Theme editor: it will redirect you to the theme editor
** Theme option: it will lead you the global configuration of theme options

==Theme Editor== 
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' theme'']]

====A quick overview of the concept of theme inheritance==== 


In LS3, a theme can now inherit from another theme, it can “extend” another theme. This means that the theme directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of themes for your different users without having to maintain a lot of different themes. For example: you can have your own home-made theme, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom theme, all the themes that inherit from it will be updated automatically. Note that the inheritance is recursive: a theme can extend a theme that extends another one etc.


<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core themes of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface==== 


To extend the Monochrome theme of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome theme. Then, click on “extend” and validate the new name “extends_monochrome”.


If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/themes/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this theme as a normal one from a survey and it will look exactly like the monochrome theme.


[[File:Extends monochrome empty.jpg|center|baseline|border|''The theme tree (directory and files) just after its creation. It's practically empty'']]


<div class="simplebox">[[File:help.png]] The resources (jpg, png etc.) from the original theme are copied when extending a theme. This is because if you copy a CSS file from the original theme locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current theme path. </div>


The theme editor for the extends_monochrome theme looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome theme'']]
<br /><br />
There is no big difference with the old theme editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the theme directory and that the file from the original theme will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to theme views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local theme and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ==== 


The button '''Copy to local theme and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the theme you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button'']]
<br>
If you open a file explorer and go to the directory upload/themes/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your theme'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).


<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the theme to find the image. If the theme you’re working on is extended to another theme, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local theme, it will loop through the theme inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your theme. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/


<div class="simplebox">
So, to add a picture to your theme:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''


* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}


* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list==== 
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which theme the current one extends (if any)

==Template options== 
Another novelty of LS3 is the theme option page. As we’ll see later, theme creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the theme options at global level: click on “theme options” in the theme list
===Advanced options===


{{QS:Theme editor - advanced options}}

===Simple options=== 


The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the theme's /options directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options (Broken link)
<div class="simplebox">[[File:help.png]] This page can be completely different from a theme to another, and theme providers are strongly encouraged to create their own look & feel. </div>


[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from


{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core themes:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a theme provider could add his own animation library or no animation library at all.


<div class="simplebox">[[File:help.png]] The monochrome themes use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for theme providers.</div>

===Inheritance system=== 


In the previous part, we’ve seen that a theme can extend another theme. A theme configuration can also inherit from another theme configuration. It means that for a given theme, you can have a configuration at


* global level (the one we’ve just seen accessible from the theme list)
* at survey group level
* a last one at survey level.


Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

====At survey group level==== 


Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of themes than in the theme list, except that here only the option button is visible (theme editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]


<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

====At survey level==== 
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example== 
Let’s say you’re using a single theme for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core theme. But of course, if you are a theme provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization = 


You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS/JS: deal with the asset manager ("why are my changes not applied?") == 
<br />


If you're trying to update the CSS/JS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.


<br />


Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />


It moves the CSS/JS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css/js file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css/js. Else, they would have to clean their browser cache.


<br />


Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.


<br />


Here the CSS links in header when asset manager is off:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.


<br />


<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>


So, when you're editing CSS/JS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache


[[File:Clearassets-ls3 3.png]]


<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>


Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme == 
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how it works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css


<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>


Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>


You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font === 
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>


You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.


Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options === 
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>


* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %} //Shouldn't this be "theme" in stead of "template"?
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>


<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector === 
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">


'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}


</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79


<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>


Of course, the XML file only contains the default values for your theme configuration. But indeed, those values are defined and read inside the database (table "template_configuration" (Question: "template_" of "theme_"?) as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174


So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

== Adding theme options to control positioning and display of survey elements == 
This tutorial will show how to add options to an extended theme to display survey elements in various locations. In this case, we will create theme options to show the survey title in two different locations.
<div class="simplebox">[[File:help.png]] For the sake of simplicity, we will base the tutorial on an extension of the "bootswatch" theme in LimeSurvey version 3.4.3.</div>
=== Create a custom theme ===
#Extend the "bootswatch" theme as described above.
#Copy <span style="color: #BA2121;">custom.css</span> to the local theme as described above.
===Create new theme options===
#Copy the contents of <span style="color: #BA2121;">/themes/survey/bootswatch/options/</span> to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/</span>.
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/options.twig</span> in an editor and find "{# Bootstrap Bootswatch theme #}". Directly before its parent <nowiki><div class='row'></nowiki> element, add this:<syntaxhighlight lang="html" enclose="div">
{# Custom survey name in navbar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div>


{# Custom survey name below progress bar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div></syntaxhighlight>
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/config.xml</span> and add two items to the "options" block so it looks like this:<syntaxhighlight lang="xml" enclose="div"> <options>
<ajaxmode>on</ajaxmode>
...
<surveyname1>on</surveyname1>
<surveyname2>on</surveyname2>
</options></syntaxhighlight>
#This should give you two new options in the Theme Options screen like this:<br />[[File:Tutorial_tp_1_1.png]]

===Modifed view for Survey Title in the navbar=== 
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/header/</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> and find "{# Logo option #}". Under that, modify the IF statement for the logo/survey-name, so it looks like this:<syntaxhighlight lang="html" enclose="div">
{# Logo option #}
{% if( aSurveyInfo.options.brandlogo == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }} logo-container" {{ aSurveyInfo.attr.navbarbrand }} >
{{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
</div>
{% endif %}
{% if( aSurveyInfo.options.surveyname1 == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }}" {{ aSurveyInfo.attr.navbarbrand }} >
{{ aSurveyInfo.name }}
</div>
{% endif %}</syntaxhighlight>
#Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60px;
font-size: 32px;
}</syntaxhighlight>
#Toggle the "Survey name in navbar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_2.png]]
===Modifed view for Survey Title under progress bar===
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> and add an <nowiki><h1></nowiki> element for the survey name. So it looks like this:<syntaxhighlight lang="html" enclose="div"><div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>

{# Custom survey name #}
{% if( aSurveyInfo.options.surveyname2 == "on") %}
<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
{% endif %}

{# Group Name #}
{{ include('./subviews/survey/group_subviews/group_name.twig') }}

{# Group Description #}
{{ include('./subviews/survey/group_subviews/group_desc.twig') }}

{#
PRESENT THE QUESTIONS

This is the main part. It will render each question for this group
#}


{% for aQuestion in aGroup.aQuestions %}
{{ include('./subviews/survey/question_container.twig') }}
{% endfor %}


{% if aGroup.show_last_group == true %}
<input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
{% endif %}

{% if aGroup.show_last_answer == true %}
<input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
{% endif %}
</div></syntaxhighlight>
# Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60ph1.custom-survey-name {
margin: 0;
text-align: center;
}</syntaxhighlight>
#Toggle the "Survey name below progress bar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_3.png]]

===Downloads=== 
* Sample extended theme: [[Media:Test_survey_names.zip]]

=Creating a theme from scratch= 
Documentation coming soon.

For now, just giving few tips.

==theme structure==

=== Files and directories ===
When you create a Theme from scratch, you don't need to respect the file/directory structure/css/js from Vanilla.
The mandatory css/js is added by core (you can still remove it if needed)

The only files your theme must have are the layout files:

* '''layout_global.twig''' : render the pages for survey taking
* '''layout_survey_list.twig''' : render the survey list (if this theme is set as default)
* '''layout_errors.twig''' : used to render errors that block survey rendering. ( wrong survey id, empty group in preview group, etc.)
* '''layout_user_forms.twig''': renders the user forms such as: token (survey participant), and register.
* '''layout_print.twig''' : used to print the survey to pdf
* '''layout_printanswers.twig''': print the answers

The content of those files, the files they include or not, is entirely up to you.
All the other files and directories that you find on Vanilla are purely optional, feel free to organize your code the way you want.

<div class="simplebox">[[File:help.png]] If you read the frontend rendering code, you'll see that those files names appear directly in it. That's why they are mandatory.
Eg: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/helpers/SurveyRuntimeHelper.php#L462
</div>

=== Content ===

In Vanilla's layout_global.twig, you'll see we use a variable called "include_content" to decide what to show
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/layout_global.twig#L114-L115

<syntaxhighlight lang="php" enclose="div">
{% set sViewContent = './subviews/content/' ~ aSurveyInfo.include_content ~ '.twig' %}
{% include './subviews/content/outerframe.twig' with {'include_content': sViewContent } %}
</syntaxhighlight>

aSurveyInfo.include_content tell you what action is currently going on: showing questions? showing submit result? showing clear all? etc
As you can see, in vanilla, we create one file to include by action. So if you want to know the list of actions, just check the vanilla's directory '''views/subviews/content''', and remove the "twig" extension :
https://github.com/LimeSurvey/LimeSurvey/tree/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/subviews/content

* '''clearall.twig'''
* '''firstpage.twig'''
* '''load.twig'''
* '''mainrow.twig'''
* '''main.twig'''
* '''optin.twig'''
* '''optout.twig'''
* '''outerframe.twig'''
* '''printanswers.twig'''
* '''quotas.twig'''
* '''register.twig'''
* '''save.twig'''
* '''submit_preview.twig'''
* '''submit.twig'''
* '''userforms.twig'''

If you already created a them for 2.x versions of LimeSurvey, you'll notice that most of them corresponds to the old pstpl files for limesurvey 2.x.
Again, there is no obligation for you in your theme to create those files, with those names, in this directory. You could for example just add a giant switch in layout_global.twig with the wanted HTML for each action.

=== The manifest config.xml ===

The manifest of the theme contains the main informations about your theme. When you install a theme, the content of the manifest will be loaded in the database, in two different tables: template and template_configuration. So each time you modify the manifest of a theme, you must uninstall and reinstall it (or just reset it). Because this process is annoying while developing a theme you can force the direct usage of the XML file rather than the DB entries. To do so, in config.phpn turn on debug mode and 'force_xmlsettings_for_survey_rendering' to true.

==== The metadata section ====

Nothing complex: just the main infos about your theme. It will be pushed in the table templates_configuration

<syntaxhighlight lang="xml" enclose="div">
<metadata>
<name>the_name_of_your_theme</name>
<title>The Title of your theme</title>
<creationDate>16/10/2017</creationDate>
<author>Your Name</author>
<authorEmail>your@email.org</authorEmail>
<authorUrl>http://www.yourwebsite.org</authorUrl>
<copyright>Your Copyright </copyright>
<license>Licence of your theme</license>
<version>version of your theme</version>
<apiVersion>3</apiVersion>
<description>Description of your theme</description>
<extends>parent_theme</extends>
</metadata>
</syntaxhighlight>

Few remarks:
* '''name''': will be used as a key in the db. So it must be unique, and it should not have any special chars (no spaces). Note that cases will not be taken in account
* '''Title''': will be used to display your theme name in the different lists. It can have special chars
* '''description''': will be used in the main list of survey theme. It can contains special chars, and even HTML code by using
* '''extends''': optional, it defines the parent themes. So if any file is not present in this theme (twig/js/css/jpg, etc) it will look for it in the parent theme
<![CDATA[

==== The files section ====

This one is an important one. It will be pushed in the table template_configuration, in the field files_css, files_js, files_print_css as json arrays.

Eg: the files section of the Material Premium Theme:

<syntaxhighlight lang="xml" enclose="div">
<files>
<css>
<add>css/bootstrap-material-design.css</add>
<add>css/ripples.min.css</add>
<replace>css/ajaxify.css</replace>
<replace>css/theme.css</replace>
<replace>css/custom.css</replace>
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</css>
<js>
<replace>scripts/theme.js</replace>
<replace>scripts/ajaxify.js</replace>
<add>scripts/material.js</add>
<add>scripts/ripples.min.js</add>
<replace>scripts/custom.js</replace>
</js>
<print_css>
<add>css/print_theme.css</add>
</print_css>
</files>
</syntaxhighlight>

All the CSS/JS files present in this section will be loaded at the launch of the survey (in ajax mode. If ajax mode is off, then of course all the files are reloaded at each page).

They will be added to a Yii Asset Packet based on the name of the theme. So when Asset Manager is on (debug mode being off), those files will be copied to the tmp directory with the rest of the theme (so you can use relative path in the CSS and JS to reach the image files).
About the Asset manager in Yii: https://www.yiiframework.com/wiki/148/understanding-assets
About packages in Yii: http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail

They will use the inheritance system. It means that if you add a CSS/JS file to a theme, but it's not present in the theme, then the engine will look into all the mother themes of this theme and will use the first one it finds. So if a user extends your theme via the theme editor, all those files will be inherited in his theme. The keywords refer to this inheritance system.

* '''add''' : it will add the file to the theme, and to all its inherited theme
* '''replace''': it will replace the the file of its mother theme
* '''remove''': it will remove the file from '''any''' package, even the core package (since 3.14)

<div class="simplebox">[[File:help.png]] Remember you can set in config.php 'force_xmlsettings_for_survey_rendering' so configuration is read from XML instead of DB (no reset needed). This will make easier to test the modifications of the XML files, and will avoid you to uninstall/reinstall theme at each modification of the XML </div>

Few remarks on those keywords:

===== Inheritance tips =====
As explained before, the "add" keyword can refer to a file being in one of the mother theme. So you can "add" a file in this section, and still not having this file in your theme, but in one of its parents theme. The engine will look into all its parent themes and will use the first one it finds. If it can't find the file, and debug mode is on in config, and js frontend debug mode is on in global setting, a message in console will warn you. Eg: if we add in a my_theme: <add>css/unexisting.css</add>, in the console we'll see:

<syntaxhighlight lang="" enclose="div">
(¯`·._.·(¯`·._.· Theme Configuration Error ·._.·´¯)·._.·´¯)

Can't find file 'css/unexisting.css' defined in theme 'my_theme'
</syntaxhighlight>

If the debug mode is off, then no error at all will be seen. The engine will just ignore the wrong add statements.

===== When to use add, when to use replace, when can I just leave it to the parent theme? =====

First: add and replace are the very same keyword. You can use the one or the other, the engine will just do the same. They are distinct for human readers, so they understand what was your intention.

You can't add a file with the same name as the mother theme: it will always replace it. eg: If you have a file called "my_mother_theme/foo.css" and you add a file called "foo.cs" in the daughter theme, only "daughter_theme/foo.css" will be added to the theme. If you want to keep "my_mother_theme/foo.css", just choose another name for "daughter_theme/foo.css", like "daughter_theme/bar.css". So the keyword "add" can be used as a "replace" keyword.

If you wonder why: this make much easier the automatic generation of inherited theme, copying the file section works out of the box (no need to rename "add" to "replace" when extending one the file).

To make it clear, let's take the Fruity example. Here its css file section:

<syntaxhighlight lang="xml" enclose="div">
<css>
<add>css/variations/sea_green.css</add>
<replace>css/animate.css</replace>
<replace>css/theme.css</replace>
<replace>css/custom.css</replace>
</css>
</syntaxhighlight>

If you look to the custom.css file in fruity, it is exactly the same as the vanilla one. We could delete the custom.css file inside fruity, the one of vanilla would loaded. We could remove the statement <replace>custom.css</replace> from the Fruity manifest, the statement from vanilla will be used, and the vanilla custom.css would be loaded.

So why do we use the statement <replace>custom.css</replace> inside the fruity manifest? The answer is easy: because we want the end user to be able to extend the fruity theme, to modify the file in his local theme, and to load this modified file from his inherited theme. To understand, just extend fruity and have a look to the extended theme. THe extended theme doesn't even have the file custom.css. So the one of fruity will be used. But: if the user create this file in the extended theme (by clicking on "extend" in the theme editor), then this file will be loaded from his theme.

So in general:
if you create a theme from scratch not extending any theme, just use the add statement to add your css/js files. Easy peasy.
if you create a theme extending another theme, and you don't want the users to be able to extends the css/js file from the mother theme: don't use the add statement in your manifest. THe files will still be loaded from the mother theme configuration.
if you create a theme extending another theme, and you want to replace a file from the mother theme: use the replace keyword (the add keyword will have the same result)
if you create a theme extending another theme, if you don't replace a given file from css/js, but you want the users to be able to extend this file: then use the "replace" statement in your manifest for this file. Even if you don't replace the file, by using the keyword replace in the manifest: you allow the user to do it if he wants to do it.

Only this very last case needs a bit of mental gymnastic ot understand, all the other cases are trivial.

<div class="simplebox">[[File:help.png]]
You can also register CSS and JS files directly from the twig code. Those files will be loaded only when the twig file is asked. If you want the users to be able to inherit those JS/Css files from the theme editor, remember to use the functions {{registerTemplateCssFile('my_style.css')}} and {{registerTemplateScript('my_script.js')}}. If you don't use those functions, your theme may work, but inheritance on it will be broken. It is the same logic as the {{image('my_picture.jpg')}} function
</div>

===== The remove keyword =====

The remove keyword is available only since 3.14. With this one, you can remove any css/file from any package, even the core ones. It is used in Material Premium Theme to remove the Awseome Bootstrap Checkbox's files:

<syntaxhighlight lang="xml" enclose="div">
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</syntaxhighlight>

so you should use the very same syntax as the package's file (eg: "awesome-bootstrap-checkbox.css" alone without it's folder path would not work). You'll find the complete list of core packages and their files in /application/config/packages.php and config/third_party.php. For example, for awesome-bootstrap-checkbox.css:
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/config/packages.php#L54-L56

<syntaxhighlight lang="php" enclose="div">
'css'=> array(
'awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css',
),
</syntaxhighlight>

Another way to find the exact name to use in the remove tag is to turn asset manager on (turning debug mode off or setting 'use_asset_manager'=>true in the config). Then, the path to use will be the one just after the random directory in the tmp directory. For example, for awesome-bootstrap-checkbox.css:
<syntaxhighlight lang="html" enclose="div">
<link rel="stylesheet" type="text/css" href="/tmp/assets/cbc4e3cb/awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css" />
</syntaxhighlight>

Files you should not remove:

'''jquery-3.1.1.min.js''' : needed

'''jquery-migrate-3.0.0.min.js''' : needed

'''survey.js''' : needed

'''moment-with-locales.min.js''' : needed for date question type (and some other i think)

'''em_javascript.js''' : needed for all Expression Manager javascript

==== The options section ====

This section is relative to the option of your theme. It will be used to feed the filed "options" of the table template_configuration as a json array.

== Some notes ==


'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.


'''NOTE''': to avoid that, you can force the use to the XML rather than DB. In config.php turn debug mode on and uncommment:


'force_xmlsettings_for_survey_rendering' => true, // Uncomment if you want to force the use of the XML file rather than DB (for easy theme development)


Becareful: everything will be loaded from the XML (included options, etc)


'''NOTE''': if you manually edit the CSS/JS files (without using the Theme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache".


'''NOTE''': if you remove the section

</translate>

New Template System in LS3.x

2018-12-04T16:47:28Z

LouisGac: /* The remove keyword */

<languages />
<translate>

__TOC__
=Introduction= 


On this page you'll learn how to:


* Use the new theme system of LimeSurvey 3.0.
* Use inheritance to manage your own themes.
* Add a picture to your theme
* Manage theme options for your surveys and survey groups


<hr/>


LimeSurvey 3 introduces a complete new theme engine system, based on Twig 1.29, Bootstrap, and allowing theme inheritance and theme options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old theme system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A theme designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new theme engine.


<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Theme Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface= 
==theme list==
On the admin dashboard, there is now a box to access the theme list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The theme list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the theme: it’s just a picture file called “preview.png” at the root of the theme
* the “title” of the theme as specified in the manifest (config.xml in the root of the theme)
* the description of the theme: a string set in its manifest
* the type of theme: Core theme (provided with LimeSurvey), User theme (added in upload directory), XML theme (not loaded in database)
* Extends: if the theme extends another theme, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a theme to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a theme in the database
** Theme editor: it will redirect you to the theme editor
** Theme option: it will lead you the global configuration of theme options

==Theme Editor== 
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' theme'']]

====A quick overview of the concept of theme inheritance==== 


In LS3, a theme can now inherit from another theme, it can “extend” another theme. This means that the theme directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of themes for your different users without having to maintain a lot of different themes. For example: you can have your own home-made theme, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom theme, all the themes that inherit from it will be updated automatically. Note that the inheritance is recursive: a theme can extend a theme that extends another one etc.


<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core themes of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface==== 


To extend the Monochrome theme of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome theme. Then, click on “extend” and validate the new name “extends_monochrome”.


If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/themes/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this theme as a normal one from a survey and it will look exactly like the monochrome theme.


[[File:Extends monochrome empty.jpg|center|baseline|border|''The theme tree (directory and files) just after its creation. It's practically empty'']]


<div class="simplebox">[[File:help.png]] The resources (jpg, png etc.) from the original theme are copied when extending a theme. This is because if you copy a CSS file from the original theme locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current theme path. </div>


The theme editor for the extends_monochrome theme looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome theme'']]
<br /><br />
There is no big difference with the old theme editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the theme directory and that the file from the original theme will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to theme views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local theme and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ==== 


The button '''Copy to local theme and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the theme you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button'']]
<br>
If you open a file explorer and go to the directory upload/themes/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your theme'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).


<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the theme to find the image. If the theme you’re working on is extended to another theme, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local theme, it will loop through the theme inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your theme. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/


<div class="simplebox">
So, to add a picture to your theme:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''


* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}


* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list==== 
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which theme the current one extends (if any)

==Template options== 
Another novelty of LS3 is the theme option page. As we’ll see later, theme creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the theme options at global level: click on “theme options” in the theme list
===Advanced options===


{{QS:Theme editor - advanced options}}

===Simple options=== 


The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the theme's /options directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options (Broken link)
<div class="simplebox">[[File:help.png]] This page can be completely different from a theme to another, and theme providers are strongly encouraged to create their own look & feel. </div>


[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from


{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core themes:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a theme provider could add his own animation library or no animation library at all.


<div class="simplebox">[[File:help.png]] The monochrome themes use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for theme providers.</div>

===Inheritance system=== 


In the previous part, we’ve seen that a theme can extend another theme. A theme configuration can also inherit from another theme configuration. It means that for a given theme, you can have a configuration at


* global level (the one we’ve just seen accessible from the theme list)
* at survey group level
* a last one at survey level.


Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

====At survey group level==== 


Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of themes than in the theme list, except that here only the option button is visible (theme editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]


<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

====At survey level==== 
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example== 
Let’s say you’re using a single theme for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core theme. But of course, if you are a theme provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization = 


You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS/JS: deal with the asset manager ("why are my changes not applied?") == 
<br />


If you're trying to update the CSS/JS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.


<br />


Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />


It moves the CSS/JS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css/js file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css/js. Else, they would have to clean their browser cache.


<br />


Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.


<br />


Here the CSS links in header when asset manager is off:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.


<br />


<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>


So, when you're editing CSS/JS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache


[[File:Clearassets-ls3 3.png]]


<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>


Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme == 
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how it works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css


<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>


Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>


You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font === 
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>


You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.


Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options === 
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>


* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %} //Shouldn't this be "theme" in stead of "template"?
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>


<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector === 
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">


'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}


</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79


<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>


Of course, the XML file only contains the default values for your theme configuration. But indeed, those values are defined and read inside the database (table "template_configuration" (Question: "template_" of "theme_"?) as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174


So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

== Adding theme options to control positioning and display of survey elements == 
This tutorial will show how to add options to an extended theme to display survey elements in various locations. In this case, we will create theme options to show the survey title in two different locations.
<div class="simplebox">[[File:help.png]] For the sake of simplicity, we will base the tutorial on an extension of the "bootswatch" theme in LimeSurvey version 3.4.3.</div>
=== Create a custom theme ===
#Extend the "bootswatch" theme as described above.
#Copy <span style="color: #BA2121;">custom.css</span> to the local theme as described above.
===Create new theme options===
#Copy the contents of <span style="color: #BA2121;">/themes/survey/bootswatch/options/</span> to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/</span>.
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/options.twig</span> in an editor and find "{# Bootstrap Bootswatch theme #}". Directly before its parent <nowiki><div class='row'></nowiki> element, add this:<syntaxhighlight lang="html" enclose="div">
{# Custom survey name in navbar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div>


{# Custom survey name below progress bar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div></syntaxhighlight>
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/config.xml</span> and add two items to the "options" block so it looks like this:<syntaxhighlight lang="xml" enclose="div"> <options>
<ajaxmode>on</ajaxmode>
...
<surveyname1>on</surveyname1>
<surveyname2>on</surveyname2>
</options></syntaxhighlight>
#This should give you two new options in the Theme Options screen like this:<br />[[File:Tutorial_tp_1_1.png]]

===Modifed view for Survey Title in the navbar=== 
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/header/</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> and find "{# Logo option #}". Under that, modify the IF statement for the logo/survey-name, so it looks like this:<syntaxhighlight lang="html" enclose="div">
{# Logo option #}
{% if( aSurveyInfo.options.brandlogo == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }} logo-container" {{ aSurveyInfo.attr.navbarbrand }} >
{{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
</div>
{% endif %}
{% if( aSurveyInfo.options.surveyname1 == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }}" {{ aSurveyInfo.attr.navbarbrand }} >
{{ aSurveyInfo.name }}
</div>
{% endif %}</syntaxhighlight>
#Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60px;
font-size: 32px;
}</syntaxhighlight>
#Toggle the "Survey name in navbar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_2.png]]
===Modifed view for Survey Title under progress bar===
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> and add an <nowiki><h1></nowiki> element for the survey name. So it looks like this:<syntaxhighlight lang="html" enclose="div"><div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>

{# Custom survey name #}
{% if( aSurveyInfo.options.surveyname2 == "on") %}
<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
{% endif %}

{# Group Name #}
{{ include('./subviews/survey/group_subviews/group_name.twig') }}

{# Group Description #}
{{ include('./subviews/survey/group_subviews/group_desc.twig') }}

{#
PRESENT THE QUESTIONS

This is the main part. It will render each question for this group
#}


{% for aQuestion in aGroup.aQuestions %}
{{ include('./subviews/survey/question_container.twig') }}
{% endfor %}


{% if aGroup.show_last_group == true %}
<input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
{% endif %}

{% if aGroup.show_last_answer == true %}
<input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
{% endif %}
</div></syntaxhighlight>
# Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60ph1.custom-survey-name {
margin: 0;
text-align: center;
}</syntaxhighlight>
#Toggle the "Survey name below progress bar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_3.png]]

===Downloads=== 
* Sample extended theme: [[Media:Test_survey_names.zip]]

=Creating a theme from scratch= 
Documentation coming soon.

For now, just giving few tips.

==theme structure==

=== Files and directories ===
When you create a Theme from scratch, you don't need to respect the file/directory structure/css/js from Vanilla.
The mandatory css/js is added by core (you can still remove it if needed)

The only files your theme must have are the layout files:

* '''layout_global.twig''' : render the pages for survey taking
* '''layout_survey_list.twig''' : render the survey list (if this theme is set as default)
* '''layout_errors.twig''' : used to render errors that block survey rendering. ( wrong survey id, empty group in preview group, etc.)
* '''layout_user_forms.twig''': renders the user forms such as: token (survey participant), and register.
* '''layout_print.twig''' : used to print the survey to pdf
* '''layout_printanswers.twig''': print the answers

The content of those files, the files they include or not, is entirely up to you.
All the other files and directories that you find on Vanilla are purely optional, feel free to organize your code the way you want.

<div class="simplebox">[[File:help.png]] If you read the frontend rendering code, you'll see that those files names appear directly in it. That's why they are mandatory.
Eg: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/helpers/SurveyRuntimeHelper.php#L462
</div>

=== Content ===

In Vanilla's layout_global.twig, you'll see we use a variable called "include_content" to decide what to show
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/layout_global.twig#L114-L115

<syntaxhighlight lang="php" enclose="div">
{% set sViewContent = './subviews/content/' ~ aSurveyInfo.include_content ~ '.twig' %}
{% include './subviews/content/outerframe.twig' with {'include_content': sViewContent } %}
</syntaxhighlight>

aSurveyInfo.include_content tell you what action is currently going on: showing questions? showing submit result? showing clear all? etc
As you can see, in vanilla, we create one file to include by action. So if you want to know the list of actions, just check the vanilla's directory '''views/subviews/content''', and remove the "twig" extension :
https://github.com/LimeSurvey/LimeSurvey/tree/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/subviews/content

* '''clearall.twig'''
* '''firstpage.twig'''
* '''load.twig'''
* '''mainrow.twig'''
* '''main.twig'''
* '''optin.twig'''
* '''optout.twig'''
* '''outerframe.twig'''
* '''printanswers.twig'''
* '''quotas.twig'''
* '''register.twig'''
* '''save.twig'''
* '''submit_preview.twig'''
* '''submit.twig'''
* '''userforms.twig'''

If you already created a them for 2.x versions of LimeSurvey, you'll notice that most of them corresponds to the old pstpl files for limesurvey 2.x.
Again, there is no obligation for you in your theme to create those files, with those names, in this directory. You could for example just add a giant switch in layout_global.twig with the wanted HTML for each action.

=== The manifest config.xml ===

The manifest of the theme contains the main informations about your theme. When you install a theme, the content of the manifest will be loaded in the database, in two different tables: template and template_configuration. So each time you modify the manifest of a theme, you must uninstall and reinstall it (or just reset it). Because this process is annoying while developing a theme you can force the direct usage of the XML file rather than the DB entries. To do so, in config.phpn turn on debug mode and 'force_xmlsettings_for_survey_rendering' to true.

==== The metadata section ====

Nothing complex: just the main infos about your theme. It will be pushed in the table templates_configuration

<syntaxhighlight lang="xml" enclose="div">
<metadata>
<name>the_name_of_your_theme</name>
<title>The Title of your theme</title>
<creationDate>16/10/2017</creationDate>
<author>Your Name</author>
<authorEmail>your@email.org</authorEmail>
<authorUrl>http://www.yourwebsite.org</authorUrl>
<copyright>Your Copyright </copyright>
<license>Licence of your theme</license>
<version>version of your theme</version>
<apiVersion>3</apiVersion>
<description>Description of your theme</description>
</metadata>
</syntaxhighlight>

Few remarks:
* '''name''': will be used as a key in the db. So it must be unique, and it should not have any special chars (no spaces). Note that cases will not be taken in account
* '''Title''': will be used to display your theme name in the different lists. It can have special chars
* '''description''': will be used in the main list of survey theme. It can contains special chars, and even HTML code by using <![CDATA[

==== The files section ====

This one is an important one. It will be pushed in the table template_configuration, in the field files_css, files_js, files_print_css as json arrays.

Eg: the files section of the Material Premium Theme:

<syntaxhighlight lang="xml" enclose="div">
<files>
<css>
<add>css/bootstrap-material-design.css</add>
<add>css/ripples.min.css</add>
<replace>css/ajaxify.css</replace>
<replace>css/theme.css</replace>
<replace>css/custom.css</replace>
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</css>
<js>
<replace>scripts/theme.js</replace>
<replace>scripts/ajaxify.js</replace>
<add>scripts/material.js</add>
<add>scripts/ripples.min.js</add>
<replace>scripts/custom.js</replace>
</js>
<print_css>
<add>css/print_theme.css</add>
</print_css>
</files>
</syntaxhighlight>

All the CSS/JS files present in this section will be loaded at the launch of the survey (in ajax mode. If ajax mode is off, then of course all the files are reloaded at each page).

They will be added to a Yii Asset Packet based on the name of the theme. So when Asset Manager is on (debug mode being off), those files will be copied to the tmp directory with the rest of the theme (so you can use relative path in the CSS and JS to reach the image files).
About the Asset manager in Yii: https://www.yiiframework.com/wiki/148/understanding-assets
About packages in Yii: http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail

They will use the inheritance system. It means that if you add a CSS/JS file to a theme, but it's not present in the theme, then the engine will look into all the mother themes of this theme and will use the first one it finds. So if a user extends your theme via the theme editor, all those files will be inherited in his theme. The keywords refer to this inheritance system.

* '''add''' : it will add the file to the theme, and to all its inherited theme
* '''replace''': it will replace the the file of its mother theme
* '''remove''': it will remove the file from '''any''' package, even the core package (since 3.14)

<div class="simplebox">[[File:help.png]] Remember you can set in config.php 'force_xmlsettings_for_survey_rendering' so configuration is read from XML instead of DB (no reset needed). This will make easier to test the modifications of the XML files, and will avoid you to uninstall/reinstall theme at each modification of the XML </div>

Few remarks on those keywords:

===== Inheritance tips =====
As explained before, the "add" keyword can refer to a file being in one of the mother theme. So you can "add" a file in this section, and still not having this file in your theme, but in one of its parents theme. The engine will look into all its parent themes and will use the first one it finds. If it can't find the file, and debug mode is on in config, and js frontend debug mode is on in global setting, a message in console will warn you. Eg: if we add in a my_theme: <add>css/unexisting.css</add>, in the console we'll see:

<syntaxhighlight lang="" enclose="div">
(¯`·._.·(¯`·._.· Theme Configuration Error ·._.·´¯)·._.·´¯)

Can't find file 'css/unexisting.css' defined in theme 'my_theme'
</syntaxhighlight>

If the debug mode is off, then no error at all will be seen. The engine will just ignore the wrong add statements.

===== When to use add, when to use replace, when can I just leave it to the parent theme? =====

First: add and replace are the very same keyword. You can use the one or the other, the engine will just do the same. They are distinct for human readers, so they understand what was your intention.

You can't add a file with the same name as the mother theme: it will always replace it. eg: If you have a file called "my_mother_theme/foo.css" and you add a file called "foo.cs" in the daughter theme, only "daughter_theme/foo.css" will be added to the theme. If you want to keep "my_mother_theme/foo.css", just choose another name for "daughter_theme/foo.css", like "daughter_theme/bar.css". So the keyword "add" can be used as a "replace" keyword.

If you wonder why: this make much easier the automatic generation of inherited theme, copying the file section works out of the box (no need to rename "add" to "replace" when extending one the file).

To make it clear, let's take the Fruity example. Here its css file section:

<syntaxhighlight lang="xml" enclose="div">
<css>
<add>css/variations/sea_green.css</add>
<replace>css/animate.css</replace>
<replace>css/theme.css</replace>
<replace>css/custom.css</replace>
</css>
</syntaxhighlight>

If you look to the custom.css file in fruity, it is exactly the same as the vanilla one. We could delete the custom.css file inside fruity, the one of vanilla would loaded. We could remove the statement <replace>custom.css</replace> from the Fruity manifest, the statement from vanilla will be used, and the vanilla custom.css would be loaded.

So why do we use the statement <replace>custom.css</replace> inside the fruity manifest? The answer is easy: because we want the end user to be able to extend the fruity theme, to modify the file in his local theme, and to load this modified file from his inherited theme. To understand, just extend fruity and have a look to the extended theme. THe extended theme doesn't even have the file custom.css. So the one of fruity will be used. But: if the user create this file in the extended theme (by clicking on "extend" in the theme editor), then this file will be loaded from his theme.

So in general:
if you create a theme from scratch not extending any theme, just use the add statement to add your css/js files. Easy peasy.
if you create a theme extending another theme, and you don't want the users to be able to extends the css/js file from the mother theme: don't use the add statement in your manifest. THe files will still be loaded from the mother theme configuration.
if you create a theme extending another theme, and you want to replace a file from the mother theme: use the replace keyword (the add keyword will have the same result)
if you create a theme extending another theme, if you don't replace a given file from css/js, but you want the users to be able to extend this file: then use the "replace" statement in your manifest for this file. Even if you don't replace the file, by using the keyword replace in the manifest: you allow the user to do it if he wants to do it.

Only this very last case needs a bit of mental gymnastic ot understand, all the other cases are trivial.

<div class="simplebox">[[File:help.png]]
You can also register CSS and JS files directly from the twig code. Those files will be loaded only when the twig file is asked. If you want the users to be able to inherit those JS/Css files from the theme editor, remember to use the functions {{registerTemplateCssFile('my_style.css')}} and {{registerTemplateScript('my_script.js')}}. If you don't use those functions, your theme may work, but inheritance on it will be broken. It is the same logic as the {{image('my_picture.jpg')}} function
</div>

===== The remove keyword =====

The remove keyword is available only since 3.14. With this one, you can remove any css/file from any package, even the core ones. It is used in Material Premium Theme to remove the Awseome Bootstrap Checkbox's files:

<syntaxhighlight lang="xml" enclose="div">
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</syntaxhighlight>

so you should use the very same syntax as the package's file (eg: "awesome-bootstrap-checkbox.css" alone without it's folder path would not work). You'll find the complete list of core packages and their files in /application/config/packages.php and config/third_party.php. For example, for awesome-bootstrap-checkbox.css:
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/config/packages.php#L54-L56

<syntaxhighlight lang="php" enclose="div">
'css'=> array(
'awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css',
),
</syntaxhighlight>

Another way to find the exact name to use in the remove tag is to turn asset manager on (turning debug mode off or setting 'use_asset_manager'=>true in the config). Then, the path to use will be the one just after the random directory in the tmp directory. For example, for awesome-bootstrap-checkbox.css:
<syntaxhighlight lang="html" enclose="div">
<link rel="stylesheet" type="text/css" href="/tmp/assets/cbc4e3cb/awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css" />
</syntaxhighlight>

Files you should not remove:

'''jquery-3.1.1.min.js''' : needed

'''jquery-migrate-3.0.0.min.js''' : needed

'''survey.js''' : needed

'''moment-with-locales.min.js''' : needed for date question type (and some other i think)

'''em_javascript.js''' : needed for all Expression Manager javascript

==== The options section ====

This section is relative to the option of your theme. It will be used to feed the filed "options" of the table template_configuration as a json array.

== Some notes ==


'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.


'''NOTE''': to avoid that, you can force the use to the XML rather than DB. In config.php turn debug mode on and uncommment:


'force_xmlsettings_for_survey_rendering' => true, // Uncomment if you want to force the use of the XML file rather than DB (for easy theme development)


Becareful: everything will be loaded from the XML (included options, etc)


'''NOTE''': if you manually edit the CSS/JS files (without using the Theme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache".


'''NOTE''': if you remove the section

</translate>

New Template System in LS3.x

2018-08-13T14:41:20Z

LouisGac: /* The files section */

<languages />
<translate>

__TOC__
=Introduction= 


On this page you'll learn how to:


* Use the new theme system of LimeSurvey 3.0.
* Use inheritance to manage your own themes.
* Add a picture to your theme
* Manage theme options for your surveys and survey groups


<hr/>


LimeSurvey 3 introduces a complete new theme engine system, based on Twig 1.29, Bootstrap, and allowing theme inheritance and theme options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old theme system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A theme designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new theme engine.


<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Theme Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface= 
==theme list==
On the admin dashboard, there is now a box to access the theme list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The theme list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the theme: it’s just a picture file called “preview.png” at the root of the theme
* the “title” of the theme as specified in the manifest (config.xml in the root of the theme)
* the description of the theme: a string set in its manifest
* the type of theme: Core theme (provided with LimeSurvey), User theme (added in upload directory), XML theme (not loaded in database)
* Extends: if the theme extends another theme, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a theme to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a theme in the database
** Theme editor: it will redirect you to the theme editor
** Theme option: it will lead you the global configuration of theme options

==Theme Editor== 
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' theme'']]

====A quick overview of the concept of theme inheritance==== 


In LS3, a theme can now inherit from another theme, it can “extend” another theme. This means that the theme directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of themes for your different users without having to maintain a lot of different themes. For example: you can have your own home-made theme, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom theme, all the themes that inherit from it will be updated automatically. Note that the inheritance is recursive: a theme can extend a theme that extends another one etc.


<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core themes of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface==== 


To extend the Monochrome theme of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome theme. Then, click on “extend” and validate the new name “extends_monochrome”.


If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/themes/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this theme as a normal one from a survey and it will look exactly like the monochrome theme.


[[File:Extends monochrome empty.jpg|center|baseline|border|''The theme tree (directory and files) just after its creation. It's practically empty'']]


<div class="simplebox">[[File:help.png]] The resources (jpg, png etc.) from the original theme are copied when extending a theme. This is because if you copy a CSS file from the original theme locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current theme path. </div>


The theme editor for the extends_monochrome theme looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome theme'']]
<br /><br />
There is no big difference with the old theme editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the theme directory and that the file from the original theme will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to theme views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local theme and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ==== 


The button '''Copy to local theme and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the theme you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button'']]
<br>
If you open a file explorer and go to the directory upload/themes/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your theme'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).


<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the theme to find the image. If the theme you’re working on is extended to another theme, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local theme, it will loop through the theme inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your theme. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/


<div class="simplebox">
So, to add a picture to your theme:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''


* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}


* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list==== 
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which theme the current one extends (if any)

==Template options== 
Another novelty of LS3 is the theme option page. As we’ll see later, theme creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the theme options at global level: click on “theme options” in the theme list
===Advanced options===


{{QS:Theme editor - advanced options}}

===Simple options=== 


The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the theme's /options directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options (Broken link)
<div class="simplebox">[[File:help.png]] This page can be completely different from a theme to another, and theme providers are strongly encouraged to create their own look & feel. </div>


[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from


{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core themes:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a theme provider could add his own animation library or no animation library at all.


<div class="simplebox">[[File:help.png]] The monochrome themes use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for theme providers.</div>

===Inheritance system=== 


In the previous part, we’ve seen that a theme can extend another theme. A theme configuration can also inherit from another theme configuration. It means that for a given theme, you can have a configuration at


* global level (the one we’ve just seen accessible from the theme list)
* at survey group level
* a last one at survey level.


Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

====At survey group level==== 


Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of themes than in the theme list, except that here only the option button is visible (theme editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]


<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

====At survey level==== 
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example== 
Let’s say you’re using a single theme for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core theme. But of course, if you are a theme provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization = 


You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS/JS: deal with the asset manager ("why are my changes not applied?") == 
<br />


If you're trying to update the CSS/JS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.


<br />


Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />


It moves the CSS/JS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css/js file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css/js. Else, they would have to clean their browser cache.


<br />


Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.


<br />


Here the CSS links in header when asset manager is off:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.


<br />


<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>


So, when you're editing CSS/JS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache


[[File:Clearassets-ls3 3.png]]


<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>


Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme == 
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how it works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css


<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>


Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>


You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font === 
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>


You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.


Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options === 
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>


* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %} //Shouldn't this be "theme" in stead of "template"?
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>


<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector === 
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">


'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}


</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79


<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>


Of course, the XML file only contains the default values for your theme configuration. But indeed, those values are defined and read inside the database (table "template_configuration" (Question: "template_" of "theme_"?) as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174


So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

== Adding theme options to control positioning and display of survey elements == 
This tutorial will show how to add options to an extended theme to display survey elements in various locations. In this case, we will create theme options to show the survey title in two different locations.
<div class="simplebox">[[File:help.png]] For the sake of simplicity, we will base the tutorial on an extension of the "bootswatch" theme in LimeSurvey version 3.4.3.</div>
=== Create a custom theme ===
#Extend the "bootswatch" theme as described above.
#Copy <span style="color: #BA2121;">custom.css</span> to the local theme as described above.
===Create new theme options===
#Copy the contents of <span style="color: #BA2121;">/themes/survey/bootswatch/options/</span> to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/</span>.
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/options.twig</span> in an editor and find "{# Bootstrap Bootswatch theme #}". Directly before its parent <nowiki><div class='row'></nowiki> element, add this:<syntaxhighlight lang="html" enclose="div">
{# Custom survey name in navbar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div>


{# Custom survey name below progress bar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div></syntaxhighlight>
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/config.xml</span> and add two items to the "options" block so it looks like this:<syntaxhighlight lang="xml" enclose="div"> <options>
<ajaxmode>on</ajaxmode>
...
<surveyname1>on</surveyname1>
<surveyname2>on</surveyname2>
</options></syntaxhighlight>
#This should give you two new options in the Theme Options screen like this:<br />[[File:Tutorial_tp_1_1.png]]

===Modifed view for Survey Title in the navbar=== 
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/header/</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> and find "{# Logo option #}". Under that, modify the IF statement for the logo/survey-name, so it looks like this:<syntaxhighlight lang="html" enclose="div">
{# Logo option #}
{% if( aSurveyInfo.options.brandlogo == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }} logo-container" {{ aSurveyInfo.attr.navbarbrand }} >
{{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
</div>
{% endif %}
{% if( aSurveyInfo.options.surveyname1 == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }}" {{ aSurveyInfo.attr.navbarbrand }} >
{{ aSurveyInfo.name }}
</div>
{% endif %}</syntaxhighlight>
#Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60px;
font-size: 32px;
}</syntaxhighlight>
#Toggle the "Survey name in navbar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_2.png]]
===Modifed view for Survey Title under progress bar===
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> and add an <nowiki><h1></nowiki> element for the survey name. So it looks like this:<syntaxhighlight lang="html" enclose="div"><div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>

{# Custom survey name #}
{% if( aSurveyInfo.options.surveyname2 == "on") %}
<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
{% endif %}

{# Group Name #}
{{ include('./subviews/survey/group_subviews/group_name.twig') }}

{# Group Description #}
{{ include('./subviews/survey/group_subviews/group_desc.twig') }}

{#
PRESENT THE QUESTIONS

This is the main part. It will render each question for this group
#}


{% for aQuestion in aGroup.aQuestions %}
{{ include('./subviews/survey/question_container.twig') }}
{% endfor %}


{% if aGroup.show_last_group == true %}
<input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
{% endif %}

{% if aGroup.show_last_answer == true %}
<input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
{% endif %}
</div></syntaxhighlight>
# Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60ph1.custom-survey-name {
margin: 0;
text-align: center;
}</syntaxhighlight>
#Toggle the "Survey name below progress bar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_3.png]]

===Downloads=== 
* Sample extended theme: [[Media:Test_survey_names.zip]]

=Creating a theme from scratch= 
Documentation coming soon.

For now, just giving few tips.

==theme structure==

=== Files and directories ===
When you create a Theme from scratch, you don't need to respect the file/directory structure/css/js from Vanilla.
The mandatory css/js is added by core (you can still remove it if needed)

The only files your theme must have are the layout files:

* '''layout_global.twig''' : render the pages for survey taking
* '''layout_survey_list.twig''' : render the survey list (if this theme is set as default)
* '''layout_errors.twig''' : used to render errors that block survey rendering. ( wrong survey id, empty group in preview group, etc.)
* '''layout_user_forms.twig''': renders the user forms such as: token (survey participant), and register.
* '''layout_print.twig''' : used to print the survey to pdf
* '''layout_printanswers.twig''': print the answers

The content of those files, the files they include or not, is entirely up to you.
All the other files and directories that you find on Vanilla are purely optional, feel free to organize your code the way you want.

<div class="simplebox">[[File:help.png]] If you read the frontend rendering code, you'll see that those files names appear directly in it. That's why they are mandatory.
Eg: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/helpers/SurveyRuntimeHelper.php#L462
</div>

=== Content ===

In Vanilla's layout_global.twig, you'll see we use a variable called "include_content" to decide what to show
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/layout_global.twig#L114-L115

<syntaxhighlight lang="php" enclose="div">
{% set sViewContent = './subviews/content/' ~ aSurveyInfo.include_content ~ '.twig' %}
{% include './subviews/content/outerframe.twig' with {'include_content': sViewContent } %}
</syntaxhighlight>

aSurveyInfo.include_content tell you what action is currently going on: showing questions? showing submit result? showing clear all? etc
As you can see, in vanilla, we create one file to include by action. So if you want to know the list of actions, just check the vanilla's directory '''views/subviews/content''', and remove the "twig" extension :
https://github.com/LimeSurvey/LimeSurvey/tree/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/subviews/content

* '''clearall.twig'''
* '''firstpage.twig'''
* '''load.twig'''
* '''mainrow.twig'''
* '''main.twig'''
* '''optin.twig'''
* '''optout.twig'''
* '''outerframe.twig'''
* '''printanswers.twig'''
* '''quotas.twig'''
* '''register.twig'''
* '''save.twig'''
* '''submit_preview.twig'''
* '''submit.twig'''
* '''userforms.twig'''

If you already created a them for 2.x versions of LimeSurvey, you'll notice that most of them corresponds to the old pstpl files for limesurvey 2.x.
Again, there is no obligation for you in your theme to create those files, with those names, in this directory. You could for example just add a giant switch in layout_global.twig with the wanted HTML for each action.

=== The manifest config.xml ===

The manifest of the theme contains the main informations about your theme. When you install a theme, the content of the manifest will be loaded in the database, in two different tables: template and template_configuration. So each time you modify the manifest of a theme, you must uninstall and reinstall it (or just reset it). Because this process is annoying while developing a theme you can force the direct usage of the XML file rather than the DB entries. To do so, in config.phpn turn on debug mode and 'force_xmlsettings_for_survey_rendering' to true.

==== The metadata section ====

Nothing complex: just the main infos about your theme. It will be pushed in the table templates_configuration

<syntaxhighlight lang="xml" enclose="div">
<metadata>
<name>the_name_of_your_theme</name>
<title>The Title of your theme</title>
<creationDate>16/10/2017</creationDate>
<author>Your Name</author>
<authorEmail>your@email.org</authorEmail>
<authorUrl>http://www.yourwebsite.org</authorUrl>
<copyright>Your Copyright </copyright>
<license>Licence of your theme</license>
<version>version of your theme</version>
<apiVersion>3</apiVersion>
<description>Description of your theme</description>
</metadata>
</syntaxhighlight>

Few remarks:
* '''name''': will be used as a key in the db. So it must be unique, and it should not have any special chars (no spaces). Note that cases will not be taken in account
* '''Title''': will be used to display your theme name in the different lists. It can have special chars
* '''description''': will be used in the main list of survey theme. It can contains special chars, and even HTML code by using <![CDATA[

==== The files section ====

This one is an important one. It will be pushed in the table template_configuration, in the field files_css, files_js, files_print_css as json arrays.

Eg: the files section of the Material Premium Theme:

<syntaxhighlight lang="xml" enclose="div">
<files>
<css>
<add>css/bootstrap-material-design.css</add>
<add>css/ripples.min.css</add>
<replace>css/ajaxify.css</replace>
<replace>css/theme.css</replace>
<replace>css/custom.css</replace>
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</css>
<js>
<replace>scripts/theme.js</replace>
<replace>scripts/ajaxify.js</replace>
<add>scripts/material.js</add>
<add>scripts/ripples.min.js</add>
<replace>scripts/custom.js</replace>
</js>
<print_css>
<add>css/print_theme.css</add>
</print_css>
</files>
</syntaxhighlight>

All the CSS/JS files present in this section will be loaded at the launch of the survey (in ajax mode. If ajax mode is off, then of course all the files are reloaded at each page).

They will be added to a Yii Asset Packet based on the name of the theme. So when Asset Manager is on (debug mode being off), those files will be copied to the tmp directory with the rest of the theme (so you can use relative path in the CSS and JS to reach the image files).
About the Asset manager in Yii: https://www.yiiframework.com/wiki/148/understanding-assets
About packages in Yii: http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail

They will use the inheritance system. It means that if you add a CSS/JS file to a theme, but it's not present in the theme, then the engine will look into all the mother themes of this theme and will use the first one it finds. So if a user extends your theme via the theme editor, all those files will be inherited in his theme. The keywords refer to this inheritance system.

* '''add''' : it will add the file to the theme, and to all its inherited theme
* '''replace''': it will replace the the file of its mother theme
* '''remove''': it will remove the file from '''any''' package, even the core package (since 3.14)

<div class="simplebox">[[File:help.png]] Remember you can set in config.php 'force_xmlsettings_for_survey_rendering' so configuration is read from XML instead of DB (no reset needed). This will make easier to test the modifications of the XML files, and will avoid you to uninstall/reinstall theme at each modification of the XML </div>

Few remarks on those keywords:

===== Inheritance tips =====
As explained before, the "add" keyword can refer to a file being in one of the mother theme. So you can "add" a file in this section, and still not having this file in your theme, but in one of its parents theme. The engine will look into all its parent themes and will use the first one it finds. If it can't find the file, and debug mode is on in config, and js frontend debug mode is on in global setting, a message in console will warn you. Eg: if we add in a my_theme: <add>css/unexisting.css</add>, in the console we'll see:

<syntaxhighlight lang="" enclose="div">
(¯`·._.·(¯`·._.· Theme Configuration Error ·._.·´¯)·._.·´¯)

Can't find file 'css/unexisting.css' defined in theme 'my_theme'
</syntaxhighlight>

If the debug mode is off, then no error at all will be seen. The engine will just ignore the wrong add statements.

===== When to use add, when to use replace, when can I just leave it to the parent theme? =====

First: add and replace are the very same keyword. You can use the one or the other, the engine will just do the same. They are distinct for human readers, so they understand what was your intention.

You can't add a file with the same name as the mother theme: it will always replace it. eg: If you have a file called "my_mother_theme/foo.css" and you add a file called "foo.cs" in the daughter theme, only "daughter_theme/foo.css" will be added to the theme. If you want to keep "my_mother_theme/foo.css", just choose another name for "daughter_theme/foo.css", like "daughter_theme/bar.css". So the keyword "add" can be used as a "replace" keyword.

If you wonder why: this make much easier the automatic generation of inherited theme, copying the file section works out of the box (no need to rename "add" to "replace" when extending one the file).

To make it clear, let's take the Fruity example. Here its css file section:

<syntaxhighlight lang="xml" enclose="div">
<css>
<add>css/variations/sea_green.css</add>
<replace>css/animate.css</replace>
<replace>css/theme.css</replace>
<replace>css/custom.css</replace>
</css>
</syntaxhighlight>

If you look to the custom.css file in fruity, it is exactly the same as the vanilla one. We could delete the custom.css file inside fruity, the one of vanilla would loaded. We could remove the statement <replace>custom.css</replace> from the Fruity manifest, the statement from vanilla will be used, and the vanilla custom.css would be loaded.

So why do we use the statement <replace>custom.css</replace> inside the fruity manifest? The answer is easy: because we want the end user to be able to extend the fruity theme, to modify the file in his local theme, and to load this modified file from his inherited theme. To understand, just extend fruity and have a look to the extended theme. THe extended theme doesn't even have the file custom.css. So the one of fruity will be used. But: if the user create this file in the extended theme (by clicking on "extend" in the theme editor), then this file will be loaded from his theme.

So in general:
if you create a theme from scratch not extending any theme, just use the add statement to add your css/js files. Easy peasy.
if you create a theme extending another theme, and you don't want the users to be able to extends the css/js file from the mother theme: don't use the add statement in your manifest. THe files will still be loaded from the mother theme configuration.
if you create a theme extending another theme, and you want to replace a file from the mother theme: use the replace keyword (the add keyword will have the same result)
if you create a theme extending another theme, if you don't replace a given file from css/js, but you want the users to be able to extend this file: then use the "replace" statement in your manifest for this file. Even if you don't replace the file, by using the keyword replace in the manifest: you allow the user to do it if he wants to do it.

Only this very last case needs a bit of mental gymnastic ot understand, all the other cases are trivial.

<div class="simplebox">[[File:help.png]]
You can also register CSS and JS files directly from the twig code. Those files will be loaded only when the twig file is asked. If you want the users to be able to inherit those JS/Css files from the theme editor, remember to use the functions {{registerTemplateCssFile('my_style.css')}} and {{registerTemplateScript('my_script.js')}}. If you don't use those functions, your theme may work, but inheritance on it will be broken. It is the same logic as the {{image('my_picture.jpg')}} function
</div>

===== The remove keyword =====

The remove keyword is available only since 3.14. With this one, you can remove any css/file from any package, even the core ones. It is used in Material Premium Theme to remove the Awseome Bootstrap Checkbox's files:

<syntaxhighlight lang="xml" enclose="div">
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</syntaxhighlight>

so you should use the very same syntax as the package's file (eg: "awesome-bootstrap-checkbox.css" alone without it's folder path would not work). You'll find the complete list of core packages and their files in /application/config/packages.php and config/third_party.php. For example, for awesome-bootstrap-checkbox.css:
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/config/packages.php#L54-L56

<syntaxhighlight lang="php" enclose="div">
'css'=> array(
'awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css',
),
</syntaxhighlight>

Another way to find the exact name to use in the remove tag is to turn asset manager on (turning debug mode off or setting 'use_asset_manager'=>true in the config). Then, the path to use will be the one just after the random directory in the tmp directory. For example, for awesome-bootstrap-checkbox.css:
<syntaxhighlight lang="html" enclose="div">
<link rel="stylesheet" type="text/css" href="/tmp/assets/cbc4e3cb/awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css" />
</syntaxhighlight>

==== The options section ====

This section is relative to the option of your theme. It will be used to feed the filed "options" of the table template_configuration as a json array.

== Some notes ==


'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.


'''NOTE''': to avoid that, you can force the use to the XML rather than DB. In config.php turn debug mode on and uncommment:


'force_xmlsettings_for_survey_rendering' => true, // Uncomment if you want to force the use of the XML file rather than DB (for easy theme development)


Becareful: everything will be loaded from the XML (included options, etc)


'''NOTE''': if you manually edit the CSS/JS files (without using the Theme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache".


'''NOTE''': if you remove the section

</translate>

New Template System in LS3.x

2018-08-13T13:05:22Z

LouisGac: /* When to use add, when to use replace, when can I just leave it to the parent theme? */

<languages />
<translate>

__TOC__
=Introduction= 


On this page you'll learn how to:


* Use the new theme system of LimeSurvey 3.0.
* Use inheritance to manage your own themes.
* Add a picture to your theme
* Manage theme options for your surveys and survey groups


<hr/>


LimeSurvey 3 introduces a complete new theme engine system, based on Twig 1.29, Bootstrap, and allowing theme inheritance and theme options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old theme system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A theme designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new theme engine.


<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Theme Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface= 
==theme list==
On the admin dashboard, there is now a box to access the theme list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The theme list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the theme: it’s just a picture file called “preview.png” at the root of the theme
* the “title” of the theme as specified in the manifest (config.xml in the root of the theme)
* the description of the theme: a string set in its manifest
* the type of theme: Core theme (provided with LimeSurvey), User theme (added in upload directory), XML theme (not loaded in database)
* Extends: if the theme extends another theme, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a theme to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a theme in the database
** Theme editor: it will redirect you to the theme editor
** Theme option: it will lead you the global configuration of theme options

==Theme Editor== 
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' theme'']]

====A quick overview of the concept of theme inheritance==== 


In LS3, a theme can now inherit from another theme, it can “extend” another theme. This means that the theme directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of themes for your different users without having to maintain a lot of different themes. For example: you can have your own home-made theme, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom theme, all the themes that inherit from it will be updated automatically. Note that the inheritance is recursive: a theme can extend a theme that extends another one etc.


<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core themes of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface==== 


To extend the Monochrome theme of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome theme. Then, click on “extend” and validate the new name “extends_monochrome”.


If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/themes/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this theme as a normal one from a survey and it will look exactly like the monochrome theme.


[[File:Extends monochrome empty.jpg|center|baseline|border|''The theme tree (directory and files) just after its creation. It's practically empty'']]


<div class="simplebox">[[File:help.png]] The resources (jpg, png etc.) from the original theme are copied when extending a theme. This is because if you copy a CSS file from the original theme locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current theme path. </div>


The theme editor for the extends_monochrome theme looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome theme'']]
<br /><br />
There is no big difference with the old theme editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the theme directory and that the file from the original theme will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to theme views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local theme and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ==== 


The button '''Copy to local theme and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the theme you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button'']]
<br>
If you open a file explorer and go to the directory upload/themes/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your theme'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).


<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the theme to find the image. If the theme you’re working on is extended to another theme, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local theme, it will loop through the theme inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your theme. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/


<div class="simplebox">
So, to add a picture to your theme:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''


* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}


* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list==== 
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which theme the current one extends (if any)

==Template options== 
Another novelty of LS3 is the theme option page. As we’ll see later, theme creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the theme options at global level: click on “theme options” in the theme list
===Advanced options===


{{QS:Theme editor - advanced options}}

===Simple options=== 


The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the theme's /options directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options (Broken link)
<div class="simplebox">[[File:help.png]] This page can be completely different from a theme to another, and theme providers are strongly encouraged to create their own look & feel. </div>


[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from


{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core themes:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a theme provider could add his own animation library or no animation library at all.


<div class="simplebox">[[File:help.png]] The monochrome themes use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for theme providers.</div>

===Inheritance system=== 


In the previous part, we’ve seen that a theme can extend another theme. A theme configuration can also inherit from another theme configuration. It means that for a given theme, you can have a configuration at


* global level (the one we’ve just seen accessible from the theme list)
* at survey group level
* a last one at survey level.


Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

====At survey group level==== 


Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of themes than in the theme list, except that here only the option button is visible (theme editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]


<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

====At survey level==== 
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example== 
Let’s say you’re using a single theme for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core theme. But of course, if you are a theme provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization = 


You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS/JS: deal with the asset manager ("why are my changes not applied?") == 
<br />


If you're trying to update the CSS/JS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.


<br />


Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />


It moves the CSS/JS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css/js file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css/js. Else, they would have to clean their browser cache.


<br />


Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.


<br />


Here the CSS links in header when asset manager is off:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.


<br />


<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>


So, when you're editing CSS/JS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache


[[File:Clearassets-ls3 3.png]]


<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>


Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme == 
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how it works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css


<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>


Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>


You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font === 
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>


You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.


Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options === 
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>


* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %} //Shouldn't this be "theme" in stead of "template"?
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>


<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector === 
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">


'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}


</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79


<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>


Of course, the XML file only contains the default values for your theme configuration. But indeed, those values are defined and read inside the database (table "template_configuration" (Question: "template_" of "theme_"?) as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174


So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

== Adding theme options to control positioning and display of survey elements == 
This tutorial will show how to add options to an extended theme to display survey elements in various locations. In this case, we will create theme options to show the survey title in two different locations.
<div class="simplebox">[[File:help.png]] For the sake of simplicity, we will base the tutorial on an extension of the "bootswatch" theme in LimeSurvey version 3.4.3.</div>
=== Create a custom theme ===
#Extend the "bootswatch" theme as described above.
#Copy <span style="color: #BA2121;">custom.css</span> to the local theme as described above.
===Create new theme options===
#Copy the contents of <span style="color: #BA2121;">/themes/survey/bootswatch/options/</span> to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/</span>.
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/options.twig</span> in an editor and find "{# Bootstrap Bootswatch theme #}". Directly before its parent <nowiki><div class='row'></nowiki> element, add this:<syntaxhighlight lang="html" enclose="div">
{# Custom survey name in navbar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div>


{# Custom survey name below progress bar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div></syntaxhighlight>
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/config.xml</span> and add two items to the "options" block so it looks like this:<syntaxhighlight lang="xml" enclose="div"> <options>
<ajaxmode>on</ajaxmode>
...
<surveyname1>on</surveyname1>
<surveyname2>on</surveyname2>
</options></syntaxhighlight>
#This should give you two new options in the Theme Options screen like this:<br />[[File:Tutorial_tp_1_1.png]]

===Modifed view for Survey Title in the navbar=== 
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/header/</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> and find "{# Logo option #}". Under that, modify the IF statement for the logo/survey-name, so it looks like this:<syntaxhighlight lang="html" enclose="div">
{# Logo option #}
{% if( aSurveyInfo.options.brandlogo == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }} logo-container" {{ aSurveyInfo.attr.navbarbrand }} >
{{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
</div>
{% endif %}
{% if( aSurveyInfo.options.surveyname1 == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }}" {{ aSurveyInfo.attr.navbarbrand }} >
{{ aSurveyInfo.name }}
</div>
{% endif %}</syntaxhighlight>
#Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60px;
font-size: 32px;
}</syntaxhighlight>
#Toggle the "Survey name in navbar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_2.png]]
===Modifed view for Survey Title under progress bar===
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> and add an <nowiki><h1></nowiki> element for the survey name. So it looks like this:<syntaxhighlight lang="html" enclose="div"><div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>

{# Custom survey name #}
{% if( aSurveyInfo.options.surveyname2 == "on") %}
<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
{% endif %}

{# Group Name #}
{{ include('./subviews/survey/group_subviews/group_name.twig') }}

{# Group Description #}
{{ include('./subviews/survey/group_subviews/group_desc.twig') }}

{#
PRESENT THE QUESTIONS

This is the main part. It will render each question for this group
#}


{% for aQuestion in aGroup.aQuestions %}
{{ include('./subviews/survey/question_container.twig') }}
{% endfor %}


{% if aGroup.show_last_group == true %}
<input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
{% endif %}

{% if aGroup.show_last_answer == true %}
<input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
{% endif %}
</div></syntaxhighlight>
# Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60ph1.custom-survey-name {
margin: 0;
text-align: center;
}</syntaxhighlight>
#Toggle the "Survey name below progress bar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_3.png]]

===Downloads=== 
* Sample extended theme: [[Media:Test_survey_names.zip]]

=Creating a theme from scratch= 
Documentation coming soon.

For now, just giving few tips.

==theme structure==

=== Files and directories ===
When you create a Theme from scratch, you don't need to respect the file/directory structure/css/js from Vanilla.
The mandatory css/js is added by core (you can still remove it if needed)

The only files your theme must have are the layout files:

* '''layout_global.twig''' : render the pages for survey taking
* '''layout_survey_list.twig''' : render the survey list (if this theme is set as default)
* '''layout_errors.twig''' : used to render errors that block survey rendering. ( wrong survey id, empty group in preview group, etc.)
* '''layout_user_forms.twig''': renders the user forms such as: token (survey participant), and register.
* '''layout_print.twig''' : used to print the survey to pdf
* '''layout_printanswers.twig''': print the answers

The content of those files, the files they include or not, is entirely up to you.
All the other files and directories that you find on Vanilla are purely optional, feel free to organize your code the way you want.

<div class="simplebox">[[File:help.png]] If you read the frontend rendering code, you'll see that those files names appear directly in it. That's why they are mandatory.
Eg: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/helpers/SurveyRuntimeHelper.php#L462
</div>

=== Content ===

In Vanilla's layout_global.twig, you'll see we use a variable called "include_content" to decide what to show
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/layout_global.twig#L114-L115

<syntaxhighlight lang="php" enclose="div">
{% set sViewContent = './subviews/content/' ~ aSurveyInfo.include_content ~ '.twig' %}
{% include './subviews/content/outerframe.twig' with {'include_content': sViewContent } %}
</syntaxhighlight>

aSurveyInfo.include_content tell you what action is currently going on: showing questions? showing submit result? showing clear all? etc
As you can see, in vanilla, we create one file to include by action. So if you want to know the list of actions, just check the vanilla's directory '''views/subviews/content''', and remove the "twig" extension :
https://github.com/LimeSurvey/LimeSurvey/tree/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/subviews/content

* '''clearall.twig'''
* '''firstpage.twig'''
* '''load.twig'''
* '''mainrow.twig'''
* '''main.twig'''
* '''optin.twig'''
* '''optout.twig'''
* '''outerframe.twig'''
* '''printanswers.twig'''
* '''quotas.twig'''
* '''register.twig'''
* '''save.twig'''
* '''submit_preview.twig'''
* '''submit.twig'''
* '''userforms.twig'''

If you already created a them for 2.x versions of LimeSurvey, you'll notice that most of them corresponds to the old pstpl files for limesurvey 2.x.
Again, there is no obligation for you in your theme to create those files, with those names, in this directory. You could for example just add a giant switch in layout_global.twig with the wanted HTML for each action.

=== The manifest config.xml ===

The manifest of the theme contains the main informations about your theme. When you install a theme, the content of the manifest will be loaded in the database, in two different tables: template and template_configuration. So each time you modify the manifest of a theme, you must uninstall and reinstall it (or just reset it). Because this process is annoying while developing a theme you can force the direct usage of the XML file rather than the DB entries. To do so, in config.phpn turn on debug mode and 'force_xmlsettings_for_survey_rendering' to true.

==== The metadata section ====

Nothing complex: just the main infos about your theme. It will be pushed in the table templates_configuration

<syntaxhighlight lang="xml" enclose="div">
<metadata>
<name>the_name_of_your_theme</name>
<title>The Title of your theme</title>
<creationDate>16/10/2017</creationDate>
<author>Your Name</author>
<authorEmail>your@email.org</authorEmail>
<authorUrl>http://www.yourwebsite.org</authorUrl>
<copyright>Your Copyright </copyright>
<license>Licence of your theme</license>
<version>version of your theme</version>
<apiVersion>3</apiVersion>
<description>Description of your theme</description>
</metadata>
</syntaxhighlight>

Few remarks:
* '''name''': will be used as a key in the db. So it must be unique, and it should not have any special chars (no spaces). Note that cases will not be taken in account
* '''Title''': will be used to display your theme name in the different lists. It can have special chars
* '''description''': will be used in the main list of survey theme. It can contains special chars, and even HTML code by using <![CDATA[

==== The files section ====

This one is an important one. It will be pushed in the table template_configuration, in the field files_css, files_js, files_print_css as json arrays.

Eg: the files section of the Material Premium Theme:

<syntaxhighlight lang="xml" enclose="div">
<files>
<css>
<add>css/bootstrap-material-design.css</add>
<add>css/ripples.min.css</add>
<add>css/ajaxify.css</add>
<add>css/theme.css</add>
<add>css/custom.css</add>
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</css>
<js>
<add>scripts/theme.js</add>
<add>scripts/ajaxify.js</add>
<add>scripts/material.js</add>
<add>scripts/ripples.min.js</add>
<add>scripts/custom.js</add>
</js>
<print_css>
<add>css/print_theme.css</add>
</print_css>
</files>
</syntaxhighlight>

All the CSS/JS files present in this section will be loaded at the launch of the survey (in ajax mode. If ajax mode is off, then of course all the files are reloaded at each page).

They will be added to a Yii Asset Packet based on the name of the theme. So when Asset Manager is on (debug mode being off), those files will be copied to the tmp directory with the rest of the theme (so you can use relative path in the CSS and JS to reach the image files).
About the Asset manager in Yii: https://www.yiiframework.com/wiki/148/understanding-assets
About packages in Yii: http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail

They will use the inheritance system. It means that if you add a CSS/JS file to a theme, but it's not present in the theme, then the engine will look into all the mother themes of this theme and will use the first one it finds. So if a user extends your theme via the theme editor, all those files will be inherited in his theme. The keywords refer to this inheritance system.

* '''add''' : it will add the file to the theme, and to all its inherited theme
* '''replace''': it will replace the the file of its mother theme
* '''remove''': it will remove the file from '''any''' package, even the core package (since 3.14)

<div class="simplebox">[[File:help.png]] Remember you can set in config.php 'force_xmlsettings_for_survey_rendering' so configuration is read from XML instead of DB (no reset needed). This will make easier to test the modifications of the XML files, and will avoid you to uninstall/reinstall theme at each modification of the XML </div>

Few remarks on those keywords:

===== Inheritance tips =====
As explained before, the "add" keyword can refer to a file being in one of the mother theme. So you can "add" a file in this section, and still not having this file in your theme, but in one of its parents theme. The engine will look into all its parent themes and will use the first one it finds. If it can't find the file, and debug mode is on in config, and js frontend debug mode is on in global setting, a message in console will warn you. Eg: if we add in a my_theme: <add>css/unexisting.css</add>, in the console we'll see:

<syntaxhighlight lang="" enclose="div">
(¯`·._.·(¯`·._.· Theme Configuration Error ·._.·´¯)·._.·´¯)

Can't find file 'css/unexisting.css' defined in theme 'my_theme'
</syntaxhighlight>

If the debug mode is off, then no error at all will be seen. The engine will just ignore the wrong add statements.

===== When to use add, when to use replace, when can I just leave it to the parent theme? =====

First: add and replace are the very same keyword. You can use the one or the other, the engine will just do the same. They are distinct for human readers, so they understand what was your intention.

You can't add a file with the same name as the mother theme: it will always replace it. eg: If you have a file called "my_mother_theme/foo.css" and you add a file called "foo.cs" in the daughter theme, only "daughter_theme/foo.css" will be added to the theme. If you want to keep "my_mother_theme/foo.css", just choose another name for "daughter_theme/foo.css", like "daughter_theme/bar.css". So the keyword "add" can be used as a "replace" keyword.

If you wonder why: this make much easier the automatic generation of inherited theme, copying the file section works out of the box (no need to rename "add" to "replace" when extending one the file).

To make it clear, let's take the Fruity example. Here its css file section:

<syntaxhighlight lang="xml" enclose="div">
<css>
<add>css/variations/sea_green.css</add>
<replace>css/animate.css</replace>
<replace>css/theme.css</replace>
<replace>css/custom.css</replace>
</css>
</syntaxhighlight>

If you look to the custom.css file in fruity, it is exactly the same as the vanilla one. We could delete the custom.css file inside fruity, the one of vanilla would loaded. We could remove the statement <replace>custom.css</replace> from the Fruity manifest, the statement from vanilla will be used, and the vanilla custom.css would be loaded.

So why do we use the statement <replace>custom.css</replace> inside the fruity manifest? The answer is easy: because we want the end user to be able to extend the fruity theme, to modify the file in his local theme, and to load this modified file from his inherited theme. To understand, just extend fruity and have a look to the extended theme. THe extended theme doesn't even have the file custom.css. So the one of fruity will be used. But: if the user create this file in the extended theme (by clicking on "extend" in the theme editor), then this file will be loaded from his theme.

So in general:
if you create a theme from scratch not extending any theme, just use the add statement to add your css/js files. Easy peasy.
if you create a theme extending another theme, and you don't want the users to be able to extends the css/js file from the mother theme: don't use the add statement in your manifest. THe files will still be loaded from the mother theme configuration.
if you create a theme extending another theme, and you want to replace a file from the mother theme: use the replace keyword (the add keyword will have the same result)
if you create a theme extending another theme, if you don't replace a given file from css/js, but you want the users to be able to extend this file: then use the "replace" statement in your manifest for this file. Even if you don't replace the file, by using the keyword replace in the manifest: you allow the user to do it if he wants to do it.

Only this very last case needs a bit of mental gymnastic ot understand, all the other cases are trivial.

<div class="simplebox">[[File:help.png]]
You can also register CSS and JS files directly from the twig code. Those files will be loaded only when the twig file is asked. If you want the users to be able to inherit those JS/Css files from the theme editor, remember to use the functions {{registerTemplateCssFile('my_style.css')}} and {{registerTemplateScript('my_script.js')}}. If you don't use those functions, your theme may work, but inheritance on it will be broken. It is the same logic as the {{image('my_picture.jpg')}} function
</div>

===== The remove keyword =====

The remove keyword is available only since 3.14. With this one, you can remove any css/file from any package, even the core ones. It is used in Material Premium Theme to remove the Awseome Bootstrap Checkbox's files:

<syntaxhighlight lang="xml" enclose="div">
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</syntaxhighlight>

so you should use the very same syntax as the package's file (eg: "awesome-bootstrap-checkbox.css" alone without it's folder path would not work). You'll find the complete list of core packages and their files in /application/config/packages.php and config/third_party.php. For example, for awesome-bootstrap-checkbox.css:
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/config/packages.php#L54-L56

<syntaxhighlight lang="php" enclose="div">
'css'=> array(
'awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css',
),
</syntaxhighlight>

Another way to find the exact name to use in the remove tag is to turn asset manager on (turning debug mode off or setting 'use_asset_manager'=>true in the config). Then, the path to use will be the one just after the random directory in the tmp directory. For example, for awesome-bootstrap-checkbox.css:
<syntaxhighlight lang="html" enclose="div">
<link rel="stylesheet" type="text/css" href="/tmp/assets/cbc4e3cb/awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css" />
</syntaxhighlight>

==== The options section ====

This section is relative to the option of your theme. It will be used to feed the filed "options" of the table template_configuration as a json array.

== Some notes ==


'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.


'''NOTE''': to avoid that, you can force the use to the XML rather than DB. In config.php turn debug mode on and uncommment:


'force_xmlsettings_for_survey_rendering' => true, // Uncomment if you want to force the use of the XML file rather than DB (for easy theme development)


Becareful: everything will be loaded from the XML (included options, etc)


'''NOTE''': if you manually edit the CSS/JS files (without using the Theme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache".


'''NOTE''': if you remove the section

</translate>

New Template System in LS3.x

2018-08-13T13:03:54Z

LouisGac: /* The remove keyword */

<languages />
<translate>

__TOC__
=Introduction= 


On this page you'll learn how to:


* Use the new theme system of LimeSurvey 3.0.
* Use inheritance to manage your own themes.
* Add a picture to your theme
* Manage theme options for your surveys and survey groups


<hr/>


LimeSurvey 3 introduces a complete new theme engine system, based on Twig 1.29, Bootstrap, and allowing theme inheritance and theme options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old theme system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A theme designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new theme engine.


<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Theme Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface= 
==theme list==
On the admin dashboard, there is now a box to access the theme list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The theme list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the theme: it’s just a picture file called “preview.png” at the root of the theme
* the “title” of the theme as specified in the manifest (config.xml in the root of the theme)
* the description of the theme: a string set in its manifest
* the type of theme: Core theme (provided with LimeSurvey), User theme (added in upload directory), XML theme (not loaded in database)
* Extends: if the theme extends another theme, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a theme to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a theme in the database
** Theme editor: it will redirect you to the theme editor
** Theme option: it will lead you the global configuration of theme options

==Theme Editor== 
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' theme'']]

====A quick overview of the concept of theme inheritance==== 


In LS3, a theme can now inherit from another theme, it can “extend” another theme. This means that the theme directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of themes for your different users without having to maintain a lot of different themes. For example: you can have your own home-made theme, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom theme, all the themes that inherit from it will be updated automatically. Note that the inheritance is recursive: a theme can extend a theme that extends another one etc.


<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core themes of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface==== 


To extend the Monochrome theme of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome theme. Then, click on “extend” and validate the new name “extends_monochrome”.


If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/themes/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this theme as a normal one from a survey and it will look exactly like the monochrome theme.


[[File:Extends monochrome empty.jpg|center|baseline|border|''The theme tree (directory and files) just after its creation. It's practically empty'']]


<div class="simplebox">[[File:help.png]] The resources (jpg, png etc.) from the original theme are copied when extending a theme. This is because if you copy a CSS file from the original theme locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current theme path. </div>


The theme editor for the extends_monochrome theme looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome theme'']]
<br /><br />
There is no big difference with the old theme editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the theme directory and that the file from the original theme will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to theme views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local theme and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ==== 


The button '''Copy to local theme and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the theme you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button'']]
<br>
If you open a file explorer and go to the directory upload/themes/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your theme'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).


<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the theme to find the image. If the theme you’re working on is extended to another theme, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local theme, it will loop through the theme inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your theme. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/


<div class="simplebox">
So, to add a picture to your theme:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''


* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}


* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list==== 
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which theme the current one extends (if any)

==Template options== 
Another novelty of LS3 is the theme option page. As we’ll see later, theme creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the theme options at global level: click on “theme options” in the theme list
===Advanced options===


{{QS:Theme editor - advanced options}}

===Simple options=== 


The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the theme's /options directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options (Broken link)
<div class="simplebox">[[File:help.png]] This page can be completely different from a theme to another, and theme providers are strongly encouraged to create their own look & feel. </div>


[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from


{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core themes:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a theme provider could add his own animation library or no animation library at all.


<div class="simplebox">[[File:help.png]] The monochrome themes use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for theme providers.</div>

===Inheritance system=== 


In the previous part, we’ve seen that a theme can extend another theme. A theme configuration can also inherit from another theme configuration. It means that for a given theme, you can have a configuration at


* global level (the one we’ve just seen accessible from the theme list)
* at survey group level
* a last one at survey level.


Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

====At survey group level==== 


Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of themes than in the theme list, except that here only the option button is visible (theme editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]


<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

====At survey level==== 
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example== 
Let’s say you’re using a single theme for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core theme. But of course, if you are a theme provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization = 


You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS/JS: deal with the asset manager ("why are my changes not applied?") == 
<br />


If you're trying to update the CSS/JS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.


<br />


Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />


It moves the CSS/JS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css/js file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css/js. Else, they would have to clean their browser cache.


<br />


Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.


<br />


Here the CSS links in header when asset manager is off:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.


<br />


<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>


So, when you're editing CSS/JS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache


[[File:Clearassets-ls3 3.png]]


<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>


Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme == 
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how it works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css


<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>


Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>


You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font === 
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>


You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.


Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options === 
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>


* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %} //Shouldn't this be "theme" in stead of "template"?
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>


<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector === 
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">


'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}


</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79


<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>


Of course, the XML file only contains the default values for your theme configuration. But indeed, those values are defined and read inside the database (table "template_configuration" (Question: "template_" of "theme_"?) as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174


So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

== Adding theme options to control positioning and display of survey elements == 
This tutorial will show how to add options to an extended theme to display survey elements in various locations. In this case, we will create theme options to show the survey title in two different locations.
<div class="simplebox">[[File:help.png]] For the sake of simplicity, we will base the tutorial on an extension of the "bootswatch" theme in LimeSurvey version 3.4.3.</div>
=== Create a custom theme ===
#Extend the "bootswatch" theme as described above.
#Copy <span style="color: #BA2121;">custom.css</span> to the local theme as described above.
===Create new theme options===
#Copy the contents of <span style="color: #BA2121;">/themes/survey/bootswatch/options/</span> to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/</span>.
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/options.twig</span> in an editor and find "{# Bootstrap Bootswatch theme #}". Directly before its parent <nowiki><div class='row'></nowiki> element, add this:<syntaxhighlight lang="html" enclose="div">
{# Custom survey name in navbar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div>


{# Custom survey name below progress bar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div></syntaxhighlight>
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/config.xml</span> and add two items to the "options" block so it looks like this:<syntaxhighlight lang="xml" enclose="div"> <options>
<ajaxmode>on</ajaxmode>
...
<surveyname1>on</surveyname1>
<surveyname2>on</surveyname2>
</options></syntaxhighlight>
#This should give you two new options in the Theme Options screen like this:<br />[[File:Tutorial_tp_1_1.png]]

===Modifed view for Survey Title in the navbar=== 
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/header/</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> and find "{# Logo option #}". Under that, modify the IF statement for the logo/survey-name, so it looks like this:<syntaxhighlight lang="html" enclose="div">
{# Logo option #}
{% if( aSurveyInfo.options.brandlogo == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }} logo-container" {{ aSurveyInfo.attr.navbarbrand }} >
{{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
</div>
{% endif %}
{% if( aSurveyInfo.options.surveyname1 == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }}" {{ aSurveyInfo.attr.navbarbrand }} >
{{ aSurveyInfo.name }}
</div>
{% endif %}</syntaxhighlight>
#Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60px;
font-size: 32px;
}</syntaxhighlight>
#Toggle the "Survey name in navbar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_2.png]]
===Modifed view for Survey Title under progress bar===
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> and add an <nowiki><h1></nowiki> element for the survey name. So it looks like this:<syntaxhighlight lang="html" enclose="div"><div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>

{# Custom survey name #}
{% if( aSurveyInfo.options.surveyname2 == "on") %}
<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
{% endif %}

{# Group Name #}
{{ include('./subviews/survey/group_subviews/group_name.twig') }}

{# Group Description #}
{{ include('./subviews/survey/group_subviews/group_desc.twig') }}

{#
PRESENT THE QUESTIONS

This is the main part. It will render each question for this group
#}


{% for aQuestion in aGroup.aQuestions %}
{{ include('./subviews/survey/question_container.twig') }}
{% endfor %}


{% if aGroup.show_last_group == true %}
<input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
{% endif %}

{% if aGroup.show_last_answer == true %}
<input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
{% endif %}
</div></syntaxhighlight>
# Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60ph1.custom-survey-name {
margin: 0;
text-align: center;
}</syntaxhighlight>
#Toggle the "Survey name below progress bar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_3.png]]

===Downloads=== 
* Sample extended theme: [[Media:Test_survey_names.zip]]

=Creating a theme from scratch= 
Documentation coming soon.

For now, just giving few tips.

==theme structure==

=== Files and directories ===
When you create a Theme from scratch, you don't need to respect the file/directory structure/css/js from Vanilla.
The mandatory css/js is added by core (you can still remove it if needed)

The only files your theme must have are the layout files:

* '''layout_global.twig''' : render the pages for survey taking
* '''layout_survey_list.twig''' : render the survey list (if this theme is set as default)
* '''layout_errors.twig''' : used to render errors that block survey rendering. ( wrong survey id, empty group in preview group, etc.)
* '''layout_user_forms.twig''': renders the user forms such as: token (survey participant), and register.
* '''layout_print.twig''' : used to print the survey to pdf
* '''layout_printanswers.twig''': print the answers

The content of those files, the files they include or not, is entirely up to you.
All the other files and directories that you find on Vanilla are purely optional, feel free to organize your code the way you want.

<div class="simplebox">[[File:help.png]] If you read the frontend rendering code, you'll see that those files names appear directly in it. That's why they are mandatory.
Eg: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/helpers/SurveyRuntimeHelper.php#L462
</div>

=== Content ===

In Vanilla's layout_global.twig, you'll see we use a variable called "include_content" to decide what to show
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/layout_global.twig#L114-L115

<syntaxhighlight lang="php" enclose="div">
{% set sViewContent = './subviews/content/' ~ aSurveyInfo.include_content ~ '.twig' %}
{% include './subviews/content/outerframe.twig' with {'include_content': sViewContent } %}
</syntaxhighlight>

aSurveyInfo.include_content tell you what action is currently going on: showing questions? showing submit result? showing clear all? etc
As you can see, in vanilla, we create one file to include by action. So if you want to know the list of actions, just check the vanilla's directory '''views/subviews/content''', and remove the "twig" extension :
https://github.com/LimeSurvey/LimeSurvey/tree/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/subviews/content

* '''clearall.twig'''
* '''firstpage.twig'''
* '''load.twig'''
* '''mainrow.twig'''
* '''main.twig'''
* '''optin.twig'''
* '''optout.twig'''
* '''outerframe.twig'''
* '''printanswers.twig'''
* '''quotas.twig'''
* '''register.twig'''
* '''save.twig'''
* '''submit_preview.twig'''
* '''submit.twig'''
* '''userforms.twig'''

If you already created a them for 2.x versions of LimeSurvey, you'll notice that most of them corresponds to the old pstpl files for limesurvey 2.x.
Again, there is no obligation for you in your theme to create those files, with those names, in this directory. You could for example just add a giant switch in layout_global.twig with the wanted HTML for each action.

=== The manifest config.xml ===

The manifest of the theme contains the main informations about your theme. When you install a theme, the content of the manifest will be loaded in the database, in two different tables: template and template_configuration. So each time you modify the manifest of a theme, you must uninstall and reinstall it (or just reset it). Because this process is annoying while developing a theme you can force the direct usage of the XML file rather than the DB entries. To do so, in config.phpn turn on debug mode and 'force_xmlsettings_for_survey_rendering' to true.

==== The metadata section ====

Nothing complex: just the main infos about your theme. It will be pushed in the table templates_configuration

<syntaxhighlight lang="xml" enclose="div">
<metadata>
<name>the_name_of_your_theme</name>
<title>The Title of your theme</title>
<creationDate>16/10/2017</creationDate>
<author>Your Name</author>
<authorEmail>your@email.org</authorEmail>
<authorUrl>http://www.yourwebsite.org</authorUrl>
<copyright>Your Copyright </copyright>
<license>Licence of your theme</license>
<version>version of your theme</version>
<apiVersion>3</apiVersion>
<description>Description of your theme</description>
</metadata>
</syntaxhighlight>

Few remarks:
* '''name''': will be used as a key in the db. So it must be unique, and it should not have any special chars (no spaces). Note that cases will not be taken in account
* '''Title''': will be used to display your theme name in the different lists. It can have special chars
* '''description''': will be used in the main list of survey theme. It can contains special chars, and even HTML code by using <![CDATA[

==== The files section ====

This one is an important one. It will be pushed in the table template_configuration, in the field files_css, files_js, files_print_css as json arrays.

Eg: the files section of the Material Premium Theme:

<syntaxhighlight lang="xml" enclose="div">
<files>
<css>
<add>css/bootstrap-material-design.css</add>
<add>css/ripples.min.css</add>
<add>css/ajaxify.css</add>
<add>css/theme.css</add>
<add>css/custom.css</add>
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</css>
<js>
<add>scripts/theme.js</add>
<add>scripts/ajaxify.js</add>
<add>scripts/material.js</add>
<add>scripts/ripples.min.js</add>
<add>scripts/custom.js</add>
</js>
<print_css>
<add>css/print_theme.css</add>
</print_css>
</files>
</syntaxhighlight>

All the CSS/JS files present in this section will be loaded at the launch of the survey (in ajax mode. If ajax mode is off, then of course all the files are reloaded at each page).

They will be added to a Yii Asset Packet based on the name of the theme. So when Asset Manager is on (debug mode being off), those files will be copied to the tmp directory with the rest of the theme (so you can use relative path in the CSS and JS to reach the image files).
About the Asset manager in Yii: https://www.yiiframework.com/wiki/148/understanding-assets
About packages in Yii: http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail

They will use the inheritance system. It means that if you add a CSS/JS file to a theme, but it's not present in the theme, then the engine will look into all the mother themes of this theme and will use the first one it finds. So if a user extends your theme via the theme editor, all those files will be inherited in his theme. The keywords refer to this inheritance system.

* '''add''' : it will add the file to the theme, and to all its inherited theme
* '''replace''': it will replace the the file of its mother theme
* '''remove''': it will remove the file from '''any''' package, even the core package (since 3.14)

<div class="simplebox">[[File:help.png]] Remember you can set in config.php 'force_xmlsettings_for_survey_rendering' so configuration is read from XML instead of DB (no reset needed). This will make easier to test the modifications of the XML files, and will avoid you to uninstall/reinstall theme at each modification of the XML </div>

Few remarks on those keywords:

===== Inheritance tips =====
As explained before, the "add" keyword can refer to a file being in one of the mother theme. So you can "add" a file in this section, and still not having this file in your theme, but in one of its parents theme. The engine will look into all its parent themes and will use the first one it finds. If it can't find the file, and debug mode is on in config, and js frontend debug mode is on in global setting, a message in console will warn you. Eg: if we add in a my_theme: <add>css/unexisting.css</add>, in the console we'll see:

<syntaxhighlight lang="" enclose="div">
(¯`·._.·(¯`·._.· Theme Configuration Error ·._.·´¯)·._.·´¯)

Can't find file 'css/unexisting.css' defined in theme 'my_theme'
</syntaxhighlight>

If the debug mode is off, then no error at all will be seen. The engine will just ignore the wrong add statements.

===== When to use add, when to use replace, when can I just leave it to the parent theme? =====

First: add and replace are the very same keyword. You can use the one or the other, the engine will just do the same. They are distinct for human readers, so they understand what was your intention.

You can't add a file with the same name as the mother theme: it will always replace it. eg: If you have a file called "my_mother_theme/foo.css" and you add a file called "foo.cs" in the daughter theme, only "daughter_theme/foo.css" will be added to the theme. If you want to keep "my_mother_theme/foo.css", just choose another name for "daughter_theme/foo.css", like "daughter_theme/bar.css". So the keyword "add" can be used as a "replace" keyword.

If you wonder why: this make much easier the automatic generation of inherited theme, copying the file section works out of the box (no need to rename "add" to "replace" when extending one the file).

To make it clear, let's take the Fruity example. Here its css file section:

<syntaxhighlight lang="xml" enclose="div">
<css>
<add>css/variations/sea_green.css</add>
<replace>css/animate.css</replace>
<replace>css/theme.css</replace>
<replace>css/custom.css</replace>
</css>
</syntaxhighlight>

If you look to the custom.css file in fruity, it is exactly the same as the vanilla one. We could delete the custom.css file inside fruity, the one of vanilla would loaded. We could remove the statement <replace>custom.css</replace> from the Fruity manifest, the statement from vanilla will be used, and the vanilla custom.css would be loaded.

So why do we use the statement <replace>custom.css</replace> inside the fruity manifest? The answer is easy: because we want the end user to be able to extend the fruity theme, to modify the file in his local theme, and to load this modified file from his inherited theme. To understand, just extend fruity and have a look to the extended theme. THe extended theme doesn't even have the file custom.css. So the one of fruity will be used. But: if the user create this file in the extended theme (by clicking on "extend" in the theme editor), then this file will be loaded from his theme.

So in general:
if you create a theme from scratch not extending any theme, just use the add statement to add your css/js files. Easy peasy.
if you create a theme extending another theme, and you don't want the users to be able to extends the css/js file from the mother theme: don't use the add statement in your manifest. THe files will still be loaded from the mother theme configuration.
if you create a theme extending another theme, and you want to replace a file from the mother theme: use the replace keyword (the add keyword will have the same result)
if you create a theme extending another theme, if you don't replace a given file from css/js, but you want the users to be able to extend this file: then use the "replace" statement in your manifest for this file. Even if you don't replace the file, by using the keyword replace in the manifest: you allow the user to do it if he wants to do it.

Only this very last case needs a bit of mental gymnastic ot understand, all the other cases are trivial.

<div class="simplebox">[[File:help.png]]
You can also register CSS and JS files directly from the twig code. Those files will be loaded only when the twig file is asked. If you want the users to be able to inherit those JS/Css files from the theme editor, remember to use the functions {{registerTemplateCssFile('my_style.css')}} and {{registerTemplateScript('my_script.js')}}. If you don't use those functions, your theme may work, but inheritance on it will be broken. It is the same logic as the {{image('my_picture.jpg')}} function
</div>

===== The remove keyword =====

The remove keyword is available only since 3.14. With this one, you can remove any css/file from any package, even the core ones. It is used in Material Premium Theme to remove the Awseome Bootstrap Checkbox's files:

<syntaxhighlight lang="xml" enclose="div">
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</syntaxhighlight>

so you should use the very same syntax as the package's file (eg: "awesome-bootstrap-checkbox.css" alone without it's folder path would not work). You'll find the complete list of core packages and their files in /application/config/packages.php and config/third_party.php. For example, for awesome-bootstrap-checkbox.css:
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/config/packages.php#L54-L56

<syntaxhighlight lang="php" enclose="div">
'css'=> array(
'awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css',
),
</syntaxhighlight>

Another way to find the exact name to use in the remove tag is to turn asset manager on (turning debug mode off or setting 'use_asset_manager'=>true in the config). Then, the path to use will be the one just after the random directory in the tmp directory. For example, for awesome-bootstrap-checkbox.css:
<syntaxhighlight lang="html" enclose="div">
<link rel="stylesheet" type="text/css" href="/tmp/assets/cbc4e3cb/awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css" />
</syntaxhighlight>

==== The options section ====

This section is relative to the option of your theme. It will be used to feed the filed "options" of the table template_configuration as a json array.

== Some notes ==


'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.


'''NOTE''': to avoid that, you can force the use to the XML rather than DB. In config.php turn debug mode on and uncommment:


'force_xmlsettings_for_survey_rendering' => true, // Uncomment if you want to force the use of the XML file rather than DB (for easy theme development)


Becareful: everything will be loaded from the XML (included options, etc)


'''NOTE''': if you manually edit the CSS/JS files (without using the Theme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache".


'''NOTE''': if you remove the section

</translate>

New Template System in LS3.x

2018-08-13T12:59:27Z

LouisGac: /* The manifest config.xml */

<languages />
<translate>

__TOC__
=Introduction= 


On this page you'll learn how to:


* Use the new theme system of LimeSurvey 3.0.
* Use inheritance to manage your own themes.
* Add a picture to your theme
* Manage theme options for your surveys and survey groups


<hr/>


LimeSurvey 3 introduces a complete new theme engine system, based on Twig 1.29, Bootstrap, and allowing theme inheritance and theme options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old theme system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A theme designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new theme engine.


<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Theme Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface= 
==theme list==
On the admin dashboard, there is now a box to access the theme list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The theme list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the theme: it’s just a picture file called “preview.png” at the root of the theme
* the “title” of the theme as specified in the manifest (config.xml in the root of the theme)
* the description of the theme: a string set in its manifest
* the type of theme: Core theme (provided with LimeSurvey), User theme (added in upload directory), XML theme (not loaded in database)
* Extends: if the theme extends another theme, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a theme to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a theme in the database
** Theme editor: it will redirect you to the theme editor
** Theme option: it will lead you the global configuration of theme options

==Theme Editor== 
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' theme'']]

====A quick overview of the concept of theme inheritance==== 


In LS3, a theme can now inherit from another theme, it can “extend” another theme. This means that the theme directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of themes for your different users without having to maintain a lot of different themes. For example: you can have your own home-made theme, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom theme, all the themes that inherit from it will be updated automatically. Note that the inheritance is recursive: a theme can extend a theme that extends another one etc.


<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core themes of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface==== 


To extend the Monochrome theme of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome theme. Then, click on “extend” and validate the new name “extends_monochrome”.


If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/themes/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this theme as a normal one from a survey and it will look exactly like the monochrome theme.


[[File:Extends monochrome empty.jpg|center|baseline|border|''The theme tree (directory and files) just after its creation. It's practically empty'']]


<div class="simplebox">[[File:help.png]] The resources (jpg, png etc.) from the original theme are copied when extending a theme. This is because if you copy a CSS file from the original theme locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current theme path. </div>


The theme editor for the extends_monochrome theme looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome theme'']]
<br /><br />
There is no big difference with the old theme editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the theme directory and that the file from the original theme will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to theme views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local theme and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ==== 


The button '''Copy to local theme and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the theme you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button'']]
<br>
If you open a file explorer and go to the directory upload/themes/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your theme'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).


<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the theme to find the image. If the theme you’re working on is extended to another theme, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local theme, it will loop through the theme inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your theme. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/


<div class="simplebox">
So, to add a picture to your theme:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''


* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}


* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list==== 
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which theme the current one extends (if any)

==Template options== 
Another novelty of LS3 is the theme option page. As we’ll see later, theme creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the theme options at global level: click on “theme options” in the theme list
===Advanced options===


{{QS:Theme editor - advanced options}}

===Simple options=== 


The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the theme's /options directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options (Broken link)
<div class="simplebox">[[File:help.png]] This page can be completely different from a theme to another, and theme providers are strongly encouraged to create their own look & feel. </div>


[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from


{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core themes:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a theme provider could add his own animation library or no animation library at all.


<div class="simplebox">[[File:help.png]] The monochrome themes use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for theme providers.</div>

===Inheritance system=== 


In the previous part, we’ve seen that a theme can extend another theme. A theme configuration can also inherit from another theme configuration. It means that for a given theme, you can have a configuration at


* global level (the one we’ve just seen accessible from the theme list)
* at survey group level
* a last one at survey level.


Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

====At survey group level==== 


Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of themes than in the theme list, except that here only the option button is visible (theme editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]


<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

====At survey level==== 
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example== 
Let’s say you’re using a single theme for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core theme. But of course, if you are a theme provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization = 


You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS/JS: deal with the asset manager ("why are my changes not applied?") == 
<br />


If you're trying to update the CSS/JS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.


<br />


Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />


It moves the CSS/JS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css/js file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css/js. Else, they would have to clean their browser cache.


<br />


Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.


<br />


Here the CSS links in header when asset manager is off:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.


<br />


<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>


So, when you're editing CSS/JS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache


[[File:Clearassets-ls3 3.png]]


<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>


Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme == 
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how it works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css


<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>


Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>


You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font === 
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>


You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.


Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options === 
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>


* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %} //Shouldn't this be "theme" in stead of "template"?
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>


<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector === 
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">


'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}


</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79


<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>


Of course, the XML file only contains the default values for your theme configuration. But indeed, those values are defined and read inside the database (table "template_configuration" (Question: "template_" of "theme_"?) as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174


So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

== Adding theme options to control positioning and display of survey elements == 
This tutorial will show how to add options to an extended theme to display survey elements in various locations. In this case, we will create theme options to show the survey title in two different locations.
<div class="simplebox">[[File:help.png]] For the sake of simplicity, we will base the tutorial on an extension of the "bootswatch" theme in LimeSurvey version 3.4.3.</div>
=== Create a custom theme ===
#Extend the "bootswatch" theme as described above.
#Copy <span style="color: #BA2121;">custom.css</span> to the local theme as described above.
===Create new theme options===
#Copy the contents of <span style="color: #BA2121;">/themes/survey/bootswatch/options/</span> to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/</span>.
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/options.twig</span> in an editor and find "{# Bootstrap Bootswatch theme #}". Directly before its parent <nowiki><div class='row'></nowiki> element, add this:<syntaxhighlight lang="html" enclose="div">
{# Custom survey name in navbar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div>


{# Custom survey name below progress bar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div></syntaxhighlight>
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/config.xml</span> and add two items to the "options" block so it looks like this:<syntaxhighlight lang="xml" enclose="div"> <options>
<ajaxmode>on</ajaxmode>
...
<surveyname1>on</surveyname1>
<surveyname2>on</surveyname2>
</options></syntaxhighlight>
#This should give you two new options in the Theme Options screen like this:<br />[[File:Tutorial_tp_1_1.png]]

===Modifed view for Survey Title in the navbar=== 
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/header/</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> and find "{# Logo option #}". Under that, modify the IF statement for the logo/survey-name, so it looks like this:<syntaxhighlight lang="html" enclose="div">
{# Logo option #}
{% if( aSurveyInfo.options.brandlogo == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }} logo-container" {{ aSurveyInfo.attr.navbarbrand }} >
{{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
</div>
{% endif %}
{% if( aSurveyInfo.options.surveyname1 == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }}" {{ aSurveyInfo.attr.navbarbrand }} >
{{ aSurveyInfo.name }}
</div>
{% endif %}</syntaxhighlight>
#Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60px;
font-size: 32px;
}</syntaxhighlight>
#Toggle the "Survey name in navbar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_2.png]]
===Modifed view for Survey Title under progress bar===
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> and add an <nowiki><h1></nowiki> element for the survey name. So it looks like this:<syntaxhighlight lang="html" enclose="div"><div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>

{# Custom survey name #}
{% if( aSurveyInfo.options.surveyname2 == "on") %}
<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
{% endif %}

{# Group Name #}
{{ include('./subviews/survey/group_subviews/group_name.twig') }}

{# Group Description #}
{{ include('./subviews/survey/group_subviews/group_desc.twig') }}

{#
PRESENT THE QUESTIONS

This is the main part. It will render each question for this group
#}


{% for aQuestion in aGroup.aQuestions %}
{{ include('./subviews/survey/question_container.twig') }}
{% endfor %}


{% if aGroup.show_last_group == true %}
<input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
{% endif %}

{% if aGroup.show_last_answer == true %}
<input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
{% endif %}
</div></syntaxhighlight>
# Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60ph1.custom-survey-name {
margin: 0;
text-align: center;
}</syntaxhighlight>
#Toggle the "Survey name below progress bar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_3.png]]

===Downloads=== 
* Sample extended theme: [[Media:Test_survey_names.zip]]

=Creating a theme from scratch= 
Documentation coming soon.

For now, just giving few tips.

==theme structure==

=== Files and directories ===
When you create a Theme from scratch, you don't need to respect the file/directory structure/css/js from Vanilla.
The mandatory css/js is added by core (you can still remove it if needed)

The only files your theme must have are the layout files:

* '''layout_global.twig''' : render the pages for survey taking
* '''layout_survey_list.twig''' : render the survey list (if this theme is set as default)
* '''layout_errors.twig''' : used to render errors that block survey rendering. ( wrong survey id, empty group in preview group, etc.)
* '''layout_user_forms.twig''': renders the user forms such as: token (survey participant), and register.
* '''layout_print.twig''' : used to print the survey to pdf
* '''layout_printanswers.twig''': print the answers

The content of those files, the files they include or not, is entirely up to you.
All the other files and directories that you find on Vanilla are purely optional, feel free to organize your code the way you want.

<div class="simplebox">[[File:help.png]] If you read the frontend rendering code, you'll see that those files names appear directly in it. That's why they are mandatory.
Eg: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/helpers/SurveyRuntimeHelper.php#L462
</div>

=== Content ===

In Vanilla's layout_global.twig, you'll see we use a variable called "include_content" to decide what to show
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/layout_global.twig#L114-L115

<syntaxhighlight lang="php" enclose="div">
{% set sViewContent = './subviews/content/' ~ aSurveyInfo.include_content ~ '.twig' %}
{% include './subviews/content/outerframe.twig' with {'include_content': sViewContent } %}
</syntaxhighlight>

aSurveyInfo.include_content tell you what action is currently going on: showing questions? showing submit result? showing clear all? etc
As you can see, in vanilla, we create one file to include by action. So if you want to know the list of actions, just check the vanilla's directory '''views/subviews/content''', and remove the "twig" extension :
https://github.com/LimeSurvey/LimeSurvey/tree/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/subviews/content

* '''clearall.twig'''
* '''firstpage.twig'''
* '''load.twig'''
* '''mainrow.twig'''
* '''main.twig'''
* '''optin.twig'''
* '''optout.twig'''
* '''outerframe.twig'''
* '''printanswers.twig'''
* '''quotas.twig'''
* '''register.twig'''
* '''save.twig'''
* '''submit_preview.twig'''
* '''submit.twig'''
* '''userforms.twig'''

If you already created a them for 2.x versions of LimeSurvey, you'll notice that most of them corresponds to the old pstpl files for limesurvey 2.x.
Again, there is no obligation for you in your theme to create those files, with those names, in this directory. You could for example just add a giant switch in layout_global.twig with the wanted HTML for each action.

=== The manifest config.xml ===

The manifest of the theme contains the main informations about your theme. When you install a theme, the content of the manifest will be loaded in the database, in two different tables: template and template_configuration. So each time you modify the manifest of a theme, you must uninstall and reinstall it (or just reset it). Because this process is annoying while developing a theme you can force the direct usage of the XML file rather than the DB entries. To do so, in config.phpn turn on debug mode and 'force_xmlsettings_for_survey_rendering' to true.

==== The metadata section ====

Nothing complex: just the main infos about your theme. It will be pushed in the table templates_configuration

<syntaxhighlight lang="xml" enclose="div">
<metadata>
<name>the_name_of_your_theme</name>
<title>The Title of your theme</title>
<creationDate>16/10/2017</creationDate>
<author>Your Name</author>
<authorEmail>your@email.org</authorEmail>
<authorUrl>http://www.yourwebsite.org</authorUrl>
<copyright>Your Copyright </copyright>
<license>Licence of your theme</license>
<version>version of your theme</version>
<apiVersion>3</apiVersion>
<description>Description of your theme</description>
</metadata>
</syntaxhighlight>

Few remarks:
* '''name''': will be used as a key in the db. So it must be unique, and it should not have any special chars (no spaces). Note that cases will not be taken in account
* '''Title''': will be used to display your theme name in the different lists. It can have special chars
* '''description''': will be used in the main list of survey theme. It can contains special chars, and even HTML code by using <![CDATA[

==== The files section ====

This one is an important one. It will be pushed in the table template_configuration, in the field files_css, files_js, files_print_css as json arrays.

Eg: the files section of the Material Premium Theme:

<syntaxhighlight lang="xml" enclose="div">
<files>
<css>
<add>css/bootstrap-material-design.css</add>
<add>css/ripples.min.css</add>
<add>css/ajaxify.css</add>
<add>css/theme.css</add>
<add>css/custom.css</add>
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</css>
<js>
<add>scripts/theme.js</add>
<add>scripts/ajaxify.js</add>
<add>scripts/material.js</add>
<add>scripts/ripples.min.js</add>
<add>scripts/custom.js</add>
</js>
<print_css>
<add>css/print_theme.css</add>
</print_css>
</files>
</syntaxhighlight>

All the CSS/JS files present in this section will be loaded at the launch of the survey (in ajax mode. If ajax mode is off, then of course all the files are reloaded at each page).

They will be added to a Yii Asset Packet based on the name of the theme. So when Asset Manager is on (debug mode being off), those files will be copied to the tmp directory with the rest of the theme (so you can use relative path in the CSS and JS to reach the image files).
About the Asset manager in Yii: https://www.yiiframework.com/wiki/148/understanding-assets
About packages in Yii: http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail

They will use the inheritance system. It means that if you add a CSS/JS file to a theme, but it's not present in the theme, then the engine will look into all the mother themes of this theme and will use the first one it finds. So if a user extends your theme via the theme editor, all those files will be inherited in his theme. The keywords refer to this inheritance system.

* '''add''' : it will add the file to the theme, and to all its inherited theme
* '''replace''': it will replace the the file of its mother theme
* '''remove''': it will remove the file from '''any''' package, even the core package (since 3.14)

<div class="simplebox">[[File:help.png]] Remember you can set in config.php 'force_xmlsettings_for_survey_rendering' so configuration is read from XML instead of DB (no reset needed). This will make easier to test the modifications of the XML files, and will avoid you to uninstall/reinstall theme at each modification of the XML </div>

Few remarks on those keywords:

===== Inheritance tips =====
As explained before, the "add" keyword can refer to a file being in one of the mother theme. So you can "add" a file in this section, and still not having this file in your theme, but in one of its parents theme. The engine will look into all its parent themes and will use the first one it finds. If it can't find the file, and debug mode is on in config, and js frontend debug mode is on in global setting, a message in console will warn you. Eg: if we add in a my_theme: <add>css/unexisting.css</add>, in the console we'll see:

<syntaxhighlight lang="" enclose="div">
(¯`·._.·(¯`·._.· Theme Configuration Error ·._.·´¯)·._.·´¯)

Can't find file 'css/unexisting.css' defined in theme 'my_theme'
</syntaxhighlight>

If the debug mode is off, then no error at all will be seen. The engine will just ignore the wrong add statements.

===== When to use add, when to use replace, when can I just leave it to the parent theme? =====

First: add and replace are the very same keyword. You can use the one or the other, the engine will just do the same. They are distinct for human readers, so they understand what was your intention.

You can't add a file with the same name as the mother theme: it will always replace it. eg: If you have a file called "my_mother_theme/foo.css" and you add a file called "foo.cs" in the daughter theme, only "daughter_theme/foo.css" will be added to the theme. If you want to keep "my_mother_theme/foo.css", just choose another name for "daughter_theme/foo.css", like "daughter_theme/bar.css". So the keyword "add" can be used as a "replace" keyword.

If you wonder why: this make much easier the automatic generation of inherited theme, copying the file section works out of the box (no need to rename "add" to "replace" when extending one the file).

To make it clear, let's take the Fruity example. Here its css file section:

<syntaxhighlight lang="xml" enclose="div">
<css>
<add>css/variations/sea_green.css</add>
<replace>css/animate.css</replace>
<replace>css/theme.css</replace>
<replace>css/custom.css</replace>
</css>
</syntaxhighlight>

If you look to the custom.css file in fruity, it is exactly the same as the vanilla one. We could delete the custom.css file inside fruity, the one of vanilla would loaded. We could remove the statement <replace>custom.css</replace> from the Fruity manifest, the statement from vanilla will be used, and the vanilla custom.css would be loaded.

So why do we use the statement <replace>custom.css</replace> inside the fruity manifest? The answer is easy: because we want the end user to be able to extend the fruity theme, to modify the file in his local theme, and to load this modified file from his inherited theme. To understand, just extend fruity and have a look to the extended theme. THe extended theme doesn't even have the file custom.css. So the one of fruity will be used. But: if the user create this file in the extended theme (by clicking on "extend" in the theme editor), then this file will be loaded from his theme.

So in general:
if you create a theme from scratch not extending any theme, just use the add statement to add your css/js files. Easy peasy.
if you create a theme extending another theme, and you don't want the users to be able to extends the css/js file from the mother theme: don't use the add statement in your manifest. THe files will still be loaded from the mother theme configuration.
if you create a theme extending another theme, and you want to replace a file from the mother theme: use the replace keyword (the add keyword will have the same result)
if you create a theme extending another theme, if you don't replace a given file from css/js, but you want the users to be able to extend this file: then use the "replace" statement in your manifest for this file. Even if you don't replace the file, by using the keyword replace in the manifest: you allow the user to do it if he wants to do it.

Only this very last case needs a bit of mental gymnastic ot understand, all the other cases are trivial.

<div class="simplebox">[[File:help.png]]
You can also register CSS and JS files directly from the twig code. Those files will be loaded only when the twig file is asked. If you want the users to be able to inherit those JS/Css files from the theme editor, remember to use the functions {{registerTemplateCssFile('my_style.css')}} and {{registerTemplateScript('my_script.js')}}. If you don't use those functions, your theme may work, but inheritance on it will be broken. It is the same logic as the {{image('my_picture.jpg')}} function
</div>

===== The remove keyword =====

The remove keyword is available only since 3.14. With this one, you can remove any css/file from any package, even the core ones. It is used in Material Premium Theme to remove the Awseome Bootstrap Checkbox's files:

<syntaxhighlight lang="xml" enclose="div">
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</syntaxhighlight>

so you should use the very same syntax as the package's file (eg: "awesome-bootstrap-checkbox.css" alone without it's folder path would not work). You'll find the complete list of core packages and their files in /application/config/packages.php and config/third_party.php. For example, for awesome-bootstrap-checkbox.css:
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/config/packages.php#L54-L56

<syntaxhighlight lang="php" enclose="div">
'css'=> array(
'awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css',
),
</syntaxhighlight>

Another way to find the exact name to use in the remove tag is to turn asset manager on (turning debug mode off or setting 'use_asset_manager'=>true in the config). Then, the path to use will be the one just after the random directory in the tmp directory. For example, for awesome-bootstrap-checkbox.css:
<syntaxhighlight lang="html" enclose="div">
<link rel="stylesheet" type="text/css" href="/tmp/assets/cbc4e3cb/awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css" />
</syntaxhighlight>

<div class="simplebox">[[File:help.png]]
You can also register CSS and JS files directly from the twig code. But, if the CSS and JS files are inside the Theme itself, remember to use the functions {{registerTemplateCssFile('my_style.css')}} and {{registerTemplateScript('my_script.js')}}. If you don't use those functions, your theme may work, but inheritance on it will be broken. It is the same logic as the {{image('my_picture.jpg')}} function
</div>

==== The options section ====

This section is relative to the option of your theme. It will be used to feed the filed "options" of the table template_configuration as a json array.

== Some notes ==


'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.


'''NOTE''': to avoid that, you can force the use to the XML rather than DB. In config.php turn debug mode on and uncommment:


'force_xmlsettings_for_survey_rendering' => true, // Uncomment if you want to force the use of the XML file rather than DB (for easy theme development)


Becareful: everything will be loaded from the XML (included options, etc)


'''NOTE''': if you manually edit the CSS/JS files (without using the Theme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache".


'''NOTE''': if you remove the section

</translate>

New Template System in LS3.x

2018-08-13T12:47:15Z

LouisGac: /* When to use add, when to use replace, when can I just leave it to the parent theme? */

<languages />
<translate>

__TOC__
=Introduction= 


On this page you'll learn how to:


* Use the new theme system of LimeSurvey 3.0.
* Use inheritance to manage your own themes.
* Add a picture to your theme
* Manage theme options for your surveys and survey groups


<hr/>


LimeSurvey 3 introduces a complete new theme engine system, based on Twig 1.29, Bootstrap, and allowing theme inheritance and theme options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old theme system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A theme designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new theme engine.


<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Theme Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface= 
==theme list==
On the admin dashboard, there is now a box to access the theme list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The theme list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the theme: it’s just a picture file called “preview.png” at the root of the theme
* the “title” of the theme as specified in the manifest (config.xml in the root of the theme)
* the description of the theme: a string set in its manifest
* the type of theme: Core theme (provided with LimeSurvey), User theme (added in upload directory), XML theme (not loaded in database)
* Extends: if the theme extends another theme, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a theme to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a theme in the database
** Theme editor: it will redirect you to the theme editor
** Theme option: it will lead you the global configuration of theme options

==Theme Editor== 
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' theme'']]

====A quick overview of the concept of theme inheritance==== 


In LS3, a theme can now inherit from another theme, it can “extend” another theme. This means that the theme directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of themes for your different users without having to maintain a lot of different themes. For example: you can have your own home-made theme, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom theme, all the themes that inherit from it will be updated automatically. Note that the inheritance is recursive: a theme can extend a theme that extends another one etc.


<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core themes of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface==== 


To extend the Monochrome theme of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome theme. Then, click on “extend” and validate the new name “extends_monochrome”.


If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/themes/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this theme as a normal one from a survey and it will look exactly like the monochrome theme.


[[File:Extends monochrome empty.jpg|center|baseline|border|''The theme tree (directory and files) just after its creation. It's practically empty'']]


<div class="simplebox">[[File:help.png]] The resources (jpg, png etc.) from the original theme are copied when extending a theme. This is because if you copy a CSS file from the original theme locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current theme path. </div>


The theme editor for the extends_monochrome theme looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome theme'']]
<br /><br />
There is no big difference with the old theme editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the theme directory and that the file from the original theme will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to theme views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local theme and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ==== 


The button '''Copy to local theme and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the theme you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button'']]
<br>
If you open a file explorer and go to the directory upload/themes/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your theme'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).


<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the theme to find the image. If the theme you’re working on is extended to another theme, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local theme, it will loop through the theme inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your theme. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/


<div class="simplebox">
So, to add a picture to your theme:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''


* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}


* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list==== 
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which theme the current one extends (if any)

==Template options== 
Another novelty of LS3 is the theme option page. As we’ll see later, theme creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the theme options at global level: click on “theme options” in the theme list
===Advanced options===


{{QS:Theme editor - advanced options}}

===Simple options=== 


The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the theme's /options directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options (Broken link)
<div class="simplebox">[[File:help.png]] This page can be completely different from a theme to another, and theme providers are strongly encouraged to create their own look & feel. </div>


[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from


{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core themes:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a theme provider could add his own animation library or no animation library at all.


<div class="simplebox">[[File:help.png]] The monochrome themes use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for theme providers.</div>

===Inheritance system=== 


In the previous part, we’ve seen that a theme can extend another theme. A theme configuration can also inherit from another theme configuration. It means that for a given theme, you can have a configuration at


* global level (the one we’ve just seen accessible from the theme list)
* at survey group level
* a last one at survey level.


Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

====At survey group level==== 


Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of themes than in the theme list, except that here only the option button is visible (theme editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]


<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

====At survey level==== 
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example== 
Let’s say you’re using a single theme for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core theme. But of course, if you are a theme provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization = 


You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS/JS: deal with the asset manager ("why are my changes not applied?") == 
<br />


If you're trying to update the CSS/JS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.


<br />


Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />


It moves the CSS/JS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css/js file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css/js. Else, they would have to clean their browser cache.


<br />


Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.


<br />


Here the CSS links in header when asset manager is off:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.


<br />


<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>


So, when you're editing CSS/JS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache


[[File:Clearassets-ls3 3.png]]


<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>


Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme == 
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how it works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css


<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>


Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>


You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font === 
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>


You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.


Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options === 
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>


* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %} //Shouldn't this be "theme" in stead of "template"?
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>


<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector === 
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">


'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}


</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79


<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>


Of course, the XML file only contains the default values for your theme configuration. But indeed, those values are defined and read inside the database (table "template_configuration" (Question: "template_" of "theme_"?) as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174


So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

== Adding theme options to control positioning and display of survey elements == 
This tutorial will show how to add options to an extended theme to display survey elements in various locations. In this case, we will create theme options to show the survey title in two different locations.
<div class="simplebox">[[File:help.png]] For the sake of simplicity, we will base the tutorial on an extension of the "bootswatch" theme in LimeSurvey version 3.4.3.</div>
=== Create a custom theme ===
#Extend the "bootswatch" theme as described above.
#Copy <span style="color: #BA2121;">custom.css</span> to the local theme as described above.
===Create new theme options===
#Copy the contents of <span style="color: #BA2121;">/themes/survey/bootswatch/options/</span> to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/</span>.
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/options.twig</span> in an editor and find "{# Bootstrap Bootswatch theme #}". Directly before its parent <nowiki><div class='row'></nowiki> element, add this:<syntaxhighlight lang="html" enclose="div">
{# Custom survey name in navbar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div>


{# Custom survey name below progress bar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div></syntaxhighlight>
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/config.xml</span> and add two items to the "options" block so it looks like this:<syntaxhighlight lang="xml" enclose="div"> <options>
<ajaxmode>on</ajaxmode>
...
<surveyname1>on</surveyname1>
<surveyname2>on</surveyname2>
</options></syntaxhighlight>
#This should give you two new options in the Theme Options screen like this:<br />[[File:Tutorial_tp_1_1.png]]

===Modifed view for Survey Title in the navbar=== 
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/header/</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> and find "{# Logo option #}". Under that, modify the IF statement for the logo/survey-name, so it looks like this:<syntaxhighlight lang="html" enclose="div">
{# Logo option #}
{% if( aSurveyInfo.options.brandlogo == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }} logo-container" {{ aSurveyInfo.attr.navbarbrand }} >
{{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
</div>
{% endif %}
{% if( aSurveyInfo.options.surveyname1 == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }}" {{ aSurveyInfo.attr.navbarbrand }} >
{{ aSurveyInfo.name }}
</div>
{% endif %}</syntaxhighlight>
#Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60px;
font-size: 32px;
}</syntaxhighlight>
#Toggle the "Survey name in navbar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_2.png]]
===Modifed view for Survey Title under progress bar===
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> and add an <nowiki><h1></nowiki> element for the survey name. So it looks like this:<syntaxhighlight lang="html" enclose="div"><div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>

{# Custom survey name #}
{% if( aSurveyInfo.options.surveyname2 == "on") %}
<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
{% endif %}

{# Group Name #}
{{ include('./subviews/survey/group_subviews/group_name.twig') }}

{# Group Description #}
{{ include('./subviews/survey/group_subviews/group_desc.twig') }}

{#
PRESENT THE QUESTIONS

This is the main part. It will render each question for this group
#}


{% for aQuestion in aGroup.aQuestions %}
{{ include('./subviews/survey/question_container.twig') }}
{% endfor %}


{% if aGroup.show_last_group == true %}
<input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
{% endif %}

{% if aGroup.show_last_answer == true %}
<input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
{% endif %}
</div></syntaxhighlight>
# Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60ph1.custom-survey-name {
margin: 0;
text-align: center;
}</syntaxhighlight>
#Toggle the "Survey name below progress bar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_3.png]]

===Downloads=== 
* Sample extended theme: [[Media:Test_survey_names.zip]]

=Creating a theme from scratch= 
Documentation coming soon.

For now, just giving few tips.

==theme structure==

=== Files and directories ===
When you create a Theme from scratch, you don't need to respect the file/directory structure/css/js from Vanilla.
The mandatory css/js is added by core (you can still remove it if needed)

The only files your theme must have are the layout files:

* '''layout_global.twig''' : render the pages for survey taking
* '''layout_survey_list.twig''' : render the survey list (if this theme is set as default)
* '''layout_errors.twig''' : used to render errors that block survey rendering. ( wrong survey id, empty group in preview group, etc.)
* '''layout_user_forms.twig''': renders the user forms such as: token (survey participant), and register.
* '''layout_print.twig''' : used to print the survey to pdf
* '''layout_printanswers.twig''': print the answers

The content of those files, the files they include or not, is entirely up to you.
All the other files and directories that you find on Vanilla are purely optional, feel free to organize your code the way you want.

<div class="simplebox">[[File:help.png]] If you read the frontend rendering code, you'll see that those files names appear directly in it. That's why they are mandatory.
Eg: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/helpers/SurveyRuntimeHelper.php#L462
</div>

=== Content ===

In Vanilla's layout_global.twig, you'll see we use a variable called "include_content" to decide what to show
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/layout_global.twig#L114-L115

<syntaxhighlight lang="php" enclose="div">
{% set sViewContent = './subviews/content/' ~ aSurveyInfo.include_content ~ '.twig' %}
{% include './subviews/content/outerframe.twig' with {'include_content': sViewContent } %}
</syntaxhighlight>

aSurveyInfo.include_content tell you what action is currently going on: showing questions? showing submit result? showing clear all? etc
As you can see, in vanilla, we create one file to include by action. So if you want to know the list of actions, just check the vanilla's directory '''views/subviews/content''', and remove the "twig" extension :
https://github.com/LimeSurvey/LimeSurvey/tree/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/subviews/content

* '''clearall.twig'''
* '''firstpage.twig'''
* '''load.twig'''
* '''mainrow.twig'''
* '''main.twig'''
* '''optin.twig'''
* '''optout.twig'''
* '''outerframe.twig'''
* '''printanswers.twig'''
* '''quotas.twig'''
* '''register.twig'''
* '''save.twig'''
* '''submit_preview.twig'''
* '''submit.twig'''
* '''userforms.twig'''

If you already created a them for 2.x versions of LimeSurvey, you'll notice that most of them corresponds to the old pstpl files for limesurvey 2.x.
Again, there is no obligation for you in your theme to create those files, with those names, in this directory. You could for example just add a giant switch in layout_global.twig with the wanted HTML for each action.

=== The manifest config.xml ===

The manifest of the theme contains the main informations about your theme. When you install a theme, the content of the manifest will be loaded in the database, in two different tables: template and template_configuration.

==== The metadata section ====

Nothing complex: just the main infos about your theme. It will be pushed in the table templates_configuration

<syntaxhighlight lang="xml" enclose="div">
<metadata>
<name>the_name_of_your_theme</name>
<title>The Title of your theme</title>
<creationDate>16/10/2017</creationDate>
<author>Your Name</author>
<authorEmail>your@email.org</authorEmail>
<authorUrl>http://www.yourwebsite.org</authorUrl>
<copyright>Your Copyright </copyright>
<license>Licence of your theme</license>
<version>version of your theme</version>
<apiVersion>3</apiVersion>
<description>Description of your theme</description>
</metadata>
</syntaxhighlight>

Few remarks:
* '''name''': will be used as a key in the db. So it must be unique, and it should not have any special chars (no spaces). Note that cases will not be taken in account
* '''Title''': will be used to display your theme name in the different lists. It can have special chars
* '''description''': will be used in the main list of survey theme. It can contains special chars, and even HTML code by using <![CDATA[

==== The files section ====

This one is an important one. It will be pushed in the table template_configuration, in the field files_css, files_js, files_print_css as json arrays.

Eg: the files section of the Material Premium Theme:

<syntaxhighlight lang="xml" enclose="div">
<files>
<css>
<add>css/bootstrap-material-design.css</add>
<add>css/ripples.min.css</add>
<add>css/ajaxify.css</add>
<add>css/theme.css</add>
<add>css/custom.css</add>
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</css>
<js>
<add>scripts/theme.js</add>
<add>scripts/ajaxify.js</add>
<add>scripts/material.js</add>
<add>scripts/ripples.min.js</add>
<add>scripts/custom.js</add>
</js>
<print_css>
<add>css/print_theme.css</add>
</print_css>
</files>
</syntaxhighlight>

All the CSS/JS files present in this section will be loaded at the launch of the survey (in ajax mode. If ajax mode is off, then of course all the files are reloaded at each page).

They will be added to a Yii Asset Packet based on the name of the theme. So when Asset Manager is on (debug mode being off), those files will be copied to the tmp directory with the rest of the theme (so you can use relative path in the CSS and JS to reach the image files).
About the Asset manager in Yii: https://www.yiiframework.com/wiki/148/understanding-assets
About packages in Yii: http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail

They will use the inheritance system. It means that if you add a CSS/JS file to a theme, but it's not present in the theme, then the engine will look into all the mother themes of this theme and will use the first one it finds. So if a user extends your theme via the theme editor, all those files will be inherited in his theme. The keywords refer to this inheritance system.

* '''add''' : it will add the file to the theme, and to all its inherited theme
* '''replace''': it will replace the the file of its mother theme
* '''remove''': it will remove the file from '''any''' package, even the core package (since 3.14)

<div class="simplebox">[[File:help.png]] Remember you can set in config.php 'force_xmlsettings_for_survey_rendering' so configuration is read from XML instead of DB (no reset needed). This will make easier to test the modifications of the XML files, and will avoid you to uninstall/reinstall theme at each modification of the XML </div>

Few remarks on those keywords:

===== Inheritance tips =====
As explained before, the "add" keyword can refer to a file being in one of the mother theme. So you can "add" a file in this section, and still not having this file in your theme, but in one of its parents theme. The engine will look into all its parent themes and will use the first one it finds. If it can't find the file, and debug mode is on in config, and js frontend debug mode is on in global setting, a message in console will warn you. Eg: if we add in a my_theme: <add>css/unexisting.css</add>, in the console we'll see:

<syntaxhighlight lang="" enclose="div">
(¯`·._.·(¯`·._.· Theme Configuration Error ·._.·´¯)·._.·´¯)

Can't find file 'css/unexisting.css' defined in theme 'my_theme'
</syntaxhighlight>

If the debug mode is off, then no error at all will be seen. The engine will just ignore the wrong add statements.

===== When to use add, when to use replace, when can I just leave it to the parent theme? =====

First: add and replace are the very same keyword. You can use the one or the other, the engine will just do the same. They are distinct for human readers, so they understand what was your intention.

You can't add a file with the same name as the mother theme: it will always replace it. eg: If you have a file called "my_mother_theme/foo.css" and you add a file called "foo.cs" in the daughter theme, only "daughter_theme/foo.css" will be added to the theme. If you want to keep "my_mother_theme/foo.css", just choose another name for "daughter_theme/foo.css", like "daughter_theme/bar.css". So the keyword "add" can be used as a "replace" keyword.

If you wonder why: this make much easier the automatic generation of inherited theme, copying the file section works out of the box (no need to rename "add" to "replace" when extending one the file).

To make it clear, let's take the Fruity example. Here its css file section:

<syntaxhighlight lang="xml" enclose="div">
<css>
<add>css/variations/sea_green.css</add>
<replace>css/animate.css</replace>
<replace>css/theme.css</replace>
<replace>css/custom.css</replace>
</css>
</syntaxhighlight>

If you look to the custom.css file in fruity, it is exactly the same as the vanilla one. We could delete the custom.css file inside fruity, the one of vanilla would loaded. We could remove the statement <replace>custom.css</replace> from the Fruity manifest, the statement from vanilla will be used, and the vanilla custom.css would be loaded.

So why do we use the statement <replace>custom.css</replace> inside the fruity manifest? The answer is easy: because we want the end user to be able to extend the fruity theme, to modify the file in his local theme, and to load this modified file from his inherited theme. To understand, just extend fruity and have a look to the extended theme. THe extended theme doesn't even have the file custom.css. So the one of fruity will be used. But: if the user create this file in the extended theme (by clicking on "extend" in the theme editor), then this file will be loaded from his theme.

So in general:
if you create a theme from scratch not extending any theme, just use the add statement to add your css/js files. Easy peasy.
if you create a theme extending another theme, and you don't want the users to be able to extends the css/js file from the mother theme: don't use the add statement in your manifest. THe files will still be loaded from the mother theme configuration.
if you create a theme extending another theme, and you want to replace a file from the mother theme: use the replace keyword (the add keyword will have the same result)
if you create a theme extending another theme, if you don't replace a given file from css/js, but you want the users to be able to extend this file: then use the "replace" statement in your manifest for this file. Even if you don't replace the file, by using the keyword replace in the manifest: you allow the user to do it if he wants to do it.

Only this very last case needs a bit of mental gymnastic ot understand, all the other cases are trivial.

<div class="simplebox">[[File:help.png]]
You can also register CSS and JS files directly from the twig code. Those files will be loaded only when the twig file is asked. If you want the users to be able to inherit those JS/Css files from the theme editor, remember to use the functions {{registerTemplateCssFile('my_style.css')}} and {{registerTemplateScript('my_script.js')}}. If you don't use those functions, your theme may work, but inheritance on it will be broken. It is the same logic as the {{image('my_picture.jpg')}} function
</div>

===== The remove keyword =====

The remove keyword is available only since 3.14. With this one, you can remove any css/file from any package, even the core ones. It is used in Material Premium Theme to remove the Awseome Bootstrap Checkbox's files:

<syntaxhighlight lang="xml" enclose="div">
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</syntaxhighlight>

so you should use the very same syntax as the package's file (eg: "awesome-bootstrap-checkbox.css" alone without it's folder path would not work). You'll find the complete list of core packages and their files in /application/config/packages.php and config/third_party.php. For example, for awesome-bootstrap-checkbox.css:
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/config/packages.php#L54-L56

<syntaxhighlight lang="php" enclose="div">
'css'=> array(
'awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css',
),
</syntaxhighlight>

Another way to find the exact name to use in the remove tag is to turn asset manager on (turning debug mode off or setting 'use_asset_manager'=>true in the config). Then, the path to use will be the one just after the random directory in the tmp directory. For example, for awesome-bootstrap-checkbox.css:
<syntaxhighlight lang="html" enclose="div">
<link rel="stylesheet" type="text/css" href="/tmp/assets/cbc4e3cb/awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css" />
</syntaxhighlight>

<div class="simplebox">[[File:help.png]]
You can also register CSS and JS files directly from the twig code. But, if the CSS and JS files are inside the Theme itself, remember to use the functions {{registerTemplateCssFile('my_style.css')}} and {{registerTemplateScript('my_script.js')}}. If you don't use those functions, your theme may work, but inheritance on it will be broken. It is the same logic as the {{image('my_picture.jpg')}} function
</div>

==== The options section ====

This section is relative to the option of your theme. It will be used to feed the filed "options" of the table template_configuration as a json array.

== Some notes ==


'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.


'''NOTE''': to avoid that, you can force the use to the XML rather than DB. In config.php turn debug mode on and uncommment:


'force_xmlsettings_for_survey_rendering' => true, // Uncomment if you want to force the use of the XML file rather than DB (for easy theme development)


Becareful: everything will be loaded from the XML (included options, etc)


'''NOTE''': if you manually edit the CSS/JS files (without using the Theme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache".


'''NOTE''': if you remove the section

</translate>

New Template System in LS3.x

2018-08-13T12:45:05Z

LouisGac: /* Inheritance tips */

<languages />
<translate>

__TOC__
=Introduction= 


On this page you'll learn how to:


* Use the new theme system of LimeSurvey 3.0.
* Use inheritance to manage your own themes.
* Add a picture to your theme
* Manage theme options for your surveys and survey groups


<hr/>


LimeSurvey 3 introduces a complete new theme engine system, based on Twig 1.29, Bootstrap, and allowing theme inheritance and theme options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old theme system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A theme designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new theme engine.


<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Theme Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface= 
==theme list==
On the admin dashboard, there is now a box to access the theme list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The theme list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the theme: it’s just a picture file called “preview.png” at the root of the theme
* the “title” of the theme as specified in the manifest (config.xml in the root of the theme)
* the description of the theme: a string set in its manifest
* the type of theme: Core theme (provided with LimeSurvey), User theme (added in upload directory), XML theme (not loaded in database)
* Extends: if the theme extends another theme, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a theme to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a theme in the database
** Theme editor: it will redirect you to the theme editor
** Theme option: it will lead you the global configuration of theme options

==Theme Editor== 
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' theme'']]

====A quick overview of the concept of theme inheritance==== 


In LS3, a theme can now inherit from another theme, it can “extend” another theme. This means that the theme directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of themes for your different users without having to maintain a lot of different themes. For example: you can have your own home-made theme, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom theme, all the themes that inherit from it will be updated automatically. Note that the inheritance is recursive: a theme can extend a theme that extends another one etc.


<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core themes of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface==== 


To extend the Monochrome theme of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome theme. Then, click on “extend” and validate the new name “extends_monochrome”.


If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/themes/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this theme as a normal one from a survey and it will look exactly like the monochrome theme.


[[File:Extends monochrome empty.jpg|center|baseline|border|''The theme tree (directory and files) just after its creation. It's practically empty'']]


<div class="simplebox">[[File:help.png]] The resources (jpg, png etc.) from the original theme are copied when extending a theme. This is because if you copy a CSS file from the original theme locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current theme path. </div>


The theme editor for the extends_monochrome theme looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome theme'']]
<br /><br />
There is no big difference with the old theme editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the theme directory and that the file from the original theme will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to theme views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local theme and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ==== 


The button '''Copy to local theme and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the theme you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button'']]
<br>
If you open a file explorer and go to the directory upload/themes/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your theme'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).


<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the theme to find the image. If the theme you’re working on is extended to another theme, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local theme, it will loop through the theme inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your theme. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/


<div class="simplebox">
So, to add a picture to your theme:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''


* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}


* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list==== 
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which theme the current one extends (if any)

==Template options== 
Another novelty of LS3 is the theme option page. As we’ll see later, theme creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the theme options at global level: click on “theme options” in the theme list
===Advanced options===


{{QS:Theme editor - advanced options}}

===Simple options=== 


The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the theme's /options directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options (Broken link)
<div class="simplebox">[[File:help.png]] This page can be completely different from a theme to another, and theme providers are strongly encouraged to create their own look & feel. </div>


[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from


{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core themes:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a theme provider could add his own animation library or no animation library at all.


<div class="simplebox">[[File:help.png]] The monochrome themes use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for theme providers.</div>

===Inheritance system=== 


In the previous part, we’ve seen that a theme can extend another theme. A theme configuration can also inherit from another theme configuration. It means that for a given theme, you can have a configuration at


* global level (the one we’ve just seen accessible from the theme list)
* at survey group level
* a last one at survey level.


Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

====At survey group level==== 


Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of themes than in the theme list, except that here only the option button is visible (theme editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]


<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

====At survey level==== 
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example== 
Let’s say you’re using a single theme for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core theme. But of course, if you are a theme provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization = 


You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS/JS: deal with the asset manager ("why are my changes not applied?") == 
<br />


If you're trying to update the CSS/JS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.


<br />


Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />


It moves the CSS/JS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css/js file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css/js. Else, they would have to clean their browser cache.


<br />


Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.


<br />


Here the CSS links in header when asset manager is off:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.


<br />


<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>


So, when you're editing CSS/JS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache


[[File:Clearassets-ls3 3.png]]


<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>


Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme == 
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how it works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css


<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>


Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>


You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font === 
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>


You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.


Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options === 
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>


* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %} //Shouldn't this be "theme" in stead of "template"?
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>


<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector === 
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">


'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}


</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79


<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>


Of course, the XML file only contains the default values for your theme configuration. But indeed, those values are defined and read inside the database (table "template_configuration" (Question: "template_" of "theme_"?) as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174


So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

== Adding theme options to control positioning and display of survey elements == 
This tutorial will show how to add options to an extended theme to display survey elements in various locations. In this case, we will create theme options to show the survey title in two different locations.
<div class="simplebox">[[File:help.png]] For the sake of simplicity, we will base the tutorial on an extension of the "bootswatch" theme in LimeSurvey version 3.4.3.</div>
=== Create a custom theme ===
#Extend the "bootswatch" theme as described above.
#Copy <span style="color: #BA2121;">custom.css</span> to the local theme as described above.
===Create new theme options===
#Copy the contents of <span style="color: #BA2121;">/themes/survey/bootswatch/options/</span> to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/</span>.
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/options.twig</span> in an editor and find "{# Bootstrap Bootswatch theme #}". Directly before its parent <nowiki><div class='row'></nowiki> element, add this:<syntaxhighlight lang="html" enclose="div">
{# Custom survey name in navbar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div>


{# Custom survey name below progress bar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div></syntaxhighlight>
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/config.xml</span> and add two items to the "options" block so it looks like this:<syntaxhighlight lang="xml" enclose="div"> <options>
<ajaxmode>on</ajaxmode>
...
<surveyname1>on</surveyname1>
<surveyname2>on</surveyname2>
</options></syntaxhighlight>
#This should give you two new options in the Theme Options screen like this:<br />[[File:Tutorial_tp_1_1.png]]

===Modifed view for Survey Title in the navbar=== 
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/header/</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> and find "{# Logo option #}". Under that, modify the IF statement for the logo/survey-name, so it looks like this:<syntaxhighlight lang="html" enclose="div">
{# Logo option #}
{% if( aSurveyInfo.options.brandlogo == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }} logo-container" {{ aSurveyInfo.attr.navbarbrand }} >
{{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
</div>
{% endif %}
{% if( aSurveyInfo.options.surveyname1 == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }}" {{ aSurveyInfo.attr.navbarbrand }} >
{{ aSurveyInfo.name }}
</div>
{% endif %}</syntaxhighlight>
#Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60px;
font-size: 32px;
}</syntaxhighlight>
#Toggle the "Survey name in navbar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_2.png]]
===Modifed view for Survey Title under progress bar===
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> and add an <nowiki><h1></nowiki> element for the survey name. So it looks like this:<syntaxhighlight lang="html" enclose="div"><div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>

{# Custom survey name #}
{% if( aSurveyInfo.options.surveyname2 == "on") %}
<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
{% endif %}

{# Group Name #}
{{ include('./subviews/survey/group_subviews/group_name.twig') }}

{# Group Description #}
{{ include('./subviews/survey/group_subviews/group_desc.twig') }}

{#
PRESENT THE QUESTIONS

This is the main part. It will render each question for this group
#}


{% for aQuestion in aGroup.aQuestions %}
{{ include('./subviews/survey/question_container.twig') }}
{% endfor %}


{% if aGroup.show_last_group == true %}
<input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
{% endif %}

{% if aGroup.show_last_answer == true %}
<input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
{% endif %}
</div></syntaxhighlight>
# Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60ph1.custom-survey-name {
margin: 0;
text-align: center;
}</syntaxhighlight>
#Toggle the "Survey name below progress bar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_3.png]]

===Downloads=== 
* Sample extended theme: [[Media:Test_survey_names.zip]]

=Creating a theme from scratch= 
Documentation coming soon.

For now, just giving few tips.

==theme structure==

=== Files and directories ===
When you create a Theme from scratch, you don't need to respect the file/directory structure/css/js from Vanilla.
The mandatory css/js is added by core (you can still remove it if needed)

The only files your theme must have are the layout files:

* '''layout_global.twig''' : render the pages for survey taking
* '''layout_survey_list.twig''' : render the survey list (if this theme is set as default)
* '''layout_errors.twig''' : used to render errors that block survey rendering. ( wrong survey id, empty group in preview group, etc.)
* '''layout_user_forms.twig''': renders the user forms such as: token (survey participant), and register.
* '''layout_print.twig''' : used to print the survey to pdf
* '''layout_printanswers.twig''': print the answers

The content of those files, the files they include or not, is entirely up to you.
All the other files and directories that you find on Vanilla are purely optional, feel free to organize your code the way you want.

<div class="simplebox">[[File:help.png]] If you read the frontend rendering code, you'll see that those files names appear directly in it. That's why they are mandatory.
Eg: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/helpers/SurveyRuntimeHelper.php#L462
</div>

=== Content ===

In Vanilla's layout_global.twig, you'll see we use a variable called "include_content" to decide what to show
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/layout_global.twig#L114-L115

<syntaxhighlight lang="php" enclose="div">
{% set sViewContent = './subviews/content/' ~ aSurveyInfo.include_content ~ '.twig' %}
{% include './subviews/content/outerframe.twig' with {'include_content': sViewContent } %}
</syntaxhighlight>

aSurveyInfo.include_content tell you what action is currently going on: showing questions? showing submit result? showing clear all? etc
As you can see, in vanilla, we create one file to include by action. So if you want to know the list of actions, just check the vanilla's directory '''views/subviews/content''', and remove the "twig" extension :
https://github.com/LimeSurvey/LimeSurvey/tree/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/subviews/content

* '''clearall.twig'''
* '''firstpage.twig'''
* '''load.twig'''
* '''mainrow.twig'''
* '''main.twig'''
* '''optin.twig'''
* '''optout.twig'''
* '''outerframe.twig'''
* '''printanswers.twig'''
* '''quotas.twig'''
* '''register.twig'''
* '''save.twig'''
* '''submit_preview.twig'''
* '''submit.twig'''
* '''userforms.twig'''

If you already created a them for 2.x versions of LimeSurvey, you'll notice that most of them corresponds to the old pstpl files for limesurvey 2.x.
Again, there is no obligation for you in your theme to create those files, with those names, in this directory. You could for example just add a giant switch in layout_global.twig with the wanted HTML for each action.

=== The manifest config.xml ===

The manifest of the theme contains the main informations about your theme. When you install a theme, the content of the manifest will be loaded in the database, in two different tables: template and template_configuration.

==== The metadata section ====

Nothing complex: just the main infos about your theme. It will be pushed in the table templates_configuration

<syntaxhighlight lang="xml" enclose="div">
<metadata>
<name>the_name_of_your_theme</name>
<title>The Title of your theme</title>
<creationDate>16/10/2017</creationDate>
<author>Your Name</author>
<authorEmail>your@email.org</authorEmail>
<authorUrl>http://www.yourwebsite.org</authorUrl>
<copyright>Your Copyright </copyright>
<license>Licence of your theme</license>
<version>version of your theme</version>
<apiVersion>3</apiVersion>
<description>Description of your theme</description>
</metadata>
</syntaxhighlight>

Few remarks:
* '''name''': will be used as a key in the db. So it must be unique, and it should not have any special chars (no spaces). Note that cases will not be taken in account
* '''Title''': will be used to display your theme name in the different lists. It can have special chars
* '''description''': will be used in the main list of survey theme. It can contains special chars, and even HTML code by using <![CDATA[

==== The files section ====

This one is an important one. It will be pushed in the table template_configuration, in the field files_css, files_js, files_print_css as json arrays.

Eg: the files section of the Material Premium Theme:

<syntaxhighlight lang="xml" enclose="div">
<files>
<css>
<add>css/bootstrap-material-design.css</add>
<add>css/ripples.min.css</add>
<add>css/ajaxify.css</add>
<add>css/theme.css</add>
<add>css/custom.css</add>
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</css>
<js>
<add>scripts/theme.js</add>
<add>scripts/ajaxify.js</add>
<add>scripts/material.js</add>
<add>scripts/ripples.min.js</add>
<add>scripts/custom.js</add>
</js>
<print_css>
<add>css/print_theme.css</add>
</print_css>
</files>
</syntaxhighlight>

All the CSS/JS files present in this section will be loaded at the launch of the survey (in ajax mode. If ajax mode is off, then of course all the files are reloaded at each page).

They will be added to a Yii Asset Packet based on the name of the theme. So when Asset Manager is on (debug mode being off), those files will be copied to the tmp directory with the rest of the theme (so you can use relative path in the CSS and JS to reach the image files).
About the Asset manager in Yii: https://www.yiiframework.com/wiki/148/understanding-assets
About packages in Yii: http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail

They will use the inheritance system. It means that if you add a CSS/JS file to a theme, but it's not present in the theme, then the engine will look into all the mother themes of this theme and will use the first one it finds. So if a user extends your theme via the theme editor, all those files will be inherited in his theme. The keywords refer to this inheritance system.

* '''add''' : it will add the file to the theme, and to all its inherited theme
* '''replace''': it will replace the the file of its mother theme
* '''remove''': it will remove the file from '''any''' package, even the core package (since 3.14)

<div class="simplebox">[[File:help.png]] Remember you can set in config.php 'force_xmlsettings_for_survey_rendering' so configuration is read from XML instead of DB (no reset needed). This will make easier to test the modifications of the XML files, and will avoid you to uninstall/reinstall theme at each modification of the XML </div>

Few remarks on those keywords:

===== Inheritance tips =====
As explained before, the "add" keyword can refer to a file being in one of the mother theme. So you can "add" a file in this section, and still not having this file in your theme, but in one of its parents theme. The engine will look into all its parent themes and will use the first one it finds. If it can't find the file, and debug mode is on in config, and js frontend debug mode is on in global setting, a message in console will warn you. Eg: if we add in a my_theme: <add>css/unexisting.css</add>, in the console we'll see:

<syntaxhighlight lang="" enclose="div">
(¯`·._.·(¯`·._.· Theme Configuration Error ·._.·´¯)·._.·´¯)

Can't find file 'css/unexisting.css' defined in theme 'my_theme'
</syntaxhighlight>

If the debug mode is off, then no error at all will be seen. The engine will just ignore the wrong add statements.

===== When to use add, when to use replace, when can I just leave it to the parent theme? =====

First: add and replace are the very same keyword. You can use the one or the other, the engine will just do the same. They are distinct for human readers, so they understand what was your intention.

You can't add a file with the same name as the mother theme: it will always replace it. eg: If you have a file called "my_mother_theme/foo.css" and you add a file called "foo.cs" in the daughter theme, only "daughter_theme/foo.css" will be added to the theme. If you want to keep "my_mother_theme/foo.css", just choose another name for "daughter_theme/foo.css", like "daughter_theme/bar.css". So the keyword "add" can be used as a "replace" keyword.

If you wonder why: this make much easier the automatic generation of inherited theme, copying the file section works out of the box (no need to rename "add" to "replace" when extending one the file).

To make it clear, let's take the Fruity example. Here its css file section:

<syntaxhighlight lang="xml" enclose="div">
<css>
<add>css/variations/sea_green.css</add>
<replace>css/animate.css</replace>
<replace>css/theme.css</replace>
<replace>css/custom.css</replace>
</css>
</syntaxhighlight>

If you look to the custom.css file in fruity, it is exactly the same as the vanilla one. We could delete the custom.css file inside fruity, the one of vanilla would loaded. We could remove the statement <replace>custom.css</replace> from the Fruity manifest, the statement from vanilla will be used, and the vanilla custom.css would be loaded.

So why do we use the statement <replace>custom.css</replace> inside the fruity manifest? The answer is easy: because we want the end user to be able to extend the fruity theme, to modify the file in his local theme, and to load this modified file from his inherited theme. To understand, just extend fruity and have a look to the extended theme. THe extended theme doesn't even have the file custom.css. So the one of fruity will be used. But: if the user create this file in the extended theme (by clicking on "extend" in the theme editor), then this file will be loaded from his theme.

So in general:
if you create a theme from scratch not extending any theme, just use the add statement to add your css/js files. Easy peasy.
if you create a theme extending another theme, and you don't want the users to be able to extends the css/js file from the mother theme: don't use the add statement in your manifest. THe files will still be loaded from the mother theme configuration.
if you create a theme extending another theme, and you want to replace a file from the mother theme: use the replace keyword (the add keyword will have the same result)
if you create a theme extending another theme, if you don't replace a given file from css/js, but you want the users to be able to extend this file: then use the "replace" statement in your manifest for this file. Even if you don't replace the file, by using the keyword replace in the manifest: you allow the user to do it if he wants to do it.

Only this very last case needs a bit of mental gymnastic ot understand, all the other cases are trivial.

===== The remove keyword =====

The remove keyword is available only since 3.14. With this one, you can remove any css/file from any package, even the core ones. It is used in Material Premium Theme to remove the Awseome Bootstrap Checkbox's files:

<syntaxhighlight lang="xml" enclose="div">
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</syntaxhighlight>

so you should use the very same syntax as the package's file (eg: "awesome-bootstrap-checkbox.css" alone without it's folder path would not work). You'll find the complete list of core packages and their files in /application/config/packages.php and config/third_party.php. For example, for awesome-bootstrap-checkbox.css:
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/config/packages.php#L54-L56

<syntaxhighlight lang="php" enclose="div">
'css'=> array(
'awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css',
),
</syntaxhighlight>

Another way to find the exact name to use in the remove tag is to turn asset manager on (turning debug mode off or setting 'use_asset_manager'=>true in the config). Then, the path to use will be the one just after the random directory in the tmp directory. For example, for awesome-bootstrap-checkbox.css:
<syntaxhighlight lang="html" enclose="div">
<link rel="stylesheet" type="text/css" href="/tmp/assets/cbc4e3cb/awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css" />
</syntaxhighlight>

<div class="simplebox">[[File:help.png]]
You can also register CSS and JS files directly from the twig code. But, if the CSS and JS files are inside the Theme itself, remember to use the functions {{registerTemplateCssFile('my_style.css')}} and {{registerTemplateScript('my_script.js')}}. If you don't use those functions, your theme may work, but inheritance on it will be broken. It is the same logic as the {{image('my_picture.jpg')}} function
</div>

==== The options section ====

This section is relative to the option of your theme. It will be used to feed the filed "options" of the table template_configuration as a json array.

== Some notes ==


'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.


'''NOTE''': to avoid that, you can force the use to the XML rather than DB. In config.php turn debug mode on and uncommment:


'force_xmlsettings_for_survey_rendering' => true, // Uncomment if you want to force the use of the XML file rather than DB (for easy theme development)


Becareful: everything will be loaded from the XML (included options, etc)


'''NOTE''': if you manually edit the CSS/JS files (without using the Theme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache".


'''NOTE''': if you remove the section

</translate>

New Template System in LS3.x

2018-08-13T12:43:29Z

LouisGac: /* The files section */

<languages />
<translate>

__TOC__
=Introduction= 


On this page you'll learn how to:


* Use the new theme system of LimeSurvey 3.0.
* Use inheritance to manage your own themes.
* Add a picture to your theme
* Manage theme options for your surveys and survey groups


<hr/>


LimeSurvey 3 introduces a complete new theme engine system, based on Twig 1.29, Bootstrap, and allowing theme inheritance and theme options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old theme system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A theme designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new theme engine.


<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Theme Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface= 
==theme list==
On the admin dashboard, there is now a box to access the theme list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The theme list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the theme: it’s just a picture file called “preview.png” at the root of the theme
* the “title” of the theme as specified in the manifest (config.xml in the root of the theme)
* the description of the theme: a string set in its manifest
* the type of theme: Core theme (provided with LimeSurvey), User theme (added in upload directory), XML theme (not loaded in database)
* Extends: if the theme extends another theme, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a theme to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a theme in the database
** Theme editor: it will redirect you to the theme editor
** Theme option: it will lead you the global configuration of theme options

==Theme Editor== 
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' theme'']]

====A quick overview of the concept of theme inheritance==== 


In LS3, a theme can now inherit from another theme, it can “extend” another theme. This means that the theme directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of themes for your different users without having to maintain a lot of different themes. For example: you can have your own home-made theme, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom theme, all the themes that inherit from it will be updated automatically. Note that the inheritance is recursive: a theme can extend a theme that extends another one etc.


<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core themes of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface==== 


To extend the Monochrome theme of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome theme. Then, click on “extend” and validate the new name “extends_monochrome”.


If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/themes/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this theme as a normal one from a survey and it will look exactly like the monochrome theme.


[[File:Extends monochrome empty.jpg|center|baseline|border|''The theme tree (directory and files) just after its creation. It's practically empty'']]


<div class="simplebox">[[File:help.png]] The resources (jpg, png etc.) from the original theme are copied when extending a theme. This is because if you copy a CSS file from the original theme locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current theme path. </div>


The theme editor for the extends_monochrome theme looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome theme'']]
<br /><br />
There is no big difference with the old theme editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the theme directory and that the file from the original theme will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to theme views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local theme and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ==== 


The button '''Copy to local theme and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the theme you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button'']]
<br>
If you open a file explorer and go to the directory upload/themes/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your theme'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).


<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the theme to find the image. If the theme you’re working on is extended to another theme, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local theme, it will loop through the theme inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your theme. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/


<div class="simplebox">
So, to add a picture to your theme:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''


* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}


* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list==== 
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which theme the current one extends (if any)

==Template options== 
Another novelty of LS3 is the theme option page. As we’ll see later, theme creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the theme options at global level: click on “theme options” in the theme list
===Advanced options===


{{QS:Theme editor - advanced options}}

===Simple options=== 


The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the theme's /options directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options (Broken link)
<div class="simplebox">[[File:help.png]] This page can be completely different from a theme to another, and theme providers are strongly encouraged to create their own look & feel. </div>


[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from


{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core themes:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a theme provider could add his own animation library or no animation library at all.


<div class="simplebox">[[File:help.png]] The monochrome themes use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for theme providers.</div>

===Inheritance system=== 


In the previous part, we’ve seen that a theme can extend another theme. A theme configuration can also inherit from another theme configuration. It means that for a given theme, you can have a configuration at


* global level (the one we’ve just seen accessible from the theme list)
* at survey group level
* a last one at survey level.


Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

====At survey group level==== 


Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of themes than in the theme list, except that here only the option button is visible (theme editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]


<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

====At survey level==== 
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example== 
Let’s say you’re using a single theme for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core theme. But of course, if you are a theme provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization = 


You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS/JS: deal with the asset manager ("why are my changes not applied?") == 
<br />


If you're trying to update the CSS/JS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.


<br />


Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />


It moves the CSS/JS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css/js file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css/js. Else, they would have to clean their browser cache.


<br />


Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.


<br />


Here the CSS links in header when asset manager is off:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.


<br />


<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>


So, when you're editing CSS/JS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache


[[File:Clearassets-ls3 3.png]]


<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>


Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme == 
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how it works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css


<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>


Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>


You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font === 
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>


You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.


Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options === 
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>


* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %} //Shouldn't this be "theme" in stead of "template"?
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>


<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector === 
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">


'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}


</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79


<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>


Of course, the XML file only contains the default values for your theme configuration. But indeed, those values are defined and read inside the database (table "template_configuration" (Question: "template_" of "theme_"?) as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174


So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

== Adding theme options to control positioning and display of survey elements == 
This tutorial will show how to add options to an extended theme to display survey elements in various locations. In this case, we will create theme options to show the survey title in two different locations.
<div class="simplebox">[[File:help.png]] For the sake of simplicity, we will base the tutorial on an extension of the "bootswatch" theme in LimeSurvey version 3.4.3.</div>
=== Create a custom theme ===
#Extend the "bootswatch" theme as described above.
#Copy <span style="color: #BA2121;">custom.css</span> to the local theme as described above.
===Create new theme options===
#Copy the contents of <span style="color: #BA2121;">/themes/survey/bootswatch/options/</span> to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/</span>.
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/options.twig</span> in an editor and find "{# Bootstrap Bootswatch theme #}". Directly before its parent <nowiki><div class='row'></nowiki> element, add this:<syntaxhighlight lang="html" enclose="div">
{# Custom survey name in navbar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div>


{# Custom survey name below progress bar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div></syntaxhighlight>
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/config.xml</span> and add two items to the "options" block so it looks like this:<syntaxhighlight lang="xml" enclose="div"> <options>
<ajaxmode>on</ajaxmode>
...
<surveyname1>on</surveyname1>
<surveyname2>on</surveyname2>
</options></syntaxhighlight>
#This should give you two new options in the Theme Options screen like this:<br />[[File:Tutorial_tp_1_1.png]]

===Modifed view for Survey Title in the navbar=== 
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/header/</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> and find "{# Logo option #}". Under that, modify the IF statement for the logo/survey-name, so it looks like this:<syntaxhighlight lang="html" enclose="div">
{# Logo option #}
{% if( aSurveyInfo.options.brandlogo == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }} logo-container" {{ aSurveyInfo.attr.navbarbrand }} >
{{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
</div>
{% endif %}
{% if( aSurveyInfo.options.surveyname1 == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }}" {{ aSurveyInfo.attr.navbarbrand }} >
{{ aSurveyInfo.name }}
</div>
{% endif %}</syntaxhighlight>
#Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60px;
font-size: 32px;
}</syntaxhighlight>
#Toggle the "Survey name in navbar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_2.png]]
===Modifed view for Survey Title under progress bar===
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> and add an <nowiki><h1></nowiki> element for the survey name. So it looks like this:<syntaxhighlight lang="html" enclose="div"><div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>

{# Custom survey name #}
{% if( aSurveyInfo.options.surveyname2 == "on") %}
<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
{% endif %}

{# Group Name #}
{{ include('./subviews/survey/group_subviews/group_name.twig') }}

{# Group Description #}
{{ include('./subviews/survey/group_subviews/group_desc.twig') }}

{#
PRESENT THE QUESTIONS

This is the main part. It will render each question for this group
#}


{% for aQuestion in aGroup.aQuestions %}
{{ include('./subviews/survey/question_container.twig') }}
{% endfor %}


{% if aGroup.show_last_group == true %}
<input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
{% endif %}

{% if aGroup.show_last_answer == true %}
<input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
{% endif %}
</div></syntaxhighlight>
# Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60ph1.custom-survey-name {
margin: 0;
text-align: center;
}</syntaxhighlight>
#Toggle the "Survey name below progress bar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_3.png]]

===Downloads=== 
* Sample extended theme: [[Media:Test_survey_names.zip]]

=Creating a theme from scratch= 
Documentation coming soon.

For now, just giving few tips.

==theme structure==

=== Files and directories ===
When you create a Theme from scratch, you don't need to respect the file/directory structure/css/js from Vanilla.
The mandatory css/js is added by core (you can still remove it if needed)

The only files your theme must have are the layout files:

* '''layout_global.twig''' : render the pages for survey taking
* '''layout_survey_list.twig''' : render the survey list (if this theme is set as default)
* '''layout_errors.twig''' : used to render errors that block survey rendering. ( wrong survey id, empty group in preview group, etc.)
* '''layout_user_forms.twig''': renders the user forms such as: token (survey participant), and register.
* '''layout_print.twig''' : used to print the survey to pdf
* '''layout_printanswers.twig''': print the answers

The content of those files, the files they include or not, is entirely up to you.
All the other files and directories that you find on Vanilla are purely optional, feel free to organize your code the way you want.

<div class="simplebox">[[File:help.png]] If you read the frontend rendering code, you'll see that those files names appear directly in it. That's why they are mandatory.
Eg: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/helpers/SurveyRuntimeHelper.php#L462
</div>

=== Content ===

In Vanilla's layout_global.twig, you'll see we use a variable called "include_content" to decide what to show
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/layout_global.twig#L114-L115

<syntaxhighlight lang="php" enclose="div">
{% set sViewContent = './subviews/content/' ~ aSurveyInfo.include_content ~ '.twig' %}
{% include './subviews/content/outerframe.twig' with {'include_content': sViewContent } %}
</syntaxhighlight>

aSurveyInfo.include_content tell you what action is currently going on: showing questions? showing submit result? showing clear all? etc
As you can see, in vanilla, we create one file to include by action. So if you want to know the list of actions, just check the vanilla's directory '''views/subviews/content''', and remove the "twig" extension :
https://github.com/LimeSurvey/LimeSurvey/tree/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/subviews/content

* '''clearall.twig'''
* '''firstpage.twig'''
* '''load.twig'''
* '''mainrow.twig'''
* '''main.twig'''
* '''optin.twig'''
* '''optout.twig'''
* '''outerframe.twig'''
* '''printanswers.twig'''
* '''quotas.twig'''
* '''register.twig'''
* '''save.twig'''
* '''submit_preview.twig'''
* '''submit.twig'''
* '''userforms.twig'''

If you already created a them for 2.x versions of LimeSurvey, you'll notice that most of them corresponds to the old pstpl files for limesurvey 2.x.
Again, there is no obligation for you in your theme to create those files, with those names, in this directory. You could for example just add a giant switch in layout_global.twig with the wanted HTML for each action.

=== The manifest config.xml ===

The manifest of the theme contains the main informations about your theme. When you install a theme, the content of the manifest will be loaded in the database, in two different tables: template and template_configuration.

==== The metadata section ====

Nothing complex: just the main infos about your theme. It will be pushed in the table templates_configuration

<syntaxhighlight lang="xml" enclose="div">
<metadata>
<name>the_name_of_your_theme</name>
<title>The Title of your theme</title>
<creationDate>16/10/2017</creationDate>
<author>Your Name</author>
<authorEmail>your@email.org</authorEmail>
<authorUrl>http://www.yourwebsite.org</authorUrl>
<copyright>Your Copyright </copyright>
<license>Licence of your theme</license>
<version>version of your theme</version>
<apiVersion>3</apiVersion>
<description>Description of your theme</description>
</metadata>
</syntaxhighlight>

Few remarks:
* '''name''': will be used as a key in the db. So it must be unique, and it should not have any special chars (no spaces). Note that cases will not be taken in account
* '''Title''': will be used to display your theme name in the different lists. It can have special chars
* '''description''': will be used in the main list of survey theme. It can contains special chars, and even HTML code by using <![CDATA[

==== The files section ====

This one is an important one. It will be pushed in the table template_configuration, in the field files_css, files_js, files_print_css as json arrays.

Eg: the files section of the Material Premium Theme:

<syntaxhighlight lang="xml" enclose="div">
<files>
<css>
<add>css/bootstrap-material-design.css</add>
<add>css/ripples.min.css</add>
<add>css/ajaxify.css</add>
<add>css/theme.css</add>
<add>css/custom.css</add>
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</css>
<js>
<add>scripts/theme.js</add>
<add>scripts/ajaxify.js</add>
<add>scripts/material.js</add>
<add>scripts/ripples.min.js</add>
<add>scripts/custom.js</add>
</js>
<print_css>
<add>css/print_theme.css</add>
</print_css>
</files>
</syntaxhighlight>

All the CSS/JS files present in this section will be loaded at the launch of the survey (in ajax mode. If ajax mode is off, then of course all the files are reloaded at each page).

They will be added to a Yii Asset Packet based on the name of the theme. So when Asset Manager is on (debug mode being off), those files will be copied to the tmp directory with the rest of the theme (so you can use relative path in the CSS and JS to reach the image files).
About the Asset manager in Yii: https://www.yiiframework.com/wiki/148/understanding-assets
About packages in Yii: http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail

They will use the inheritance system. It means that if you add a CSS/JS file to a theme, but it's not present in the theme, then the engine will look into all the mother themes of this theme and will use the first one it finds. So if a user extends your theme via the theme editor, all those files will be inherited in his theme. The keywords refer to this inheritance system.

* '''add''' : it will add the file to the theme, and to all its inherited theme
* '''replace''': it will replace the the file of its mother theme
* '''remove''': it will remove the file from '''any''' package, even the core package (since 3.14)

<div class="simplebox">[[File:help.png]] Remember you can set in config.php 'force_xmlsettings_for_survey_rendering' so configuration is read from XML instead of DB (no reset needed). This will make easier to test the modifications of the XML files, and will avoid you to uninstall/reinstall theme at each modification of the XML </div>

Few remarks on those keywords:

===== Inheritance tips =====
As explained before, the "add" keyword can refer to a file being in one of the mother theme. So you can "add" a file in this section, and still not having this file in your theme, but in one of its parents theme. The engine will look into all its parent themes and will use the first one it finds. If it can't find the file, and debug mode is on in config, and js frontend debug mode is on in global setting, a message in console will warn you. Eg: if we add in a my_theme: <add>css/unexisting.css</add>, in the console we'll see:

<syntaxhighlight lang="" enclose="div">
(¯`·._.·(¯`·._.· Theme Configuration Error ·._.·´¯)·._.·´¯)

Can't find file 'css/unexisting.css' defined in theme 'my_theme'
</syntaxhighlight>

If the debug mode is off, then no error at all will be seen. The engine will just ignore the wrong add statements.

===== When to use add, when to use replace, when can I just leave it to the parent theme? =====

First: add and replace are the very same keyword. You can use the one or the other, the engine will just do the same. They are distinct for human readers, so they understand what was your intention.

You can't add a file with the same name as the mother theme: it will always replace it. eg: If you have a file called "my_mother_theme/foo.css" and you add a file called "foo.cs" in the daughter theme, only "daughter_theme/foo.css" will be added to the theme. If you want to keep "my_mother_theme/foo.css", just choose another name for "daughter_theme/foo.css", like "daughter_theme/bar.css". So the keyword "add" can be used as a "replace" keyword.

If you wonder why: this make much easier the automatic generation of inherited theme, copying the file section works out of the box (no need to rename "add" to "replace" when extending one the file).

To make it clear, let's take the Fruity example. Here its css file section:

<syntaxhighlight lang="xml" enclose="div">
<css>
<add>css/variations/sea_green.css</add>
<replace>css/animate.css</replace>
<replace>css/theme.css</replace>
<replace>css/custom.css</replace>
</css>
</syntaxhighlight>

If you look to the custom.css file in fruity, it is exactly the same as the vanilla one. We could delete the custom.css file inside fruity, the one of vanilla would loaded. We could remove the statement <replace>custom.css</replace> from the Fruity manifest, the statement from vanilla will be used, and the vanilla custom.css would be loaded.

So why do we use the statement <replace>custom.css</replace> inside the fruity manifest? The answer is easy: because we want the end user to be able to extend the fruity theme, to modify the file in his local theme, and to load this modified file from his inherited theme. To understand, just extend fruity and have a look to the extended theme. THe extended theme doesn't even have the file custom.css. So the one of fruity will be used. But: if the user create this file in the extended theme (by clicking on "extend" in the theme editor), then this file will be loaded from his theme.

So in general:
if you create a theme from scratch not extending any theme, just use the add statement to add your css/js files. Easy peasy.
if you create a theme extending another theme, and you don't want the users to be able to extends the css/js file from the mother theme: don't use the add statement in your manifest. THe files will still be loaded from the mother theme configuration.
if you create a theme extending another theme, and you want to replace a file from the mother theme: use the replace keyword (the add keyword will have the same result)
if you create a theme extending another theme, if you don't replace a given file from css/js, but you want the users to be able to extend this file: then use the "replace" statement in your manifest for this file. Even if you don't replace the file, by using the keyword replace in the manifest: you allow the user to do it if he wants to do it.

Only this very last case needs a bit of mental gymnastic ot understand, all the other cases are trivial.

===== The remove keyword =====

The remove keyword is available only since 3.14. With this one, you can remove any css/file from any package, even the core ones. It is used in Material Premium Theme to remove the Awseome Bootstrap Checkbox's files:

<syntaxhighlight lang="xml" enclose="div">
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</syntaxhighlight>

so you should use the very same syntax as the package's file (eg: "awesome-bootstrap-checkbox.css" alone without it's folder path would not work). You'll find the complete list of core packages and their files in /application/config/packages.php and config/third_party.php. For example, for awesome-bootstrap-checkbox.css:
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/config/packages.php#L54-L56

<syntaxhighlight lang="php" enclose="div">
'css'=> array(
'awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css',
),
</syntaxhighlight>

Another way to find the exact name to use in the remove tag is to turn asset manager on (turning debug mode off or setting 'use_asset_manager'=>true in the config). Then, the path to use will be the one just after the random directory in the tmp directory. For example, for awesome-bootstrap-checkbox.css:
<syntaxhighlight lang="html" enclose="div">
<link rel="stylesheet" type="text/css" href="/tmp/assets/cbc4e3cb/awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css" />
</syntaxhighlight>

<div class="simplebox">[[File:help.png]]
You can also register CSS and JS files directly from the twig code. But, if the CSS and JS files are inside the Theme itself, remember to use the functions {{registerTemplateCssFile('my_style.css')}} and {{registerTemplateScript('my_script.js')}}. If you don't use those functions, your theme may work, but inheritance on it will be broken. It is the same logic as the {{image('my_picture.jpg')}} function
</div>

==== The options section ====

This section is relative to the option of your theme. It will be used to feed the filed "options" of the table template_configuration as a json array.

== Some notes ==


'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.


'''NOTE''': to avoid that, you can force the use to the XML rather than DB. In config.php turn debug mode on and uncommment:


'force_xmlsettings_for_survey_rendering' => true, // Uncomment if you want to force the use of the XML file rather than DB (for easy theme development)


Becareful: everything will be loaded from the XML (included options, etc)


'''NOTE''': if you manually edit the CSS/JS files (without using the Theme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache".


'''NOTE''': if you remove the section

</translate>

New Template System in LS3.x

2018-08-13T11:50:43Z

LouisGac:

<languages />
<translate>

__TOC__
=Introduction= 


On this page you'll learn how to:


* Use the new theme system of LimeSurvey 3.0.
* Use inheritance to manage your own themes.
* Add a picture to your theme
* Manage theme options for your surveys and survey groups


<hr/>


LimeSurvey 3 introduces a complete new theme engine system, based on Twig 1.29, Bootstrap, and allowing theme inheritance and theme options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old theme system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A theme designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new theme engine.


<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Theme Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface= 
==theme list==
On the admin dashboard, there is now a box to access the theme list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The theme list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the theme: it’s just a picture file called “preview.png” at the root of the theme
* the “title” of the theme as specified in the manifest (config.xml in the root of the theme)
* the description of the theme: a string set in its manifest
* the type of theme: Core theme (provided with LimeSurvey), User theme (added in upload directory), XML theme (not loaded in database)
* Extends: if the theme extends another theme, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a theme to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a theme in the database
** Theme editor: it will redirect you to the theme editor
** Theme option: it will lead you the global configuration of theme options

==Theme Editor== 
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' theme'']]

====A quick overview of the concept of theme inheritance==== 


In LS3, a theme can now inherit from another theme, it can “extend” another theme. This means that the theme directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of themes for your different users without having to maintain a lot of different themes. For example: you can have your own home-made theme, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom theme, all the themes that inherit from it will be updated automatically. Note that the inheritance is recursive: a theme can extend a theme that extends another one etc.


<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core themes of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface==== 


To extend the Monochrome theme of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome theme. Then, click on “extend” and validate the new name “extends_monochrome”.


If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/themes/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this theme as a normal one from a survey and it will look exactly like the monochrome theme.


[[File:Extends monochrome empty.jpg|center|baseline|border|''The theme tree (directory and files) just after its creation. It's practically empty'']]


<div class="simplebox">[[File:help.png]] The resources (jpg, png etc.) from the original theme are copied when extending a theme. This is because if you copy a CSS file from the original theme locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current theme path. </div>


The theme editor for the extends_monochrome theme looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome theme'']]
<br /><br />
There is no big difference with the old theme editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the theme directory and that the file from the original theme will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to theme views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local theme and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ==== 


The button '''Copy to local theme and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the theme you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button'']]
<br>
If you open a file explorer and go to the directory upload/themes/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your theme'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).


<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the theme to find the image. If the theme you’re working on is extended to another theme, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local theme, it will loop through the theme inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your theme. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/


<div class="simplebox">
So, to add a picture to your theme:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''


* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}


* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list==== 
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which theme the current one extends (if any)

==Template options== 
Another novelty of LS3 is the theme option page. As we’ll see later, theme creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the theme options at global level: click on “theme options” in the theme list
===Advanced options===


{{QS:Theme editor - advanced options}}

===Simple options=== 


The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the theme's /options directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options (Broken link)
<div class="simplebox">[[File:help.png]] This page can be completely different from a theme to another, and theme providers are strongly encouraged to create their own look & feel. </div>


[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from


{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core themes:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a theme provider could add his own animation library or no animation library at all.


<div class="simplebox">[[File:help.png]] The monochrome themes use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for theme providers.</div>

===Inheritance system=== 


In the previous part, we’ve seen that a theme can extend another theme. A theme configuration can also inherit from another theme configuration. It means that for a given theme, you can have a configuration at


* global level (the one we’ve just seen accessible from the theme list)
* at survey group level
* a last one at survey level.


Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

====At survey group level==== 


Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of themes than in the theme list, except that here only the option button is visible (theme editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]


<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

====At survey level==== 
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example== 
Let’s say you’re using a single theme for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core theme. But of course, if you are a theme provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization = 


You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS/JS: deal with the asset manager ("why are my changes not applied?") == 
<br />


If you're trying to update the CSS/JS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.


<br />


Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />


It moves the CSS/JS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css/js file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css/js. Else, they would have to clean their browser cache.


<br />


Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.


<br />


Here the CSS links in header when asset manager is off:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.


<br />


<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>


So, when you're editing CSS/JS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache


[[File:Clearassets-ls3 3.png]]


<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>


Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme == 
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how it works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css


<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>


Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>


You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font === 
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>


You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.


Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options === 
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>


* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %} //Shouldn't this be "theme" in stead of "template"?
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>


<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector === 
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">


'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}


</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79


<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>


Of course, the XML file only contains the default values for your theme configuration. But indeed, those values are defined and read inside the database (table "template_configuration" (Question: "template_" of "theme_"?) as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174


So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

== Adding theme options to control positioning and display of survey elements == 
This tutorial will show how to add options to an extended theme to display survey elements in various locations. In this case, we will create theme options to show the survey title in two different locations.
<div class="simplebox">[[File:help.png]] For the sake of simplicity, we will base the tutorial on an extension of the "bootswatch" theme in LimeSurvey version 3.4.3.</div>
=== Create a custom theme ===
#Extend the "bootswatch" theme as described above.
#Copy <span style="color: #BA2121;">custom.css</span> to the local theme as described above.
===Create new theme options===
#Copy the contents of <span style="color: #BA2121;">/themes/survey/bootswatch/options/</span> to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/</span>.
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/options.twig</span> in an editor and find "{# Bootstrap Bootswatch theme #}". Directly before its parent <nowiki><div class='row'></nowiki> element, add this:<syntaxhighlight lang="html" enclose="div">
{# Custom survey name in navbar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div>


{# Custom survey name below progress bar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div></syntaxhighlight>
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/config.xml</span> and add two items to the "options" block so it looks like this:<syntaxhighlight lang="xml" enclose="div"> <options>
<ajaxmode>on</ajaxmode>
...
<surveyname1>on</surveyname1>
<surveyname2>on</surveyname2>
</options></syntaxhighlight>
#This should give you two new options in the Theme Options screen like this:<br />[[File:Tutorial_tp_1_1.png]]

===Modifed view for Survey Title in the navbar=== 
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/header/</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> and find "{# Logo option #}". Under that, modify the IF statement for the logo/survey-name, so it looks like this:<syntaxhighlight lang="html" enclose="div">
{# Logo option #}
{% if( aSurveyInfo.options.brandlogo == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }} logo-container" {{ aSurveyInfo.attr.navbarbrand }} >
{{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
</div>
{% endif %}
{% if( aSurveyInfo.options.surveyname1 == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }}" {{ aSurveyInfo.attr.navbarbrand }} >
{{ aSurveyInfo.name }}
</div>
{% endif %}</syntaxhighlight>
#Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60px;
font-size: 32px;
}</syntaxhighlight>
#Toggle the "Survey name in navbar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_2.png]]
===Modifed view for Survey Title under progress bar===
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> and add an <nowiki><h1></nowiki> element for the survey name. So it looks like this:<syntaxhighlight lang="html" enclose="div"><div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>

{# Custom survey name #}
{% if( aSurveyInfo.options.surveyname2 == "on") %}
<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
{% endif %}

{# Group Name #}
{{ include('./subviews/survey/group_subviews/group_name.twig') }}

{# Group Description #}
{{ include('./subviews/survey/group_subviews/group_desc.twig') }}

{#
PRESENT THE QUESTIONS

This is the main part. It will render each question for this group
#}


{% for aQuestion in aGroup.aQuestions %}
{{ include('./subviews/survey/question_container.twig') }}
{% endfor %}


{% if aGroup.show_last_group == true %}
<input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
{% endif %}

{% if aGroup.show_last_answer == true %}
<input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
{% endif %}
</div></syntaxhighlight>
# Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60ph1.custom-survey-name {
margin: 0;
text-align: center;
}</syntaxhighlight>
#Toggle the "Survey name below progress bar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_3.png]]

===Downloads=== 
* Sample extended theme: [[Media:Test_survey_names.zip]]

=Creating a theme from scratch= 
Documentation coming soon.

For now, just giving few tips.

==theme structure==

=== Files and directories ===
When you create a Theme from scratch, you don't need to respect the file/directory structure/css/js from Vanilla.
The mandatory css/js is added by core (you can still remove it if needed)

The only files your theme must have are the layout files:

* '''layout_global.twig''' : render the pages for survey taking
* '''layout_survey_list.twig''' : render the survey list (if this theme is set as default)
* '''layout_errors.twig''' : used to render errors that block survey rendering. ( wrong survey id, empty group in preview group, etc.)
* '''layout_user_forms.twig''': renders the user forms such as: token (survey participant), and register.
* '''layout_print.twig''' : used to print the survey to pdf
* '''layout_printanswers.twig''': print the answers

The content of those files, the files they include or not, is entirely up to you.
All the other files and directories that you find on Vanilla are purely optional, feel free to organize your code the way you want.

<div class="simplebox">[[File:help.png]] If you read the frontend rendering code, you'll see that those files names appear directly in it. That's why they are mandatory.
Eg: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/helpers/SurveyRuntimeHelper.php#L462
</div>

=== Content ===

In Vanilla's layout_global.twig, you'll see we use a variable called "include_content" to decide what to show
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/layout_global.twig#L114-L115

<syntaxhighlight lang="php" enclose="div">
{% set sViewContent = './subviews/content/' ~ aSurveyInfo.include_content ~ '.twig' %}
{% include './subviews/content/outerframe.twig' with {'include_content': sViewContent } %}
</syntaxhighlight>

aSurveyInfo.include_content tell you what action is currently going on: showing questions? showing submit result? showing clear all? etc
As you can see, in vanilla, we create one file to include by action. So if you want to know the list of actions, just check the vanilla's directory '''views/subviews/content''', and remove the "twig" extension :
https://github.com/LimeSurvey/LimeSurvey/tree/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/subviews/content

* '''clearall.twig'''
* '''firstpage.twig'''
* '''load.twig'''
* '''mainrow.twig'''
* '''main.twig'''
* '''optin.twig'''
* '''optout.twig'''
* '''outerframe.twig'''
* '''printanswers.twig'''
* '''quotas.twig'''
* '''register.twig'''
* '''save.twig'''
* '''submit_preview.twig'''
* '''submit.twig'''
* '''userforms.twig'''

If you already created a them for 2.x versions of LimeSurvey, you'll notice that most of them corresponds to the old pstpl files for limesurvey 2.x.
Again, there is no obligation for you in your theme to create those files, with those names, in this directory. You could for example just add a giant switch in layout_global.twig with the wanted HTML for each action.

=== The manifest config.xml ===

The manifest of the theme contains the main informations about your theme. When you install a theme, the content of the manifest will be loaded in the database, in two different tables: template and template_configuration.

==== The metadata section ====

Nothing complex: just the main infos about your theme. It will be pushed in the table templates_configuration

<syntaxhighlight lang="xml" enclose="div">
<metadata>
<name>the_name_of_your_theme</name>
<title>The Title of your theme</title>
<creationDate>16/10/2017</creationDate>
<author>Your Name</author>
<authorEmail>your@email.org</authorEmail>
<authorUrl>http://www.yourwebsite.org</authorUrl>
<copyright>Your Copyright </copyright>
<license>Licence of your theme</license>
<version>version of your theme</version>
<apiVersion>3</apiVersion>
<description>Description of your theme</description>
</metadata>
</syntaxhighlight>

Few remarks:
* '''name''': will be used as a key in the db. So it must be unique, and it should not have any special chars (no spaces). Note that cases will not be taken in account
* '''Title''': will be used to display your theme name in the different lists. It can have special chars
* '''description''': will be used in the main list of survey theme. It can contains special chars, and even HTML code by using <![CDATA[

==== The files section ====

This one is an important one. It will be pushed in the table template_configuration, in the field files_css, files_js, files_print_css as json arrays.

Eg: the files section of the Material Premium Theme:

<syntaxhighlight lang="xml" enclose="div">
<files>
<css>
<add>css/bootstrap-material-design.css</add>
<add>css/ripples.min.css</add>
<add>css/ajaxify.css</add>
<add>css/theme.css</add>
<add>css/custom.css</add>
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</css>
<js>
<add>scripts/theme.js</add>
<add>scripts/ajaxify.js</add>
<add>scripts/material.js</add>
<add>scripts/ripples.min.js</add>
<add>scripts/custom.js</add>
</js>
<print_css>
<add>css/print_theme.css</add>
</print_css>
</files>
</syntaxhighlight>

All the CSS/JS files present in this section will be loaded at the launch of the survey (in ajax mode. If ajax mode is off, then of course all the files are reloaded at each page).

They will be added to a Yii Asset Packet based on the name of the theme. So when Asset Manager is on (debug mode being off), those files will be copied to the tmp directory with the rest of the theme (so you can use relative path in the CSS and JS to reach the image files).
About the Asset manager in Yii: https://www.yiiframework.com/wiki/148/understanding-assets
About packages in Yii: http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail

They will use the inheritance system. It means that if you add a CSS/JS file to a theme, but it's not present in the theme, then the engine will look into all the mother themes of this theme and will use the first one it finds. So if a user extend your theme via the theme editor, all those files will be inherited in his theme. The keyword refer to this inheritance system.

* '''add''' : it will add the file to the theme, and to all its inherited theme
* '''replace''': it will replace the the file of its mother theme
* '''remove''': it will remove the file from '''any''' package, even the core package (since 3.14)

Few remarks on those keywords:

You can't add a file with the same name as the mother theme: it will always replace it. eg: If you have a file called "my_mother_theme/foo.css" and you add a file called "foo.cs" in the daughter theme, only "daughter_theme/foo.css" will be added to the theme. If you want to keep "my_mother_theme/foo.css", just choose another name for "daughter_theme/foo.css", like "daughter_theme/bar.css". So the keyword "add" can be used as a "replace" keyword. If you wonder why: this make much easier the automatic generation of inherited theme, copying the file section works out of the box (no need to rename "add" to "replace" when extending one the file).

The remove keyword is available only since 3.14. With this one, you can remove any css/file from any package, even the core ones. It is used in Material Premium Theme to remove the Awseome Bootstrap Checkbox's files:

<syntaxhighlight lang="xml" enclose="div">
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</syntaxhighlight>

so you should use the very same syntax as the package's file (eg: "awesome-bootstrap-checkbox.css" alone without it's folder path would not work). You'll find the complete list of core packages and their files in /application/config/packages.php and config/third_party.php. For example, for awesome-bootstrap-checkbox.css:
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/config/packages.php#L54-L56

<syntaxhighlight lang="php" enclose="div">
'css'=> array(
'awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css',
),
</syntaxhighlight>

Another way to find the exact name to use in the remove tag is to turn asset manager on (turning debug mode off or setting 'use_asset_manager'=>true in the config). Then, the path to use will be the one just after the random directory in the tmp directory. For example, for awesome-bootstrap-checkbox.css:
<syntaxhighlight lang="html" enclose="div">
<link rel="stylesheet" type="text/css" href="/tmp/assets/cbc4e3cb/awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css" />
</syntaxhighlight>

<div class="simplebox">[[File:help.png]]
You can also register CSS and JS files directly from the twig code. But, if the CSS and JS files are inside the Theme itself, remember to use the functions {{registerTemplateCssFile('my_style.css')}} and {{registerTemplateScript('my_script.js')}}. If you don't use those functions, your theme may work, but inheritance on it will be broken. It is the same logic as the {{image('my_picture.jpg')}} function
</div>

==== The options section ====

This section is relative to the option of your theme. It will be used to feed the filed "options" of the table template_configuration as a json array.

== Some notes ==


'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.


'''NOTE''': to avoid that, you can force the use to the XML rather than DB. In config.php turn debug mode on and uncommment:


'force_xmlsettings_for_survey_rendering' => true, // Uncomment if you want to force the use of the XML file rather than DB (for easy theme development)


Becareful: everything will be loaded from the XML (included options, etc)


'''NOTE''': if you manually edit the CSS/JS files (without using the Theme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache".


'''NOTE''': if you remove the section

</translate>

New Template System in LS3.x

2018-08-13T11:44:19Z

LouisGac:

<languages />
<translate>

__TOC__
=Introduction= 


On this page you'll learn how to:


* Use the new theme system of LimeSurvey 3.0.
* Use inheritance to manage your own themes.
* Add a picture to your theme
* Manage theme options for your surveys and survey groups


<hr/>


LimeSurvey 3 introduces a complete new theme engine system, based on Twig 1.29, Bootstrap, and allowing theme inheritance and theme options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old theme system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A theme designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new theme engine.


<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Theme Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface= 
==theme list==
On the admin dashboard, there is now a box to access the theme list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The theme list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the theme: it’s just a picture file called “preview.png” at the root of the theme
* the “title” of the theme as specified in the manifest (config.xml in the root of the theme)
* the description of the theme: a string set in its manifest
* the type of theme: Core theme (provided with LimeSurvey), User theme (added in upload directory), XML theme (not loaded in database)
* Extends: if the theme extends another theme, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a theme to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a theme in the database
** Theme editor: it will redirect you to the theme editor
** Theme option: it will lead you the global configuration of theme options

==Theme Editor== 
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' theme'']]

====A quick overview of the concept of theme inheritance==== 


In LS3, a theme can now inherit from another theme, it can “extend” another theme. This means that the theme directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of themes for your different users without having to maintain a lot of different themes. For example: you can have your own home-made theme, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom theme, all the themes that inherit from it will be updated automatically. Note that the inheritance is recursive: a theme can extend a theme that extends another one etc.


<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core themes of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface==== 


To extend the Monochrome theme of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome theme. Then, click on “extend” and validate the new name “extends_monochrome”.


If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/themes/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this theme as a normal one from a survey and it will look exactly like the monochrome theme.


[[File:Extends monochrome empty.jpg|center|baseline|border|''The theme tree (directory and files) just after its creation. It's practically empty'']]


<div class="simplebox">[[File:help.png]] The resources (jpg, png etc.) from the original theme are copied when extending a theme. This is because if you copy a CSS file from the original theme locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current theme path. </div>


The theme editor for the extends_monochrome theme looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome theme'']]
<br /><br />
There is no big difference with the old theme editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the theme directory and that the file from the original theme will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to theme views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local theme and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ==== 


The button '''Copy to local theme and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the theme you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button'']]
<br>
If you open a file explorer and go to the directory upload/themes/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your theme'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).


<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the theme to find the image. If the theme you’re working on is extended to another theme, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local theme, it will loop through the theme inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your theme. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/


<div class="simplebox">
So, to add a picture to your theme:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''


* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}


* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list==== 
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which theme the current one extends (if any)

==Template options== 
Another novelty of LS3 is the theme option page. As we’ll see later, theme creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the theme options at global level: click on “theme options” in the theme list
===Advanced options===


{{QS:Theme editor - advanced options}}

===Simple options=== 


The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the theme's /options directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options (Broken link)
<div class="simplebox">[[File:help.png]] This page can be completely different from a theme to another, and theme providers are strongly encouraged to create their own look & feel. </div>


[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from


{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core themes:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a theme provider could add his own animation library or no animation library at all.


<div class="simplebox">[[File:help.png]] The monochrome themes use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for theme providers.</div>

===Inheritance system=== 


In the previous part, we’ve seen that a theme can extend another theme. A theme configuration can also inherit from another theme configuration. It means that for a given theme, you can have a configuration at


* global level (the one we’ve just seen accessible from the theme list)
* at survey group level
* a last one at survey level.


Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

====At survey group level==== 


Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of themes than in the theme list, except that here only the option button is visible (theme editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]


<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

====At survey level==== 
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example== 
Let’s say you’re using a single theme for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core theme. But of course, if you are a theme provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization = 


You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS/JS: deal with the asset manager ("why are my changes not applied?") == 
<br />


If you're trying to update the CSS/JS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.


<br />


Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />


It moves the CSS/JS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css/js file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css/js. Else, they would have to clean their browser cache.


<br />


Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.


<br />


Here the CSS links in header when asset manager is off:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.


<br />


<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>


So, when you're editing CSS/JS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache


[[File:Clearassets-ls3 3.png]]


<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>


Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme == 
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how it works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css


<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>


Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>


You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font === 
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>


You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.


Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options === 
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>


* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %} //Shouldn't this be "theme" in stead of "template"?
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>


<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector === 
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">


'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}


</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79


<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>


Of course, the XML file only contains the default values for your theme configuration. But indeed, those values are defined and read inside the database (table "template_configuration" (Question: "template_" of "theme_"?) as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174


So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

== Adding theme options to control positioning and display of survey elements == 
This tutorial will show how to add options to an extended theme to display survey elements in various locations. In this case, we will create theme options to show the survey title in two different locations.
<div class="simplebox">[[File:help.png]] For the sake of simplicity, we will base the tutorial on an extension of the "bootswatch" theme in LimeSurvey version 3.4.3.</div>
=== Create a custom theme ===
#Extend the "bootswatch" theme as described above.
#Copy <span style="color: #BA2121;">custom.css</span> to the local theme as described above.
===Create new theme options===
#Copy the contents of <span style="color: #BA2121;">/themes/survey/bootswatch/options/</span> to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/</span>.
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/options.twig</span> in an editor and find "{# Bootstrap Bootswatch theme #}". Directly before its parent <nowiki><div class='row'></nowiki> element, add this:<syntaxhighlight lang="html" enclose="div">
{# Custom survey name in navbar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div>


{# Custom survey name below progress bar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div></syntaxhighlight>
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/config.xml</span> and add two items to the "options" block so it looks like this:<syntaxhighlight lang="xml" enclose="div"> <options>
<ajaxmode>on</ajaxmode>
...
<surveyname1>on</surveyname1>
<surveyname2>on</surveyname2>
</options></syntaxhighlight>
#This should give you two new options in the Theme Options screen like this:<br />[[File:Tutorial_tp_1_1.png]]

===Modifed view for Survey Title in the navbar=== 
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/header/</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> and find "{# Logo option #}". Under that, modify the IF statement for the logo/survey-name, so it looks like this:<syntaxhighlight lang="html" enclose="div">
{# Logo option #}
{% if( aSurveyInfo.options.brandlogo == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }} logo-container" {{ aSurveyInfo.attr.navbarbrand }} >
{{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
</div>
{% endif %}
{% if( aSurveyInfo.options.surveyname1 == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }}" {{ aSurveyInfo.attr.navbarbrand }} >
{{ aSurveyInfo.name }}
</div>
{% endif %}</syntaxhighlight>
#Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60px;
font-size: 32px;
}</syntaxhighlight>
#Toggle the "Survey name in navbar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_2.png]]
===Modifed view for Survey Title under progress bar===
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> and add an <nowiki><h1></nowiki> element for the survey name. So it looks like this:<syntaxhighlight lang="html" enclose="div"><div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>

{# Custom survey name #}
{% if( aSurveyInfo.options.surveyname2 == "on") %}
<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
{% endif %}

{# Group Name #}
{{ include('./subviews/survey/group_subviews/group_name.twig') }}

{# Group Description #}
{{ include('./subviews/survey/group_subviews/group_desc.twig') }}

{#
PRESENT THE QUESTIONS

This is the main part. It will render each question for this group
#}


{% for aQuestion in aGroup.aQuestions %}
{{ include('./subviews/survey/question_container.twig') }}
{% endfor %}


{% if aGroup.show_last_group == true %}
<input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
{% endif %}

{% if aGroup.show_last_answer == true %}
<input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
{% endif %}
</div></syntaxhighlight>
# Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60ph1.custom-survey-name {
margin: 0;
text-align: center;
}</syntaxhighlight>
#Toggle the "Survey name below progress bar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_3.png]]

===Downloads=== 
* Sample extended theme: [[Media:Test_survey_names.zip]]

=Creating a theme from scratch= 
Documentation coming soon.

For now, just giving few tips.

==theme structure==

=== Files and directories ===
When you create a Theme from scratch, you don't need to respect the file/directory structure/css/js from Vanilla.
The mandatory css/js is added by core (you can still remove it if needed)

The only files your theme must have are the layout files:

* '''layout_global.twig''' : render the pages for survey taking
* '''layout_survey_list.twig''' : render the survey list (if this theme is set as default)
* '''layout_errors.twig''' : used to render errors that block survey rendering. ( wrong survey id, empty group in preview group, etc.)
* '''layout_user_forms.twig''': renders the user forms such as: token (survey participant), and register.
* '''layout_print.twig''' : used to print the survey to pdf
* '''layout_printanswers.twig''': print the answers

The content of those files, the files they include or not, is entirely up to you.
All the other files and directories that you find on Vanilla are purely optional, feel free to organize your code the way you want.

<div class="simplebox">[[File:help.png]] If you read the frontend rendering code, you'll see that those files names appear directly in it. That's why they are mandatory.
Eg: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/helpers/SurveyRuntimeHelper.php#L462
</div>

=== Content ===

In Vanilla's layout_global.twig, you'll see we use a variable called "include_content" to decide what to show
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/layout_global.twig#L114-L115

<syntaxhighlight lang="php" enclose="div">
{% set sViewContent = './subviews/content/' ~ aSurveyInfo.include_content ~ '.twig' %}
{% include './subviews/content/outerframe.twig' with {'include_content': sViewContent } %}
</syntaxhighlight>

aSurveyInfo.include_content tell you what action is currently going on: showing questions? showing submit result? showing clear all? etc
As you can see, in vanilla, we create one file to include by action. So if you want to know the list of actions, just check the vanilla's directory '''views/subviews/content''', and remove the "twig" extension :
https://github.com/LimeSurvey/LimeSurvey/tree/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/subviews/content

* '''clearall.twig'''
* '''firstpage.twig'''
* '''load.twig'''
* '''mainrow.twig'''
* '''main.twig'''
* '''optin.twig'''
* '''optout.twig'''
* '''outerframe.twig'''
* '''printanswers.twig'''
* '''quotas.twig'''
* '''register.twig'''
* '''save.twig'''
* '''submit_preview.twig'''
* '''submit.twig'''
* '''userforms.twig'''

If you already created a them for 2.x versions of LimeSurvey, you'll notice that most of them corresponds to the old pstpl files for limesurvey 2.x.
Again, there is no obligation for you in your theme to create those files, with those names, in this directory. You could for example just add a giant switch in layout_global.twig with the wanted HTML for each action.

=== The manifest config.xml ===

The manifest of the theme contains the main informations about your theme. When you install a theme, the content of the manifest will be loaded in the database, in two different tables: template and template_configuration.

==== The metadata section ====

Nothing complex: just the main infos about your theme.

<syntaxhighlight lang="xml" enclose="div">
<metadata>
<name>the_name_of_your_theme</name>
<title>The Title of your theme</title>
<creationDate>16/10/2017</creationDate>
<author>Your Name</author>
<authorEmail>your@email.org</authorEmail>
<authorUrl>http://www.yourwebsite.org</authorUrl>
<copyright>Your Copyright </copyright>
<license>Licence of your theme</license>
<version>version of your theme</version>
<apiVersion>3</apiVersion>
<description>Description of your theme</description>
</metadata>
</syntaxhighlight>

Few remarks:
* '''name''': will be used as a key in the db. So it must be unique, and it should not have any special chars (no spaces). Note that cases will not be taken in account
* '''Title''': will be used to display your theme name in the different lists. It can have special chars
* '''description''': will be used in the main list of survey theme. It can contains special chars, and even HTML code by using <![CDATA[

==== The files section ====

This one is an important one.

Eg: the files section of the Material Premium Theme:

<syntaxhighlight lang="xml" enclose="div">
<files>
<css>
<add>css/bootstrap-material-design.css</add>
<add>css/ripples.min.css</add>
<add>css/ajaxify.css</add>
<add>css/theme.css</add>
<add>css/custom.css</add>
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</css>
<js>
<add>scripts/theme.js</add>
<add>scripts/ajaxify.js</add>
<add>scripts/material.js</add>
<add>scripts/ripples.min.js</add>
<add>scripts/custom.js</add>
</js>
<print_css>
<add>css/print_theme.css</add>
</print_css>
</files>
</syntaxhighlight>

All the CSS/JS files present in this section will be loaded at the launch of the survey (in ajax mode. If ajax mode is off, then of course all the files are reloaded at each page).

They will be added to a Yii Asset Packet based on the name of the theme. So when Asset Manager is on (debug mode being off), those files will be copied to the tmp directory with the rest of the theme (so you can use relative path in the CSS and JS to reach the image files).
About the Asset manager in Yii: https://www.yiiframework.com/wiki/148/understanding-assets
About packages in Yii: http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail

They will use the inheritance system. It means that if you add a CSS/JS file to a theme, but it's not present in the theme, then the engine will look into all the mother themes of this theme and will use the first one it finds. So if a user extend your theme via the theme editor, all those files will be inherited in his theme. The keyword refer to this inheritance system.

* '''add''' : it will add the file to the theme, and to all its inherited theme
* '''replace''': it will replace the the file of its mother theme
* '''remove''': it will remove the file from '''any''' package, even the core package (since 3.14)

Few remarks on those keywords:

You can't add a file with the same name as the mother theme: it will always replace it. eg: If you have a file called "my_mother_theme/foo.css" and you add a file called "foo.cs" in the daughter theme, only "daughter_theme/foo.css" will be added to the theme. If you want to keep "my_mother_theme/foo.css", just choose another name for "daughter_theme/foo.css", like "daughter_theme/bar.css". So the keyword "add" can be used as a "replace" keyword. If you wonder why: this make much easier the automatic generation of inherited theme, copying the file section works out of the box (no need to rename "add" to "replace" when extending one the file).

The remove keyword is available only since 3.14. With this one, you can remove any css/file from any package, even the core ones. It is used in Material Premium Theme to remove the Awseome Bootstrap Checkbox's files:

<syntaxhighlight lang="xml" enclose="div">
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</syntaxhighlight>

so you should use the very same syntax as the package's file (eg: "awesome-bootstrap-checkbox.css" alone without it's folder path would not work). You'll find the complete list of core packages and their files in /application/config/packages.php and config/third_party.php. For example, for awesome-bootstrap-checkbox.css:
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/config/packages.php#L54-L56

<syntaxhighlight lang="php" enclose="div">
'css'=> array(
'awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css',
),
</syntaxhighlight>

Another way to find the exact name to use in the remove tag is to turn asset manager on (turning debug mode off or setting 'use_asset_manager'=>true in the config). Then, the path to use will be the one just after the random directory in the tmp directory. For example, for awesome-bootstrap-checkbox.css:
<syntaxhighlight lang="html" enclose="div">
<link rel="stylesheet" type="text/css" href="/tmp/assets/cbc4e3cb/awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css" />
</syntaxhighlight>

<div class="simplebox">[[File:help.png]]
You can also register CSS and JS files directly from the twig code. But, if the CSS and JS files are inside the Theme itself, remember to use the functions {{registerTemplateCssFile('my_style.css')}} and {{registerTemplateScript('my_script.js')}}. If you don't use those functions, your theme may work, but inheritance on it will be broken. It is the same logic as the {{image('my_picture.jpg')}} function
</div>

== Some notes ==


'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.


'''NOTE''': to avoid that, you can force the use to the XML rather than DB. In config.php turn debug mode on and uncommment:


'force_xmlsettings_for_survey_rendering' => true, // Uncomment if you want to force the use of the XML file rather than DB (for easy theme development)


Becareful: everything will be loaded from the XML (included options, etc)


'''NOTE''': if you manually edit the CSS/JS files (without using the Theme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache".


'''NOTE''': if you remove the section

</translate>

New Template System in LS3.x

2018-08-13T11:39:47Z

LouisGac: /* The files section */

<languages />
<translate>

__TOC__
=Introduction= 


On this page you'll learn how to:


* Use the new theme system of LimeSurvey 3.0.
* Use inheritance to manage your own themes.
* Add a picture to your theme
* Manage theme options for your surveys and survey groups


<hr/>


LimeSurvey 3 introduces a complete new theme engine system, based on Twig 1.29, Bootstrap, and allowing theme inheritance and theme options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old theme system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A theme designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new theme engine.


<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Theme Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface= 
==theme list==
On the admin dashboard, there is now a box to access the theme list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The theme list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the theme: it’s just a picture file called “preview.png” at the root of the theme
* the “title” of the theme as specified in the manifest (config.xml in the root of the theme)
* the description of the theme: a string set in its manifest
* the type of theme: Core theme (provided with LimeSurvey), User theme (added in upload directory), XML theme (not loaded in database)
* Extends: if the theme extends another theme, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a theme to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a theme in the database
** Theme editor: it will redirect you to the theme editor
** Theme option: it will lead you the global configuration of theme options

==Theme Editor== 
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' theme'']]

====A quick overview of the concept of theme inheritance==== 


In LS3, a theme can now inherit from another theme, it can “extend” another theme. This means that the theme directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of themes for your different users without having to maintain a lot of different themes. For example: you can have your own home-made theme, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom theme, all the themes that inherit from it will be updated automatically. Note that the inheritance is recursive: a theme can extend a theme that extends another one etc.


<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core themes of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface==== 


To extend the Monochrome theme of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome theme. Then, click on “extend” and validate the new name “extends_monochrome”.


If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/themes/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this theme as a normal one from a survey and it will look exactly like the monochrome theme.


[[File:Extends monochrome empty.jpg|center|baseline|border|''The theme tree (directory and files) just after its creation. It's practically empty'']]


<div class="simplebox">[[File:help.png]] The resources (jpg, png etc.) from the original theme are copied when extending a theme. This is because if you copy a CSS file from the original theme locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current theme path. </div>


The theme editor for the extends_monochrome theme looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome theme'']]
<br /><br />
There is no big difference with the old theme editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the theme directory and that the file from the original theme will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to theme views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local theme and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ==== 


The button '''Copy to local theme and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the theme you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button'']]
<br>
If you open a file explorer and go to the directory upload/themes/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your theme'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).


<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the theme to find the image. If the theme you’re working on is extended to another theme, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local theme, it will loop through the theme inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your theme. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/


<div class="simplebox">
So, to add a picture to your theme:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''


* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}


* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list==== 
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which theme the current one extends (if any)

==Template options== 
Another novelty of LS3 is the theme option page. As we’ll see later, theme creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the theme options at global level: click on “theme options” in the theme list
===Advanced options===


{{QS:Theme editor - advanced options}}

===Simple options=== 


The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the theme's /options directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options (Broken link)
<div class="simplebox">[[File:help.png]] This page can be completely different from a theme to another, and theme providers are strongly encouraged to create their own look & feel. </div>


[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from


{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core themes:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a theme provider could add his own animation library or no animation library at all.


<div class="simplebox">[[File:help.png]] The monochrome themes use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for theme providers.</div>

===Inheritance system=== 


In the previous part, we’ve seen that a theme can extend another theme. A theme configuration can also inherit from another theme configuration. It means that for a given theme, you can have a configuration at


* global level (the one we’ve just seen accessible from the theme list)
* at survey group level
* a last one at survey level.


Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

====At survey group level==== 


Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of themes than in the theme list, except that here only the option button is visible (theme editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]


<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

====At survey level==== 
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example== 
Let’s say you’re using a single theme for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core theme. But of course, if you are a theme provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization = 


You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS/JS: deal with the asset manager ("why are my changes not applied?") == 
<br />


If you're trying to update the CSS/JS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.


<br />


Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />


It moves the CSS/JS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css/js file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css/js. Else, they would have to clean their browser cache.


<br />


Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.


<br />


Here the CSS links in header when asset manager is off:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.


<br />


<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>


So, when you're editing CSS/JS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache


[[File:Clearassets-ls3 3.png]]


<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>


Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme == 
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how it works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css


<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>


Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>


You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font === 
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>


You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.


Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options === 
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>


* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %} //Shouldn't this be "theme" in stead of "template"?
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>


<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector === 
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">


'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}


</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79


<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>


Of course, the XML file only contains the default values for your theme configuration. But indeed, those values are defined and read inside the database (table "template_configuration" (Question: "template_" of "theme_"?) as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174


So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

== Adding theme options to control positioning and display of survey elements == 
This tutorial will show how to add options to an extended theme to display survey elements in various locations. In this case, we will create theme options to show the survey title in two different locations.
<div class="simplebox">[[File:help.png]] For the sake of simplicity, we will base the tutorial on an extension of the "bootswatch" theme in LimeSurvey version 3.4.3.</div>
=== Create a custom theme ===
#Extend the "bootswatch" theme as described above.
#Copy <span style="color: #BA2121;">custom.css</span> to the local theme as described above.
===Create new theme options===
#Copy the contents of <span style="color: #BA2121;">/themes/survey/bootswatch/options/</span> to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/</span>.
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/options.twig</span> in an editor and find "{# Bootstrap Bootswatch theme #}". Directly before its parent <nowiki><div class='row'></nowiki> element, add this:<syntaxhighlight lang="html" enclose="div">
{# Custom survey name in navbar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div>


{# Custom survey name below progress bar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div></syntaxhighlight>
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/config.xml</span> and add two items to the "options" block so it looks like this:<syntaxhighlight lang="xml" enclose="div"> <options>
<ajaxmode>on</ajaxmode>
...
<surveyname1>on</surveyname1>
<surveyname2>on</surveyname2>
</options></syntaxhighlight>
#This should give you two new options in the Theme Options screen like this:<br />[[File:Tutorial_tp_1_1.png]]

===Modifed view for Survey Title in the navbar=== 
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/header/</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> and find "{# Logo option #}". Under that, modify the IF statement for the logo/survey-name, so it looks like this:<syntaxhighlight lang="html" enclose="div">
{# Logo option #}
{% if( aSurveyInfo.options.brandlogo == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }} logo-container" {{ aSurveyInfo.attr.navbarbrand }} >
{{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
</div>
{% endif %}
{% if( aSurveyInfo.options.surveyname1 == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }}" {{ aSurveyInfo.attr.navbarbrand }} >
{{ aSurveyInfo.name }}
</div>
{% endif %}</syntaxhighlight>
#Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60px;
font-size: 32px;
}</syntaxhighlight>
#Toggle the "Survey name in navbar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_2.png]]
===Modifed view for Survey Title under progress bar===
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> and add an <nowiki><h1></nowiki> element for the survey name. So it looks like this:<syntaxhighlight lang="html" enclose="div"><div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>

{# Custom survey name #}
{% if( aSurveyInfo.options.surveyname2 == "on") %}
<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
{% endif %}

{# Group Name #}
{{ include('./subviews/survey/group_subviews/group_name.twig') }}

{# Group Description #}
{{ include('./subviews/survey/group_subviews/group_desc.twig') }}

{#
PRESENT THE QUESTIONS

This is the main part. It will render each question for this group
#}


{% for aQuestion in aGroup.aQuestions %}
{{ include('./subviews/survey/question_container.twig') }}
{% endfor %}


{% if aGroup.show_last_group == true %}
<input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
{% endif %}

{% if aGroup.show_last_answer == true %}
<input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
{% endif %}
</div></syntaxhighlight>
# Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60ph1.custom-survey-name {
margin: 0;
text-align: center;
}</syntaxhighlight>
#Toggle the "Survey name below progress bar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_3.png]]

===Downloads=== 
* Sample extended theme: [[Media:Test_survey_names.zip]]

=Creating a theme from scratch= 
Documentation coming soon.

For now, just giving few tips.

==theme structure==

=== Files and directories ===
When you create a Theme from scratch, you don't need to respect the file/directory structure/css/js from Vanilla.
The mandatory css/js is added by core (you can still remove it if needed)

The only files your theme must have are the layout files:

* '''layout_global.twig''' : render the pages for survey taking
* '''layout_survey_list.twig''' : render the survey list (if this theme is set as default)
* '''layout_errors.twig''' : used to render errors that block survey rendering. ( wrong survey id, empty group in preview group, etc.)
* '''layout_user_forms.twig''': renders the user forms such as: token (survey participant), and register.
* '''layout_print.twig''' : used to print the survey to pdf
* '''layout_printanswers.twig''': print the answers

The content of those files, the files they include or not, is entirely up to you.
All the other files and directories that you find on Vanilla are purely optional, feel free to organize your code the way you want.

<div class="simplebox">[[File:help.png]] If you read the frontend rendering code, you'll see that those files names appear directly in it. That's why they are mandatory.
Eg: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/helpers/SurveyRuntimeHelper.php#L462
</div>

=== Content ===

In Vanilla's layout_global.twig, you'll see we use a variable called "include_content" to decide what to show
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/layout_global.twig#L114-L115

<syntaxhighlight lang="php" enclose="div">
{% set sViewContent = './subviews/content/' ~ aSurveyInfo.include_content ~ '.twig' %}
{% include './subviews/content/outerframe.twig' with {'include_content': sViewContent } %}
</syntaxhighlight>

aSurveyInfo.include_content tell you what action is currently going on: showing questions? showing submit result? showing clear all? etc
As you can see, in vanilla, we create one file to include by action. So if you want to know the list of actions, just check the vanilla's directory '''views/subviews/content''', and remove the "twig" extension :
https://github.com/LimeSurvey/LimeSurvey/tree/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/subviews/content

* '''clearall.twig'''
* '''firstpage.twig'''
* '''load.twig'''
* '''mainrow.twig'''
* '''main.twig'''
* '''optin.twig'''
* '''optout.twig'''
* '''outerframe.twig'''
* '''printanswers.twig'''
* '''quotas.twig'''
* '''register.twig'''
* '''save.twig'''
* '''submit_preview.twig'''
* '''submit.twig'''
* '''userforms.twig'''

If you already created a them for 2.x versions of LimeSurvey, you'll notice that most of them corresponds to the old pstpl files for limesurvey 2.x.
Again, there is no obligation for you in your theme to create those files, with those names, in this directory. You could for example just add a giant switch in layout_global.twig with the wanted HTML for each action.

=== The manifest config.xml ===

The manifest of the theme contains the main informations about your theme. When you install a theme, the content of the manifest will be loaded in the database, in two different tables: template and template_configuration.

==== The metadata section ====

Nothing complex: just the main infos about your theme.

<syntaxhighlight lang="xml" enclose="div">
<metadata>
<name>the_name_of_your_theme</name>
<title>The Title of your theme</title>
<creationDate>16/10/2017</creationDate>
<author>Your Name</author>
<authorEmail>your@email.org</authorEmail>
<authorUrl>http://www.yourwebsite.org</authorUrl>
<copyright>Your Copyright </copyright>
<license>Licence of your theme</license>
<version>version of your theme</version>
<apiVersion>3</apiVersion>
<description>Description of your theme</description>
</metadata>
</syntaxhighlight>

Few remarks:
* '''name''': will be used as a key in the db. So it must be unique, and it should not have any special chars (no spaces). Note that cases will not be taken in account
* '''Title''': will be used to display your theme name in the different lists. It can have special chars
* '''description''': will be used in the main list of survey theme. It can contains special chars, and even HTML code by using <![CDATA[

==== The files section ====

This one is an important one.

Eg: the files section of the Material Premium Theme:

<syntaxhighlight lang="xml" enclose="div">
<files>
<css>
<add>css/bootstrap-material-design.css</add>
<add>css/ripples.min.css</add>
<add>css/ajaxify.css</add>
<add>css/theme.css</add>
<add>css/custom.css</add>
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</css>
<js>
<add>scripts/theme.js</add>
<add>scripts/ajaxify.js</add>
<add>scripts/material.js</add>
<add>scripts/ripples.min.js</add>
<add>scripts/custom.js</add>
</js>
<print_css>
<add>css/print_theme.css</add>
</print_css>
</files>
</syntaxhighlight>

All the CSS/JS files present in this section will be loaded at the launch of the survey (in ajax mode. If ajax mode is off, then of course all the files are reloaded at each page).

They will be added to a Yii Asset Packet based on the name of the theme. So when Asset Manager is on (debug mode being off), those files will be copied to the tmp directory with the rest of the theme (so you can use relative path in the CSS and JS to reach the image files).
About the Asset manager in Yii: https://www.yiiframework.com/wiki/148/understanding-assets
About packages in Yii: http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail

They will use the inheritance system. It means that if you add a CSS/JS file to a theme, but it's not present in the theme, then the engine will look into all the mother themes of this theme and will use the first one it finds. So if a user extend your theme via the theme editor, all those files will be inherited in his theme. The keyword refer to this inheritance system.

* '''add''' : it will add the file to the theme, and to all its inherited theme
* '''replace''': it will replace the the file of its mother theme
* '''remove''': it will remove the file from '''any''' package, even the core package (since 3.14)

Few remarks on those keywords:

You can't add a file with the same name as the mother theme: it will always replace it. eg: If you have a file called "my_mother_theme/foo.css" and you add a file called "foo.cs" in the daughter theme, only "daughter_theme/foo.css" will be added to the theme. If you want to keep "my_mother_theme/foo.css", just choose another name for "daughter_theme/foo.css", like "daughter_theme/bar.css". So the keyword "add" can be used as a "replace" keyword. If you wonder why: this make much easier the automatic generation of inherited theme, copying the file section works out of the box (no need to rename "add" to "replace" when extending one the file).

The remove keyword is available only since 3.14. With this one, you can remove any css/file from any package, even the core ones. It is used in Material Premium Theme to remove the Awseome Bootstrap Checkbox's files:

<syntaxhighlight lang="xml" enclose="div">
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</syntaxhighlight>

so you should use the very same syntax as the package's file (eg: "awesome-bootstrap-checkbox.css" alone without it's folder path would not work). You'll find the complete list of core packages and their files in /application/config/packages.php and config/third_party.php. For example, for awesome-bootstrap-checkbox.css:
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/config/packages.php#L54-L56

<syntaxhighlight lang="php" enclose="div">
'css'=> array(
'awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css',
),
</syntaxhighlight>

Another way to find the exact name to use in the remove tag is to turn asset manager on (turning debug mode off or setting 'use_asset_manager'=>true in the config). Then, the path to use will be the one just after the random directory in the tmp directory. For example, for awesome-bootstrap-checkbox.css:
<syntaxhighlight lang="html" enclose="div">
<link rel="stylesheet" type="text/css" href="/tmp/assets/cbc4e3cb/awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css" />
</syntaxhighlight>

== Some notes ==


'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.


'''NOTE''': to avoid that, you can force the use to the XML rather than DB. In config.php turn debug mode on and uncommment:


'force_xmlsettings_for_survey_rendering' => true, // Uncomment if you want to force the use of the XML file rather than DB (for easy theme development)


Becareful: everything will be loaded from the XML (included options, etc)


'''NOTE''': if you manually edit the CSS/JS files (without using the Theme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache".


'''NOTE''': if you remove the section

</translate>

New Template System in LS3.x

2018-08-13T11:39:17Z

LouisGac: /* The files section */

<languages />
<translate>

__TOC__
=Introduction= 


On this page you'll learn how to:


* Use the new theme system of LimeSurvey 3.0.
* Use inheritance to manage your own themes.
* Add a picture to your theme
* Manage theme options for your surveys and survey groups


<hr/>


LimeSurvey 3 introduces a complete new theme engine system, based on Twig 1.29, Bootstrap, and allowing theme inheritance and theme options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old theme system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A theme designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new theme engine.


<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Theme Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface= 
==theme list==
On the admin dashboard, there is now a box to access the theme list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The theme list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the theme: it’s just a picture file called “preview.png” at the root of the theme
* the “title” of the theme as specified in the manifest (config.xml in the root of the theme)
* the description of the theme: a string set in its manifest
* the type of theme: Core theme (provided with LimeSurvey), User theme (added in upload directory), XML theme (not loaded in database)
* Extends: if the theme extends another theme, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a theme to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a theme in the database
** Theme editor: it will redirect you to the theme editor
** Theme option: it will lead you the global configuration of theme options

==Theme Editor== 
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' theme'']]

====A quick overview of the concept of theme inheritance==== 


In LS3, a theme can now inherit from another theme, it can “extend” another theme. This means that the theme directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of themes for your different users without having to maintain a lot of different themes. For example: you can have your own home-made theme, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom theme, all the themes that inherit from it will be updated automatically. Note that the inheritance is recursive: a theme can extend a theme that extends another one etc.


<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core themes of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface==== 


To extend the Monochrome theme of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome theme. Then, click on “extend” and validate the new name “extends_monochrome”.


If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/themes/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this theme as a normal one from a survey and it will look exactly like the monochrome theme.


[[File:Extends monochrome empty.jpg|center|baseline|border|''The theme tree (directory and files) just after its creation. It's practically empty'']]


<div class="simplebox">[[File:help.png]] The resources (jpg, png etc.) from the original theme are copied when extending a theme. This is because if you copy a CSS file from the original theme locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current theme path. </div>


The theme editor for the extends_monochrome theme looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome theme'']]
<br /><br />
There is no big difference with the old theme editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the theme directory and that the file from the original theme will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to theme views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local theme and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ==== 


The button '''Copy to local theme and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the theme you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button'']]
<br>
If you open a file explorer and go to the directory upload/themes/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your theme'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).


<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the theme to find the image. If the theme you’re working on is extended to another theme, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local theme, it will loop through the theme inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your theme. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/


<div class="simplebox">
So, to add a picture to your theme:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''


* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}


* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list==== 
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which theme the current one extends (if any)

==Template options== 
Another novelty of LS3 is the theme option page. As we’ll see later, theme creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the theme options at global level: click on “theme options” in the theme list
===Advanced options===


{{QS:Theme editor - advanced options}}

===Simple options=== 


The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the theme's /options directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options (Broken link)
<div class="simplebox">[[File:help.png]] This page can be completely different from a theme to another, and theme providers are strongly encouraged to create their own look & feel. </div>


[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from


{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core themes:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a theme provider could add his own animation library or no animation library at all.


<div class="simplebox">[[File:help.png]] The monochrome themes use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for theme providers.</div>

===Inheritance system=== 


In the previous part, we’ve seen that a theme can extend another theme. A theme configuration can also inherit from another theme configuration. It means that for a given theme, you can have a configuration at


* global level (the one we’ve just seen accessible from the theme list)
* at survey group level
* a last one at survey level.


Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

====At survey group level==== 


Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of themes than in the theme list, except that here only the option button is visible (theme editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]


<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

====At survey level==== 
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example== 
Let’s say you’re using a single theme for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core theme. But of course, if you are a theme provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization = 


You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS/JS: deal with the asset manager ("why are my changes not applied?") == 
<br />


If you're trying to update the CSS/JS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.


<br />


Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />


It moves the CSS/JS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css/js file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css/js. Else, they would have to clean their browser cache.


<br />


Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.


<br />


Here the CSS links in header when asset manager is off:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.


<br />


<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>


So, when you're editing CSS/JS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache


[[File:Clearassets-ls3 3.png]]


<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>


Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme == 
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how it works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css


<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>


Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>


You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font === 
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>


You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.


Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options === 
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>


* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %} //Shouldn't this be "theme" in stead of "template"?
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>


<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector === 
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">


'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}


</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79


<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>


Of course, the XML file only contains the default values for your theme configuration. But indeed, those values are defined and read inside the database (table "template_configuration" (Question: "template_" of "theme_"?) as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174


So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

== Adding theme options to control positioning and display of survey elements == 
This tutorial will show how to add options to an extended theme to display survey elements in various locations. In this case, we will create theme options to show the survey title in two different locations.
<div class="simplebox">[[File:help.png]] For the sake of simplicity, we will base the tutorial on an extension of the "bootswatch" theme in LimeSurvey version 3.4.3.</div>
=== Create a custom theme ===
#Extend the "bootswatch" theme as described above.
#Copy <span style="color: #BA2121;">custom.css</span> to the local theme as described above.
===Create new theme options===
#Copy the contents of <span style="color: #BA2121;">/themes/survey/bootswatch/options/</span> to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/</span>.
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/options.twig</span> in an editor and find "{# Bootstrap Bootswatch theme #}". Directly before its parent <nowiki><div class='row'></nowiki> element, add this:<syntaxhighlight lang="html" enclose="div">
{# Custom survey name in navbar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div>


{# Custom survey name below progress bar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div></syntaxhighlight>
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/config.xml</span> and add two items to the "options" block so it looks like this:<syntaxhighlight lang="xml" enclose="div"> <options>
<ajaxmode>on</ajaxmode>
...
<surveyname1>on</surveyname1>
<surveyname2>on</surveyname2>
</options></syntaxhighlight>
#This should give you two new options in the Theme Options screen like this:<br />[[File:Tutorial_tp_1_1.png]]

===Modifed view for Survey Title in the navbar=== 
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/header/</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> and find "{# Logo option #}". Under that, modify the IF statement for the logo/survey-name, so it looks like this:<syntaxhighlight lang="html" enclose="div">
{# Logo option #}
{% if( aSurveyInfo.options.brandlogo == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }} logo-container" {{ aSurveyInfo.attr.navbarbrand }} >
{{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
</div>
{% endif %}
{% if( aSurveyInfo.options.surveyname1 == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }}" {{ aSurveyInfo.attr.navbarbrand }} >
{{ aSurveyInfo.name }}
</div>
{% endif %}</syntaxhighlight>
#Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60px;
font-size: 32px;
}</syntaxhighlight>
#Toggle the "Survey name in navbar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_2.png]]
===Modifed view for Survey Title under progress bar===
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> and add an <nowiki><h1></nowiki> element for the survey name. So it looks like this:<syntaxhighlight lang="html" enclose="div"><div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>

{# Custom survey name #}
{% if( aSurveyInfo.options.surveyname2 == "on") %}
<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
{% endif %}

{# Group Name #}
{{ include('./subviews/survey/group_subviews/group_name.twig') }}

{# Group Description #}
{{ include('./subviews/survey/group_subviews/group_desc.twig') }}

{#
PRESENT THE QUESTIONS

This is the main part. It will render each question for this group
#}


{% for aQuestion in aGroup.aQuestions %}
{{ include('./subviews/survey/question_container.twig') }}
{% endfor %}


{% if aGroup.show_last_group == true %}
<input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
{% endif %}

{% if aGroup.show_last_answer == true %}
<input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
{% endif %}
</div></syntaxhighlight>
# Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60ph1.custom-survey-name {
margin: 0;
text-align: center;
}</syntaxhighlight>
#Toggle the "Survey name below progress bar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_3.png]]

===Downloads=== 
* Sample extended theme: [[Media:Test_survey_names.zip]]

=Creating a theme from scratch= 
Documentation coming soon.

For now, just giving few tips.

==theme structure==

=== Files and directories ===
When you create a Theme from scratch, you don't need to respect the file/directory structure/css/js from Vanilla.
The mandatory css/js is added by core (you can still remove it if needed)

The only files your theme must have are the layout files:

* '''layout_global.twig''' : render the pages for survey taking
* '''layout_survey_list.twig''' : render the survey list (if this theme is set as default)
* '''layout_errors.twig''' : used to render errors that block survey rendering. ( wrong survey id, empty group in preview group, etc.)
* '''layout_user_forms.twig''': renders the user forms such as: token (survey participant), and register.
* '''layout_print.twig''' : used to print the survey to pdf
* '''layout_printanswers.twig''': print the answers

The content of those files, the files they include or not, is entirely up to you.
All the other files and directories that you find on Vanilla are purely optional, feel free to organize your code the way you want.

<div class="simplebox">[[File:help.png]] If you read the frontend rendering code, you'll see that those files names appear directly in it. That's why they are mandatory.
Eg: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/helpers/SurveyRuntimeHelper.php#L462
</div>

=== Content ===

In Vanilla's layout_global.twig, you'll see we use a variable called "include_content" to decide what to show
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/layout_global.twig#L114-L115

<syntaxhighlight lang="php" enclose="div">
{% set sViewContent = './subviews/content/' ~ aSurveyInfo.include_content ~ '.twig' %}
{% include './subviews/content/outerframe.twig' with {'include_content': sViewContent } %}
</syntaxhighlight>

aSurveyInfo.include_content tell you what action is currently going on: showing questions? showing submit result? showing clear all? etc
As you can see, in vanilla, we create one file to include by action. So if you want to know the list of actions, just check the vanilla's directory '''views/subviews/content''', and remove the "twig" extension :
https://github.com/LimeSurvey/LimeSurvey/tree/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/subviews/content

* '''clearall.twig'''
* '''firstpage.twig'''
* '''load.twig'''
* '''mainrow.twig'''
* '''main.twig'''
* '''optin.twig'''
* '''optout.twig'''
* '''outerframe.twig'''
* '''printanswers.twig'''
* '''quotas.twig'''
* '''register.twig'''
* '''save.twig'''
* '''submit_preview.twig'''
* '''submit.twig'''
* '''userforms.twig'''

If you already created a them for 2.x versions of LimeSurvey, you'll notice that most of them corresponds to the old pstpl files for limesurvey 2.x.
Again, there is no obligation for you in your theme to create those files, with those names, in this directory. You could for example just add a giant switch in layout_global.twig with the wanted HTML for each action.

=== The manifest config.xml ===

The manifest of the theme contains the main informations about your theme. When you install a theme, the content of the manifest will be loaded in the database, in two different tables: template and template_configuration.

==== The metadata section ====

Nothing complex: just the main infos about your theme.

<syntaxhighlight lang="xml" enclose="div">
<metadata>
<name>the_name_of_your_theme</name>
<title>The Title of your theme</title>
<creationDate>16/10/2017</creationDate>
<author>Your Name</author>
<authorEmail>your@email.org</authorEmail>
<authorUrl>http://www.yourwebsite.org</authorUrl>
<copyright>Your Copyright </copyright>
<license>Licence of your theme</license>
<version>version of your theme</version>
<apiVersion>3</apiVersion>
<description>Description of your theme</description>
</metadata>
</syntaxhighlight>

Few remarks:
* '''name''': will be used as a key in the db. So it must be unique, and it should not have any special chars (no spaces). Note that cases will not be taken in account
* '''Title''': will be used to display your theme name in the different lists. It can have special chars
* '''description''': will be used in the main list of survey theme. It can contains special chars, and even HTML code by using <![CDATA[

==== The files section ====

This one is an important one.

Eg: the files section of the Material Premium Theme:

<syntaxhighlight lang="xml" enclose="div">
<files>
<css>
<add>css/bootstrap-material-design.css</add>
<add>css/ripples.min.css</add>
<add>css/ajaxify.css</add>
<add>css/theme.css</add>
<add>css/custom.css</add>
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</css>
<js>
<add>scripts/theme.js</add>
<add>scripts/ajaxify.js</add>
<add>scripts/material.js</add>
<add>scripts/ripples.min.js</add>
<add>scripts/custom.js</add>
</js>
<print_css>
<add>css/print_theme.css</add>
</print_css>
</files>
</syntaxhighlight>

All the CSS/JS files present in this section will be loaded at the launch of the survey (in ajax mode. If ajax mode is off, then of course all the files are reloaded at each page).

They will be added to a Yii Asset Packet based on the name of the theme. So when Asset Manager is on (debug mode being off), those files will be copied to the tmp directory with the rest of the theme (so you can use relative path in the CSS and JS to reach the image files).
About the Asset manager in Yii: https://www.yiiframework.com/wiki/148/understanding-assets
About packages in Yii: http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail

They will use the inheritance system. It means that if you add a CSS/JS file to a theme, but it's not present in the theme, then the engine will look into all the mother themes of this theme and will use the first one it finds. So if a user extend your theme via the theme editor, all those files will be inherited in his theme. The keyword refer to this inheritance system.

* '''add''' : it will add the file to the theme, and to all its inherited theme
* '''replace''': it will replace the the file of its mother theme
* '''remove''': it will remove the file from '''any''' package, even the core package (since 3.14)

Few remarks on those keywords:

You can't add a file with the same name as the mother theme: it will always replace it. eg: If you have a file called "my_mother_theme/foo.css" and you add a file called "foo.cs" in the daughter theme, only "daughter_theme/foo.css" will be added to the theme. If you want to keep "my_mother_theme/foo.css", just choose another name for "daughter_theme/foo.css", like "daughter_theme/bar.css". So the keyword "add" can be used as a "replace" keyword. If you wonder why: this make much easier the automatic generation of inherited theme, copying the file section works out of the box (no need to rename "add" to "replace" when extending one the file).

The remove keyword is available only since 3.14. With this one, you can remove any css/file from any package, even the core ones. It is used in Material Premium Theme to remove the Awseome Bootstrap Checkbox's files:

<syntaxhighlight lang="xml" enclose="div">
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</syntaxhighlight>

so you should use the very same syntax as the package's file (eg: "awesome-bootstrap-checkbox.css" alone without it's folder path would not work). You'll find the complete list of core packages and their files in /application/config/packages.php and config/third_party.php. For example, for awesome-bootstrap-checkbox.css:
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/config/packages.php#L54-L56

<syntaxhighlight lang="php" enclose="div">
<remove>
'css'=> array(
'awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css',
),
</remove>
</syntaxhighlight>

Another way to find the exact name to use in the remove tag is to turn asset manager on (turning debug mode off or setting 'use_asset_manager'=>true in the config). Then, the path to use will be the one just after the random directory in the tmp directory. For example, for awesome-bootstrap-checkbox.css:
<syntaxhighlight lang="html" enclose="div">
<link rel="stylesheet" type="text/css" href="/tmp/assets/cbc4e3cb/awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css" />
</syntaxhighlight>

== Some notes ==


'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.


'''NOTE''': to avoid that, you can force the use to the XML rather than DB. In config.php turn debug mode on and uncommment:


'force_xmlsettings_for_survey_rendering' => true, // Uncomment if you want to force the use of the XML file rather than DB (for easy theme development)


Becareful: everything will be loaded from the XML (included options, etc)


'''NOTE''': if you manually edit the CSS/JS files (without using the Theme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache".


'''NOTE''': if you remove the section

</translate>

New Template System in LS3.x

2018-08-13T11:33:12Z

LouisGac: /* The files section */

<languages />
<translate>

__TOC__
=Introduction= 


On this page you'll learn how to:


* Use the new theme system of LimeSurvey 3.0.
* Use inheritance to manage your own themes.
* Add a picture to your theme
* Manage theme options for your surveys and survey groups


<hr/>


LimeSurvey 3 introduces a complete new theme engine system, based on Twig 1.29, Bootstrap, and allowing theme inheritance and theme options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old theme system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A theme designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new theme engine.


<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Theme Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface= 
==theme list==
On the admin dashboard, there is now a box to access the theme list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The theme list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the theme: it’s just a picture file called “preview.png” at the root of the theme
* the “title” of the theme as specified in the manifest (config.xml in the root of the theme)
* the description of the theme: a string set in its manifest
* the type of theme: Core theme (provided with LimeSurvey), User theme (added in upload directory), XML theme (not loaded in database)
* Extends: if the theme extends another theme, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a theme to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a theme in the database
** Theme editor: it will redirect you to the theme editor
** Theme option: it will lead you the global configuration of theme options

==Theme Editor== 
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' theme'']]

====A quick overview of the concept of theme inheritance==== 


In LS3, a theme can now inherit from another theme, it can “extend” another theme. This means that the theme directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of themes for your different users without having to maintain a lot of different themes. For example: you can have your own home-made theme, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom theme, all the themes that inherit from it will be updated automatically. Note that the inheritance is recursive: a theme can extend a theme that extends another one etc.


<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core themes of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface==== 


To extend the Monochrome theme of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome theme. Then, click on “extend” and validate the new name “extends_monochrome”.


If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/themes/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this theme as a normal one from a survey and it will look exactly like the monochrome theme.


[[File:Extends monochrome empty.jpg|center|baseline|border|''The theme tree (directory and files) just after its creation. It's practically empty'']]


<div class="simplebox">[[File:help.png]] The resources (jpg, png etc.) from the original theme are copied when extending a theme. This is because if you copy a CSS file from the original theme locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current theme path. </div>


The theme editor for the extends_monochrome theme looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome theme'']]
<br /><br />
There is no big difference with the old theme editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the theme directory and that the file from the original theme will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to theme views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local theme and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ==== 


The button '''Copy to local theme and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the theme you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button'']]
<br>
If you open a file explorer and go to the directory upload/themes/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your theme'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).


<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the theme to find the image. If the theme you’re working on is extended to another theme, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local theme, it will loop through the theme inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your theme. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/


<div class="simplebox">
So, to add a picture to your theme:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''


* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}


* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list==== 
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which theme the current one extends (if any)

==Template options== 
Another novelty of LS3 is the theme option page. As we’ll see later, theme creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the theme options at global level: click on “theme options” in the theme list
===Advanced options===


{{QS:Theme editor - advanced options}}

===Simple options=== 


The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the theme's /options directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options (Broken link)
<div class="simplebox">[[File:help.png]] This page can be completely different from a theme to another, and theme providers are strongly encouraged to create their own look & feel. </div>


[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from


{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core themes:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a theme provider could add his own animation library or no animation library at all.


<div class="simplebox">[[File:help.png]] The monochrome themes use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for theme providers.</div>

===Inheritance system=== 


In the previous part, we’ve seen that a theme can extend another theme. A theme configuration can also inherit from another theme configuration. It means that for a given theme, you can have a configuration at


* global level (the one we’ve just seen accessible from the theme list)
* at survey group level
* a last one at survey level.


Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

====At survey group level==== 


Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of themes than in the theme list, except that here only the option button is visible (theme editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]


<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

====At survey level==== 
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example== 
Let’s say you’re using a single theme for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core theme. But of course, if you are a theme provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization = 


You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS/JS: deal with the asset manager ("why are my changes not applied?") == 
<br />


If you're trying to update the CSS/JS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.


<br />


Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />


It moves the CSS/JS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css/js file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css/js. Else, they would have to clean their browser cache.


<br />


Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.


<br />


Here the CSS links in header when asset manager is off:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.


<br />


<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>


So, when you're editing CSS/JS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache


[[File:Clearassets-ls3 3.png]]


<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>


Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme == 
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how it works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css


<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>


Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>


You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font === 
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>


You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.


Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options === 
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>


* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %} //Shouldn't this be "theme" in stead of "template"?
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>


<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector === 
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">


'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}


</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79


<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>


Of course, the XML file only contains the default values for your theme configuration. But indeed, those values are defined and read inside the database (table "template_configuration" (Question: "template_" of "theme_"?) as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174


So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

== Adding theme options to control positioning and display of survey elements == 
This tutorial will show how to add options to an extended theme to display survey elements in various locations. In this case, we will create theme options to show the survey title in two different locations.
<div class="simplebox">[[File:help.png]] For the sake of simplicity, we will base the tutorial on an extension of the "bootswatch" theme in LimeSurvey version 3.4.3.</div>
=== Create a custom theme ===
#Extend the "bootswatch" theme as described above.
#Copy <span style="color: #BA2121;">custom.css</span> to the local theme as described above.
===Create new theme options===
#Copy the contents of <span style="color: #BA2121;">/themes/survey/bootswatch/options/</span> to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/</span>.
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/options.twig</span> in an editor and find "{# Bootstrap Bootswatch theme #}". Directly before its parent <nowiki><div class='row'></nowiki> element, add this:<syntaxhighlight lang="html" enclose="div">
{# Custom survey name in navbar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div>


{# Custom survey name below progress bar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div></syntaxhighlight>
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/config.xml</span> and add two items to the "options" block so it looks like this:<syntaxhighlight lang="xml" enclose="div"> <options>
<ajaxmode>on</ajaxmode>
...
<surveyname1>on</surveyname1>
<surveyname2>on</surveyname2>
</options></syntaxhighlight>
#This should give you two new options in the Theme Options screen like this:<br />[[File:Tutorial_tp_1_1.png]]

===Modifed view for Survey Title in the navbar=== 
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/header/</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> and find "{# Logo option #}". Under that, modify the IF statement for the logo/survey-name, so it looks like this:<syntaxhighlight lang="html" enclose="div">
{# Logo option #}
{% if( aSurveyInfo.options.brandlogo == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }} logo-container" {{ aSurveyInfo.attr.navbarbrand }} >
{{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
</div>
{% endif %}
{% if( aSurveyInfo.options.surveyname1 == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }}" {{ aSurveyInfo.attr.navbarbrand }} >
{{ aSurveyInfo.name }}
</div>
{% endif %}</syntaxhighlight>
#Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60px;
font-size: 32px;
}</syntaxhighlight>
#Toggle the "Survey name in navbar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_2.png]]
===Modifed view for Survey Title under progress bar===
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> and add an <nowiki><h1></nowiki> element for the survey name. So it looks like this:<syntaxhighlight lang="html" enclose="div"><div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>

{# Custom survey name #}
{% if( aSurveyInfo.options.surveyname2 == "on") %}
<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
{% endif %}

{# Group Name #}
{{ include('./subviews/survey/group_subviews/group_name.twig') }}

{# Group Description #}
{{ include('./subviews/survey/group_subviews/group_desc.twig') }}

{#
PRESENT THE QUESTIONS

This is the main part. It will render each question for this group
#}


{% for aQuestion in aGroup.aQuestions %}
{{ include('./subviews/survey/question_container.twig') }}
{% endfor %}


{% if aGroup.show_last_group == true %}
<input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
{% endif %}

{% if aGroup.show_last_answer == true %}
<input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
{% endif %}
</div></syntaxhighlight>
# Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60ph1.custom-survey-name {
margin: 0;
text-align: center;
}</syntaxhighlight>
#Toggle the "Survey name below progress bar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_3.png]]

===Downloads=== 
* Sample extended theme: [[Media:Test_survey_names.zip]]

=Creating a theme from scratch= 
Documentation coming soon.

For now, just giving few tips.

==theme structure==

=== Files and directories ===
When you create a Theme from scratch, you don't need to respect the file/directory structure/css/js from Vanilla.
The mandatory css/js is added by core (you can still remove it if needed)

The only files your theme must have are the layout files:

* '''layout_global.twig''' : render the pages for survey taking
* '''layout_survey_list.twig''' : render the survey list (if this theme is set as default)
* '''layout_errors.twig''' : used to render errors that block survey rendering. ( wrong survey id, empty group in preview group, etc.)
* '''layout_user_forms.twig''': renders the user forms such as: token (survey participant), and register.
* '''layout_print.twig''' : used to print the survey to pdf
* '''layout_printanswers.twig''': print the answers

The content of those files, the files they include or not, is entirely up to you.
All the other files and directories that you find on Vanilla are purely optional, feel free to organize your code the way you want.

<div class="simplebox">[[File:help.png]] If you read the frontend rendering code, you'll see that those files names appear directly in it. That's why they are mandatory.
Eg: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/helpers/SurveyRuntimeHelper.php#L462
</div>

=== Content ===

In Vanilla's layout_global.twig, you'll see we use a variable called "include_content" to decide what to show
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/layout_global.twig#L114-L115

<syntaxhighlight lang="php" enclose="div">
{% set sViewContent = './subviews/content/' ~ aSurveyInfo.include_content ~ '.twig' %}
{% include './subviews/content/outerframe.twig' with {'include_content': sViewContent } %}
</syntaxhighlight>

aSurveyInfo.include_content tell you what action is currently going on: showing questions? showing submit result? showing clear all? etc
As you can see, in vanilla, we create one file to include by action. So if you want to know the list of actions, just check the vanilla's directory '''views/subviews/content''', and remove the "twig" extension :
https://github.com/LimeSurvey/LimeSurvey/tree/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/subviews/content

* '''clearall.twig'''
* '''firstpage.twig'''
* '''load.twig'''
* '''mainrow.twig'''
* '''main.twig'''
* '''optin.twig'''
* '''optout.twig'''
* '''outerframe.twig'''
* '''printanswers.twig'''
* '''quotas.twig'''
* '''register.twig'''
* '''save.twig'''
* '''submit_preview.twig'''
* '''submit.twig'''
* '''userforms.twig'''

If you already created a them for 2.x versions of LimeSurvey, you'll notice that most of them corresponds to the old pstpl files for limesurvey 2.x.
Again, there is no obligation for you in your theme to create those files, with those names, in this directory. You could for example just add a giant switch in layout_global.twig with the wanted HTML for each action.

=== The manifest config.xml ===

The manifest of the theme contains the main informations about your theme. When you install a theme, the content of the manifest will be loaded in the database, in two different tables: template and template_configuration.

==== The metadata section ====

Nothing complex: just the main infos about your theme.

<syntaxhighlight lang="xml" enclose="div">
<metadata>
<name>the_name_of_your_theme</name>
<title>The Title of your theme</title>
<creationDate>16/10/2017</creationDate>
<author>Your Name</author>
<authorEmail>your@email.org</authorEmail>
<authorUrl>http://www.yourwebsite.org</authorUrl>
<copyright>Your Copyright </copyright>
<license>Licence of your theme</license>
<version>version of your theme</version>
<apiVersion>3</apiVersion>
<description>Description of your theme</description>
</metadata>
</syntaxhighlight>

Few remarks:
* '''name''': will be used as a key in the db. So it must be unique, and it should not have any special chars (no spaces). Note that cases will not be taken in account
* '''Title''': will be used to display your theme name in the different lists. It can have special chars
* '''description''': will be used in the main list of survey theme. It can contains special chars, and even HTML code by using <![CDATA[

==== The files section ====

This one is an important one.

Eg: the files section of the Material Premium Theme:

<syntaxhighlight lang="xml" enclose="div">
<files>
<css>
<add>css/bootstrap-material-design.css</add>
<add>css/ripples.min.css</add>
<add>css/ajaxify.css</add>
<add>css/theme.css</add>
<add>css/custom.css</add>
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</css>
<js>
<add>scripts/theme.js</add>
<add>scripts/ajaxify.js</add>
<add>scripts/material.js</add>
<add>scripts/ripples.min.js</add>
<add>scripts/custom.js</add>
</js>
<print_css>
<add>css/print_theme.css</add>
</print_css>
</files>
</syntaxhighlight>

All the CSS/JS files present in this section will be loaded at the launch of the survey (in ajax mode. If ajax mode is off, then of course all the files are reloaded at each page).

They will be added to a Yii Asset Packet based on the name of the theme. So when Asset Manager is on (debug mode being off), those files will be copied to the tmp directory with the rest of the theme (so you can use relative path in the CSS and JS to reach the image files).
About the Asset manager in Yii: https://www.yiiframework.com/wiki/148/understanding-assets
About packages in Yii: http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail

They will use the inheritance system. It means that if you add a CSS/JS file to a theme, but it's not present in the theme, then the engine will look into all the mother themes of this theme and will use the first one it finds. So if a user extend your theme via the theme editor, all those files will be inherited in his theme. The keyword refer to this inheritance system.

* '''add''' : it will add the file to the theme, and to all its inherited theme
* '''replace''': it will replace the the file of its mother theme
* '''remove''': it will remove the file from '''any''' package, even the core package (since 3.14)

Few remarks on those keywords:

You can't add a file with the same name as the mother theme: it will always replace it. eg: If you have a file called "my_mother_theme/foo.css" and you add a file called "foo.cs" in the daughter theme, only "daughter_theme/foo.css" will be added to the theme. If you want to keep "my_mother_theme/foo.css", just choose another name for "daughter_theme/foo.css", like "daughter_theme/bar.css". So the keyword "add" can be used as a "replace" keyword. If you wonder why: this make much easier the automatic generation of inherited theme, copying the file section works out of the box (no need to rename "add" to "replace" when extending one the file).

The remove keyword is available only since 3.14. With this one, you can remove any css/file from any package, even the core ones. It is used in Material Premium Theme to remove the Awseome Bootstrap Checkbox's files:

<syntaxhighlight lang="xml" enclose="div">
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</syntaxhighlight>

so you should use the very same syntax as the package's file (eg: "awesome-bootstrap-checkbox.css" alone without it's folder path would not work). You'll find the complete list of core packages and their files in /application/config/packages.php and config/third_party.php:
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/config/packages.php
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/config/third_party.php

For example, for awesome-bootstrap-checkbox.css:
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/config/packages.php#L55

== Some notes ==


'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.


'''NOTE''': to avoid that, you can force the use to the XML rather than DB. In config.php turn debug mode on and uncommment:


'force_xmlsettings_for_survey_rendering' => true, // Uncomment if you want to force the use of the XML file rather than DB (for easy theme development)


Becareful: everything will be loaded from the XML (included options, etc)


'''NOTE''': if you manually edit the CSS/JS files (without using the Theme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache".


'''NOTE''': if you remove the section

</translate>

New Template System in LS3.x

2018-08-13T11:24:34Z

LouisGac: /* The files section */

<languages />
<translate>

__TOC__
=Introduction= 


On this page you'll learn how to:


* Use the new theme system of LimeSurvey 3.0.
* Use inheritance to manage your own themes.
* Add a picture to your theme
* Manage theme options for your surveys and survey groups


<hr/>


LimeSurvey 3 introduces a complete new theme engine system, based on Twig 1.29, Bootstrap, and allowing theme inheritance and theme options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old theme system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A theme designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new theme engine.


<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Theme Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface= 
==theme list==
On the admin dashboard, there is now a box to access the theme list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The theme list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the theme: it’s just a picture file called “preview.png” at the root of the theme
* the “title” of the theme as specified in the manifest (config.xml in the root of the theme)
* the description of the theme: a string set in its manifest
* the type of theme: Core theme (provided with LimeSurvey), User theme (added in upload directory), XML theme (not loaded in database)
* Extends: if the theme extends another theme, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a theme to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a theme in the database
** Theme editor: it will redirect you to the theme editor
** Theme option: it will lead you the global configuration of theme options

==Theme Editor== 
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' theme'']]

====A quick overview of the concept of theme inheritance==== 


In LS3, a theme can now inherit from another theme, it can “extend” another theme. This means that the theme directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of themes for your different users without having to maintain a lot of different themes. For example: you can have your own home-made theme, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom theme, all the themes that inherit from it will be updated automatically. Note that the inheritance is recursive: a theme can extend a theme that extends another one etc.


<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core themes of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface==== 


To extend the Monochrome theme of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome theme. Then, click on “extend” and validate the new name “extends_monochrome”.


If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/themes/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this theme as a normal one from a survey and it will look exactly like the monochrome theme.


[[File:Extends monochrome empty.jpg|center|baseline|border|''The theme tree (directory and files) just after its creation. It's practically empty'']]


<div class="simplebox">[[File:help.png]] The resources (jpg, png etc.) from the original theme are copied when extending a theme. This is because if you copy a CSS file from the original theme locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current theme path. </div>


The theme editor for the extends_monochrome theme looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome theme'']]
<br /><br />
There is no big difference with the old theme editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the theme directory and that the file from the original theme will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to theme views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local theme and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ==== 


The button '''Copy to local theme and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the theme you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button'']]
<br>
If you open a file explorer and go to the directory upload/themes/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your theme'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).


<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the theme to find the image. If the theme you’re working on is extended to another theme, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local theme, it will loop through the theme inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your theme. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/


<div class="simplebox">
So, to add a picture to your theme:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''


* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}


* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list==== 
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which theme the current one extends (if any)

==Template options== 
Another novelty of LS3 is the theme option page. As we’ll see later, theme creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the theme options at global level: click on “theme options” in the theme list
===Advanced options===


{{QS:Theme editor - advanced options}}

===Simple options=== 


The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the theme's /options directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options (Broken link)
<div class="simplebox">[[File:help.png]] This page can be completely different from a theme to another, and theme providers are strongly encouraged to create their own look & feel. </div>


[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from


{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core themes:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a theme provider could add his own animation library or no animation library at all.


<div class="simplebox">[[File:help.png]] The monochrome themes use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for theme providers.</div>

===Inheritance system=== 


In the previous part, we’ve seen that a theme can extend another theme. A theme configuration can also inherit from another theme configuration. It means that for a given theme, you can have a configuration at


* global level (the one we’ve just seen accessible from the theme list)
* at survey group level
* a last one at survey level.


Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

====At survey group level==== 


Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of themes than in the theme list, except that here only the option button is visible (theme editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]


<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

====At survey level==== 
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example== 
Let’s say you’re using a single theme for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core theme. But of course, if you are a theme provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization = 


You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS/JS: deal with the asset manager ("why are my changes not applied?") == 
<br />


If you're trying to update the CSS/JS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.


<br />


Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />


It moves the CSS/JS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css/js file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css/js. Else, they would have to clean their browser cache.


<br />


Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.


<br />


Here the CSS links in header when asset manager is off:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.


<br />


<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>


So, when you're editing CSS/JS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache


[[File:Clearassets-ls3 3.png]]


<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>


Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme == 
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how it works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css


<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>


Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>


You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font === 
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>


You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.


Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options === 
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>


* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %} //Shouldn't this be "theme" in stead of "template"?
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>


<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector === 
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">


'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}


</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79


<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>


Of course, the XML file only contains the default values for your theme configuration. But indeed, those values are defined and read inside the database (table "template_configuration" (Question: "template_" of "theme_"?) as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174


So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

== Adding theme options to control positioning and display of survey elements == 
This tutorial will show how to add options to an extended theme to display survey elements in various locations. In this case, we will create theme options to show the survey title in two different locations.
<div class="simplebox">[[File:help.png]] For the sake of simplicity, we will base the tutorial on an extension of the "bootswatch" theme in LimeSurvey version 3.4.3.</div>
=== Create a custom theme ===
#Extend the "bootswatch" theme as described above.
#Copy <span style="color: #BA2121;">custom.css</span> to the local theme as described above.
===Create new theme options===
#Copy the contents of <span style="color: #BA2121;">/themes/survey/bootswatch/options/</span> to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/</span>.
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/options.twig</span> in an editor and find "{# Bootstrap Bootswatch theme #}". Directly before its parent <nowiki><div class='row'></nowiki> element, add this:<syntaxhighlight lang="html" enclose="div">
{# Custom survey name in navbar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div>


{# Custom survey name below progress bar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div></syntaxhighlight>
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/config.xml</span> and add two items to the "options" block so it looks like this:<syntaxhighlight lang="xml" enclose="div"> <options>
<ajaxmode>on</ajaxmode>
...
<surveyname1>on</surveyname1>
<surveyname2>on</surveyname2>
</options></syntaxhighlight>
#This should give you two new options in the Theme Options screen like this:<br />[[File:Tutorial_tp_1_1.png]]

===Modifed view for Survey Title in the navbar=== 
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/header/</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> and find "{# Logo option #}". Under that, modify the IF statement for the logo/survey-name, so it looks like this:<syntaxhighlight lang="html" enclose="div">
{# Logo option #}
{% if( aSurveyInfo.options.brandlogo == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }} logo-container" {{ aSurveyInfo.attr.navbarbrand }} >
{{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
</div>
{% endif %}
{% if( aSurveyInfo.options.surveyname1 == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }}" {{ aSurveyInfo.attr.navbarbrand }} >
{{ aSurveyInfo.name }}
</div>
{% endif %}</syntaxhighlight>
#Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60px;
font-size: 32px;
}</syntaxhighlight>
#Toggle the "Survey name in navbar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_2.png]]
===Modifed view for Survey Title under progress bar===
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> and add an <nowiki><h1></nowiki> element for the survey name. So it looks like this:<syntaxhighlight lang="html" enclose="div"><div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>

{# Custom survey name #}
{% if( aSurveyInfo.options.surveyname2 == "on") %}
<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
{% endif %}

{# Group Name #}
{{ include('./subviews/survey/group_subviews/group_name.twig') }}

{# Group Description #}
{{ include('./subviews/survey/group_subviews/group_desc.twig') }}

{#
PRESENT THE QUESTIONS

This is the main part. It will render each question for this group
#}


{% for aQuestion in aGroup.aQuestions %}
{{ include('./subviews/survey/question_container.twig') }}
{% endfor %}


{% if aGroup.show_last_group == true %}
<input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
{% endif %}

{% if aGroup.show_last_answer == true %}
<input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
{% endif %}
</div></syntaxhighlight>
# Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60ph1.custom-survey-name {
margin: 0;
text-align: center;
}</syntaxhighlight>
#Toggle the "Survey name below progress bar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_3.png]]

===Downloads=== 
* Sample extended theme: [[Media:Test_survey_names.zip]]

=Creating a theme from scratch= 
Documentation coming soon.

For now, just giving few tips.

==theme structure==

=== Files and directories ===
When you create a Theme from scratch, you don't need to respect the file/directory structure/css/js from Vanilla.
The mandatory css/js is added by core (you can still remove it if needed)

The only files your theme must have are the layout files:

* '''layout_global.twig''' : render the pages for survey taking
* '''layout_survey_list.twig''' : render the survey list (if this theme is set as default)
* '''layout_errors.twig''' : used to render errors that block survey rendering. ( wrong survey id, empty group in preview group, etc.)
* '''layout_user_forms.twig''': renders the user forms such as: token (survey participant), and register.
* '''layout_print.twig''' : used to print the survey to pdf
* '''layout_printanswers.twig''': print the answers

The content of those files, the files they include or not, is entirely up to you.
All the other files and directories that you find on Vanilla are purely optional, feel free to organize your code the way you want.

<div class="simplebox">[[File:help.png]] If you read the frontend rendering code, you'll see that those files names appear directly in it. That's why they are mandatory.
Eg: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/helpers/SurveyRuntimeHelper.php#L462
</div>

=== Content ===

In Vanilla's layout_global.twig, you'll see we use a variable called "include_content" to decide what to show
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/layout_global.twig#L114-L115

<syntaxhighlight lang="php" enclose="div">
{% set sViewContent = './subviews/content/' ~ aSurveyInfo.include_content ~ '.twig' %}
{% include './subviews/content/outerframe.twig' with {'include_content': sViewContent } %}
</syntaxhighlight>

aSurveyInfo.include_content tell you what action is currently going on: showing questions? showing submit result? showing clear all? etc
As you can see, in vanilla, we create one file to include by action. So if you want to know the list of actions, just check the vanilla's directory '''views/subviews/content''', and remove the "twig" extension :
https://github.com/LimeSurvey/LimeSurvey/tree/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/subviews/content

* '''clearall.twig'''
* '''firstpage.twig'''
* '''load.twig'''
* '''mainrow.twig'''
* '''main.twig'''
* '''optin.twig'''
* '''optout.twig'''
* '''outerframe.twig'''
* '''printanswers.twig'''
* '''quotas.twig'''
* '''register.twig'''
* '''save.twig'''
* '''submit_preview.twig'''
* '''submit.twig'''
* '''userforms.twig'''

If you already created a them for 2.x versions of LimeSurvey, you'll notice that most of them corresponds to the old pstpl files for limesurvey 2.x.
Again, there is no obligation for you in your theme to create those files, with those names, in this directory. You could for example just add a giant switch in layout_global.twig with the wanted HTML for each action.

=== The manifest config.xml ===

The manifest of the theme contains the main informations about your theme. When you install a theme, the content of the manifest will be loaded in the database, in two different tables: template and template_configuration.

==== The metadata section ====

Nothing complex: just the main infos about your theme.

<syntaxhighlight lang="xml" enclose="div">
<metadata>
<name>the_name_of_your_theme</name>
<title>The Title of your theme</title>
<creationDate>16/10/2017</creationDate>
<author>Your Name</author>
<authorEmail>your@email.org</authorEmail>
<authorUrl>http://www.yourwebsite.org</authorUrl>
<copyright>Your Copyright </copyright>
<license>Licence of your theme</license>
<version>version of your theme</version>
<apiVersion>3</apiVersion>
<description>Description of your theme</description>
</metadata>
</syntaxhighlight>

Few remarks:
* '''name''': will be used as a key in the db. So it must be unique, and it should not have any special chars (no spaces). Note that cases will not be taken in account
* '''Title''': will be used to display your theme name in the different lists. It can have special chars
* '''description''': will be used in the main list of survey theme. It can contains special chars, and even HTML code by using <![CDATA[

==== The files section ====

This one is an important one.

Eg: the files section of the Material Premium Theme:

<syntaxhighlight lang="xml" enclose="div">
<files>
<css>
<add>css/bootstrap-material-design.css</add>
<add>css/ripples.min.css</add>
<add>css/ajaxify.css</add>
<add>css/theme.css</add>
<add>css/custom.css</add>
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</css>
<js>
<add>scripts/theme.js</add>
<add>scripts/ajaxify.js</add>
<add>scripts/material.js</add>
<add>scripts/ripples.min.js</add>
<add>scripts/custom.js</add>
</js>
<print_css>
<add>css/print_theme.css</add>
</print_css>
</files>
</syntaxhighlight>

All the CSS/JS files present in this section will be loaded at the launch of the survey (in ajax mode. If ajax mode is off, then of course all the files are reloaded at each page).

They will be added to a Yii Asset Packet based on the name of the theme. So when Asset Manager is on (debug mode being off), those files will be copied to the tmp directory with the rest of the theme (so you can use relative path in the CSS and JS to reach the image files).
About the Asset manager in Yii: https://www.yiiframework.com/wiki/148/understanding-assets
About packages in Yii: http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail

They will use the inheritance system. It means that if you add a CSS/JS file to a theme, but it's not present in the theme, then the engine will look into all the mother themes of this theme and will use the first one it finds. So if a user extend your theme via the theme editor, all those files will be inherited in his theme. The keyword refer to this inheritance system.

* '''add''' : it will add the file to the theme, and to all its inherited theme
* '''replace''': it will replace the the file of its mother theme
* '''remove''': it will remove the file from '''any''' package, even the core package (since 3.14)

Few remarks on those keywords:

You can't add a file with the same name as the mother theme: it will always replace it. eg: If you have a file called "my_mother_theme/foo.css" and you add a file called "foo.cs" in the daughter theme, only "daughter_theme/foo.css" will be added to the theme. If you want to keep "my_mother_theme/foo.css", just choose another name for "daughter_theme/foo.css", like "daughter_theme/bar.css".

== Some notes ==


'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.


'''NOTE''': to avoid that, you can force the use to the XML rather than DB. In config.php turn debug mode on and uncommment:


'force_xmlsettings_for_survey_rendering' => true, // Uncomment if you want to force the use of the XML file rather than DB (for easy theme development)


Becareful: everything will be loaded from the XML (included options, etc)


'''NOTE''': if you manually edit the CSS/JS files (without using the Theme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache".


'''NOTE''': if you remove the section

</translate>

New Template System in LS3.x

2018-08-13T11:23:40Z

LouisGac: /* The files section */

<languages />
<translate>

__TOC__
=Introduction= 


On this page you'll learn how to:


* Use the new theme system of LimeSurvey 3.0.
* Use inheritance to manage your own themes.
* Add a picture to your theme
* Manage theme options for your surveys and survey groups


<hr/>


LimeSurvey 3 introduces a complete new theme engine system, based on Twig 1.29, Bootstrap, and allowing theme inheritance and theme options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old theme system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A theme designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new theme engine.


<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Theme Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface= 
==theme list==
On the admin dashboard, there is now a box to access the theme list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The theme list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the theme: it’s just a picture file called “preview.png” at the root of the theme
* the “title” of the theme as specified in the manifest (config.xml in the root of the theme)
* the description of the theme: a string set in its manifest
* the type of theme: Core theme (provided with LimeSurvey), User theme (added in upload directory), XML theme (not loaded in database)
* Extends: if the theme extends another theme, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a theme to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a theme in the database
** Theme editor: it will redirect you to the theme editor
** Theme option: it will lead you the global configuration of theme options

==Theme Editor== 
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' theme'']]

====A quick overview of the concept of theme inheritance==== 


In LS3, a theme can now inherit from another theme, it can “extend” another theme. This means that the theme directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of themes for your different users without having to maintain a lot of different themes. For example: you can have your own home-made theme, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom theme, all the themes that inherit from it will be updated automatically. Note that the inheritance is recursive: a theme can extend a theme that extends another one etc.


<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core themes of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface==== 


To extend the Monochrome theme of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome theme. Then, click on “extend” and validate the new name “extends_monochrome”.


If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/themes/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this theme as a normal one from a survey and it will look exactly like the monochrome theme.


[[File:Extends monochrome empty.jpg|center|baseline|border|''The theme tree (directory and files) just after its creation. It's practically empty'']]


<div class="simplebox">[[File:help.png]] The resources (jpg, png etc.) from the original theme are copied when extending a theme. This is because if you copy a CSS file from the original theme locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current theme path. </div>


The theme editor for the extends_monochrome theme looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome theme'']]
<br /><br />
There is no big difference with the old theme editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the theme directory and that the file from the original theme will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to theme views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local theme and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ==== 


The button '''Copy to local theme and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the theme you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button'']]
<br>
If you open a file explorer and go to the directory upload/themes/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your theme'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).


<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the theme to find the image. If the theme you’re working on is extended to another theme, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local theme, it will loop through the theme inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your theme. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/


<div class="simplebox">
So, to add a picture to your theme:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''


* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}


* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list==== 
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which theme the current one extends (if any)

==Template options== 
Another novelty of LS3 is the theme option page. As we’ll see later, theme creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the theme options at global level: click on “theme options” in the theme list
===Advanced options===


{{QS:Theme editor - advanced options}}

===Simple options=== 


The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the theme's /options directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options (Broken link)
<div class="simplebox">[[File:help.png]] This page can be completely different from a theme to another, and theme providers are strongly encouraged to create their own look & feel. </div>


[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from


{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core themes:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a theme provider could add his own animation library or no animation library at all.


<div class="simplebox">[[File:help.png]] The monochrome themes use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for theme providers.</div>

===Inheritance system=== 


In the previous part, we’ve seen that a theme can extend another theme. A theme configuration can also inherit from another theme configuration. It means that for a given theme, you can have a configuration at


* global level (the one we’ve just seen accessible from the theme list)
* at survey group level
* a last one at survey level.


Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

====At survey group level==== 


Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of themes than in the theme list, except that here only the option button is visible (theme editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]


<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

====At survey level==== 
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example== 
Let’s say you’re using a single theme for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core theme. But of course, if you are a theme provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization = 


You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS/JS: deal with the asset manager ("why are my changes not applied?") == 
<br />


If you're trying to update the CSS/JS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.


<br />


Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />


It moves the CSS/JS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css/js file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css/js. Else, they would have to clean their browser cache.


<br />


Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.


<br />


Here the CSS links in header when asset manager is off:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.


<br />


<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>


So, when you're editing CSS/JS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache


[[File:Clearassets-ls3 3.png]]


<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>


Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme == 
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how it works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css


<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>


Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>


You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font === 
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>


You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.


Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options === 
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>


* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %} //Shouldn't this be "theme" in stead of "template"?
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>


<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector === 
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">


'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}


</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79


<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>


Of course, the XML file only contains the default values for your theme configuration. But indeed, those values are defined and read inside the database (table "template_configuration" (Question: "template_" of "theme_"?) as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174


So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

== Adding theme options to control positioning and display of survey elements == 
This tutorial will show how to add options to an extended theme to display survey elements in various locations. In this case, we will create theme options to show the survey title in two different locations.
<div class="simplebox">[[File:help.png]] For the sake of simplicity, we will base the tutorial on an extension of the "bootswatch" theme in LimeSurvey version 3.4.3.</div>
=== Create a custom theme ===
#Extend the "bootswatch" theme as described above.
#Copy <span style="color: #BA2121;">custom.css</span> to the local theme as described above.
===Create new theme options===
#Copy the contents of <span style="color: #BA2121;">/themes/survey/bootswatch/options/</span> to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/</span>.
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/options.twig</span> in an editor and find "{# Bootstrap Bootswatch theme #}". Directly before its parent <nowiki><div class='row'></nowiki> element, add this:<syntaxhighlight lang="html" enclose="div">
{# Custom survey name in navbar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div>


{# Custom survey name below progress bar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div></syntaxhighlight>
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/config.xml</span> and add two items to the "options" block so it looks like this:<syntaxhighlight lang="xml" enclose="div"> <options>
<ajaxmode>on</ajaxmode>
...
<surveyname1>on</surveyname1>
<surveyname2>on</surveyname2>
</options></syntaxhighlight>
#This should give you two new options in the Theme Options screen like this:<br />[[File:Tutorial_tp_1_1.png]]

===Modifed view for Survey Title in the navbar=== 
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/header/</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> and find "{# Logo option #}". Under that, modify the IF statement for the logo/survey-name, so it looks like this:<syntaxhighlight lang="html" enclose="div">
{# Logo option #}
{% if( aSurveyInfo.options.brandlogo == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }} logo-container" {{ aSurveyInfo.attr.navbarbrand }} >
{{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
</div>
{% endif %}
{% if( aSurveyInfo.options.surveyname1 == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }}" {{ aSurveyInfo.attr.navbarbrand }} >
{{ aSurveyInfo.name }}
</div>
{% endif %}</syntaxhighlight>
#Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60px;
font-size: 32px;
}</syntaxhighlight>
#Toggle the "Survey name in navbar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_2.png]]
===Modifed view for Survey Title under progress bar===
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> and add an <nowiki><h1></nowiki> element for the survey name. So it looks like this:<syntaxhighlight lang="html" enclose="div"><div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>

{# Custom survey name #}
{% if( aSurveyInfo.options.surveyname2 == "on") %}
<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
{% endif %}

{# Group Name #}
{{ include('./subviews/survey/group_subviews/group_name.twig') }}

{# Group Description #}
{{ include('./subviews/survey/group_subviews/group_desc.twig') }}

{#
PRESENT THE QUESTIONS

This is the main part. It will render each question for this group
#}


{% for aQuestion in aGroup.aQuestions %}
{{ include('./subviews/survey/question_container.twig') }}
{% endfor %}


{% if aGroup.show_last_group == true %}
<input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
{% endif %}

{% if aGroup.show_last_answer == true %}
<input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
{% endif %}
</div></syntaxhighlight>
# Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60ph1.custom-survey-name {
margin: 0;
text-align: center;
}</syntaxhighlight>
#Toggle the "Survey name below progress bar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_3.png]]

===Downloads=== 
* Sample extended theme: [[Media:Test_survey_names.zip]]

=Creating a theme from scratch= 
Documentation coming soon.

For now, just giving few tips.

==theme structure==

=== Files and directories ===
When you create a Theme from scratch, you don't need to respect the file/directory structure/css/js from Vanilla.
The mandatory css/js is added by core (you can still remove it if needed)

The only files your theme must have are the layout files:

* '''layout_global.twig''' : render the pages for survey taking
* '''layout_survey_list.twig''' : render the survey list (if this theme is set as default)
* '''layout_errors.twig''' : used to render errors that block survey rendering. ( wrong survey id, empty group in preview group, etc.)
* '''layout_user_forms.twig''': renders the user forms such as: token (survey participant), and register.
* '''layout_print.twig''' : used to print the survey to pdf
* '''layout_printanswers.twig''': print the answers

The content of those files, the files they include or not, is entirely up to you.
All the other files and directories that you find on Vanilla are purely optional, feel free to organize your code the way you want.

<div class="simplebox">[[File:help.png]] If you read the frontend rendering code, you'll see that those files names appear directly in it. That's why they are mandatory.
Eg: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/helpers/SurveyRuntimeHelper.php#L462
</div>

=== Content ===

In Vanilla's layout_global.twig, you'll see we use a variable called "include_content" to decide what to show
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/layout_global.twig#L114-L115

<syntaxhighlight lang="php" enclose="div">
{% set sViewContent = './subviews/content/' ~ aSurveyInfo.include_content ~ '.twig' %}
{% include './subviews/content/outerframe.twig' with {'include_content': sViewContent } %}
</syntaxhighlight>

aSurveyInfo.include_content tell you what action is currently going on: showing questions? showing submit result? showing clear all? etc
As you can see, in vanilla, we create one file to include by action. So if you want to know the list of actions, just check the vanilla's directory '''views/subviews/content''', and remove the "twig" extension :
https://github.com/LimeSurvey/LimeSurvey/tree/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/subviews/content

* '''clearall.twig'''
* '''firstpage.twig'''
* '''load.twig'''
* '''mainrow.twig'''
* '''main.twig'''
* '''optin.twig'''
* '''optout.twig'''
* '''outerframe.twig'''
* '''printanswers.twig'''
* '''quotas.twig'''
* '''register.twig'''
* '''save.twig'''
* '''submit_preview.twig'''
* '''submit.twig'''
* '''userforms.twig'''

If you already created a them for 2.x versions of LimeSurvey, you'll notice that most of them corresponds to the old pstpl files for limesurvey 2.x.
Again, there is no obligation for you in your theme to create those files, with those names, in this directory. You could for example just add a giant switch in layout_global.twig with the wanted HTML for each action.

=== The manifest config.xml ===

The manifest of the theme contains the main informations about your theme. When you install a theme, the content of the manifest will be loaded in the database, in two different tables: template and template_configuration.

==== The metadata section ====

Nothing complex: just the main infos about your theme.

<syntaxhighlight lang="xml" enclose="div">
<metadata>
<name>the_name_of_your_theme</name>
<title>The Title of your theme</title>
<creationDate>16/10/2017</creationDate>
<author>Your Name</author>
<authorEmail>your@email.org</authorEmail>
<authorUrl>http://www.yourwebsite.org</authorUrl>
<copyright>Your Copyright </copyright>
<license>Licence of your theme</license>
<version>version of your theme</version>
<apiVersion>3</apiVersion>
<description>Description of your theme</description>
</metadata>
</syntaxhighlight>

Few remarks:
* '''name''': will be used as a key in the db. So it must be unique, and it should not have any special chars (no spaces). Note that cases will not be taken in account
* '''Title''': will be used to display your theme name in the different lists. It can have special chars
* '''description''': will be used in the main list of survey theme. It can contains special chars, and even HTML code by using <![CDATA[

==== The files section ====

This one is an important one.

Eg: the files section of the Material Premium Theme:

<syntaxhighlight lang="xml" enclose="div">
<files>
<css>
<add>css/bootstrap-material-design.css</add>
<add>css/ripples.min.css</add>
<add>css/ajaxify.css</add>
<add>css/theme.css</add>
<add>css/custom.css</add>
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</css>
<js>
<add>scripts/theme.js</add>
<add>scripts/ajaxify.js</add>
<add>scripts/material.js</add>
<add>scripts/ripples.min.js</add>
<add>scripts/custom.js</add>
</js>
<print_css>
<add>css/print_theme.css</add>
</print_css>
</files>
</syntaxhighlight>

All the CSS/JS files present in this section will be loaded at the launch of the survey (in ajax mode. If ajax mode is off, then of course all the files are reloaded at each page).

They will be added to a Yii Asset Packet based on the name of the theme. So when Asset Manager is on (debug mode being off), those files will be copied to the tmp directory with the rest of the theme (so you can use relative path in the CSS and JS to reach the image files).
About the Asset manager in Yii: https://www.yiiframework.com/wiki/148/understanding-assets
About packages in Yii: http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail

They will use the inheritance system. It means that if you add a CSS/JS file to a theme, but it's not present in the theme, then the engine will look into all the mother themes of this theme and will use the first one it finds. So if a user extend your theme via the theme editor, all those files will be inherited in his theme. The keyword refer to this inheritance system.

* add : it will add the file to the theme, and to all its inherited theme
* replace: it will replace the the file of its mother theme
* remove: it will remove the file from '''any''' package, even the core package

Few remarks on those keywords:

You can't add a file with the same name as the mother theme: it will always replace it. eg: If you have a file called "my_mother_theme/foo.css" and you add a file called "foo.cs" in the daughter theme, only "daughter_theme/foo.css" will be added to the theme. If you want to keep "my_mother_theme/foo.css", just choose another name for "daughter_theme/foo.css", like "daughter_theme/bar.css".

== Some notes ==


'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.


'''NOTE''': to avoid that, you can force the use to the XML rather than DB. In config.php turn debug mode on and uncommment:


'force_xmlsettings_for_survey_rendering' => true, // Uncomment if you want to force the use of the XML file rather than DB (for easy theme development)


Becareful: everything will be loaded from the XML (included options, etc)


'''NOTE''': if you manually edit the CSS/JS files (without using the Theme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache".


'''NOTE''': if you remove the section

</translate>

New Template System in LS3.x

2018-08-13T11:23:00Z

LouisGac: /* The files section */

<languages />
<translate>

__TOC__
=Introduction= 


On this page you'll learn how to:


* Use the new theme system of LimeSurvey 3.0.
* Use inheritance to manage your own themes.
* Add a picture to your theme
* Manage theme options for your surveys and survey groups


<hr/>


LimeSurvey 3 introduces a complete new theme engine system, based on Twig 1.29, Bootstrap, and allowing theme inheritance and theme options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old theme system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A theme designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new theme engine.


<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Theme Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface= 
==theme list==
On the admin dashboard, there is now a box to access the theme list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The theme list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the theme: it’s just a picture file called “preview.png” at the root of the theme
* the “title” of the theme as specified in the manifest (config.xml in the root of the theme)
* the description of the theme: a string set in its manifest
* the type of theme: Core theme (provided with LimeSurvey), User theme (added in upload directory), XML theme (not loaded in database)
* Extends: if the theme extends another theme, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a theme to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a theme in the database
** Theme editor: it will redirect you to the theme editor
** Theme option: it will lead you the global configuration of theme options

==Theme Editor== 
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' theme'']]

====A quick overview of the concept of theme inheritance==== 


In LS3, a theme can now inherit from another theme, it can “extend” another theme. This means that the theme directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of themes for your different users without having to maintain a lot of different themes. For example: you can have your own home-made theme, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom theme, all the themes that inherit from it will be updated automatically. Note that the inheritance is recursive: a theme can extend a theme that extends another one etc.


<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core themes of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface==== 


To extend the Monochrome theme of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome theme. Then, click on “extend” and validate the new name “extends_monochrome”.


If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/themes/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this theme as a normal one from a survey and it will look exactly like the monochrome theme.


[[File:Extends monochrome empty.jpg|center|baseline|border|''The theme tree (directory and files) just after its creation. It's practically empty'']]


<div class="simplebox">[[File:help.png]] The resources (jpg, png etc.) from the original theme are copied when extending a theme. This is because if you copy a CSS file from the original theme locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current theme path. </div>


The theme editor for the extends_monochrome theme looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome theme'']]
<br /><br />
There is no big difference with the old theme editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the theme directory and that the file from the original theme will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to theme views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local theme and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ==== 


The button '''Copy to local theme and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the theme you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button'']]
<br>
If you open a file explorer and go to the directory upload/themes/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your theme'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).


<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the theme to find the image. If the theme you’re working on is extended to another theme, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local theme, it will loop through the theme inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your theme. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/


<div class="simplebox">
So, to add a picture to your theme:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''


* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}


* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list==== 
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which theme the current one extends (if any)

==Template options== 
Another novelty of LS3 is the theme option page. As we’ll see later, theme creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the theme options at global level: click on “theme options” in the theme list
===Advanced options===


{{QS:Theme editor - advanced options}}

===Simple options=== 


The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the theme's /options directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options (Broken link)
<div class="simplebox">[[File:help.png]] This page can be completely different from a theme to another, and theme providers are strongly encouraged to create their own look & feel. </div>


[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from


{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core themes:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a theme provider could add his own animation library or no animation library at all.


<div class="simplebox">[[File:help.png]] The monochrome themes use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for theme providers.</div>

===Inheritance system=== 


In the previous part, we’ve seen that a theme can extend another theme. A theme configuration can also inherit from another theme configuration. It means that for a given theme, you can have a configuration at


* global level (the one we’ve just seen accessible from the theme list)
* at survey group level
* a last one at survey level.


Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

====At survey group level==== 


Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of themes than in the theme list, except that here only the option button is visible (theme editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]


<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

====At survey level==== 
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example== 
Let’s say you’re using a single theme for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core theme. But of course, if you are a theme provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization = 


You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS/JS: deal with the asset manager ("why are my changes not applied?") == 
<br />


If you're trying to update the CSS/JS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.


<br />


Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />


It moves the CSS/JS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css/js file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css/js. Else, they would have to clean their browser cache.


<br />


Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.


<br />


Here the CSS links in header when asset manager is off:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.


<br />


<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>


So, when you're editing CSS/JS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache


[[File:Clearassets-ls3 3.png]]


<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>


Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme == 
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how it works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css


<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>


Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>


You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font === 
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>


You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.


Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options === 
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>


* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %} //Shouldn't this be "theme" in stead of "template"?
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>


<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector === 
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">


'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}


</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79


<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>


Of course, the XML file only contains the default values for your theme configuration. But indeed, those values are defined and read inside the database (table "template_configuration" (Question: "template_" of "theme_"?) as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174


So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

== Adding theme options to control positioning and display of survey elements == 
This tutorial will show how to add options to an extended theme to display survey elements in various locations. In this case, we will create theme options to show the survey title in two different locations.
<div class="simplebox">[[File:help.png]] For the sake of simplicity, we will base the tutorial on an extension of the "bootswatch" theme in LimeSurvey version 3.4.3.</div>
=== Create a custom theme ===
#Extend the "bootswatch" theme as described above.
#Copy <span style="color: #BA2121;">custom.css</span> to the local theme as described above.
===Create new theme options===
#Copy the contents of <span style="color: #BA2121;">/themes/survey/bootswatch/options/</span> to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/</span>.
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/options.twig</span> in an editor and find "{# Bootstrap Bootswatch theme #}". Directly before its parent <nowiki><div class='row'></nowiki> element, add this:<syntaxhighlight lang="html" enclose="div">
{# Custom survey name in navbar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div>


{# Custom survey name below progress bar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div></syntaxhighlight>
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/config.xml</span> and add two items to the "options" block so it looks like this:<syntaxhighlight lang="xml" enclose="div"> <options>
<ajaxmode>on</ajaxmode>
...
<surveyname1>on</surveyname1>
<surveyname2>on</surveyname2>
</options></syntaxhighlight>
#This should give you two new options in the Theme Options screen like this:<br />[[File:Tutorial_tp_1_1.png]]

===Modifed view for Survey Title in the navbar=== 
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/header/</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> and find "{# Logo option #}". Under that, modify the IF statement for the logo/survey-name, so it looks like this:<syntaxhighlight lang="html" enclose="div">
{# Logo option #}
{% if( aSurveyInfo.options.brandlogo == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }} logo-container" {{ aSurveyInfo.attr.navbarbrand }} >
{{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
</div>
{% endif %}
{% if( aSurveyInfo.options.surveyname1 == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }}" {{ aSurveyInfo.attr.navbarbrand }} >
{{ aSurveyInfo.name }}
</div>
{% endif %}</syntaxhighlight>
#Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60px;
font-size: 32px;
}</syntaxhighlight>
#Toggle the "Survey name in navbar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_2.png]]
===Modifed view for Survey Title under progress bar===
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> and add an <nowiki><h1></nowiki> element for the survey name. So it looks like this:<syntaxhighlight lang="html" enclose="div"><div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>

{# Custom survey name #}
{% if( aSurveyInfo.options.surveyname2 == "on") %}
<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
{% endif %}

{# Group Name #}
{{ include('./subviews/survey/group_subviews/group_name.twig') }}

{# Group Description #}
{{ include('./subviews/survey/group_subviews/group_desc.twig') }}

{#
PRESENT THE QUESTIONS

This is the main part. It will render each question for this group
#}


{% for aQuestion in aGroup.aQuestions %}
{{ include('./subviews/survey/question_container.twig') }}
{% endfor %}


{% if aGroup.show_last_group == true %}
<input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
{% endif %}

{% if aGroup.show_last_answer == true %}
<input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
{% endif %}
</div></syntaxhighlight>
# Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60ph1.custom-survey-name {
margin: 0;
text-align: center;
}</syntaxhighlight>
#Toggle the "Survey name below progress bar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_3.png]]

===Downloads=== 
* Sample extended theme: [[Media:Test_survey_names.zip]]

=Creating a theme from scratch= 
Documentation coming soon.

For now, just giving few tips.

==theme structure==

=== Files and directories ===
When you create a Theme from scratch, you don't need to respect the file/directory structure/css/js from Vanilla.
The mandatory css/js is added by core (you can still remove it if needed)

The only files your theme must have are the layout files:

* '''layout_global.twig''' : render the pages for survey taking
* '''layout_survey_list.twig''' : render the survey list (if this theme is set as default)
* '''layout_errors.twig''' : used to render errors that block survey rendering. ( wrong survey id, empty group in preview group, etc.)
* '''layout_user_forms.twig''': renders the user forms such as: token (survey participant), and register.
* '''layout_print.twig''' : used to print the survey to pdf
* '''layout_printanswers.twig''': print the answers

The content of those files, the files they include or not, is entirely up to you.
All the other files and directories that you find on Vanilla are purely optional, feel free to organize your code the way you want.

<div class="simplebox">[[File:help.png]] If you read the frontend rendering code, you'll see that those files names appear directly in it. That's why they are mandatory.
Eg: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/helpers/SurveyRuntimeHelper.php#L462
</div>

=== Content ===

In Vanilla's layout_global.twig, you'll see we use a variable called "include_content" to decide what to show
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/layout_global.twig#L114-L115

<syntaxhighlight lang="php" enclose="div">
{% set sViewContent = './subviews/content/' ~ aSurveyInfo.include_content ~ '.twig' %}
{% include './subviews/content/outerframe.twig' with {'include_content': sViewContent } %}
</syntaxhighlight>

aSurveyInfo.include_content tell you what action is currently going on: showing questions? showing submit result? showing clear all? etc
As you can see, in vanilla, we create one file to include by action. So if you want to know the list of actions, just check the vanilla's directory '''views/subviews/content''', and remove the "twig" extension :
https://github.com/LimeSurvey/LimeSurvey/tree/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/subviews/content

* '''clearall.twig'''
* '''firstpage.twig'''
* '''load.twig'''
* '''mainrow.twig'''
* '''main.twig'''
* '''optin.twig'''
* '''optout.twig'''
* '''outerframe.twig'''
* '''printanswers.twig'''
* '''quotas.twig'''
* '''register.twig'''
* '''save.twig'''
* '''submit_preview.twig'''
* '''submit.twig'''
* '''userforms.twig'''

If you already created a them for 2.x versions of LimeSurvey, you'll notice that most of them corresponds to the old pstpl files for limesurvey 2.x.
Again, there is no obligation for you in your theme to create those files, with those names, in this directory. You could for example just add a giant switch in layout_global.twig with the wanted HTML for each action.

=== The manifest config.xml ===

The manifest of the theme contains the main informations about your theme. When you install a theme, the content of the manifest will be loaded in the database, in two different tables: template and template_configuration.

==== The metadata section ====

Nothing complex: just the main infos about your theme.

<syntaxhighlight lang="xml" enclose="div">
<metadata>
<name>the_name_of_your_theme</name>
<title>The Title of your theme</title>
<creationDate>16/10/2017</creationDate>
<author>Your Name</author>
<authorEmail>your@email.org</authorEmail>
<authorUrl>http://www.yourwebsite.org</authorUrl>
<copyright>Your Copyright </copyright>
<license>Licence of your theme</license>
<version>version of your theme</version>
<apiVersion>3</apiVersion>
<description>Description of your theme</description>
</metadata>
</syntaxhighlight>

Few remarks:
* '''name''': will be used as a key in the db. So it must be unique, and it should not have any special chars (no spaces). Note that cases will not be taken in account
* '''Title''': will be used to display your theme name in the different lists. It can have special chars
* '''description''': will be used in the main list of survey theme. It can contains special chars, and even HTML code by using <![CDATA[

==== The files section ====

This one is an important one.

All the CSS/JS files present in this section will be loaded at the launch of the survey (in ajax mode. If ajax mode is off, then of course all the files are reloaded at each page).

They will be added to a Yii Asset Packet based on the name of the theme. So when Asset Manager is on (debug mode being off), those files will be copied to the tmp directory with the rest of the theme (so you can use relative path in the CSS and JS to reach the image files).
About the Asset manager in Yii: https://www.yiiframework.com/wiki/148/understanding-assets
About packages in Yii: http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail

They will use the inheritance system. It means that if you add a CSS/JS file to a theme, but it's not present in the theme, then the engine will look into all the mother themes of this theme and will use the first one it finds. So if a user extend your theme via the theme editor, all those files will be inherited in his theme. The keyword refer to this inheritance system.

Eg: the files section of the Material Premium Theme:

<syntaxhighlight lang="xml" enclose="div">
<files>
<css>
<add>css/bootstrap-material-design.css</add>
<add>css/ripples.min.css</add>
<add>css/ajaxify.css</add>
<add>css/theme.css</add>
<add>css/custom.css</add>
<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
</css>
<js>
<add>scripts/theme.js</add>
<add>scripts/ajaxify.js</add>
<add>scripts/material.js</add>
<add>scripts/ripples.min.js</add>
<add>scripts/custom.js</add>
</js>
<print_css>
<add>css/print_theme.css</add>
</print_css>
</files>
</syntaxhighlight>

* add : it will add the file to the theme, and to all its inherited theme
* replace: it will replace the the file of its mother theme
* remove: it will remove the file from '''any''' package, even the core package

Few remarks on those keywords:

You can't add a file with the same name as the mother theme: it will always replace it. eg: If you have a file called "my_mother_theme/foo.css" and you add a file called "foo.cs" in the daughter theme, only "daughter_theme/foo.css" will be added to the theme. If you want to keep "my_mother_theme/foo.css", just choose another name for "daughter_theme/foo.css", like "daughter_theme/bar.css".

== Some notes ==


'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.


'''NOTE''': to avoid that, you can force the use to the XML rather than DB. In config.php turn debug mode on and uncommment:


'force_xmlsettings_for_survey_rendering' => true, // Uncomment if you want to force the use of the XML file rather than DB (for easy theme development)


Becareful: everything will be loaded from the XML (included options, etc)


'''NOTE''': if you manually edit the CSS/JS files (without using the Theme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache".


'''NOTE''': if you remove the section

</translate>

New Template System in LS3.x

2018-08-13T11:20:57Z

LouisGac: /* The manifest config.xml */

<languages />
<translate>

__TOC__
=Introduction= 


On this page you'll learn how to:


* Use the new theme system of LimeSurvey 3.0.
* Use inheritance to manage your own themes.
* Add a picture to your theme
* Manage theme options for your surveys and survey groups


<hr/>


LimeSurvey 3 introduces a complete new theme engine system, based on Twig 1.29, Bootstrap, and allowing theme inheritance and theme options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old theme system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A theme designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new theme engine.


<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Theme Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface= 
==theme list==
On the admin dashboard, there is now a box to access the theme list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The theme list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the theme: it’s just a picture file called “preview.png” at the root of the theme
* the “title” of the theme as specified in the manifest (config.xml in the root of the theme)
* the description of the theme: a string set in its manifest
* the type of theme: Core theme (provided with LimeSurvey), User theme (added in upload directory), XML theme (not loaded in database)
* Extends: if the theme extends another theme, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a theme to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a theme in the database
** Theme editor: it will redirect you to the theme editor
** Theme option: it will lead you the global configuration of theme options

==Theme Editor== 
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' theme'']]

====A quick overview of the concept of theme inheritance==== 


In LS3, a theme can now inherit from another theme, it can “extend” another theme. This means that the theme directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of themes for your different users without having to maintain a lot of different themes. For example: you can have your own home-made theme, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom theme, all the themes that inherit from it will be updated automatically. Note that the inheritance is recursive: a theme can extend a theme that extends another one etc.


<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core themes of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface==== 


To extend the Monochrome theme of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome theme. Then, click on “extend” and validate the new name “extends_monochrome”.


If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/themes/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this theme as a normal one from a survey and it will look exactly like the monochrome theme.


[[File:Extends monochrome empty.jpg|center|baseline|border|''The theme tree (directory and files) just after its creation. It's practically empty'']]


<div class="simplebox">[[File:help.png]] The resources (jpg, png etc.) from the original theme are copied when extending a theme. This is because if you copy a CSS file from the original theme locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current theme path. </div>


The theme editor for the extends_monochrome theme looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome theme'']]
<br /><br />
There is no big difference with the old theme editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the theme directory and that the file from the original theme will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to theme views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local theme and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ==== 


The button '''Copy to local theme and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the theme you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button'']]
<br>
If you open a file explorer and go to the directory upload/themes/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your theme'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).


<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the theme to find the image. If the theme you’re working on is extended to another theme, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local theme, it will loop through the theme inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your theme. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/


<div class="simplebox">
So, to add a picture to your theme:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''


* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}


* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list==== 
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which theme the current one extends (if any)

==Template options== 
Another novelty of LS3 is the theme option page. As we’ll see later, theme creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the theme options at global level: click on “theme options” in the theme list
===Advanced options===


{{QS:Theme editor - advanced options}}

===Simple options=== 


The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the theme's /options directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options (Broken link)
<div class="simplebox">[[File:help.png]] This page can be completely different from a theme to another, and theme providers are strongly encouraged to create their own look & feel. </div>


[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from


{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core themes:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a theme provider could add his own animation library or no animation library at all.


<div class="simplebox">[[File:help.png]] The monochrome themes use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for theme providers.</div>

===Inheritance system=== 


In the previous part, we’ve seen that a theme can extend another theme. A theme configuration can also inherit from another theme configuration. It means that for a given theme, you can have a configuration at


* global level (the one we’ve just seen accessible from the theme list)
* at survey group level
* a last one at survey level.


Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

====At survey group level==== 


Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of themes than in the theme list, except that here only the option button is visible (theme editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]


<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

====At survey level==== 
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example== 
Let’s say you’re using a single theme for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core theme. But of course, if you are a theme provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization = 


You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS/JS: deal with the asset manager ("why are my changes not applied?") == 
<br />


If you're trying to update the CSS/JS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.


<br />


Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />


It moves the CSS/JS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css/js file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css/js. Else, they would have to clean their browser cache.


<br />


Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.


<br />


Here the CSS links in header when asset manager is off:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.


<br />


<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>


So, when you're editing CSS/JS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache


[[File:Clearassets-ls3 3.png]]


<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>


Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme == 
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how it works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css


<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>


Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>


You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font === 
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>


You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.


Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options === 
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>


* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %} //Shouldn't this be "theme" in stead of "template"?
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>


<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector === 
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">


'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}


</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79


<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>


Of course, the XML file only contains the default values for your theme configuration. But indeed, those values are defined and read inside the database (table "template_configuration" (Question: "template_" of "theme_"?) as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174


So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

== Adding theme options to control positioning and display of survey elements == 
This tutorial will show how to add options to an extended theme to display survey elements in various locations. In this case, we will create theme options to show the survey title in two different locations.
<div class="simplebox">[[File:help.png]] For the sake of simplicity, we will base the tutorial on an extension of the "bootswatch" theme in LimeSurvey version 3.4.3.</div>
=== Create a custom theme ===
#Extend the "bootswatch" theme as described above.
#Copy <span style="color: #BA2121;">custom.css</span> to the local theme as described above.
===Create new theme options===
#Copy the contents of <span style="color: #BA2121;">/themes/survey/bootswatch/options/</span> to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/</span>.
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/options.twig</span> in an editor and find "{# Bootstrap Bootswatch theme #}". Directly before its parent <nowiki><div class='row'></nowiki> element, add this:<syntaxhighlight lang="html" enclose="div">
{# Custom survey name in navbar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div>


{# Custom survey name below progress bar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div></syntaxhighlight>
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/config.xml</span> and add two items to the "options" block so it looks like this:<syntaxhighlight lang="xml" enclose="div"> <options>
<ajaxmode>on</ajaxmode>
...
<surveyname1>on</surveyname1>
<surveyname2>on</surveyname2>
</options></syntaxhighlight>
#This should give you two new options in the Theme Options screen like this:<br />[[File:Tutorial_tp_1_1.png]]

===Modifed view for Survey Title in the navbar=== 
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/header/</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> and find "{# Logo option #}". Under that, modify the IF statement for the logo/survey-name, so it looks like this:<syntaxhighlight lang="html" enclose="div">
{# Logo option #}
{% if( aSurveyInfo.options.brandlogo == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }} logo-container" {{ aSurveyInfo.attr.navbarbrand }} >
{{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
</div>
{% endif %}
{% if( aSurveyInfo.options.surveyname1 == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }}" {{ aSurveyInfo.attr.navbarbrand }} >
{{ aSurveyInfo.name }}
</div>
{% endif %}</syntaxhighlight>
#Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60px;
font-size: 32px;
}</syntaxhighlight>
#Toggle the "Survey name in navbar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_2.png]]
===Modifed view for Survey Title under progress bar===
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> and add an <nowiki><h1></nowiki> element for the survey name. So it looks like this:<syntaxhighlight lang="html" enclose="div"><div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>

{# Custom survey name #}
{% if( aSurveyInfo.options.surveyname2 == "on") %}
<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
{% endif %}

{# Group Name #}
{{ include('./subviews/survey/group_subviews/group_name.twig') }}

{# Group Description #}
{{ include('./subviews/survey/group_subviews/group_desc.twig') }}

{#
PRESENT THE QUESTIONS

This is the main part. It will render each question for this group
#}


{% for aQuestion in aGroup.aQuestions %}
{{ include('./subviews/survey/question_container.twig') }}
{% endfor %}


{% if aGroup.show_last_group == true %}
<input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
{% endif %}

{% if aGroup.show_last_answer == true %}
<input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
{% endif %}
</div></syntaxhighlight>
# Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60ph1.custom-survey-name {
margin: 0;
text-align: center;
}</syntaxhighlight>
#Toggle the "Survey name below progress bar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_3.png]]

===Downloads=== 
* Sample extended theme: [[Media:Test_survey_names.zip]]

=Creating a theme from scratch= 
Documentation coming soon.

For now, just giving few tips.

==theme structure==

=== Files and directories ===
When you create a Theme from scratch, you don't need to respect the file/directory structure/css/js from Vanilla.
The mandatory css/js is added by core (you can still remove it if needed)

The only files your theme must have are the layout files:

* '''layout_global.twig''' : render the pages for survey taking
* '''layout_survey_list.twig''' : render the survey list (if this theme is set as default)
* '''layout_errors.twig''' : used to render errors that block survey rendering. ( wrong survey id, empty group in preview group, etc.)
* '''layout_user_forms.twig''': renders the user forms such as: token (survey participant), and register.
* '''layout_print.twig''' : used to print the survey to pdf
* '''layout_printanswers.twig''': print the answers

The content of those files, the files they include or not, is entirely up to you.
All the other files and directories that you find on Vanilla are purely optional, feel free to organize your code the way you want.

<div class="simplebox">[[File:help.png]] If you read the frontend rendering code, you'll see that those files names appear directly in it. That's why they are mandatory.
Eg: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/helpers/SurveyRuntimeHelper.php#L462
</div>

=== Content ===

In Vanilla's layout_global.twig, you'll see we use a variable called "include_content" to decide what to show
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/layout_global.twig#L114-L115

<syntaxhighlight lang="php" enclose="div">
{% set sViewContent = './subviews/content/' ~ aSurveyInfo.include_content ~ '.twig' %}
{% include './subviews/content/outerframe.twig' with {'include_content': sViewContent } %}
</syntaxhighlight>

aSurveyInfo.include_content tell you what action is currently going on: showing questions? showing submit result? showing clear all? etc
As you can see, in vanilla, we create one file to include by action. So if you want to know the list of actions, just check the vanilla's directory '''views/subviews/content''', and remove the "twig" extension :
https://github.com/LimeSurvey/LimeSurvey/tree/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/subviews/content

* '''clearall.twig'''
* '''firstpage.twig'''
* '''load.twig'''
* '''mainrow.twig'''
* '''main.twig'''
* '''optin.twig'''
* '''optout.twig'''
* '''outerframe.twig'''
* '''printanswers.twig'''
* '''quotas.twig'''
* '''register.twig'''
* '''save.twig'''
* '''submit_preview.twig'''
* '''submit.twig'''
* '''userforms.twig'''

If you already created a them for 2.x versions of LimeSurvey, you'll notice that most of them corresponds to the old pstpl files for limesurvey 2.x.
Again, there is no obligation for you in your theme to create those files, with those names, in this directory. You could for example just add a giant switch in layout_global.twig with the wanted HTML for each action.

=== The manifest config.xml ===

The manifest of the theme contains the main informations about your theme. When you install a theme, the content of the manifest will be loaded in the database, in two different tables: template and template_configuration.

==== The metadata section ====

Nothing complex: just the main infos about your theme.

<syntaxhighlight lang="xml" enclose="div">
<metadata>
<name>the_name_of_your_theme</name>
<title>The Title of your theme</title>
<creationDate>16/10/2017</creationDate>
<author>Your Name</author>
<authorEmail>your@email.org</authorEmail>
<authorUrl>http://www.yourwebsite.org</authorUrl>
<copyright>Your Copyright </copyright>
<license>Licence of your theme</license>
<version>version of your theme</version>
<apiVersion>3</apiVersion>
<description>Description of your theme</description>
</metadata>
</syntaxhighlight>

Few remarks:
* '''name''': will be used as a key in the db. So it must be unique, and it should not have any special chars (no spaces). Note that cases will not be taken in account
* '''Title''': will be used to display your theme name in the different lists. It can have special chars
* '''description''': will be used in the main list of survey theme. It can contains special chars, and even HTML code by using <![CDATA[

==== The files section ====

This one is an important one.

All the CSS/JS files present in this section will be loaded at the launch of the survey (in ajax mode. If ajax mode is off, then of course all the files are reloaded at each page).

They will be added to a Yii Asset Packet based on the name of the theme. So when Asset Manager is on (debug mode being off), those files will be copied to the tmp directory with the rest of the theme (so you can use relative path in the CSS and JS to reach the image files).
About the Asset manager in Yii: https://www.yiiframework.com/wiki/148/understanding-assets
About packages in Yii: http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail

They will use the inheritance system. It means that if you add a CSS/JS file to a theme, but it's not present in the theme, then the engine will look into all the mother themes of this theme and will use the first one it finds. So if a user extend your theme via the theme editor, all those files will be inherited in his theme. The keyword refer to this inheritance system:

* add : it will add the file to the theme, and to all its inherited theme
* replace: it will replace the the file of its mother theme
* remove: it will remove the file from '''any''' package, even the core package

Few remarks on those keywords:

You can't add a file with the same name as the mother theme: it will always replace it. eg: If you have a file called "my_mother_theme/foo.css" and you add a file called "foo.cs" in the daughter theme, only "daughter_theme/foo.css" will be added to the theme. If you want to keep "my_mother_theme/foo.css", just choose another name for "daughter_theme/foo.css", like "daughter_theme/bar.css".

== Some notes ==


'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.


'''NOTE''': to avoid that, you can force the use to the XML rather than DB. In config.php turn debug mode on and uncommment:


'force_xmlsettings_for_survey_rendering' => true, // Uncomment if you want to force the use of the XML file rather than DB (for easy theme development)


Becareful: everything will be loaded from the XML (included options, etc)


'''NOTE''': if you manually edit the CSS/JS files (without using the Theme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache".


'''NOTE''': if you remove the section

</translate>

New Template System in LS3.x

2018-08-13T11:08:29Z

LouisGac: /* theme structure */

<languages />
<translate>

__TOC__
=Introduction= 


On this page you'll learn how to:


* Use the new theme system of LimeSurvey 3.0.
* Use inheritance to manage your own themes.
* Add a picture to your theme
* Manage theme options for your surveys and survey groups


<hr/>


LimeSurvey 3 introduces a complete new theme engine system, based on Twig 1.29, Bootstrap, and allowing theme inheritance and theme options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old theme system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A theme designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new theme engine.


<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Theme Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface= 
==theme list==
On the admin dashboard, there is now a box to access the theme list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The theme list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the theme: it’s just a picture file called “preview.png” at the root of the theme
* the “title” of the theme as specified in the manifest (config.xml in the root of the theme)
* the description of the theme: a string set in its manifest
* the type of theme: Core theme (provided with LimeSurvey), User theme (added in upload directory), XML theme (not loaded in database)
* Extends: if the theme extends another theme, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a theme to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a theme in the database
** Theme editor: it will redirect you to the theme editor
** Theme option: it will lead you the global configuration of theme options

==Theme Editor== 
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' theme'']]

====A quick overview of the concept of theme inheritance==== 


In LS3, a theme can now inherit from another theme, it can “extend” another theme. This means that the theme directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of themes for your different users without having to maintain a lot of different themes. For example: you can have your own home-made theme, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom theme, all the themes that inherit from it will be updated automatically. Note that the inheritance is recursive: a theme can extend a theme that extends another one etc.


<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core themes of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface==== 


To extend the Monochrome theme of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome theme. Then, click on “extend” and validate the new name “extends_monochrome”.


If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/themes/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this theme as a normal one from a survey and it will look exactly like the monochrome theme.


[[File:Extends monochrome empty.jpg|center|baseline|border|''The theme tree (directory and files) just after its creation. It's practically empty'']]


<div class="simplebox">[[File:help.png]] The resources (jpg, png etc.) from the original theme are copied when extending a theme. This is because if you copy a CSS file from the original theme locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current theme path. </div>


The theme editor for the extends_monochrome theme looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome theme'']]
<br /><br />
There is no big difference with the old theme editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the theme directory and that the file from the original theme will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to theme views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local theme and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ==== 


The button '''Copy to local theme and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the theme you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button'']]
<br>
If you open a file explorer and go to the directory upload/themes/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your theme'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).


<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the theme to find the image. If the theme you’re working on is extended to another theme, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local theme, it will loop through the theme inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your theme. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/


<div class="simplebox">
So, to add a picture to your theme:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''


* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}


* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list==== 
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which theme the current one extends (if any)

==Template options== 
Another novelty of LS3 is the theme option page. As we’ll see later, theme creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the theme options at global level: click on “theme options” in the theme list
===Advanced options===


{{QS:Theme editor - advanced options}}

===Simple options=== 


The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the theme's /options directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options (Broken link)
<div class="simplebox">[[File:help.png]] This page can be completely different from a theme to another, and theme providers are strongly encouraged to create their own look & feel. </div>


[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from


{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core themes:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a theme provider could add his own animation library or no animation library at all.


<div class="simplebox">[[File:help.png]] The monochrome themes use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for theme providers.</div>

===Inheritance system=== 


In the previous part, we’ve seen that a theme can extend another theme. A theme configuration can also inherit from another theme configuration. It means that for a given theme, you can have a configuration at


* global level (the one we’ve just seen accessible from the theme list)
* at survey group level
* a last one at survey level.


Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

====At survey group level==== 


Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of themes than in the theme list, except that here only the option button is visible (theme editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]


<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

====At survey level==== 
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example== 
Let’s say you’re using a single theme for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core theme. But of course, if you are a theme provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization = 


You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS/JS: deal with the asset manager ("why are my changes not applied?") == 
<br />


If you're trying to update the CSS/JS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.


<br />


Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />


It moves the CSS/JS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css/js file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css/js. Else, they would have to clean their browser cache.


<br />


Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.


<br />


Here the CSS links in header when asset manager is off:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.


<br />


<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>


So, when you're editing CSS/JS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache


[[File:Clearassets-ls3 3.png]]


<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>


Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme == 
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how it works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css


<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>


Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>


You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font === 
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>


You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.


Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options === 
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>


* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %} //Shouldn't this be "theme" in stead of "template"?
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>


<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector === 
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">


'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}


</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79


<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>


Of course, the XML file only contains the default values for your theme configuration. But indeed, those values are defined and read inside the database (table "template_configuration" (Question: "template_" of "theme_"?) as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174


So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

== Adding theme options to control positioning and display of survey elements == 
This tutorial will show how to add options to an extended theme to display survey elements in various locations. In this case, we will create theme options to show the survey title in two different locations.
<div class="simplebox">[[File:help.png]] For the sake of simplicity, we will base the tutorial on an extension of the "bootswatch" theme in LimeSurvey version 3.4.3.</div>
=== Create a custom theme ===
#Extend the "bootswatch" theme as described above.
#Copy <span style="color: #BA2121;">custom.css</span> to the local theme as described above.
===Create new theme options===
#Copy the contents of <span style="color: #BA2121;">/themes/survey/bootswatch/options/</span> to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/</span>.
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/options.twig</span> in an editor and find "{# Bootstrap Bootswatch theme #}". Directly before its parent <nowiki><div class='row'></nowiki> element, add this:<syntaxhighlight lang="html" enclose="div">
{# Custom survey name in navbar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div>


{# Custom survey name below progress bar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div></syntaxhighlight>
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/config.xml</span> and add two items to the "options" block so it looks like this:<syntaxhighlight lang="xml" enclose="div"> <options>
<ajaxmode>on</ajaxmode>
...
<surveyname1>on</surveyname1>
<surveyname2>on</surveyname2>
</options></syntaxhighlight>
#This should give you two new options in the Theme Options screen like this:<br />[[File:Tutorial_tp_1_1.png]]

===Modifed view for Survey Title in the navbar=== 
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/header/</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> and find "{# Logo option #}". Under that, modify the IF statement for the logo/survey-name, so it looks like this:<syntaxhighlight lang="html" enclose="div">
{# Logo option #}
{% if( aSurveyInfo.options.brandlogo == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }} logo-container" {{ aSurveyInfo.attr.navbarbrand }} >
{{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
</div>
{% endif %}
{% if( aSurveyInfo.options.surveyname1 == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }}" {{ aSurveyInfo.attr.navbarbrand }} >
{{ aSurveyInfo.name }}
</div>
{% endif %}</syntaxhighlight>
#Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60px;
font-size: 32px;
}</syntaxhighlight>
#Toggle the "Survey name in navbar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_2.png]]
===Modifed view for Survey Title under progress bar===
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> and add an <nowiki><h1></nowiki> element for the survey name. So it looks like this:<syntaxhighlight lang="html" enclose="div"><div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>

{# Custom survey name #}
{% if( aSurveyInfo.options.surveyname2 == "on") %}
<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
{% endif %}

{# Group Name #}
{{ include('./subviews/survey/group_subviews/group_name.twig') }}

{# Group Description #}
{{ include('./subviews/survey/group_subviews/group_desc.twig') }}

{#
PRESENT THE QUESTIONS

This is the main part. It will render each question for this group
#}


{% for aQuestion in aGroup.aQuestions %}
{{ include('./subviews/survey/question_container.twig') }}
{% endfor %}


{% if aGroup.show_last_group == true %}
<input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
{% endif %}

{% if aGroup.show_last_answer == true %}
<input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
{% endif %}
</div></syntaxhighlight>
# Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60ph1.custom-survey-name {
margin: 0;
text-align: center;
}</syntaxhighlight>
#Toggle the "Survey name below progress bar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_3.png]]

===Downloads=== 
* Sample extended theme: [[Media:Test_survey_names.zip]]

=Creating a theme from scratch= 
Documentation coming soon.

For now, just giving few tips.

==theme structure==

=== Files and directories ===
When you create a Theme from scratch, you don't need to respect the file/directory structure/css/js from Vanilla.
The mandatory css/js is added by core (you can still remove it if needed)

The only files your theme must have are the layout files:

* '''layout_global.twig''' : render the pages for survey taking
* '''layout_survey_list.twig''' : render the survey list (if this theme is set as default)
* '''layout_errors.twig''' : used to render errors that block survey rendering. ( wrong survey id, empty group in preview group, etc.)
* '''layout_user_forms.twig''': renders the user forms such as: token (survey participant), and register.
* '''layout_print.twig''' : used to print the survey to pdf
* '''layout_printanswers.twig''': print the answers

The content of those files, the files they include or not, is entirely up to you.
All the other files and directories that you find on Vanilla are purely optional, feel free to organize your code the way you want.

<div class="simplebox">[[File:help.png]] If you read the frontend rendering code, you'll see that those files names appear directly in it. That's why they are mandatory.
Eg: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/helpers/SurveyRuntimeHelper.php#L462
</div>

=== Content ===

In Vanilla's layout_global.twig, you'll see we use a variable called "include_content" to decide what to show
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/layout_global.twig#L114-L115

<syntaxhighlight lang="php" enclose="div">
{% set sViewContent = './subviews/content/' ~ aSurveyInfo.include_content ~ '.twig' %}
{% include './subviews/content/outerframe.twig' with {'include_content': sViewContent } %}
</syntaxhighlight>

aSurveyInfo.include_content tell you what action is currently going on: showing questions? showing submit result? showing clear all? etc
As you can see, in vanilla, we create one file to include by action. So if you want to know the list of actions, just check the vanilla's directory '''views/subviews/content''', and remove the "twig" extension :
https://github.com/LimeSurvey/LimeSurvey/tree/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/subviews/content

* '''clearall.twig'''
* '''firstpage.twig'''
* '''load.twig'''
* '''mainrow.twig'''
* '''main.twig'''
* '''optin.twig'''
* '''optout.twig'''
* '''outerframe.twig'''
* '''printanswers.twig'''
* '''quotas.twig'''
* '''register.twig'''
* '''save.twig'''
* '''submit_preview.twig'''
* '''submit.twig'''
* '''userforms.twig'''

If you already created a them for 2.x versions of LimeSurvey, you'll notice that most of them corresponds to the old pstpl files for limesurvey 2.x.
Again, there is no obligation for you in your theme to create those files, with those names, in this directory. You could for example just add a giant switch in layout_global.twig with the wanted HTML for each action.

=== The manifest config.xml ===

The manifest of the theme contains the main informations about your theme. When you install a theme, the content of the manifest will be loaded in the database, in two different tables: template and template_configuration.

==== The metadata section ====

Nothing complex: just the main infos about your theme.

<syntaxhighlight lang="xml" enclose="div">
<metadata>
<name>the_name_of_your_theme</name>
<title>The Title of your theme</title>
<creationDate>16/10/2017</creationDate>
<author>Your Name</author>
<authorEmail>your@email.org</authorEmail>
<authorUrl>http://www.yourwebsite.org</authorUrl>
<copyright>Your Copyright </copyright>
<license>Licence of your theme</license>
<version>version of your theme</version>
<apiVersion>3</apiVersion>
<description>Description of your theme</description>
</metadata>
</syntaxhighlight>

Few remarks:
* '''name''': will be used as a key in the db. So it must be unique, and it should not have any special chars (no spaces). Note that cases will not be taken in account
* '''Title''': will be used to display your theme name in the different lists. It can have special chars
* '''description''': will be used in the main list of survey theme. It can contains special chars, and even HTML code by using <![CDATA[

== Some notes ==


'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.


'''NOTE''': to avoid that, you can force the use to the XML rather than DB. In config.php turn debug mode on and uncommment:


'force_xmlsettings_for_survey_rendering' => true, // Uncomment if you want to force the use of the XML file rather than DB (for easy theme development)


Becareful: everything will be loaded from the XML (included options, etc)


'''NOTE''': if you manually edit the CSS/JS files (without using the Theme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache".


'''NOTE''': if you remove the section

</translate>

New Template System in LS3.x

2018-08-13T10:58:42Z

LouisGac: /* Content */

<languages />
<translate>

__TOC__
=Introduction= 


On this page you'll learn how to:


* Use the new theme system of LimeSurvey 3.0.
* Use inheritance to manage your own themes.
* Add a picture to your theme
* Manage theme options for your surveys and survey groups


<hr/>


LimeSurvey 3 introduces a complete new theme engine system, based on Twig 1.29, Bootstrap, and allowing theme inheritance and theme options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old theme system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A theme designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new theme engine.


<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Theme Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface= 
==theme list==
On the admin dashboard, there is now a box to access the theme list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The theme list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the theme: it’s just a picture file called “preview.png” at the root of the theme
* the “title” of the theme as specified in the manifest (config.xml in the root of the theme)
* the description of the theme: a string set in its manifest
* the type of theme: Core theme (provided with LimeSurvey), User theme (added in upload directory), XML theme (not loaded in database)
* Extends: if the theme extends another theme, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a theme to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a theme in the database
** Theme editor: it will redirect you to the theme editor
** Theme option: it will lead you the global configuration of theme options

==Theme Editor== 
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' theme'']]

====A quick overview of the concept of theme inheritance==== 


In LS3, a theme can now inherit from another theme, it can “extend” another theme. This means that the theme directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of themes for your different users without having to maintain a lot of different themes. For example: you can have your own home-made theme, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom theme, all the themes that inherit from it will be updated automatically. Note that the inheritance is recursive: a theme can extend a theme that extends another one etc.


<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core themes of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface==== 


To extend the Monochrome theme of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome theme. Then, click on “extend” and validate the new name “extends_monochrome”.


If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/themes/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this theme as a normal one from a survey and it will look exactly like the monochrome theme.


[[File:Extends monochrome empty.jpg|center|baseline|border|''The theme tree (directory and files) just after its creation. It's practically empty'']]


<div class="simplebox">[[File:help.png]] The resources (jpg, png etc.) from the original theme are copied when extending a theme. This is because if you copy a CSS file from the original theme locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current theme path. </div>


The theme editor for the extends_monochrome theme looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome theme'']]
<br /><br />
There is no big difference with the old theme editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the theme directory and that the file from the original theme will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to theme views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local theme and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ==== 


The button '''Copy to local theme and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the theme you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button'']]
<br>
If you open a file explorer and go to the directory upload/themes/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your theme'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).


<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the theme to find the image. If the theme you’re working on is extended to another theme, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local theme, it will loop through the theme inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your theme. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/


<div class="simplebox">
So, to add a picture to your theme:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''


* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}


* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list==== 
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which theme the current one extends (if any)

==Template options== 
Another novelty of LS3 is the theme option page. As we’ll see later, theme creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the theme options at global level: click on “theme options” in the theme list
===Advanced options===


{{QS:Theme editor - advanced options}}

===Simple options=== 


The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the theme's /options directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options (Broken link)
<div class="simplebox">[[File:help.png]] This page can be completely different from a theme to another, and theme providers are strongly encouraged to create their own look & feel. </div>


[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from


{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core themes:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a theme provider could add his own animation library or no animation library at all.


<div class="simplebox">[[File:help.png]] The monochrome themes use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for theme providers.</div>

===Inheritance system=== 


In the previous part, we’ve seen that a theme can extend another theme. A theme configuration can also inherit from another theme configuration. It means that for a given theme, you can have a configuration at


* global level (the one we’ve just seen accessible from the theme list)
* at survey group level
* a last one at survey level.


Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

====At survey group level==== 


Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of themes than in the theme list, except that here only the option button is visible (theme editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]


<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

====At survey level==== 
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example== 
Let’s say you’re using a single theme for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core theme. But of course, if you are a theme provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization = 


You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS/JS: deal with the asset manager ("why are my changes not applied?") == 
<br />


If you're trying to update the CSS/JS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.


<br />


Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />


It moves the CSS/JS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css/js file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css/js. Else, they would have to clean their browser cache.


<br />


Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.


<br />


Here the CSS links in header when asset manager is off:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.


<br />


<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>


So, when you're editing CSS/JS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache


[[File:Clearassets-ls3 3.png]]


<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>


Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme == 
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how it works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css


<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>


Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>


You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font === 
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>


You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.


Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options === 
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>


* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %} //Shouldn't this be "theme" in stead of "template"?
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>


<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector === 
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">


'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}


</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79


<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>


Of course, the XML file only contains the default values for your theme configuration. But indeed, those values are defined and read inside the database (table "template_configuration" (Question: "template_" of "theme_"?) as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174


So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

== Adding theme options to control positioning and display of survey elements == 
This tutorial will show how to add options to an extended theme to display survey elements in various locations. In this case, we will create theme options to show the survey title in two different locations.
<div class="simplebox">[[File:help.png]] For the sake of simplicity, we will base the tutorial on an extension of the "bootswatch" theme in LimeSurvey version 3.4.3.</div>
=== Create a custom theme ===
#Extend the "bootswatch" theme as described above.
#Copy <span style="color: #BA2121;">custom.css</span> to the local theme as described above.
===Create new theme options===
#Copy the contents of <span style="color: #BA2121;">/themes/survey/bootswatch/options/</span> to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/</span>.
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/options.twig</span> in an editor and find "{# Bootstrap Bootswatch theme #}". Directly before its parent <nowiki><div class='row'></nowiki> element, add this:<syntaxhighlight lang="html" enclose="div">
{# Custom survey name in navbar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div>


{# Custom survey name below progress bar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div></syntaxhighlight>
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/config.xml</span> and add two items to the "options" block so it looks like this:<syntaxhighlight lang="xml" enclose="div"> <options>
<ajaxmode>on</ajaxmode>
...
<surveyname1>on</surveyname1>
<surveyname2>on</surveyname2>
</options></syntaxhighlight>
#This should give you two new options in the Theme Options screen like this:<br />[[File:Tutorial_tp_1_1.png]]

===Modifed view for Survey Title in the navbar=== 
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/header/</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> and find "{# Logo option #}". Under that, modify the IF statement for the logo/survey-name, so it looks like this:<syntaxhighlight lang="html" enclose="div">
{# Logo option #}
{% if( aSurveyInfo.options.brandlogo == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }} logo-container" {{ aSurveyInfo.attr.navbarbrand }} >
{{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
</div>
{% endif %}
{% if( aSurveyInfo.options.surveyname1 == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }}" {{ aSurveyInfo.attr.navbarbrand }} >
{{ aSurveyInfo.name }}
</div>
{% endif %}</syntaxhighlight>
#Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60px;
font-size: 32px;
}</syntaxhighlight>
#Toggle the "Survey name in navbar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_2.png]]
===Modifed view for Survey Title under progress bar===
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> and add an <nowiki><h1></nowiki> element for the survey name. So it looks like this:<syntaxhighlight lang="html" enclose="div"><div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>

{# Custom survey name #}
{% if( aSurveyInfo.options.surveyname2 == "on") %}
<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
{% endif %}

{# Group Name #}
{{ include('./subviews/survey/group_subviews/group_name.twig') }}

{# Group Description #}
{{ include('./subviews/survey/group_subviews/group_desc.twig') }}

{#
PRESENT THE QUESTIONS

This is the main part. It will render each question for this group
#}


{% for aQuestion in aGroup.aQuestions %}
{{ include('./subviews/survey/question_container.twig') }}
{% endfor %}


{% if aGroup.show_last_group == true %}
<input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
{% endif %}

{% if aGroup.show_last_answer == true %}
<input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
{% endif %}
</div></syntaxhighlight>
# Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60ph1.custom-survey-name {
margin: 0;
text-align: center;
}</syntaxhighlight>
#Toggle the "Survey name below progress bar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_3.png]]

===Downloads=== 
* Sample extended theme: [[Media:Test_survey_names.zip]]

=Creating a theme from scratch= 
Documentation coming soon.

For now, just giving few tips.

==theme structure==

=== Files and directories ===
When you create a Theme from scratch, you don't need to respect the file/directory structure/css/js from Vanilla.
The mandatory css/js is added by core (you can still remove it if needed)

The only files your theme must have are the layout files:

* '''layout_global.twig''' : render the pages for survey taking
* '''layout_survey_list.twig''' : render the survey list (if this theme is set as default)
* '''layout_errors.twig''' : used to render errors that block survey rendering. ( wrong survey id, empty group in preview group, etc.)
* '''layout_user_forms.twig''': renders the user forms such as: token (survey participant), and register.
* '''layout_print.twig''' : used to print the survey to pdf
* '''layout_printanswers.twig''': print the answers

The content of those files, the files they include or not, is entirely up to you.
All the other files and directories that you find on Vanilla are purely optional, feel free to organize your code the way you want.

<div class="simplebox">[[File:help.png]] If you read the frontend rendering code, you'll see that those files names appear directly in it. That's why they are mandatory.
Eg: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/helpers/SurveyRuntimeHelper.php#L462
</div>

=== Content ===

In Vanilla's layout_global.twig, you'll see we use a variable called "include_content" to decide what to show
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/layout_global.twig#L114-L115

<syntaxhighlight lang="php" enclose="div">
{% set sViewContent = './subviews/content/' ~ aSurveyInfo.include_content ~ '.twig' %}
{% include './subviews/content/outerframe.twig' with {'include_content': sViewContent } %}
</syntaxhighlight>

aSurveyInfo.include_content tell you what action is currently going on: showing questions? showing submit result? showing clear all? etc
As you can see, in vanilla, we create one file to include by action. So if you want to know the list of actions, just check the vanilla's directory '''views/subviews/content''', and remove the "twig" extension :
https://github.com/LimeSurvey/LimeSurvey/tree/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/subviews/content

* '''clearall.twig'''
* '''firstpage.twig'''
* '''load.twig'''
* '''mainrow.twig'''
* '''main.twig'''
* '''optin.twig'''
* '''optout.twig'''
* '''outerframe.twig'''
* '''printanswers.twig'''
* '''quotas.twig'''
* '''register.twig'''
* '''save.twig'''
* '''submit_preview.twig'''
* '''submit.twig'''
* '''userforms.twig'''

If you already created a them for 2.x versions of LimeSurvey, you'll notice that most of them corresponds to the old pstpl files for limesurvey 2.x.
Again, there is no obligation for you in your theme to create those files, with those names, in this directory. You could for example just add a giant switch in layout_global.twig with the wanted HTML for each action.

=== Some notes ===


'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.


'''NOTE''': to avoid that, you can force the use to the XML rather than DB. In config.php turn debug mode on and uncommment:


'force_xmlsettings_for_survey_rendering' => true, // Uncomment if you want to force the use of the XML file rather than DB (for easy theme development)


Becareful: everything will be loaded from the XML (included options, etc)


'''NOTE''': if you manually edit the CSS/JS files (without using the Theme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache".


'''NOTE''': if you remove the section

</translate>

New Template System in LS3.x

2018-08-13T10:46:06Z

LouisGac:

<languages />
<translate>

__TOC__
=Introduction= 


On this page you'll learn how to:


* Use the new theme system of LimeSurvey 3.0.
* Use inheritance to manage your own themes.
* Add a picture to your theme
* Manage theme options for your surveys and survey groups


<hr/>


LimeSurvey 3 introduces a complete new theme engine system, based on Twig 1.29, Bootstrap, and allowing theme inheritance and theme options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old theme system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A theme designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new theme engine.


<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Theme Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface= 
==theme list==
On the admin dashboard, there is now a box to access the theme list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The theme list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the theme: it’s just a picture file called “preview.png” at the root of the theme
* the “title” of the theme as specified in the manifest (config.xml in the root of the theme)
* the description of the theme: a string set in its manifest
* the type of theme: Core theme (provided with LimeSurvey), User theme (added in upload directory), XML theme (not loaded in database)
* Extends: if the theme extends another theme, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a theme to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a theme in the database
** Theme editor: it will redirect you to the theme editor
** Theme option: it will lead you the global configuration of theme options

==Theme Editor== 
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' theme'']]

====A quick overview of the concept of theme inheritance==== 


In LS3, a theme can now inherit from another theme, it can “extend” another theme. This means that the theme directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of themes for your different users without having to maintain a lot of different themes. For example: you can have your own home-made theme, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom theme, all the themes that inherit from it will be updated automatically. Note that the inheritance is recursive: a theme can extend a theme that extends another one etc.


<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core themes of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface==== 


To extend the Monochrome theme of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome theme. Then, click on “extend” and validate the new name “extends_monochrome”.


If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/themes/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this theme as a normal one from a survey and it will look exactly like the monochrome theme.


[[File:Extends monochrome empty.jpg|center|baseline|border|''The theme tree (directory and files) just after its creation. It's practically empty'']]


<div class="simplebox">[[File:help.png]] The resources (jpg, png etc.) from the original theme are copied when extending a theme. This is because if you copy a CSS file from the original theme locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current theme path. </div>


The theme editor for the extends_monochrome theme looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome theme'']]
<br /><br />
There is no big difference with the old theme editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the theme directory and that the file from the original theme will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to theme views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local theme and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ==== 


The button '''Copy to local theme and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the theme you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button'']]
<br>
If you open a file explorer and go to the directory upload/themes/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your theme'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).


<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the theme to find the image. If the theme you’re working on is extended to another theme, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local theme, it will loop through the theme inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your theme. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/


<div class="simplebox">
So, to add a picture to your theme:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''


* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}


* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list==== 
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which theme the current one extends (if any)

==Template options== 
Another novelty of LS3 is the theme option page. As we’ll see later, theme creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the theme options at global level: click on “theme options” in the theme list
===Advanced options===


{{QS:Theme editor - advanced options}}

===Simple options=== 


The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the theme's /options directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options (Broken link)
<div class="simplebox">[[File:help.png]] This page can be completely different from a theme to another, and theme providers are strongly encouraged to create their own look & feel. </div>


[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from


{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core themes:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a theme provider could add his own animation library or no animation library at all.


<div class="simplebox">[[File:help.png]] The monochrome themes use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for theme providers.</div>

===Inheritance system=== 


In the previous part, we’ve seen that a theme can extend another theme. A theme configuration can also inherit from another theme configuration. It means that for a given theme, you can have a configuration at


* global level (the one we’ve just seen accessible from the theme list)
* at survey group level
* a last one at survey level.


Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

====At survey group level==== 


Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of themes than in the theme list, except that here only the option button is visible (theme editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]


<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

====At survey level==== 
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example== 
Let’s say you’re using a single theme for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core theme. But of course, if you are a theme provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization = 


You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS/JS: deal with the asset manager ("why are my changes not applied?") == 
<br />


If you're trying to update the CSS/JS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.


<br />


Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />


It moves the CSS/JS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css/js file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css/js. Else, they would have to clean their browser cache.


<br />


Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.


<br />


Here the CSS links in header when asset manager is off:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.


<br />


<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>


So, when you're editing CSS/JS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache


[[File:Clearassets-ls3 3.png]]


<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>


Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme == 
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how it works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css


<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>


Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>


You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font === 
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>


You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.


Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options === 
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>


* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %} //Shouldn't this be "theme" in stead of "template"?
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>


<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector === 
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">


'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}


</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79


<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>


Of course, the XML file only contains the default values for your theme configuration. But indeed, those values are defined and read inside the database (table "template_configuration" (Question: "template_" of "theme_"?) as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174


So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

== Adding theme options to control positioning and display of survey elements == 
This tutorial will show how to add options to an extended theme to display survey elements in various locations. In this case, we will create theme options to show the survey title in two different locations.
<div class="simplebox">[[File:help.png]] For the sake of simplicity, we will base the tutorial on an extension of the "bootswatch" theme in LimeSurvey version 3.4.3.</div>
=== Create a custom theme ===
#Extend the "bootswatch" theme as described above.
#Copy <span style="color: #BA2121;">custom.css</span> to the local theme as described above.
===Create new theme options===
#Copy the contents of <span style="color: #BA2121;">/themes/survey/bootswatch/options/</span> to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/</span>.
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/options.twig</span> in an editor and find "{# Bootstrap Bootswatch theme #}". Directly before its parent <nowiki><div class='row'></nowiki> element, add this:<syntaxhighlight lang="html" enclose="div">
{# Custom survey name in navbar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div>


{# Custom survey name below progress bar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div></syntaxhighlight>
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/config.xml</span> and add two items to the "options" block so it looks like this:<syntaxhighlight lang="xml" enclose="div"> <options>
<ajaxmode>on</ajaxmode>
...
<surveyname1>on</surveyname1>
<surveyname2>on</surveyname2>
</options></syntaxhighlight>
#This should give you two new options in the Theme Options screen like this:<br />[[File:Tutorial_tp_1_1.png]]

===Modifed view for Survey Title in the navbar=== 
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/header/</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> and find "{# Logo option #}". Under that, modify the IF statement for the logo/survey-name, so it looks like this:<syntaxhighlight lang="html" enclose="div">
{# Logo option #}
{% if( aSurveyInfo.options.brandlogo == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }} logo-container" {{ aSurveyInfo.attr.navbarbrand }} >
{{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
</div>
{% endif %}
{% if( aSurveyInfo.options.surveyname1 == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }}" {{ aSurveyInfo.attr.navbarbrand }} >
{{ aSurveyInfo.name }}
</div>
{% endif %}</syntaxhighlight>
#Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60px;
font-size: 32px;
}</syntaxhighlight>
#Toggle the "Survey name in navbar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_2.png]]
===Modifed view for Survey Title under progress bar===
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> and add an <nowiki><h1></nowiki> element for the survey name. So it looks like this:<syntaxhighlight lang="html" enclose="div"><div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>

{# Custom survey name #}
{% if( aSurveyInfo.options.surveyname2 == "on") %}
<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
{% endif %}

{# Group Name #}
{{ include('./subviews/survey/group_subviews/group_name.twig') }}

{# Group Description #}
{{ include('./subviews/survey/group_subviews/group_desc.twig') }}

{#
PRESENT THE QUESTIONS

This is the main part. It will render each question for this group
#}


{% for aQuestion in aGroup.aQuestions %}
{{ include('./subviews/survey/question_container.twig') }}
{% endfor %}


{% if aGroup.show_last_group == true %}
<input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
{% endif %}

{% if aGroup.show_last_answer == true %}
<input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
{% endif %}
</div></syntaxhighlight>
# Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60ph1.custom-survey-name {
margin: 0;
text-align: center;
}</syntaxhighlight>
#Toggle the "Survey name below progress bar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_3.png]]

===Downloads=== 
* Sample extended theme: [[Media:Test_survey_names.zip]]

=Creating a theme from scratch= 
Documentation coming soon.

For now, just giving few tips.

==theme structure==

=== Files and directories ===
When you create a Theme from scratch, you don't need to respect the file/directory structure/css/js from Vanilla.
The mandatory css/js is added by core (you can still remove it if needed)

The only files your theme must have are the layout files:

* '''layout_global.twig''' : render the pages for survey taking
* '''layout_survey_list.twig''' : render the survey list (if this theme is set as default)
* '''layout_errors.twig''' : used to render errors that block survey rendering. ( wrong survey id, empty group in preview group, etc.)
* '''layout_user_forms.twig''': renders the user forms such as: token (survey participant), and register.
* '''layout_print.twig''' : used to print the survey to pdf
* '''layout_printanswers.twig''': print the answers

The content of those files, the files they include or not, is entirely up to you.
All the other files and directories that you find on Vanilla are purely optional, feel free to organize your code the way you want.

<div class="simplebox">[[File:help.png]] If you read the frontend rendering code, you'll see that those files names appear directly in it. That's why they are mandatory.
Eg: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/helpers/SurveyRuntimeHelper.php#L462
</div>

=== Content ===

In Vanilla's layout_global.twig, you'll see we use a variable called "include_content" to decide what to show
https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/layout_global.twig#L114-L115

<syntaxhighlight lang="php" enclose="div">
{% set sViewContent = './subviews/content/' ~ aSurveyInfo.include_content ~ '.twig' %}
{% include './subviews/content/outerframe.twig' with {'include_content': sViewContent } %}
</syntaxhighlight>


'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.


'''NOTE''': to avoid that, you can force the use to the XML rather than DB. In config.php turn debug mode on and uncommment:


'force_xmlsettings_for_survey_rendering' => true, // Uncomment if you want to force the use of the XML file rather than DB (for easy theme development)


Becareful: everything will be loaded from the XML (included options, etc)


'''NOTE''': if you manually edit the CSS/JS files (without using the Theme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache".


'''NOTE''': if you remove the section

</translate>

New Template System in LS3.x

2018-04-09T08:12:42Z

LouisGac:

<languages />
<translate>

__TOC__
=Introduction= 


On this page you'll learn how to:


* Use the new template system of LimeSurvey 3.0.
* Use inheritance to manage your own templates.
* Add a picture to your template
* Manage template options for your surveys and survey groups


<hr/>


LimeSurvey 3 introduces a complete new template engine system, based on Twig 1.29, Bootstrap, and allowing template inheritance and template options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old template system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A template designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new template engine.


<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Template Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface= 
==Template list==
On the admin dashboard, there is now a box to access the template list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The template list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the template: it’s just a picture file called “preview.png” at the root of the template
* the “name” of the template: the directory name of the template. Before we release the LS3 master, it will become the template “Title” (can be different from directory name, and it can contain special cgunnarhars)
* the description of the template: a string set in its manifest
* the type of template: Core template (provided with LimeSurvey), User template (added in upload directory), XML template (not loaded in database)
* Extends: if the template extends another template, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a template to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a template in the database
** Template editor: it will redirect you to the template editor
** Template option: it will lead you the global configuration of template options

==Template Editor== 
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' template'']]

====A quick overview of the concept of template inheritance==== 


In LS3, a template can now inherit from another template, it can “extend” another template. This means that the template directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of templates for your different users without having to maintain a lot of different templates. For example: you can have your own home-made template, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom template, all the templates that inherit from it will be updated automatically. Note that the inheritance is recursive: a template can extend a template that extends another one etc.


<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core templates of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface==== 


To extend the Monochrome template of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome template. Then, click on “extend” and validate the new name “extends_monochrome”.


If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/templates/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this template as a normal one from a survey and it will look exactly like the monochrome template.


[[File:Extends monochrome empty.jpg|center|baseline|border|''The template tree (directory and files) just after its creation. It's practically empty'']]


<div class="simplebox">[[File:help.png]] The resources (jpg, png etc.) from the original template are copied when extending a template. This is because if you copy a CSS file from the original template locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current template path. </div>


The template editor for the extends_monochrome template looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome template'']]
<br /><br />
There is no big difference with the old template editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the template directory and that the file from the original template will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to template views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local template and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ==== 


The button '''Copy to local template and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the template you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button'']]
<br>
If you open a file explorer and go to the directory upload/templates/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your template'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).


<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the template to find the image. If the template you’re working on is extended to another template, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local template, it will loop through the template inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your template. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/


<div class="simplebox">
So, to add a picture to your template:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''


* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}


* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list==== 
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which template the current one extends (if any)

==Template options== 
Another novelty of LS3 is the template option page. As we’ll see later, template creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the template options at global level: click on “template options” in the template list
===Advanced options===


{{QS:Theme editor - advanced options}}

===Simple options=== 


The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the template/options/ directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options
<div class="simplebox">[[File:help.png]] This page can be completely different from a template to another, and template providers are strongly encouraged to create their own look & feel. </div>


[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from


{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core templates:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a template provider could add his own animation library or no animation library at all.


<div class="simplebox">[[File:help.png]] The monochrome templates use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for template providers.</div>

===Inheritance system=== 


In the previous part, we’ve seen that a template can extend another template. A template configuration can also inherit from another template configuration. It means that for a given template, you can have a configuration at


* global level (the one we’ve just seen accessible from the template list)
* at survey group level
* a last one at survey level.


Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

====At survey group level==== 


Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of templates than in the template list, except that here only the option button is visible (template editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]


<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

====At survey level==== 
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example== 
Let’s say you’re using a single template for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core template. But of course, if you are a template provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization = 


You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS/JS: deal with the asset manager ("why my changes are not applied?") == 
<br />


If you're trying to update the CSS/JS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.


<br />


Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />


It moves the CSS/JS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css/js file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css/js. Else, they would have to clean their browser cache.


<br />


Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.


<br />


Here the CSS links in header when asset manager is off:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.


<br />


<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>


So, when you're editing CSS/JS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache


[[File:Clearassets-ls3 3.png]]


<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>


Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme == 
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how ti works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css


<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>


Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>


You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font === 
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>


You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.


Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options === 
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>


* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %}
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>


<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector === 
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">


'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}


</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79


<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>


Of course, the XML file only contains the default values for your template configuration. But indeed, those values are defined and read inside the database (table "template_configuration") as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174


So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

== Adding theme options to control positioning and display of survey elements == 
This tutorial will show how to add options to an extended theme to display survey elements in various locations. In this case, we will create theme options to show the survey title in two different locations.
<div class="simplebox">[[File:help.png]] For the sake of simplicity, we will base the tutorial on an extension of the "bootswatch" theme in LimeSurvey version 3.4.3.</div>
=== Create a custom theme ===
#Extend the "bootswatch" theme as described above.
#Copy <span style="color: #BA2121;">custom.css</span> to the local template as described above.
===Create new template options===
#Copy the contents of <span style="color: #BA2121;">/themes/survey/bootswatch/options/</span> to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/</span>.
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/options/options.twig</span> in an editor and find "{# Bootstrap Bootswatch theme #}". Directly before its parent <nowiki><div class='row'></nowiki> element, add this:<syntaxhighlight lang="html" enclose="div">
{# Custom survey name in navbar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div>


{# Custom survey name below progress bar #}
<div class='row'>
<div class='col-sm-12 col-md-6'>


<div class='form-group row'>
<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
<div class='col-sm-12'>
<div class="btn-group" data-toggle="buttons">
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
Yes
</label>
<label class="btn btn-default">
<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
No
</label>
</div>
</div>
</div>
</div>
</div>
<div class='row'>
<hr/>
</div></syntaxhighlight>
#Open <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/config.xml</span> and add two items to the "options" block so it looks like this:<syntaxhighlight lang="xml" enclose="div"> <options>
<ajaxmode>on</ajaxmode>
...
<surveyname1>on</surveyname1>
<surveyname2>on</surveyname2>
</options></syntaxhighlight>
#This should give you two new options in the Theme Options screen like this:<br />[[File:Tutorial_tp_1_1.png]]

===Modifed view for Survey Title in the navbar=== 
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/header/</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/header/nav_bar.twig</span> and find "{# Logo option #}". Under that, modify the IF statement for the logo/survey-name, so it looks like this:<syntaxhighlight lang="html" enclose="div">
{# Logo option #}
{% if( aSurveyInfo.options.brandlogo == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }} logo-container" {{ aSurveyInfo.attr.navbarbrand }} >
{{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
</div>
{% endif %}
{% if( aSurveyInfo.options.surveyname1 == "on") %}
<div class="{{ aSurveyInfo.class.navbarbrand }}" {{ aSurveyInfo.attr.navbarbrand }} >
{{ aSurveyInfo.name }}
</div>
{% endif %}</syntaxhighlight>
#Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60px;
font-size: 32px;
}</syntaxhighlight>
#Toggle the "Survey name in navbar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_2.png]]
===Modifed view for Survey Title under progress bar===
#Create a new directory <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews</span>.
#Copy <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> to that new directory.
#Open <span style="color: #BA2121;">/themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig</span> and add an <nowiki><h1></nowiki> element for the survey name. So it looks like this:<syntaxhighlight lang="html" enclose="div"><div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>

{# Custom survey name #}
{% if( aSurveyInfo.options.surveyname2 == "on") %}
<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
{% endif %}

{# Group Name #}
{{ include('./subviews/survey/group_subviews/group_name.twig') }}

{# Group Description #}
{{ include('./subviews/survey/group_subviews/group_desc.twig') }}

{#
PRESENT THE QUESTIONS

This is the main part. It will render each question for this group
#}


{% for aQuestion in aGroup.aQuestions %}
{{ include('./subviews/survey/question_container.twig') }}
{% endfor %}


{% if aGroup.show_last_group == true %}
<input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
{% endif %}

{% if aGroup.show_last_answer == true %}
<input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
{% endif %}
</div></syntaxhighlight>
# Add something like this to <span style="color: #BA2121;">/upload/themes/survey/yourThemeName/css/custom.css</span>:<syntaxhighlight lang="css" enclose="div">.navbar-brand {
line-height: 60ph1.custom-survey-name {
margin: 0;
text-align: center;
}</syntaxhighlight>
#Toggle the "Survey name below progress bar" theme option to "Yes"
#You should see this:<br />[[File:Tutorial_tp_1_3.png]]

===Downloads=== 
* Sample extended theme: [[Media:Test_survey_names.zip]]

=Creating a template from scratch= 
Documentation coming soon...


'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.


'''NOTE''': to avoid that, you can force the use to the XML rather than DB. In config.php turn debug mode on and uncommment:


'force_xmlsettings_for_survey_rendering' => true, // Uncomment if you want to force the use of the XML file rather than DB (for easy theme development)


Becareful: everything will be loaded from the XML (included options, etc)


'''NOTE''': if you manually edit the CSS/JS files (without using the Teeme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache:"

</translate>

Theme editor

2018-04-04T11:05:39Z

LouisGac:

<languages /> <translate>

=Introduction= 


LimeSurvey has an advanced theme and style system providing to developers an efficient way to customize the survey appearance. Since LS3, we're not speaking anymore about '''"templates"''' like in previous versions, but about '''"themes"'''. The '''themes''' allow control over the look and feel of pages during a survey. A survey administrator can select a default theme that will be used for each survey to further personalize it and improve its look and feel. '''Themes''' come with options that provide to admin without coding skill a simple way to add a logo on the welcome page, to change the background colors, to select a font, etc.


LimeSurvey comes with 3 themes right out of the box. These initial themes are defined by directories located in the LimeSurvey installation "themes/survey/" directory. Each theme has it's own directory. Within the main directory of a theme you'll find a configuration file in XML, and numerous directories containing the views ''themes (.twig)''', '''cascading style sheets (.css)''', '''scripts''', '''images''' ('''.jpg''' or '''.png'''), and maybe others.


Since LimeSurvey 2.50, the theme engine use [http://getbootstrap.com/docs/3.3/ Bootstrap 3] as CSS framework. Bootstrap 3 being a standard framework, developers will find a lot of documentation, tutorials and forum threads about it on Internet.

Since LimeSurvey 3, the theme engine use [https://twig.symfony.com Twig], so the theme developers can change the logic of the survey rendering in a safe and easy way. Twig replace the old system of replacement keywords that was used in the previous versions. The logic that was used to generate the HTML of the keywords are now available inside the theme's views.

Snippet from Vanilla Theme:


<syntaxhighlight lang="twig" enclose="div">
<div class="{{ aSurveyInfo.class.answercontainer }} col-xs-12" {{ aSurveyInfo.attr.answercontainer }}>
{# NOTE: If you want to customize the question rendering, use a question theme #}
{{ aQuestion.answer | raw }}
</div>
</syntaxhighlight>


Themes, being HTML and Twig code, tend to define the positioning and type of text to be displayed and similar structural features of the page. They often reference or include other files. Most of them reference a common cascading style sheets (CSS) file that defines the font style, color, size, background, and similar parameters common to all pages in the survey. Style sheets reference HTML '''class''' parameters that are associated with the various types of objects in the HTML code. This allows the style sheet to describe how to display each of the many types of text or other objects that may appear in multiple places. There are unique classes for each question type in LimeSurvey and thus giving detailed control over the appearance of each. Image files, like logos or special progress-bar constructors, may be referenced as well in the Theme file. Finally, special keywords in curly braces are replaced with text defined in the survey for each language translation correspondent (for example, the 'Survey Title' or 'Question Text' for each language defined).


If you create a new custom theme, please consider contributing it back to the LimeSurvey community and make it available to others. With your help, we can grow our repository of themes, surveys, and other add-ons to make LimeSurvey even better!
See our [https://www.limesurvey.org/index.php?option=com_sobipro&sid=55:Templates&Itemid=729 LimeSurvey template repository] where you can share your templates.

=Creating a new theme= 


To be able to create a new theme (or edit an existing theme), you need [[Manage users#Set global permissions for a user|Template Editing user permission]] in LimeSurvey as well as permission to manipulate the files in the underlying operating system hosting your LimeSurvey installation.


<div class="simplebox"><span style='color:red'>'''Note of Warning:'''</span> If you change themes, you could also affect all the pre-existing surveys from your LimeSurvey installation. Themes are an advanced feature that require experience and HTML knowledge in order to make them running smoothly.</div>


The preferred way to create a new theme is through the '''Theme Editor''' (see below), which is located in the '''Configuration''' dialog. Some people may like to work directly with theme files so that they can use their favorite text editor instead of the web interface. In this case, still use the Theme Editor to first create your new theme. This will create a new base theme with all the files you need in the ''LimeSurvey_web_root/upload/themes/survey/your_new_template'' directory. From there you can use your text editor to manually adjust the template files.


<div class="simplebox">'''Permissions Note:''' on unix/linux systems, these theme files will be owned by the group and user where the web server is running (may be "www" for some systems). So, make sure you have enough access to edit these files, When you save them, make sure they don't change ownership! In this way, you can still use the web Theme Editing interface if needed.</div><br />


A number of 'public' elements of LimeSurvey can be adjusted by a series of themes. The next section provides a very brief explanation of these templates.


{{Note|Themes files may seem complex. Besides HTML, you might also need to understand CSS, Twig, and JavaScript.}}

=The LimeSurvey Theme editor= 


To ease the understanding and quick update of a Theme, LimeSurvey provides a '''Theme Editor''' in the main '''administrative''' toolbar of the application. This Theme Editor is only available to users [[Manage users#Set global permissions for a user|with the Templates permission]] and to superadministrators.


{{Alert|title=Attention|text=A theme that is not correctly constructed can make a survey (that uses the respective template) inoperable. }}


The LimeSurvey theme editor allows you to edit the contents of your themes online. To start the Theme Editor: click on '''Themes''' link in the '''Configuration''' menu, and then click on the "Theme editor" button next of the theme you want to edit or extend.


[[File:Themes menu.png]]
[[File:Theme editor button.png|''The button to access the theme editor for Bootswatch theme'']]


The template editor page allows you to select the template you would like to edit/view.


[[File:Template-editor-2013-7-10_11_38_16.png|center]]


The following options are available:


*'''Create''': Allows you to create a new template. In order not to start from scratch, the template 'default' is copied.
*'''Import''': Allows you to import a template from a ZIP file.
*'''Export''': Allows you to export the current template to a ZIP file.
*'''Copy''': Allows you to make a new template by copying the current one.
*'''Rename''': Allows you to change the name of the template. It is generally used after copying or importing a template.
*'''Template''': It is a drop-down list that shows all the available templates that are located in your LimeSurvey installation.


*'''Screen''': It is a drop-down list which allows you to choose which particular survey page of that template you want to look at.
*'''Return to admin panel'''.

==Import/export/copy a template== 


When you '''export '''a template, a ZIP-file archive with all the files your template consists of will be created (.pstpl files, images, css files, ...). You can simply '''import''' the exported zip-file into another LimeSurvey installation by using the import feature or you can manually copy the archive into another LimeSurvey installation and extract it into the corresponding [[Theme editor#Template files location|template directory there]].


However, it is preferred to use the LimeSurvey template import/export/copy functions in the template editor.

==Page Structure / Template Use== 
*'''The Welcome Page:''' startpage.pstpl, welcome.pstpl, privacy.pstpl, navigator.pstpl, endpage.pstpl
*'''The Questions Pages:''' startpage.pstpl, survey.pstpl, startgroup.pstpl, groupdescription.pstpl, question.pstpl, endgroup.pstpl, endpage.pstpl
*'''The Final Page:''' startpage.pstpl, assessment.pstpl, completed.pstpl, endpage.pstpl

==Template Files== 


The following template files are used to produce your public survey and must exist in any new template folder you create:
*'''startpage.pstpl:''' Produces the start of each html page. It starts at the "<head>" tag, and should not contain the "<html>" tag. This 'very beginning' of a standard html page is written by the scripts. Please ensure that your startpage.pstpl files contains a <body> tag. Even though many browsers do not require strict adherence to the W3 HTML standards, the LimeSurvey script needs to find a <body> tag to run certain javascript elements. It is not expected to see many 'keywords' used in the startpage.pstpl file. However, you may wish to put the {SURVEYNAME} into the title. The startpage.pstpl file can contain code that ends in the corresponding endpage.pstpl file. For example, you can start a table in this file and close the table in the endpage.pstpl file. The startpage.pstpl and endpage.pstpl files wrap around every possible page used by LimeSurvey.
*'''survey.pstpl:''' This template is the second used on most pages and provides a space to put the survey name and description. This template does not have a corresponding 'closing' template, and subsequently you should close all tags opened in this template file (i.e.: don't leave a table open here because there is nowhere else to close it).
*'''welcome.pstpl:''' This template is only used in the welcome screen (which is also on the main page for 'all in one' surveys). You can use this to print out the welcome text, and other information that should be provided in the introduction. Like the 'survey.pstpl' file, there is no corresponding 'closing' template, so all tags opened in this template file should be closed as well.
*'''startgroup.pstpl:''' This template can provide a 'summary' wrap around for questions within a group. It has a matching 'endgroup.pstpl' template that can be used to close any opened tags in this file, so you can open a table within this.
*'''groupdescription.pstpl:''' This template file is used to display a description of a group. Please note that in the survey settings (access the ''Presentation & navigation settings'' by clicking on the '''Presentation''' tab) you can set if the group description should be shown or not. If not, then this file is not included at all.
*'''question.pstpl:''' This file contains the question, answer, and help text sections of your survey. In the "group by group" and "all in one" surveys, this template is cycled repeatedly with each question. There is no corresponding closing file for this and all tags should be closed.
*'''question_start.pstpl:''' This file contains the individual elements found at the start of a question. It is included within 'question.pstpl' via the {QUESTION} keyword. It is intended to allow template designers more control over the layout of a question. This template sits outside the normal templating system and '''was superseeded (as of LimeSurvey 1.87)'''. All keywords from this template are now available directly in question.pstpl.
*'''completed.pstpl:''' This page is displayed as the final page when the survey responses have been saved and the survey is over. It can be used to display a "forwarding link" as set in the survey setup.
*'''endgroup.pstpl:''' This file closes the group, and can be used to close off any tags opened in the startgroup.pstpl file
*'''navigator.pstpl:''' This file contains the buttons that navigate through the survey, "next", "prev", "last", "submit", "save so far" and the "clear all" link. It is used in all pages except the completed page.
*'''printanswers.pstpl:''' This file has the HTML wrapper necessary for the print version of the survey.
*'''print_group.pstpl:''' This file is the same as startgroup.pstpl and endgroup.pstpl, but for the print version of the survey.
*'''print_question.pstpl:''' This file is the same as question.pstpl, but for the print version of the survey.
*'''print_survey.pstpl:''' This file is the same as survey.pstpl, but for the print version of the survey.

== CSS and Javascript== 


Two files that are always used in a template are template.css (for CSS) and template.js (for Javascript).
*'''{TEMPLATECSS}:''' Add lines for default css, template.css, and template-rtl.css for rtl language.
*'''{TEMPLATEJS}:''' Add lines for default javascript files, template.js, and all js files needed for LimeSurvey.

=== Using Bootstrap=== 
LimeSurvey has Bootstrap 3 embedded, so you can style all your templates with the well documented Bootstrap classes.
For more information please refer to the [https://getbootstrap.com Bootstrap documentation].


The [https://github.com/flatlogic/awesome-bootstrap-checkbox Awesome-Bootstrap-Checkbox] plugin is also included. With it, you can use the typical Bootstrap color-classes (info,warning,danger,etc.) also with the suffix "-checkbox" or "-radio", though styling checkboxes and radios as you prefer.

=== Replacing default CSS or Javascript=== 


Some questions use specific files for Javascript or CSS. If you need to replace a function, use a cascading system. For javascript function, the last function read is the function used.

==Other Template Files== 


The '''privacy.pstpl''', '''invitationemail.pstpl''', '''reminderemail.pstpl''', and '''confirmationemail.pstpl''' are no longer used by LimeSurvey and defaults are instead set in the applicable language files. The email messages can now be edited on a survey by survey basis.

==Standard Pages== 


There are ten standard pages that a survey participant may see in the course of taking or accessing the LimeSurvey application. Each is constructed from a number of common '''Template''' files from the '''Template''' specified in the settings of the survey. The table below indicates which template files are used in constructing each of these pages.


{| class="wikitable"
! '''Survey Pages/'''<br />'''Template Files'''!!Survey<br />List!!Welcome!!Question!!Completed!!Clear All!!Register!!Load!!Save!!Print<br />Answers!!Print<br />Survey
|-
|SurveyList||align="center" | [[File:check.gif]]|| || || || || || || || ||
|-
|Welcome|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Privacy|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Navigator|| ||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Survey|| || ||align="center" | [[File:check.gif]]|| || ||align="center" | [[File:check.gif]]|| || || ||
|-
|StartGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|GroupDescription|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Question<span style='color:red'>'''*'''</span>|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|EndGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Assessment|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|Completed|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|ClearAll|| || || || ||align="center" | [[File:check.gif]]|| || || || ||
|-
|Register|| || || || || ||align="center" | [[File:check.gif]]|| || || ||
|-
|Load|| || || || || || ||align="center" | [[File:check.gif]]|| || ||
|-
|Save|| || || || || || || ||align="center" | [[File:check.gif]]|| ||
|-
|PrintAnswers|| || || || || || || || ||align="center" | [[File:check.gif]]||
|-
|Print Survey || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Group || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Question || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|StartPage<br />EndPage<br />Template.css||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||
|}


<span style='color:red'>'''*'''</span>NOTE: In version 1.90+, this replaces question.pstpl AND question_start.pstpl. If you are using an old custom template, you need to add the following line to the beginning of question.pstpl:<syntaxhighlight lang="php" enclose="div"><div {QUESTION_ESSENTIALS} class="{QUESTION_CLASS}{QUESTION_MAN_CLASS}{QUESTION_INPUT_ERROR_CLASS}"></syntaxhighlight>And then add the corresponding closing tag to the end of question.pstpl:<syntaxhighlight lang="php" enclose="div"></div></syntaxhighlight>


<span style='color:red'>'''*'''</span>NOTE: In version 1.91 and earlier, LimeSurvey js files are not included in the template. In version 2, '''you have to use {TEMPLATEJS} in one of your template file''' to add the link to the js file. You can add it in startpage.pstpl or in endpage.pstpl. You can remove the {TEMPLATEURL}/template.js line and you have to replace with {TEMPLATEJS} to update a personal template.

==The File Control Section== 


In the "file control" window on the left, you can click on one of the template files that is used to compile the page. You can see the ''Screen part'', JavaScript, and CSS files. The HTML code for that file will then appear in the "Now editing" window in the center. If the template is editable (determined by directory permissions) you can then make any changes and save them.


<center>[[File:File Control Section.png|center]]</center>


The "Other files" window shows a list of all other files from the template directory. You can use the right side to '''upload and select image files (your pics, logos,...) or other files needed to create your template'''.


Instead of using a link for each picture, utilize the field string {TEMPLATEURL}. So, instead of:


<syntaxhighlight lang="html4strict" enclose="div">img src='/limesurvey/templates/yourtemplate/files/mypicture.jpg'</syntaxhighlight>
You can use {{NewIn|2.50}}:
<syntaxhighlight lang="html4strict" enclose="div">img src='{TEMPLATEURL}files/mypicture.jpg'</syntaxhighlight>


In LimeSurvey versions before 2.50 use:
<syntaxhighlight lang="html4strict" enclose="div">img src='{TEMPLATEURL}mypicture.jpg'</syntaxhighlight>


A "sample" of the template page you are editing will be visible in the bottom of the screen. There is no way to delete a template from the template editor. This must be done by accessing the underlying directory and deleting manually the files from there. You also have the possibility to select different screen resolutions in order to better evaluate the feel and look of the template.


<div class="simplebox">'''Note:''' The shipped templates cannot be edited using the template editor. If you want to modify them, create a copy first and edit the copy.</div>

==Template files location== 


LimeSurvey stores each of the 'standard' templates in their own distinct sub-directory within the ''/templates'' directory that is kept in the public directory with the other LimeSurvey public files. Customized user templates are stored in the ''/upload/templates'' directory.


There should '''ALWAYS''' be a "default" directory in the templates directory. This template is used by default and as a fall-back if a template folder doesn't exist, or can't be found. It comes installed by default.


You can use any image files that you upload into the template management area with the help of this syntax:


<syntaxhighlight lang="php" enclose="div">{TEMPLATEURL}filename.xyz</syntaxhighlight>

=Styling questions with CSS= 


Styling of questions in CSS has become much easier. Each question type has now a unique class. The mandatory questions have an additional mandatory class. For example, for a non-mandatory question:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender">
...
</div></syntaxhighlight>


and if the question is mandatory:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory">
...
</div></syntaxhighlight>


and if the question is mandatory, but the user didn't answer it or if there is validation on a question:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory input-error">
...
</div></syntaxhighlight>


and if the question has validation applied, but the user hasn't answered correctly:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question6" class="text-short input-error">
...
</div></syntaxhighlight>

==Global classes for question part== 


These classes are used for each question type. Some question types use only one or two classes, while others may use much more.


{| class="wikitable alternance"
|+ Global classes
|-
! scope="col" | Class name
! scope="col" | Part
! scope="col" | Question type
! scope="col" | Examples
! scope="col" | Note
|-
! scope="row" | .question {{ObsoleteIn|3.0}}
| All question block
| All question type
|<p class="question">, <ul class="question">, <table class="question">
|
|-
! scope="row" | .ls-answers {{NewIn|3.0}}
| All question block
| All question type
|<div class="ls-answers ">, <ul class="ls-answers ">, <table class="ls-answers">
|
|-
! scope="row" | .subquestions-list
| List of subquestion
| Multi choice question, array question type
| <ul class="subquestions-list">, <table class="subquestions-list">
| .questions-list is used too
|-
! scope="row" | .answers-list
| List of answers
| Single choice question, array question type, Multi input text question
| <ul class="answers-list">, <table class="answers-list">
|
|-
! scope="row" | .answer-item
| The answer part: one answer
| Single choice question, array question type, Multi input text question
| <li class="answer-item">, <td class="answer-item">
|
|-
! scope="row" | .noanswer-item
| The answer part for no answer
| Single choice question, array question type
| <li class="noanswer-item">, <td class="noanswer-item">
| No answer is an answer too, then have double class noanswer-item and answer-item
|-
! scope="row" | .question-item
| The question part: one question
| Multi text question, array question type
| <li class="question-item">, <tr class="question-item">
| Some answers are questions too. Then we have a lot of class="question-item answer-item"
|-
! scope="row" | .checkbox-list
| A list of checkbox
| Multi choice question, array number (checkbox) question type
| <ul class="checkbox-list">, <tr class="checkbox-list">
| Some question types use multi-list class, like checkbox with comment: class="checkbox-list text-list"
|-
! scope="row" | .checkbox-array {{NewIn|3.0}}
| A array of checkbox
| Array (numbers) with checkbox option
| <table class="checkbox-list">
|
|-
! scope="row" | .checkbox-item
| The answer part with a checkbox
| Multi choice question, array number (checkbox) question type
| <li class="checkbox-item">, <td class="checkbox-item">
|
|-
! scope="row" | .radio-list
| A list of radio item
| Single choice question, array question type (each row)
| <ul class="radio-list">, <tr class="radio-list">
|
|-
! scope="row" | .radio-array {{NewIn|3.0}}
| A array of radio item
| Array question type
| <table class="radio-array">
|
|-
! scope="row" | .radio-item
| The answer part with a radio
| Single choice question, array question type
| <li class="radio-item">, <td class="radio-item">
|
|-
! scope="row" | .text-list
| A list of text input
| Multi text question type, array of text
| <ul class="text-list">, <tr class="text-list">
|
|-
! scope="row" | .text-item
| The answer part of a text input
| Multi text question type, array of text
| <li class="text-item">, <td class="text-item">
|
|-
! scope="row" | .numeric-list
| A list of text input with numeric only answer
| Multi numeric question type, array of number
| <ul class="text-list numeric-list">, <tr class="text-list numeric-list">
|
|-
! scope="row" | .number-list
| A list of text input with numeric only answer (each row)
| Multi numeric question type, array of number
| <ul class="text-list numeric-list">, <tr class="text-list numeric-list">
|
|-
! scope="row" | .number-array {{NewIn|3.0}}
| The answer part of a numeric input
| Array of number
| <table class="number-array">
|
|-
! scope="row" | .select-list {{ObsoleteIn|2.50}}
| A list of select
| Array numbers, Dual scale array (select)
| <table class="select-list">
|
|-
! scope="row" | .dropdown-list {{NewIn|2.50}}
| A list of select
| Array numbers, Dual scale array (select) (each row)
| <table class="dropdown-list">
|
|-
! scope="row" | .dropdown-array {{NewIn|3.0}}
| A array of dropdown
| Array numbers, Dual scale array (select)
| <table class="dropdown-array">
|
|-
! scope="row" | .select-item {{ObsoleteIn|2.50}}
| The answer part of a select
| Array numbers, Dual scale array (select), single choice with select
| <p class="select-item">, <td class="select-item">
|
|-
! scope="row" | .dropdown-item {{NewIn|2.50}}
| The answer part of a select
| Array numbers, Dual scale array (select), single choice with select
| <p class="dropdown-item">, <td class="dropdown-item">
|
|-
! scope="row" | .hide {{ObsoleteIn|3.0}}
| Used for accessibility: hidden with css but read by screenreader, since 2.50 : you can use sr-only from bootstrap
| Short text question
| <label class="hide">
| Can be used for other purposes
|-
! scope="row" | .ls-js-hidden {{NewIn|3.0}}
| Used for part to be hidden if javascript is activated
| Button for example
| <div class="ls-js-hidden">
| LimeSurvey core used it, but you can use it too in your template
|-
! scope="row" | .ls-js-hidden-sr {{NewIn|3.0}}
| Used for accessibility: hide it if js is activated, but always show if user use a screenreader
| Button for example
| <a class="ls-js-hidden-sr">
| Button
|-
! scope="row" | .ls-no-js-hidden {{NewIn|3.0}}
| Used for part to be hidden if javascript is not activated
| Link
| <a class="ls-no-js-hidden">
| LimeSurvey core used it for inactive link if javascript is not activated
|-
! scope="row" | .ls-label-xs-visibility {{NewIn|3.0}}
| Label to be hidden in big screen, but show with little screen (with no more table) and to screenreader
| label
| <label class="ls-no-js-hidden">
| Used for label inside table cell of array question type
|-
! scope="row" | .ls-input-group-extra {{NewIn|3.0}}
| Same usage of boostrap input-group-addon, but without the border and the background.
| right suffix
| <div class="ls-input-group-extra">
| Used for right and left suffix (global)
|-
! scope="row" | .checkbox {{ObsoleteIn|3.0}}
| input[type=checkbox]
| Question with checkbox
| <input type="checkbox" class="checkbox">
| With modern browser: not needed, but some old browser need this
|-
! scope="row" | .radio {{ObsoleteIn|3.0}}
| input[type=radio]
| Question with radio
| <input type="radio" class="radio">
| With modern browser: not needed, but some old browser need this
|-
! scope="row" | .text
| input[type=text]
| Question with input text, or textarea
| <textarea class="text">
|
|-
! scope="row" | .answertext
| Array question type
| Answer part of array question type
| <th class="answertext">
|
|-
! scope="row" | .col-answers
| Array question type
| Column of answers
| <col class="col-answers">
|
|-
! scope="row" | .odd .even {{ObsoleteIn|2.50}}
| Array question type
| Alternation for column
| <col class="odd">
|
|-
! scope="row" | .array1 .array2 {{ObsoleteIn|3.0}}
| Array question type
| Alternation for line
| <tr class="array1">
|
|-
! scope="row" | .ls-odd .ls-even {{NewIn|3.0}}
| Array question type
| Alternation for sub-question and Y axis
| <tr class="ls-odd">
|
|}

=== Some example of question part with classes=== 


'''Text-short question type:'''
</translate><source lang="html4strict">
<p class="question answer-item text-item ">
<label class="hide label" for="answerSGQA">Answer</label><input type="text" value="" id="answerSGQA" name="SGQA" size="50" class="text empty">
</p>
</source><translate>


'''Multiple short text'''
</translate><source lang="html4strict">
<ul class="subquestions-list questions-list text-list">
<li class="question-item answer-item text-item" id="javatbdSGQA">
<label for="answerSGQA">Some example subquestion</label>
<span><input type="text" value="" id="answerSGQA" name="SGQA" size="20" class="text empty"></span>
</li>
</ul>
</source><translate>


'''Array question type'''
</translate><source lang="html4strict">
<table class="question subquestion-list questions-list ">
<caption class="hide read">Some explanation for accessibility.</caption>
<colgroup class="col-responses">
<col width="50%" class="col-answers">
<col width="25%" class="odd">
<col width="13.3%" class="col-no-answer even">
</colgroup>
<thead>
<tr class="array1 dontread">
<td> </td>
<th>1</th>
<th>No answer</th>
</tr>
</thead>
<tbody>
<tr class="array2 answers-list radio-list" id="javatbdSGQ">
<th width="20%" class="answertext">Some example subquestion
</th>
<td class="answer_cell_001 answer-item radio-item">
<label for="answerSGQA" class="hide read">1</label>
<input type="radio" value="1" id="answerSGQA" name="SGQA" class="radio">
</td>
<td class="answer-item radio-item noanswer-item">
<label for="answerSGQA" class="hide read">No answer</label>
<input type="radio" value="" id="answerSGQA" name="SGQA" class="radio">
</td>
</tr>
</tbody>
</table>
</source><translate>

==The full list of question classes== 


{|
|'''Question Type'''||'''Question Class'''||'''Question ID'''
|-
|5 point choice||.choice-5-pt-radio||5
|-
|Array (10 point choice)||.array-10-pt||B
|-
|Array (5 point choice)||.array-5-pt||A
|-
|Array (Flexible Labels) dual scale||.array-flexible-duel-scale ||1
|-
|Array (Increase, Same, Decrease)||.array-increase-same-decrease||E
|-
|Array (Multi Flexible) (Numbers)||.array-multi-flexi ||:
|-
|Array (Multi Flexible) (Text)||.array-multi-flexi-text||;
|-
|Array (Yes/No/Uncertain)||.array-yes-uncertain-no||C
|-
|Array (flexible labels)||.array-flexible-row ||F
|-
|Array (flexible labels) by column||.array-flexible-column||H
|-
|Boilerplate question||.boilerplate||X
|-
|Date||.date||D
|-
|Gender||.gender||G
|-
|Huge free text||.text-huge||U
|-
|Language switch||.language||I
|-
|List (dropdown)||.list-dropdown||!
|-
|List (radio)||.list-radio||L
|-
|List with comment||.list-with-comment||O
|-
|Long free text||.text-long||T
|-
|Multiple numerical input||.numeric-multi||K
|-
|Multiple options||.multiple-opt||M
|-
|Multiple options with comments||.multiple-opt-comments||P
|-
|Multiple short text||.multiple-short-txt||Q
|-
|Numerical input||.numeric||N
|-
|Ranking||.ranking||R
|-
|Short free text||.text-short||S
|-
|Yes/No||.yes-no||Y
|-
|
|}

==The full list of validation classes== 


<div class="simplebox">Note: Prior to 1.92, only .mandatory and .input-error classes were available.</div>


These apply to the help and/or validation tip messages so that each type can be individually styled.


The .hide-tip option and .input-error options interact by default so that you can have validation tips hidden. However, they do appear when there are validation errors and disappear again when those errors are rectified.


All of these are designed to eliminate the need for pop-up alert messages. Instead, tips can appear/disappear as needed and are color-coded to indicate whether the answers pass the validation criteria.


Furthermore, when you first visit a page that has unmet validation criteria, you can color-code the tips in a pleasing color to show which validation criteria have not been met yet; then re-display the page using a harsher color if the person submits the page with lingering validation errors.


{|
|'''Purpose'''||'''CSS Class'''||'''Description'''
|-
|Mandatory||.mandatory||the question is mandatory
|-
|User input error||.input-error||the question had at least one validation error
|-
|Hide Tip||.hide-tip||added if you use the hide_tip option
|-
|Num answers||.em_num_answers||for for min_answers and max_answers
|-
|Value range||.em_value_range||for min/max_num_value_n and multiflexible_min/max
|-
|Sum range||.em_sum_range||for min/max/equals_num_value
|-
|Regex validation||.em_regex_validation||for regular-expression validation of the question
|-
|Question-level validation function||.em_q_fn_validation||for the em_validation_q option
|-
|Subquestion-level validation function||.em_sq_fn_validation||for the em_validation_sq option
|-
|Other comment mandatory||.em_other_comment_mandatory||for other_comment_mandatory option - shows when "other" is selected but associated comment is missing.
|-
|
|}

==Importing styles into your custom template== 


The custom question styles are near the bottom of each template's CSS file and start with:<syntaxhighlight lang="php" enclose="div">/* --------------------------- START: Question styles ------------------------------ */</syntaxhighlight>


If you're styling your own custom template, you should be able to copy everything after the above one from ''templates/default/template.css'' (for table-based layouts) or ''/templates/limespired/template.css'' (for CSS-based layouts) into your own style sheet without any impact on your other styles.

==Internet Explorer conditional style sheets== 


Because of the marked discrepancies in rendering between IE6 & IE7 and the other browsers, there are special IE conditional style sheets included for each template.


<source lang="html4strict" enclose="div">



</source>


You should include the above code within your '''startpage.pstpl''' and copies of both the IE style sheets from either ''/templates/default/'' or ''/templates/limespired'' for Tables base layout and CSS based layout respectively.


<div class="simplebox">'''Note:''' If you copy the styles into your own style sheet you will almost certainly need to tweak them.</div>

===Alternative solution for Internet explorer=== 


You can put a conditional class for body in startpage.pstpl and use this class in your template.css. This method is used in the citronade template{{ObsoleteIn|2.06}}. Adding a js / no-js class to have javascript / no javascript system.


<source lang="html4strict">



<body id="body" class="lang-{SURVEYLANGUAGE} {SURVEYFORMAT} no-js">
<script type='text/javascript'>/*<![CDATA[*/(function(H){ H.className=H.className.replace(/\bno-js\b/,'js') })(document.getElementsByTagName('body')[0]);/*]]>*/</script></source>


And in template.css use:


<source lang="css">.ie6{/*specific for internet explorer 6*/}
.ielt8{/*specific for internet explorer 6 and 7*/}
.ie{/*specific for all internet explorer */}</source>

== Right-to-Left (RTL) Languages and justify== 


The text editor within LimeSurvey is able to format RTL text. However, the editor itself shows the RTL language in a left to right format when justified. This is just an editor display issue. The RTL and justified question or text will display correctly from right to left, even when justified, in your survey or on preview.

==Keywords== 


{{Deprecated|3.0}}


Keywords within a template file get replaced by the current survey information. They are surrounded by curly brackets, for example: {SURVEYNAME}.


The following strings will be replaced by LimeSurvey when parsing the template file and presenting it to survey users. These field strings will work on almost every template except for the 'Completed Page'. (Most of these strings can be found in the common.php file. If it's not there, look in the index.php file.)


{|class=wikitable
!'''Keyword'''!!'''Template files'''!!'''Description'''
|-
|{SURVEYNAME}||All Files||The survey title
|-
|{SURVEYDESCRIPTION}||All Files||The survey description
|-
|{WELCOME}||All files (mainly for welcome.pstpl)||The survey 'welcome' text
|-
|{PERCENTCOMPLETE}||survey.pstpl||A small graph showing the percentage of the survey completed
|-
|{GROUPNAME}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group name
|-
|{GROUPDESCRIPTION}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group description
|-
|{NUMBEROFQUESTIONS}||welcome.pstpl||Displays the total number of questions in the survey (just the number)
|-
|{THEREAREXQUESTIONS}||welcome.pstpl||Displays the sentence "There are X questions in this survey" - from the relevant language file. The X is replaced with the number of questions. Note that this will also work appropriately for singular or plural. If there is only 1 question, it will print "There is 1 question in this survey".
|-
|{CHECKJAVASCRIPT}||All files (mainly for welcome.pstpl)||Warning message when end-user browser have javascript disabled
|-
|{QUESTION}||Question.pstpl||('''Has been superseeded as of LS1.87''') Displays the current question text (The format of {QUESTION} can customised by editing 'question_start.pstpl') Use the following: {QUESTION_TEXT}, {QUESTION_MANDATORY}, {QUESTION_HELP}, {QUESTION_MAN_MESSAGE}, {QUESTION_VALID_MESSAGE}, {QUESTION_INPUT_ERROR_CLASS}, and appropriate wrapping HTML instead of {QUESTION}
|-
|{ANSWER}||question.pstpl, print_question.pstpl||presents the answer form for the current question
|-
|{SGQ}||question.pstpl, question text||Can be used in the question text itself to reference the input field of the question dynamically by displaying the Survey-Group-Question id for the current question. (as of svn build 9755)
|-
|{QUESTIONHELP}||question.pstpl, print_question.pstpl||Displays help text (predefined tip for question type) for the current question
|-
|{QUESTION_CLASS}||question.pstpl, print_question.pstpl||unique class for each question type. (To be included in the question's wrapping tag.)
|-
|{QUESTION_CODE}||question.pstpl, print_question.pstpl||Displays the current question code
|-
|{QUESTION_ESSENTIALS}||question.pstpl||the question ID and (if a question is conditional), 'style="display:none;"'. (To be included in the question's wrapping tag.)
|-
|{QUESTION_HELP}||question.pstp, question_start.pstpl||Displays the user defined help text for the current question
|-
|{QUESTION_TYPE_HELP}||print_question.pstp||Displays the user defined help text for the current question
|-
|{QUESTION_INPUT_ERROR_CLASS}||question.pstp, question_start.pstpl||Provides a class if there was user input error
|-
|{QUESTION_ID}||print_question.pstp||Provides a unique ID for each question to allow styling for specific questions
|-
|{QUESTION_TEXT}||question.pstp, print_question.pstp, question_start.pstpl||Displays the text for the current question
|-
|{QUESTION_MANDATORY}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' text for the current question
|-
|{QUESTION_MAN_CLASS}||question.pstpl, print_question.pstpl||class if a question is mandatory. (To be included in the question's wrapping tag.)
|-
|{QUESTION_MAN_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' help message text for the current question
|-
|{QUESTION_NUMBER}||print_question.pstpl||Incremental count of questions.
|-
|{QUESTION_VALID_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated valid help message text for the current question
|-
|{QUESTION_SCENARIO}||print_question.pstp||Prints out the 'scenario' text for conditional questions.
|-
|{NAVIGATOR}||navigator.pstpl||Displays navigation buttons (next, prev, last)
|-
|{CLEARALL}||All files (but intended for navigator.pstpl)||Displays the "Exit and Clear Results" link
|-
|{COMPLETED}||completed.pstpl||Displays the 'completed' message for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{URL}||completed.pstpl||Displays the survey 'url' and 'url text'
|-
|{PRIVACYMESSAGE}||privacy.pstpl||The privacy message is shown if you set your survey to be anonymous. [[Translating LimeSurvey|The text can be edited/translated]] in the language files. This can also be changed manually by editing the privacy.pstpl template you wish to use.
|-
|{TEMPLATEURL}||All Files||The URL to the current template location (useful for referencing image files in your template)
|-
|{SURVEYRESOURCESURL}||All Files||The URL to the current uploaded files for this survey location (useful for referencing image files in your question, group, ....)
|-
|{SUBMITCOMPLETE}||endpage.pstpl||The statement (from the language files) that tells the user they have completed the survey, and to press the "Submit" button
|-
|{SUBMITREVIEW}||survey.pstpl||The statement (from the language files) that tells the user they can review/change the answers they have made by clicking "<< prev"
|-
|{SAVEDID}||All Files||Displays 'Response ID' of user
|-
|-
|{QUEXMLPDF}||All Files||Displays button to export the queXML PDF of questionnaire including answers entered up until the point that has been completed in the survey.
|-
|{TOKEN:FIRSTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users first name from the tokens table
|-
|{TOKEN:LASTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users last name from the tokens table***
|-
|{TOKEN:EMAIL}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users email from the tokens table***
|-
|{TOKEN:ATTRIBUTE_1}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_1 from the tokens table***
|-
|{TOKEN:ATTRIBUTE_2}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_2 from the tokens table***
|-
|{ANSWERSCLEARED}||Preferably in navigator.pstpl||The "Answers Cleared" statement from the language files
|-
|{RESTART}||clearall.pstpl||URL to restart the survey
|-
|{REGISTERERROR}||register.pstpl||Shows any error messages in the register page (ie: "You must include an email address")
|-
|{REGISTERMESSAGE1}||register.pstpl||The statement "You must be registered to complete this survey" from the language files
|-
|{REGISTERMESSAGE2}||register.pstpl||Details about registering from the language files
|-
|{REGISTERFORM}||register.pstpl||The actual form for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{SAVE}||Works suitable on navigator.pstpl||Displays the 'Save your responses so far' button to offer the user to save and come back later to continue the survey. If the Save option is deactivated in the survey properties the tag will not be shown and ignored.
|-
|{LANGUAGECHANGER}||survey.pstpl||Displays a switch in multilingual surveys to change the question.
|}

==Input/Buttons== 


Each "input" type in a survey has been given its own class name, so that you can add CSS to your "startpage.pstpl" file and have some control over the appearance of form buttons and inputs. These class names are as follows:
*'''submit''' (Submit Buttons)
*'''text''' (Text Inputs - for short free text, date, and numerical type)
*'''answertext''' (Text of answers)
*'''radio''' (Radio Buttons)
*'''checkbox''' (Check Boxes)
*'''select''' (Select / List Boxes)
*'''textarea''' (Large text inputs - for long free text)
*'''clearall''' (The "Exit and Clear Survey" link)
*'''rank''' (The rank style question. Doesn't set the colour of the select box or the text boxes, but it does allow the changing of background colour, text colour, size etc., for the rest of the ranking question)
*'''graph''' (The "percentage completed" graph table)
*'''innergraph''' (The table inside the graph table - this contains the 0% and 100% text. Use this for changing the size of this text)
*'''question''' (General settings for any question that is displayed within a table. Generally, you should use this to make sure that their font size and color is the same as you have used elsewhere as a default)
*'''mandatory''' (Mandatory questions)
*'''input-error''' (User input error - for if a user has made a mistake with a mandatory question or question with validation)
*'''array1''' and '''array2''' (These two styles are cycled when presenting the range of answers for an array type question. This allows you to set an alternating background color for these question types. '''Array1''' is also used for the column headings in these question types)
*'''errormandatory''' (Sets the color and style of the "This question is mandatory" error message)
*'''warningjs''' (Sets the color and style of the warning message displayed if the participant's browser has javascript disabled)


There are also some elements that can be accessed using the ID of the element ('''#ID''' in CSS):
*'''surveycontact''' (The contact message shown on the start page)
*'''tokenmessage''' (used for messages inside the survey, e.g. the session expired error message)


Because you can edit all the HTML aspects, there's no reason to surround your templates with a
<syntaxhighlight lang="php" enclose="div"><div class='new_name'></div></syntaxhighlight>
and then define a css for that new_name class.

==Styling the progress bar== 


The progress bar appearance can be modified with CSS.


To change the background color of the bar, add something like the following to the end of your template.css file:


<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-header {
background-color: #3300FF;
}</syntaxhighlight>


To change the border color of the bar, add something like the following to the end of your template.css file:


<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-content,
#progress-wrapper .ui-widget-header {
border: 1px solid #FF0000;
}</syntaxhighlight>

==Advanced Features Available to Developers== 


LimeSurvey has integrated some user-made patches that permits some special changes. These very advanced features (generally) require changes to the underlying code base of LimeSurvey and should be done carefully in order not to introduce security holes.

===Support for your own Javascript functions=== 


Some users may need to run Javascript on the survey pages, but calling '''checkconditions()''' in the BODY element made it impossible to do so. This call has been replaced with a small JavaScript function in the HEAD that sniffs for the existence of '''checkconditions()''' and '''template_onload()''' before calling them. In this way, a template author can create his or her own '''template_onload()''' function in the HEAD that replaces the default one.


*Disable XSS filter - in Global settings -> Security, set "Filter HTML for XSS" to No.
*Enter your script in the source of a question or group description.


{{Note|For further details, see the [[Workarounds: Manipulating a survey at runtime using Javascript#How to use Script (eg. JavaScript etc.) in LimeSurvey|workaround section]].}}

=Videos on Templates= 


This video will demonstrate the basic and advanced template functions that are available to all LimeSurvey users. This includes changing the appearance of certain forms and inserting custom graphics. Additionally, it will thoroughly walk you through on how to edit and preview specific page templates, importing/exporting templates, modify appearance of questions in the CSS, and customizing survey description page.


Video - needed

=Tips & Tricks= 

==Some language specific element== 


If you want to have some language specific sentence in a survey, for example a help at the end of each page, you can add in a .pstl file a sentence and hidding it for other language. If we hide it in the template.css, we can use the pseudo selector :lang, but we use some class for better compatibility.


Below, there are two help sentences, in French and English. Put this on endpage.pstpl:


<syntaxhighlight lang="php" enclose="div"><div class="fr" lang="fr">Pour de l'aide en direct appelez le 000000</div>
<div class="en" lang="en">For some help, please call 000000</div></syntaxhighlight>


and in template.css:


<syntaxhighlight lang="php" enclose="div">.lang-fr .en{display:none}
.lang-en .fr{display:none}</syntaxhighlight>

==Change the layout of the survey page== 


After editing and saving a template, it applies to a survey list page only if it is selected from the settings of the survey. To make it the default template, go under the '''General tab''' located in the '''Global settings''' of your LimeSurvey installation and choose the desired template. From now on, all the templates that use the "default" option as template plus the ones that are going to be newly created, will use the newly selected default template.


To use your current template for this page, you have to change the according setting from '''Global settings'''. In older versions, this change can be done by editing the $defaulttemplate setting from the config file: copy this setting from config-defaults.php to config.php which overrides config-defaults.php and edit this setting to <code lang="html">$defaulttemplate = 'yourtemplatename';</code>.

==Import/Export of templates: Mac users== 


<u>Mac users</u>, please note that the Mac OSX default archive utility may have problems with zip folders "generated on the fly".


A workaround is to unix'es unzip from the command line:


$ unzip template.zip -d template


Archive: template.zip


inflating: template/startpage


inflating: ...


Another workaround is to use scripts in their mac-compiled counterparts.

==Replacing the help icon {{ObsoleteIn|2.50}} == 


When a question help text is shown, then an help.gif image is used from the default template folder.


You can replace this image by uploading a new help.gif, help.png or help.jpg in your custom template folder. It will then be automatically used instead of the default help icon.

==Replacing an existing logo {{NewIn|2.50}} {{ObsoleteIn|3.0}}== 


'''Note''': In the '''default'' Template of 2.50, there is no preembedded logo. Read further our [[#Adding_your_own_logo |wiki on how to add your own logo]].


1. To edit the logo go to the ''<u>template.css</u>'' file which you can find it here:


<center>[[File:t1.PNG|200px]]</center>


2. Click the search button to find occurrences of logo related styles and search for ''logo''


<center>[[File:2.png|200px]]</center>


4. Edit the main style file.


You will see something similar to:


<center>[[File:t4.PNG|500px]]</center>


If you want to change the image, just replace logo.gif with another image link. Example: (<u>logo.png</u> or <u>logo.jpg</u>).


If you want to change the image size, adjust width and height (in pixels) like this:


<syntaxhighlight lang="php" enclose="div">width:100px; height:100px;</syntaxhighlight>

==Adding your own logo {{ObsoleteIn|3.0}} == 


1. Find and open the '''startpage.pstpl''' template file.


<center>[[File:startpage.pstpl.png]]</center>


2. After this
<source lang="html4strict" ><div id="topContainer" class="jumbotron"></source>
add this line to '''startpage.pstpl''':
<source lang="html4strict">
<div class="container"><img id='page_logo' src='{TEMPLATEURL}/files/logo.png' class="clearfix pull-right" /></div>
</source>


3. To upload your own logo, go to the template editor and upload your logo.


<center>[[File:uploadyourlogo.png]]</center>


To position your logo, please use one of the following css classes:


*'''If you want the logo to be placed on the left side:'''


<source lang="html">clearfix pull-left</source>


*'''If you want the logo to be placed on the right side:'''


<source lang="html">clearfix pull-right</source>


*'''If you want to center the logo'''


<source lang="html">clearfix center-block</source>

==Use the same template with different logos== 


If you want to use the same template for all surveys and just want to change the logo for each survey, you can use the {SID} placeholder in the template .pstpl file and thereby refer to different images:


<syntaxhighlight lang="php" enclose="div"><img src="{TEMPLATEURL}files/logoImage-{SID}.png"></syntaxhighlight>

==Remove the default help to all question (hide_tip) {{ObsoleteIn|1.92}}== 


There are 3 solutions to remove the default help:
# like a hide_tip attribute but for all question and survey.
# you can remove the {QUESTIONHELP} and its container from the file question.pstl. However, it can be a bad idea for the screenreader.
# for the default template and some other, add this at the end of tempate.css


<syntaxhighlight lang="php" enclose="div">span.questionhelp{display:none;}</syntaxhighlight>

== Display custom favicon== 


A favicon is the little icon you see in the browser's address bar, list of bookmarks or tab. You can display your own icon as follows:
#Create a favicon - google will find you lots of free favicon generators.
#Name your new favicon "favicon.ico" and place it in your template /files directory.
#Add the following code to your '''startpage.pstpl''' before the </head> tag.


<syntaxhighlight lang="html4strict" enclose="div"><link rel="shortcut icon" href="{TEMPLATEURL}files/favicon.ico" type="image/x-icon">
<link rel="icon" href="{TEMPLATEURL}files/favicon.ico" type="image/x-icon"></syntaxhighlight>

== Different appearance for survey-/question-pages== 


If you want LimeSurvey to change the appearance of every second page (i.e. of even and odd survey pages), you can use '''.page-odd''' class in your CSS file to change the appearance of odd pages.


An example from default template of LimeSurvey 1.91+:


<syntaxhighlight lang="php" enclose="div">
.page-odd table.question-group {
background-color: #D2F2D3;
}</syntaxhighlight>


If you do '''not''' want differentiate even and odd pages, find all instances of ''.page-odd'' in template.css and remove those styles.

==Create a vertical separator border for dual scale array== 


To create a vertical separator border for a dual scale array, you can add the following lines to your '''template.css'''-file.


<syntaxhighlight lang="php" enclose="div">
table.question thead td.header_separator,
table.question tbody td.dual_scale_separator
{
border-right:solid 1px #00A8E1;
}
</syntaxhighlight>


''header_separator'' is used to adress the separator for the header "td". The "dual_scale_separator" is used to address the separator column in the dual scale array.

==Hide the survey contact message shown on the start page/survey list {{ObsoleteIn|3.0}} == 


To hide the "Please contact ..." message on the start page (with the survey list), you can add the following to the '''$(document).ready''' function in the '''template.js''' of your used design template:


<syntaxhighlight lang="php" enclose="div">


$('#surveycontact').hide(); //Hides the survey contact message


</syntaxhighlight>

==Remove the survey contact message shown on error messages {{ObsoleteIn|3.0}}== 


If you want to remove the survey contact message from error messages, it'll be trickier. You can add the function from below. It calls the '''$(document).ready''' function in the '''template.css''' of your used design template:


<syntaxhighlight lang="php" enclose="div">
removeContactAdressFromMessage(); //Removes the survey contact message from error messages
</syntaxhighlight>


and add the following function to your *template.js* file


<syntaxhighlight lang="php" enclose="div">
function removeContactAdressFromMessage()
{
if ($('#tokenmessage').length > 0)
{
var oldMessage = $('#tokenmessage').html();
var indexContact = oldMessage.indexOf('Bitte kontaktieren');
var newMessage = oldMessage.substr(0, indexContact);
$('#tokenmessage').html(newMessage);
}
}
</syntaxhighlight>


It will probably not work for a survey in English language and has to be extended when used for multilingual surveys. But it's an idea/tip on how to solve this.

==How to deal with multilingual question attributes {{ObsoleteIn|2.50}}== 


If you have a multilingual survey and e. g. want to use a different string for the "other" field, this could only be done for the base language (until this feature was added at LimeSurvey 2.0). To work around this, paste in the field to change the label for "other":


<syntaxhighlight lang="php" enclose="div"><span class="en">New label</span><span class="fr">Nouveau label</span></syntaxhighlight>


Add in the template.css of your template (at ''/limesurvey/upload/templates/<yourtemplatename>/template.css''):


<syntaxhighlight lang="php" enclose="div">html:lang(en) .fr{display:none}
html:lang(fr) .en{display:none}</syntaxhighlight>

==Adding your own logo to the survey list {{ NewIn|3.0}} == 


# First please open the theme editor for the theme you like to use. [[File:OpenThemeEditor.jpg]]
# We recommend to use fruity, it is our best theme currently.
# Then extend the theme and give it a name you will recognize. [[File:ExtendTheme.jpg]]
# In the following view you may upload the logo you want to use. [[File:UploadFileTheme.jpg]]
# Select the editor screen `Survey List´ in the Screen dropdown in the top right corner. [[File:OpenScreenSurveyList.jpg]]
# Then select `layout_survey_list.twig´ in the left side menu. [[File:EditLayoutSurveyListTwig.jpg]]
# In the editor scroll to line 126 and change the marked part to the filename of the image you uploaded to the theme before. [[File:ChangeSurveyListHeaderImageEditor.jpg]]
# Save your file. [[File:ThemeEditorSaveChanges.jpg]]
# Change default theme to your extended theme. [[File:ChangeDefaultTheme.jpg]]

=Custom Question Views {{NewIn|3.0}}= 


<div class="simplebox">'''Note:''' This is a temporary feature to be replaced in the future by question object (it will be very easy to move custom views to question object). It is disabled by default.</div>


As of version 2.5, you can create template-specific custom views for questions and some of their incorporated elements. This is useful if you want to modify the HTML layout of a particular question type for one or more surveys.


*In application/config/config.php, find 'config'=>array and add this line to the array : 'allow_templates_to_overwrite_views'=>1
*In /{your_template}/config.xml, set "overwrite_question_views" to true
*Copy application/views/survey/* to template/{your_view_directory}/survey/
*Note that you only need to copy the files that you intend to modify but the file structure must remain the same as in application/views/survey/

=Insert Custom CSS or JavaScript files for template {{NewIn|2.50}}= 


As of version 2.50, you can use the config.xml file to automatically load plugin files.


*Upload your files to the template /css or /scripts folder
*In /{your_template}/config.xml, add the file paths to the <css> or <js> blocks, something like this:<syntaxhighlight lang="xml" enclose="div"><css>
<filename>css/jquery-ui-custom.css</filename>
<filename>css/bootstrap-slider.css</filename>


<filename>css/awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</filename>
<filename>css/flat_and_modern.css</filename>


<filename>css/template.css</filename>


<filename>css/myCustomPlugin.css</filename>
</css>
<js>
<filename>scripts/template.js</filename>
<filename>scripts/bootstrap-slider.js</filename>


<filename>scripts/myCustomPlugin.js</filename>
</js>
</syntaxhighlight>

</translate>

File:Theme editor button.png

2018-04-04T11:02:54Z

LouisGac: A screen shot of the theme editor button in Themes List, LS3.5

A screen shot of the theme editor button in Themes List, LS3.5

File:Themes menu.png

2018-04-04T10:57:53Z

LouisGac: screen shot of the menu "Themes" inside configuration.

screen shot of the menu "Themes" inside configuration.

Theme editor

2018-04-04T10:44:20Z

LouisGac:

<languages /> <translate>

=Introduction= 


LimeSurvey has an advanced theme and style system providing to developers an efficient way to customize the survey appearance. Since LS3, we're not speaking anymore about '''"templates"''' like in previous versions, but about '''"themes"'''. The '''themes''' allow control over the look and feel of pages during a survey. A survey administrator can select a default theme that will be used for each survey to further personalize it and improve its look and feel. '''Themes''' come with options that provide to admin without coding skill a simple way to add a logo on the welcome page, to change the background colors, to select a font, etc.


LimeSurvey comes with 3 themes right out of the box. These initial themes are defined by directories located in the LimeSurvey installation "themes/survey/" directory. Each theme has it's own directory. Within the main directory of a theme you'll find a configuration file in XML, and numerous directories containing the views ''themes (.twig)''', '''cascading style sheets (.css)''', '''scripts''', '''images''' ('''.jpg''' or '''.png'''), and maybe others.


Since LimeSurvey 2.50, the theme engine use [http://getbootstrap.com/docs/3.3/ Bootstrap 3] as CSS framework. Bootstrap 3 being a standard framework, developers will find a lot of documentation, tutorials and forum threads about it on Internet.

Since LimeSurvey 3, the theme engine use [https://twig.symfony.com Twig], so the theme developers can change the logic of the survey rendering in a safe and easy way. Twig replace the old system of replacement keywords that was used in the previous versions. The logic that was used to generate the HTML of the keywords are now available inside the theme's views.

Snippet from Vanilla Theme:


<syntaxhighlight lang="twig" enclose="div">
<div class="{{ aSurveyInfo.class.answercontainer }} col-xs-12" {{ aSurveyInfo.attr.answercontainer }}>
{# NOTE: If you want to customize the question rendering, use a question theme #}
{{ aQuestion.answer | raw }}
</div>
</syntaxhighlight>


Themes, being HTML and Twig code, tend to define the positioning and type of text to be displayed and similar structural features of the page. They often reference or include other files. Most of them reference a common cascading style sheets (CSS) file that defines the font style, color, size, background, and similar parameters common to all pages in the survey. Style sheets reference HTML '''class''' parameters that are associated with the various types of objects in the HTML code. This allows the style sheet to describe how to display each of the many types of text or other objects that may appear in multiple places. There are unique classes for each question type in LimeSurvey and thus giving detailed control over the appearance of each. Image files, like logos or special progress-bar constructors, may be referenced as well in the Theme file. Finally, special keywords in curly braces are replaced with text defined in the survey for each language translation correspondent (for example, the 'Survey Title' or 'Question Text' for each language defined).


If you create a new custom theme, please consider contributing it back to the LimeSurvey community and make it available to others. With your help, we can grow our repository of themes, surveys, and other add-ons to make LimeSurvey even better!
See our [https://www.limesurvey.org/index.php?option=com_sobipro&sid=55:Templates&Itemid=729 LimeSurvey template repository] where you can share your templates.

=Creating a new theme= 


To be able to create a new theme (or edit an existing theme), you need [[Manage users#Set global permissions for a user|Template Editing user permission]] in LimeSurvey as well as permission to manipulate the files in the underlying operating system hosting your LimeSurvey installation.


<div class="simplebox"><span style='color:red'>'''Note of Warning:'''</span> If you change themes, you could also affect all the pre-existing surveys from your LimeSurvey installation. Themes are an advanced feature that require experience and HTML knowledge in order to make them running smoothly.</div>


The preferred way to create a new theme is through the '''Theme Editor''' (see below), which is located in the '''Configuration''' dialog. Some people may like to work directly with theme files so that they can use their favorite text editor instead of the web interface. In this case, still use the Theme Editor to first create your new theme. This will create a new base theme with all the files you need in the ''LimeSurvey_web_root/upload/themes/survey/your_new_template'' directory. From there you can use your text editor to manually adjust the template files.


<div class="simplebox">'''Permissions Note:''' on unix/linux systems, these theme files will be owned by the group and user where the web server is running (may be "www" for some systems). So, make sure you have enough access to edit these files, When you save them, make sure they don't change ownership! In this way, you can still use the web Theme Editing interface if needed.</div><br />


A number of 'public' elements of LimeSurvey can be adjusted by a series of themes. The next section provides a very brief explanation of these templates.


{{Note|Themes files may seem complex. Besides HTML, you might also need to understand CSS, Twig, and JavaScript.}}

=The LimeSurvey Theme editor= 


To ease the understanding and quick update of a Theme, LimeSurvey provides a '''Theme Editor''' in the main '''administrative''' toolbar of the application. This Theme Editor is only available to users [[Manage users#Set global permissions for a user|with the Templates permission]] and to superadministrators.


{{Alert|title=Attention|text=A theme that is not correctly constructed can make a survey (that uses the respective template) inoperable. }}


The LimeSurvey theme editor allows you to edit the contents of your themes online. To start the Theme Editor: click on '''Themes''' link in the '''Configuration''' menu, and then click on the "Theme editor" button next of the theme you want to edit or extend.


[[File:templates.png]]


The template editor page allows you to select the template you would like to edit/view.


[[File:Template-editor-2013-7-10_11_38_16.png|center]]

==The template menu== 


The following options are available:


*'''Create''': Allows you to create a new template. In order not to start from scratch, the template 'default' is copied.
*'''Import''': Allows you to import a template from a ZIP file.
*'''Export''': Allows you to export the current template to a ZIP file.
*'''Copy''': Allows you to make a new template by copying the current one.
*'''Rename''': Allows you to change the name of the template. It is generally used after copying or importing a template.
*'''Template''': It is a drop-down list that shows all the available templates that are located in your LimeSurvey installation.


*'''Screen''': It is a drop-down list which allows you to choose which particular survey page of that template you want to look at.
*'''Return to admin panel'''.

==Import/export/copy a template== 


When you '''export '''a template, a ZIP-file archive with all the files your template consists of will be created (.pstpl files, images, css files, ...). You can simply '''import''' the exported zip-file into another LimeSurvey installation by using the import feature or you can manually copy the archive into another LimeSurvey installation and extract it into the corresponding [[Theme editor#Template files location|template directory there]].


However, it is preferred to use the LimeSurvey template import/export/copy functions in the template editor.

==Page Structure / Template Use== 
*'''The Welcome Page:''' startpage.pstpl, welcome.pstpl, privacy.pstpl, navigator.pstpl, endpage.pstpl
*'''The Questions Pages:''' startpage.pstpl, survey.pstpl, startgroup.pstpl, groupdescription.pstpl, question.pstpl, endgroup.pstpl, endpage.pstpl
*'''The Final Page:''' startpage.pstpl, assessment.pstpl, completed.pstpl, endpage.pstpl

==Template Files== 


The following template files are used to produce your public survey and must exist in any new template folder you create:
*'''startpage.pstpl:''' Produces the start of each html page. It starts at the "<head>" tag, and should not contain the "<html>" tag. This 'very beginning' of a standard html page is written by the scripts. Please ensure that your startpage.pstpl files contains a <body> tag. Even though many browsers do not require strict adherence to the W3 HTML standards, the LimeSurvey script needs to find a <body> tag to run certain javascript elements. It is not expected to see many 'keywords' used in the startpage.pstpl file. However, you may wish to put the {SURVEYNAME} into the title. The startpage.pstpl file can contain code that ends in the corresponding endpage.pstpl file. For example, you can start a table in this file and close the table in the endpage.pstpl file. The startpage.pstpl and endpage.pstpl files wrap around every possible page used by LimeSurvey.
*'''survey.pstpl:''' This template is the second used on most pages and provides a space to put the survey name and description. This template does not have a corresponding 'closing' template, and subsequently you should close all tags opened in this template file (i.e.: don't leave a table open here because there is nowhere else to close it).
*'''welcome.pstpl:''' This template is only used in the welcome screen (which is also on the main page for 'all in one' surveys). You can use this to print out the welcome text, and other information that should be provided in the introduction. Like the 'survey.pstpl' file, there is no corresponding 'closing' template, so all tags opened in this template file should be closed as well.
*'''startgroup.pstpl:''' This template can provide a 'summary' wrap around for questions within a group. It has a matching 'endgroup.pstpl' template that can be used to close any opened tags in this file, so you can open a table within this.
*'''groupdescription.pstpl:''' This template file is used to display a description of a group. Please note that in the survey settings (access the ''Presentation & navigation settings'' by clicking on the '''Presentation''' tab) you can set if the group description should be shown or not. If not, then this file is not included at all.
*'''question.pstpl:''' This file contains the question, answer, and help text sections of your survey. In the "group by group" and "all in one" surveys, this template is cycled repeatedly with each question. There is no corresponding closing file for this and all tags should be closed.
*'''question_start.pstpl:''' This file contains the individual elements found at the start of a question. It is included within 'question.pstpl' via the {QUESTION} keyword. It is intended to allow template designers more control over the layout of a question. This template sits outside the normal templating system and '''was superseeded (as of LimeSurvey 1.87)'''. All keywords from this template are now available directly in question.pstpl.
*'''completed.pstpl:''' This page is displayed as the final page when the survey responses have been saved and the survey is over. It can be used to display a "forwarding link" as set in the survey setup.
*'''endgroup.pstpl:''' This file closes the group, and can be used to close off any tags opened in the startgroup.pstpl file
*'''navigator.pstpl:''' This file contains the buttons that navigate through the survey, "next", "prev", "last", "submit", "save so far" and the "clear all" link. It is used in all pages except the completed page.
*'''printanswers.pstpl:''' This file has the HTML wrapper necessary for the print version of the survey.
*'''print_group.pstpl:''' This file is the same as startgroup.pstpl and endgroup.pstpl, but for the print version of the survey.
*'''print_question.pstpl:''' This file is the same as question.pstpl, but for the print version of the survey.
*'''print_survey.pstpl:''' This file is the same as survey.pstpl, but for the print version of the survey.

== CSS and Javascript== 


Two files that are always used in a template are template.css (for CSS) and template.js (for Javascript).
*'''{TEMPLATECSS}:''' Add lines for default css, template.css, and template-rtl.css for rtl language.
*'''{TEMPLATEJS}:''' Add lines for default javascript files, template.js, and all js files needed for LimeSurvey.

=== Using Bootstrap=== 
LimeSurvey has Bootstrap 3 embedded, so you can style all your templates with the well documented Bootstrap classes.
For more information please refer to the [https://getbootstrap.com Bootstrap documentation].


The [https://github.com/flatlogic/awesome-bootstrap-checkbox Awesome-Bootstrap-Checkbox] plugin is also included. With it, you can use the typical Bootstrap color-classes (info,warning,danger,etc.) also with the suffix "-checkbox" or "-radio", though styling checkboxes and radios as you prefer.

=== Replacing default CSS or Javascript=== 


Some questions use specific files for Javascript or CSS. If you need to replace a function, use a cascading system. For javascript function, the last function read is the function used.

==Other Template Files== 


The '''privacy.pstpl''', '''invitationemail.pstpl''', '''reminderemail.pstpl''', and '''confirmationemail.pstpl''' are no longer used by LimeSurvey and defaults are instead set in the applicable language files. The email messages can now be edited on a survey by survey basis.

==Standard Pages== 


There are ten standard pages that a survey participant may see in the course of taking or accessing the LimeSurvey application. Each is constructed from a number of common '''Template''' files from the '''Template''' specified in the settings of the survey. The table below indicates which template files are used in constructing each of these pages.


{| class="wikitable"
! '''Survey Pages/'''<br />'''Template Files'''!!Survey<br />List!!Welcome!!Question!!Completed!!Clear All!!Register!!Load!!Save!!Print<br />Answers!!Print<br />Survey
|-
|SurveyList||align="center" | [[File:check.gif]]|| || || || || || || || ||
|-
|Welcome|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Privacy|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Navigator|| ||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Survey|| || ||align="center" | [[File:check.gif]]|| || ||align="center" | [[File:check.gif]]|| || || ||
|-
|StartGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|GroupDescription|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Question<span style='color:red'>'''*'''</span>|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|EndGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Assessment|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|Completed|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|ClearAll|| || || || ||align="center" | [[File:check.gif]]|| || || || ||
|-
|Register|| || || || || ||align="center" | [[File:check.gif]]|| || || ||
|-
|Load|| || || || || || ||align="center" | [[File:check.gif]]|| || ||
|-
|Save|| || || || || || || ||align="center" | [[File:check.gif]]|| ||
|-
|PrintAnswers|| || || || || || || || ||align="center" | [[File:check.gif]]||
|-
|Print Survey || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Group || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Question || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|StartPage<br />EndPage<br />Template.css||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||
|}


<span style='color:red'>'''*'''</span>NOTE: In version 1.90+, this replaces question.pstpl AND question_start.pstpl. If you are using an old custom template, you need to add the following line to the beginning of question.pstpl:<syntaxhighlight lang="php" enclose="div"><div {QUESTION_ESSENTIALS} class="{QUESTION_CLASS}{QUESTION_MAN_CLASS}{QUESTION_INPUT_ERROR_CLASS}"></syntaxhighlight>And then add the corresponding closing tag to the end of question.pstpl:<syntaxhighlight lang="php" enclose="div"></div></syntaxhighlight>


<span style='color:red'>'''*'''</span>NOTE: In version 1.91 and earlier, LimeSurvey js files are not included in the template. In version 2, '''you have to use {TEMPLATEJS} in one of your template file''' to add the link to the js file. You can add it in startpage.pstpl or in endpage.pstpl. You can remove the {TEMPLATEURL}/template.js line and you have to replace with {TEMPLATEJS} to update a personal template.

==The File Control Section== 


In the "file control" window on the left, you can click on one of the template files that is used to compile the page. You can see the ''Screen part'', JavaScript, and CSS files. The HTML code for that file will then appear in the "Now editing" window in the center. If the template is editable (determined by directory permissions) you can then make any changes and save them.


<center>[[File:File Control Section.png|center]]</center>


The "Other files" window shows a list of all other files from the template directory. You can use the right side to '''upload and select image files (your pics, logos,...) or other files needed to create your template'''.


Instead of using a link for each picture, utilize the field string {TEMPLATEURL}. So, instead of:


<syntaxhighlight lang="html4strict" enclose="div">img src='/limesurvey/templates/yourtemplate/files/mypicture.jpg'</syntaxhighlight>
You can use {{NewIn|2.50}}:
<syntaxhighlight lang="html4strict" enclose="div">img src='{TEMPLATEURL}files/mypicture.jpg'</syntaxhighlight>


In LimeSurvey versions before 2.50 use:
<syntaxhighlight lang="html4strict" enclose="div">img src='{TEMPLATEURL}mypicture.jpg'</syntaxhighlight>


A "sample" of the template page you are editing will be visible in the bottom of the screen. There is no way to delete a template from the template editor. This must be done by accessing the underlying directory and deleting manually the files from there. You also have the possibility to select different screen resolutions in order to better evaluate the feel and look of the template.


<div class="simplebox">'''Note:''' The shipped templates cannot be edited using the template editor. If you want to modify them, create a copy first and edit the copy.</div>

==Template files location== 


LimeSurvey stores each of the 'standard' templates in their own distinct sub-directory within the ''/templates'' directory that is kept in the public directory with the other LimeSurvey public files. Customized user templates are stored in the ''/upload/templates'' directory.


There should '''ALWAYS''' be a "default" directory in the templates directory. This template is used by default and as a fall-back if a template folder doesn't exist, or can't be found. It comes installed by default.


You can use any image files that you upload into the template management area with the help of this syntax:


<syntaxhighlight lang="php" enclose="div">{TEMPLATEURL}filename.xyz</syntaxhighlight>

=Styling questions with CSS= 


Styling of questions in CSS has become much easier. Each question type has now a unique class. The mandatory questions have an additional mandatory class. For example, for a non-mandatory question:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender">
...
</div></syntaxhighlight>


and if the question is mandatory:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory">
...
</div></syntaxhighlight>


and if the question is mandatory, but the user didn't answer it or if there is validation on a question:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory input-error">
...
</div></syntaxhighlight>


and if the question has validation applied, but the user hasn't answered correctly:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question6" class="text-short input-error">
...
</div></syntaxhighlight>

==Global classes for question part== 


These classes are used for each question type. Some question types use only one or two classes, while others may use much more.


{| class="wikitable alternance"
|+ Global classes
|-
! scope="col" | Class name
! scope="col" | Part
! scope="col" | Question type
! scope="col" | Examples
! scope="col" | Note
|-
! scope="row" | .question {{ObsoleteIn|3.0}}
| All question block
| All question type
|<p class="question">, <ul class="question">, <table class="question">
|
|-
! scope="row" | .ls-answers {{NewIn|3.0}}
| All question block
| All question type
|<div class="ls-answers ">, <ul class="ls-answers ">, <table class="ls-answers">
|
|-
! scope="row" | .subquestions-list
| List of subquestion
| Multi choice question, array question type
| <ul class="subquestions-list">, <table class="subquestions-list">
| .questions-list is used too
|-
! scope="row" | .answers-list
| List of answers
| Single choice question, array question type, Multi input text question
| <ul class="answers-list">, <table class="answers-list">
|
|-
! scope="row" | .answer-item
| The answer part: one answer
| Single choice question, array question type, Multi input text question
| <li class="answer-item">, <td class="answer-item">
|
|-
! scope="row" | .noanswer-item
| The answer part for no answer
| Single choice question, array question type
| <li class="noanswer-item">, <td class="noanswer-item">
| No answer is an answer too, then have double class noanswer-item and answer-item
|-
! scope="row" | .question-item
| The question part: one question
| Multi text question, array question type
| <li class="question-item">, <tr class="question-item">
| Some answers are questions too. Then we have a lot of class="question-item answer-item"
|-
! scope="row" | .checkbox-list
| A list of checkbox
| Multi choice question, array number (checkbox) question type
| <ul class="checkbox-list">, <tr class="checkbox-list">
| Some question types use multi-list class, like checkbox with comment: class="checkbox-list text-list"
|-
! scope="row" | .checkbox-array {{NewIn|3.0}}
| A array of checkbox
| Array (numbers) with checkbox option
| <table class="checkbox-list">
|
|-
! scope="row" | .checkbox-item
| The answer part with a checkbox
| Multi choice question, array number (checkbox) question type
| <li class="checkbox-item">, <td class="checkbox-item">
|
|-
! scope="row" | .radio-list
| A list of radio item
| Single choice question, array question type (each row)
| <ul class="radio-list">, <tr class="radio-list">
|
|-
! scope="row" | .radio-array {{NewIn|3.0}}
| A array of radio item
| Array question type
| <table class="radio-array">
|
|-
! scope="row" | .radio-item
| The answer part with a radio
| Single choice question, array question type
| <li class="radio-item">, <td class="radio-item">
|
|-
! scope="row" | .text-list
| A list of text input
| Multi text question type, array of text
| <ul class="text-list">, <tr class="text-list">
|
|-
! scope="row" | .text-item
| The answer part of a text input
| Multi text question type, array of text
| <li class="text-item">, <td class="text-item">
|
|-
! scope="row" | .numeric-list
| A list of text input with numeric only answer
| Multi numeric question type, array of number
| <ul class="text-list numeric-list">, <tr class="text-list numeric-list">
|
|-
! scope="row" | .number-list
| A list of text input with numeric only answer (each row)
| Multi numeric question type, array of number
| <ul class="text-list numeric-list">, <tr class="text-list numeric-list">
|
|-
! scope="row" | .number-array {{NewIn|3.0}}
| The answer part of a numeric input
| Array of number
| <table class="number-array">
|
|-
! scope="row" | .select-list {{ObsoleteIn|2.50}}
| A list of select
| Array numbers, Dual scale array (select)
| <table class="select-list">
|
|-
! scope="row" | .dropdown-list {{NewIn|2.50}}
| A list of select
| Array numbers, Dual scale array (select) (each row)
| <table class="dropdown-list">
|
|-
! scope="row" | .dropdown-array {{NewIn|3.0}}
| A array of dropdown
| Array numbers, Dual scale array (select)
| <table class="dropdown-array">
|
|-
! scope="row" | .select-item {{ObsoleteIn|2.50}}
| The answer part of a select
| Array numbers, Dual scale array (select), single choice with select
| <p class="select-item">, <td class="select-item">
|
|-
! scope="row" | .dropdown-item {{NewIn|2.50}}
| The answer part of a select
| Array numbers, Dual scale array (select), single choice with select
| <p class="dropdown-item">, <td class="dropdown-item">
|
|-
! scope="row" | .hide {{ObsoleteIn|3.0}}
| Used for accessibility: hidden with css but read by screenreader, since 2.50 : you can use sr-only from bootstrap
| Short text question
| <label class="hide">
| Can be used for other purposes
|-
! scope="row" | .ls-js-hidden {{NewIn|3.0}}
| Used for part to be hidden if javascript is activated
| Button for example
| <div class="ls-js-hidden">
| LimeSurvey core used it, but you can use it too in your template
|-
! scope="row" | .ls-js-hidden-sr {{NewIn|3.0}}
| Used for accessibility: hide it if js is activated, but always show if user use a screenreader
| Button for example
| <a class="ls-js-hidden-sr">
| Button
|-
! scope="row" | .ls-no-js-hidden {{NewIn|3.0}}
| Used for part to be hidden if javascript is not activated
| Link
| <a class="ls-no-js-hidden">
| LimeSurvey core used it for inactive link if javascript is not activated
|-
! scope="row" | .ls-label-xs-visibility {{NewIn|3.0}}
| Label to be hidden in big screen, but show with little screen (with no more table) and to screenreader
| label
| <label class="ls-no-js-hidden">
| Used for label inside table cell of array question type
|-
! scope="row" | .ls-input-group-extra {{NewIn|3.0}}
| Same usage of boostrap input-group-addon, but without the border and the background.
| right suffix
| <div class="ls-input-group-extra">
| Used for right and left suffix (global)
|-
! scope="row" | .checkbox {{ObsoleteIn|3.0}}
| input[type=checkbox]
| Question with checkbox
| <input type="checkbox" class="checkbox">
| With modern browser: not needed, but some old browser need this
|-
! scope="row" | .radio {{ObsoleteIn|3.0}}
| input[type=radio]
| Question with radio
| <input type="radio" class="radio">
| With modern browser: not needed, but some old browser need this
|-
! scope="row" | .text
| input[type=text]
| Question with input text, or textarea
| <textarea class="text">
|
|-
! scope="row" | .answertext
| Array question type
| Answer part of array question type
| <th class="answertext">
|
|-
! scope="row" | .col-answers
| Array question type
| Column of answers
| <col class="col-answers">
|
|-
! scope="row" | .odd .even {{ObsoleteIn|2.50}}
| Array question type
| Alternation for column
| <col class="odd">
|
|-
! scope="row" | .array1 .array2 {{ObsoleteIn|3.0}}
| Array question type
| Alternation for line
| <tr class="array1">
|
|-
! scope="row" | .ls-odd .ls-even {{NewIn|3.0}}
| Array question type
| Alternation for sub-question and Y axis
| <tr class="ls-odd">
|
|}

=== Some example of question part with classes=== 


'''Text-short question type:'''
</translate><source lang="html4strict">
<p class="question answer-item text-item ">
<label class="hide label" for="answerSGQA">Answer</label><input type="text" value="" id="answerSGQA" name="SGQA" size="50" class="text empty">
</p>
</source><translate>


'''Multiple short text'''
</translate><source lang="html4strict">
<ul class="subquestions-list questions-list text-list">
<li class="question-item answer-item text-item" id="javatbdSGQA">
<label for="answerSGQA">Some example subquestion</label>
<span><input type="text" value="" id="answerSGQA" name="SGQA" size="20" class="text empty"></span>
</li>
</ul>
</source><translate>


'''Array question type'''
</translate><source lang="html4strict">
<table class="question subquestion-list questions-list ">
<caption class="hide read">Some explanation for accessibility.</caption>
<colgroup class="col-responses">
<col width="50%" class="col-answers">
<col width="25%" class="odd">
<col width="13.3%" class="col-no-answer even">
</colgroup>
<thead>
<tr class="array1 dontread">
<td> </td>
<th>1</th>
<th>No answer</th>
</tr>
</thead>
<tbody>
<tr class="array2 answers-list radio-list" id="javatbdSGQ">
<th width="20%" class="answertext">Some example subquestion
</th>
<td class="answer_cell_001 answer-item radio-item">
<label for="answerSGQA" class="hide read">1</label>
<input type="radio" value="1" id="answerSGQA" name="SGQA" class="radio">
</td>
<td class="answer-item radio-item noanswer-item">
<label for="answerSGQA" class="hide read">No answer</label>
<input type="radio" value="" id="answerSGQA" name="SGQA" class="radio">
</td>
</tr>
</tbody>
</table>
</source><translate>

==The full list of question classes== 


{|
|'''Question Type'''||'''Question Class'''||'''Question ID'''
|-
|5 point choice||.choice-5-pt-radio||5
|-
|Array (10 point choice)||.array-10-pt||B
|-
|Array (5 point choice)||.array-5-pt||A
|-
|Array (Flexible Labels) dual scale||.array-flexible-duel-scale ||1
|-
|Array (Increase, Same, Decrease)||.array-increase-same-decrease||E
|-
|Array (Multi Flexible) (Numbers)||.array-multi-flexi ||:
|-
|Array (Multi Flexible) (Text)||.array-multi-flexi-text||;
|-
|Array (Yes/No/Uncertain)||.array-yes-uncertain-no||C
|-
|Array (flexible labels)||.array-flexible-row ||F
|-
|Array (flexible labels) by column||.array-flexible-column||H
|-
|Boilerplate question||.boilerplate||X
|-
|Date||.date||D
|-
|Gender||.gender||G
|-
|Huge free text||.text-huge||U
|-
|Language switch||.language||I
|-
|List (dropdown)||.list-dropdown||!
|-
|List (radio)||.list-radio||L
|-
|List with comment||.list-with-comment||O
|-
|Long free text||.text-long||T
|-
|Multiple numerical input||.numeric-multi||K
|-
|Multiple options||.multiple-opt||M
|-
|Multiple options with comments||.multiple-opt-comments||P
|-
|Multiple short text||.multiple-short-txt||Q
|-
|Numerical input||.numeric||N
|-
|Ranking||.ranking||R
|-
|Short free text||.text-short||S
|-
|Yes/No||.yes-no||Y
|-
|
|}

==The full list of validation classes== 


<div class="simplebox">Note: Prior to 1.92, only .mandatory and .input-error classes were available.</div>


These apply to the help and/or validation tip messages so that each type can be individually styled.


The .hide-tip option and .input-error options interact by default so that you can have validation tips hidden. However, they do appear when there are validation errors and disappear again when those errors are rectified.


All of these are designed to eliminate the need for pop-up alert messages. Instead, tips can appear/disappear as needed and are color-coded to indicate whether the answers pass the validation criteria.


Furthermore, when you first visit a page that has unmet validation criteria, you can color-code the tips in a pleasing color to show which validation criteria have not been met yet; then re-display the page using a harsher color if the person submits the page with lingering validation errors.


{|
|'''Purpose'''||'''CSS Class'''||'''Description'''
|-
|Mandatory||.mandatory||the question is mandatory
|-
|User input error||.input-error||the question had at least one validation error
|-
|Hide Tip||.hide-tip||added if you use the hide_tip option
|-
|Num answers||.em_num_answers||for for min_answers and max_answers
|-
|Value range||.em_value_range||for min/max_num_value_n and multiflexible_min/max
|-
|Sum range||.em_sum_range||for min/max/equals_num_value
|-
|Regex validation||.em_regex_validation||for regular-expression validation of the question
|-
|Question-level validation function||.em_q_fn_validation||for the em_validation_q option
|-
|Subquestion-level validation function||.em_sq_fn_validation||for the em_validation_sq option
|-
|Other comment mandatory||.em_other_comment_mandatory||for other_comment_mandatory option - shows when "other" is selected but associated comment is missing.
|-
|
|}

==Importing styles into your custom template== 


The custom question styles are near the bottom of each template's CSS file and start with:<syntaxhighlight lang="php" enclose="div">/* --------------------------- START: Question styles ------------------------------ */</syntaxhighlight>


If you're styling your own custom template, you should be able to copy everything after the above one from ''templates/default/template.css'' (for table-based layouts) or ''/templates/limespired/template.css'' (for CSS-based layouts) into your own style sheet without any impact on your other styles.

==Internet Explorer conditional style sheets== 


Because of the marked discrepancies in rendering between IE6 & IE7 and the other browsers, there are special IE conditional style sheets included for each template.


<source lang="html4strict" enclose="div">



</source>


You should include the above code within your '''startpage.pstpl''' and copies of both the IE style sheets from either ''/templates/default/'' or ''/templates/limespired'' for Tables base layout and CSS based layout respectively.


<div class="simplebox">'''Note:''' If you copy the styles into your own style sheet you will almost certainly need to tweak them.</div>

===Alternative solution for Internet explorer=== 


You can put a conditional class for body in startpage.pstpl and use this class in your template.css. This method is used in the citronade template{{ObsoleteIn|2.06}}. Adding a js / no-js class to have javascript / no javascript system.


<source lang="html4strict">



<body id="body" class="lang-{SURVEYLANGUAGE} {SURVEYFORMAT} no-js">
<script type='text/javascript'>/*<![CDATA[*/(function(H){ H.className=H.className.replace(/\bno-js\b/,'js') })(document.getElementsByTagName('body')[0]);/*]]>*/</script></source>


And in template.css use:


<source lang="css">.ie6{/*specific for internet explorer 6*/}
.ielt8{/*specific for internet explorer 6 and 7*/}
.ie{/*specific for all internet explorer */}</source>

== Right-to-Left (RTL) Languages and justify== 


The text editor within LimeSurvey is able to format RTL text. However, the editor itself shows the RTL language in a left to right format when justified. This is just an editor display issue. The RTL and justified question or text will display correctly from right to left, even when justified, in your survey or on preview.

==Keywords== 


{{Deprecated|3.0}}


Keywords within a template file get replaced by the current survey information. They are surrounded by curly brackets, for example: {SURVEYNAME}.


The following strings will be replaced by LimeSurvey when parsing the template file and presenting it to survey users. These field strings will work on almost every template except for the 'Completed Page'. (Most of these strings can be found in the common.php file. If it's not there, look in the index.php file.)


{|class=wikitable
!'''Keyword'''!!'''Template files'''!!'''Description'''
|-
|{SURVEYNAME}||All Files||The survey title
|-
|{SURVEYDESCRIPTION}||All Files||The survey description
|-
|{WELCOME}||All files (mainly for welcome.pstpl)||The survey 'welcome' text
|-
|{PERCENTCOMPLETE}||survey.pstpl||A small graph showing the percentage of the survey completed
|-
|{GROUPNAME}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group name
|-
|{GROUPDESCRIPTION}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group description
|-
|{NUMBEROFQUESTIONS}||welcome.pstpl||Displays the total number of questions in the survey (just the number)
|-
|{THEREAREXQUESTIONS}||welcome.pstpl||Displays the sentence "There are X questions in this survey" - from the relevant language file. The X is replaced with the number of questions. Note that this will also work appropriately for singular or plural. If there is only 1 question, it will print "There is 1 question in this survey".
|-
|{CHECKJAVASCRIPT}||All files (mainly for welcome.pstpl)||Warning message when end-user browser have javascript disabled
|-
|{QUESTION}||Question.pstpl||('''Has been superseeded as of LS1.87''') Displays the current question text (The format of {QUESTION} can customised by editing 'question_start.pstpl') Use the following: {QUESTION_TEXT}, {QUESTION_MANDATORY}, {QUESTION_HELP}, {QUESTION_MAN_MESSAGE}, {QUESTION_VALID_MESSAGE}, {QUESTION_INPUT_ERROR_CLASS}, and appropriate wrapping HTML instead of {QUESTION}
|-
|{ANSWER}||question.pstpl, print_question.pstpl||presents the answer form for the current question
|-
|{SGQ}||question.pstpl, question text||Can be used in the question text itself to reference the input field of the question dynamically by displaying the Survey-Group-Question id for the current question. (as of svn build 9755)
|-
|{QUESTIONHELP}||question.pstpl, print_question.pstpl||Displays help text (predefined tip for question type) for the current question
|-
|{QUESTION_CLASS}||question.pstpl, print_question.pstpl||unique class for each question type. (To be included in the question's wrapping tag.)
|-
|{QUESTION_CODE}||question.pstpl, print_question.pstpl||Displays the current question code
|-
|{QUESTION_ESSENTIALS}||question.pstpl||the question ID and (if a question is conditional), 'style="display:none;"'. (To be included in the question's wrapping tag.)
|-
|{QUESTION_HELP}||question.pstp, question_start.pstpl||Displays the user defined help text for the current question
|-
|{QUESTION_TYPE_HELP}||print_question.pstp||Displays the user defined help text for the current question
|-
|{QUESTION_INPUT_ERROR_CLASS}||question.pstp, question_start.pstpl||Provides a class if there was user input error
|-
|{QUESTION_ID}||print_question.pstp||Provides a unique ID for each question to allow styling for specific questions
|-
|{QUESTION_TEXT}||question.pstp, print_question.pstp, question_start.pstpl||Displays the text for the current question
|-
|{QUESTION_MANDATORY}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' text for the current question
|-
|{QUESTION_MAN_CLASS}||question.pstpl, print_question.pstpl||class if a question is mandatory. (To be included in the question's wrapping tag.)
|-
|{QUESTION_MAN_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' help message text for the current question
|-
|{QUESTION_NUMBER}||print_question.pstpl||Incremental count of questions.
|-
|{QUESTION_VALID_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated valid help message text for the current question
|-
|{QUESTION_SCENARIO}||print_question.pstp||Prints out the 'scenario' text for conditional questions.
|-
|{NAVIGATOR}||navigator.pstpl||Displays navigation buttons (next, prev, last)
|-
|{CLEARALL}||All files (but intended for navigator.pstpl)||Displays the "Exit and Clear Results" link
|-
|{COMPLETED}||completed.pstpl||Displays the 'completed' message for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{URL}||completed.pstpl||Displays the survey 'url' and 'url text'
|-
|{PRIVACYMESSAGE}||privacy.pstpl||The privacy message is shown if you set your survey to be anonymous. [[Translating LimeSurvey|The text can be edited/translated]] in the language files. This can also be changed manually by editing the privacy.pstpl template you wish to use.
|-
|{TEMPLATEURL}||All Files||The URL to the current template location (useful for referencing image files in your template)
|-
|{SURVEYRESOURCESURL}||All Files||The URL to the current uploaded files for this survey location (useful for referencing image files in your question, group, ....)
|-
|{SUBMITCOMPLETE}||endpage.pstpl||The statement (from the language files) that tells the user they have completed the survey, and to press the "Submit" button
|-
|{SUBMITREVIEW}||survey.pstpl||The statement (from the language files) that tells the user they can review/change the answers they have made by clicking "<< prev"
|-
|{SAVEDID}||All Files||Displays 'Response ID' of user
|-
|-
|{QUEXMLPDF}||All Files||Displays button to export the queXML PDF of questionnaire including answers entered up until the point that has been completed in the survey.
|-
|{TOKEN:FIRSTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users first name from the tokens table
|-
|{TOKEN:LASTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users last name from the tokens table***
|-
|{TOKEN:EMAIL}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users email from the tokens table***
|-
|{TOKEN:ATTRIBUTE_1}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_1 from the tokens table***
|-
|{TOKEN:ATTRIBUTE_2}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_2 from the tokens table***
|-
|{ANSWERSCLEARED}||Preferably in navigator.pstpl||The "Answers Cleared" statement from the language files
|-
|{RESTART}||clearall.pstpl||URL to restart the survey
|-
|{REGISTERERROR}||register.pstpl||Shows any error messages in the register page (ie: "You must include an email address")
|-
|{REGISTERMESSAGE1}||register.pstpl||The statement "You must be registered to complete this survey" from the language files
|-
|{REGISTERMESSAGE2}||register.pstpl||Details about registering from the language files
|-
|{REGISTERFORM}||register.pstpl||The actual form for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{SAVE}||Works suitable on navigator.pstpl||Displays the 'Save your responses so far' button to offer the user to save and come back later to continue the survey. If the Save option is deactivated in the survey properties the tag will not be shown and ignored.
|-
|{LANGUAGECHANGER}||survey.pstpl||Displays a switch in multilingual surveys to change the question.
|}

==Input/Buttons== 


Each "input" type in a survey has been given its own class name, so that you can add CSS to your "startpage.pstpl" file and have some control over the appearance of form buttons and inputs. These class names are as follows:
*'''submit''' (Submit Buttons)
*'''text''' (Text Inputs - for short free text, date, and numerical type)
*'''answertext''' (Text of answers)
*'''radio''' (Radio Buttons)
*'''checkbox''' (Check Boxes)
*'''select''' (Select / List Boxes)
*'''textarea''' (Large text inputs - for long free text)
*'''clearall''' (The "Exit and Clear Survey" link)
*'''rank''' (The rank style question. Doesn't set the colour of the select box or the text boxes, but it does allow the changing of background colour, text colour, size etc., for the rest of the ranking question)
*'''graph''' (The "percentage completed" graph table)
*'''innergraph''' (The table inside the graph table - this contains the 0% and 100% text. Use this for changing the size of this text)
*'''question''' (General settings for any question that is displayed within a table. Generally, you should use this to make sure that their font size and color is the same as you have used elsewhere as a default)
*'''mandatory''' (Mandatory questions)
*'''input-error''' (User input error - for if a user has made a mistake with a mandatory question or question with validation)
*'''array1''' and '''array2''' (These two styles are cycled when presenting the range of answers for an array type question. This allows you to set an alternating background color for these question types. '''Array1''' is also used for the column headings in these question types)
*'''errormandatory''' (Sets the color and style of the "This question is mandatory" error message)
*'''warningjs''' (Sets the color and style of the warning message displayed if the participant's browser has javascript disabled)


There are also some elements that can be accessed using the ID of the element ('''#ID''' in CSS):
*'''surveycontact''' (The contact message shown on the start page)
*'''tokenmessage''' (used for messages inside the survey, e.g. the session expired error message)


Because you can edit all the HTML aspects, there's no reason to surround your templates with a
<syntaxhighlight lang="php" enclose="div"><div class='new_name'></div></syntaxhighlight>
and then define a css for that new_name class.

==Styling the progress bar== 


The progress bar appearance can be modified with CSS.


To change the background color of the bar, add something like the following to the end of your template.css file:


<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-header {
background-color: #3300FF;
}</syntaxhighlight>


To change the border color of the bar, add something like the following to the end of your template.css file:


<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-content,
#progress-wrapper .ui-widget-header {
border: 1px solid #FF0000;
}</syntaxhighlight>

==Advanced Features Available to Developers== 


LimeSurvey has integrated some user-made patches that permits some special changes. These very advanced features (generally) require changes to the underlying code base of LimeSurvey and should be done carefully in order not to introduce security holes.

===Support for your own Javascript functions=== 


Some users may need to run Javascript on the survey pages, but calling '''checkconditions()''' in the BODY element made it impossible to do so. This call has been replaced with a small JavaScript function in the HEAD that sniffs for the existence of '''checkconditions()''' and '''template_onload()''' before calling them. In this way, a template author can create his or her own '''template_onload()''' function in the HEAD that replaces the default one.


*Disable XSS filter - in Global settings -> Security, set "Filter HTML for XSS" to No.
*Enter your script in the source of a question or group description.


{{Note|For further details, see the [[Workarounds: Manipulating a survey at runtime using Javascript#How to use Script (eg. JavaScript etc.) in LimeSurvey|workaround section]].}}

=Videos on Templates= 


This video will demonstrate the basic and advanced template functions that are available to all LimeSurvey users. This includes changing the appearance of certain forms and inserting custom graphics. Additionally, it will thoroughly walk you through on how to edit and preview specific page templates, importing/exporting templates, modify appearance of questions in the CSS, and customizing survey description page.


Video - needed

=Tips & Tricks= 

==Some language specific element== 


If you want to have some language specific sentence in a survey, for example a help at the end of each page, you can add in a .pstl file a sentence and hidding it for other language. If we hide it in the template.css, we can use the pseudo selector :lang, but we use some class for better compatibility.


Below, there are two help sentences, in French and English. Put this on endpage.pstpl:


<syntaxhighlight lang="php" enclose="div"><div class="fr" lang="fr">Pour de l'aide en direct appelez le 000000</div>
<div class="en" lang="en">For some help, please call 000000</div></syntaxhighlight>


and in template.css:


<syntaxhighlight lang="php" enclose="div">.lang-fr .en{display:none}
.lang-en .fr{display:none}</syntaxhighlight>

==Change the layout of the survey page== 


After editing and saving a template, it applies to a survey list page only if it is selected from the settings of the survey. To make it the default template, go under the '''General tab''' located in the '''Global settings''' of your LimeSurvey installation and choose the desired template. From now on, all the templates that use the "default" option as template plus the ones that are going to be newly created, will use the newly selected default template.


To use your current template for this page, you have to change the according setting from '''Global settings'''. In older versions, this change can be done by editing the $defaulttemplate setting from the config file: copy this setting from config-defaults.php to config.php which overrides config-defaults.php and edit this setting to <code lang="html">$defaulttemplate = 'yourtemplatename';</code>.

==Import/Export of templates: Mac users== 


<u>Mac users</u>, please note that the Mac OSX default archive utility may have problems with zip folders "generated on the fly".


A workaround is to unix'es unzip from the command line:


$ unzip template.zip -d template


Archive: template.zip


inflating: template/startpage


inflating: ...


Another workaround is to use scripts in their mac-compiled counterparts.

==Replacing the help icon {{ObsoleteIn|2.50}} == 


When a question help text is shown, then an help.gif image is used from the default template folder.


You can replace this image by uploading a new help.gif, help.png or help.jpg in your custom template folder. It will then be automatically used instead of the default help icon.

==Replacing an existing logo {{NewIn|2.50}} {{ObsoleteIn|3.0}}== 


'''Note''': In the '''default'' Template of 2.50, there is no preembedded logo. Read further our [[#Adding_your_own_logo |wiki on how to add your own logo]].


1. To edit the logo go to the ''<u>template.css</u>'' file which you can find it here:


<center>[[File:t1.PNG|200px]]</center>


2. Click the search button to find occurrences of logo related styles and search for ''logo''


<center>[[File:2.png|200px]]</center>


4. Edit the main style file.


You will see something similar to:


<center>[[File:t4.PNG|500px]]</center>


If you want to change the image, just replace logo.gif with another image link. Example: (<u>logo.png</u> or <u>logo.jpg</u>).


If you want to change the image size, adjust width and height (in pixels) like this:


<syntaxhighlight lang="php" enclose="div">width:100px; height:100px;</syntaxhighlight>

==Adding your own logo {{ObsoleteIn|3.0}} == 


1. Find and open the '''startpage.pstpl''' template file.


<center>[[File:startpage.pstpl.png]]</center>


2. After this
<source lang="html4strict" ><div id="topContainer" class="jumbotron"></source>
add this line to '''startpage.pstpl''':
<source lang="html4strict">
<div class="container"><img id='page_logo' src='{TEMPLATEURL}/files/logo.png' class="clearfix pull-right" /></div>
</source>


3. To upload your own logo, go to the template editor and upload your logo.


<center>[[File:uploadyourlogo.png]]</center>


To position your logo, please use one of the following css classes:


*'''If you want the logo to be placed on the left side:'''


<source lang="html">clearfix pull-left</source>


*'''If you want the logo to be placed on the right side:'''


<source lang="html">clearfix pull-right</source>


*'''If you want to center the logo'''


<source lang="html">clearfix center-block</source>

==Use the same template with different logos== 


If you want to use the same template for all surveys and just want to change the logo for each survey, you can use the {SID} placeholder in the template .pstpl file and thereby refer to different images:


<syntaxhighlight lang="php" enclose="div"><img src="{TEMPLATEURL}files/logoImage-{SID}.png"></syntaxhighlight>

==Remove the default help to all question (hide_tip) {{ObsoleteIn|1.92}}== 


There are 3 solutions to remove the default help:
# like a hide_tip attribute but for all question and survey.
# you can remove the {QUESTIONHELP} and its container from the file question.pstl. However, it can be a bad idea for the screenreader.
# for the default template and some other, add this at the end of tempate.css


<syntaxhighlight lang="php" enclose="div">span.questionhelp{display:none;}</syntaxhighlight>

== Display custom favicon== 


A favicon is the little icon you see in the browser's address bar, list of bookmarks or tab. You can display your own icon as follows:
#Create a favicon - google will find you lots of free favicon generators.
#Name your new favicon "favicon.ico" and place it in your template /files directory.
#Add the following code to your '''startpage.pstpl''' before the </head> tag.


<syntaxhighlight lang="html4strict" enclose="div"><link rel="shortcut icon" href="{TEMPLATEURL}files/favicon.ico" type="image/x-icon">
<link rel="icon" href="{TEMPLATEURL}files/favicon.ico" type="image/x-icon"></syntaxhighlight>

== Different appearance for survey-/question-pages== 


If you want LimeSurvey to change the appearance of every second page (i.e. of even and odd survey pages), you can use '''.page-odd''' class in your CSS file to change the appearance of odd pages.


An example from default template of LimeSurvey 1.91+:


<syntaxhighlight lang="php" enclose="div">
.page-odd table.question-group {
background-color: #D2F2D3;
}</syntaxhighlight>


If you do '''not''' want differentiate even and odd pages, find all instances of ''.page-odd'' in template.css and remove those styles.

==Create a vertical separator border for dual scale array== 


To create a vertical separator border for a dual scale array, you can add the following lines to your '''template.css'''-file.


<syntaxhighlight lang="php" enclose="div">
table.question thead td.header_separator,
table.question tbody td.dual_scale_separator
{
border-right:solid 1px #00A8E1;
}
</syntaxhighlight>


''header_separator'' is used to adress the separator for the header "td". The "dual_scale_separator" is used to address the separator column in the dual scale array.

==Hide the survey contact message shown on the start page/survey list {{ObsoleteIn|3.0}} == 


To hide the "Please contact ..." message on the start page (with the survey list), you can add the following to the '''$(document).ready''' function in the '''template.js''' of your used design template:


<syntaxhighlight lang="php" enclose="div">


$('#surveycontact').hide(); //Hides the survey contact message


</syntaxhighlight>

==Remove the survey contact message shown on error messages {{ObsoleteIn|3.0}}== 


If you want to remove the survey contact message from error messages, it'll be trickier. You can add the function from below. It calls the '''$(document).ready''' function in the '''template.css''' of your used design template:


<syntaxhighlight lang="php" enclose="div">
removeContactAdressFromMessage(); //Removes the survey contact message from error messages
</syntaxhighlight>


and add the following function to your *template.js* file


<syntaxhighlight lang="php" enclose="div">
function removeContactAdressFromMessage()
{
if ($('#tokenmessage').length > 0)
{
var oldMessage = $('#tokenmessage').html();
var indexContact = oldMessage.indexOf('Bitte kontaktieren');
var newMessage = oldMessage.substr(0, indexContact);
$('#tokenmessage').html(newMessage);
}
}
</syntaxhighlight>


It will probably not work for a survey in English language and has to be extended when used for multilingual surveys. But it's an idea/tip on how to solve this.

==How to deal with multilingual question attributes {{ObsoleteIn|2.50}}== 


If you have a multilingual survey and e. g. want to use a different string for the "other" field, this could only be done for the base language (until this feature was added at LimeSurvey 2.0). To work around this, paste in the field to change the label for "other":


<syntaxhighlight lang="php" enclose="div"><span class="en">New label</span><span class="fr">Nouveau label</span></syntaxhighlight>


Add in the template.css of your template (at ''/limesurvey/upload/templates/<yourtemplatename>/template.css''):


<syntaxhighlight lang="php" enclose="div">html:lang(en) .fr{display:none}
html:lang(fr) .en{display:none}</syntaxhighlight>

==Adding your own logo to the survey list {{ NewIn|3.0}} == 


# First please open the theme editor for the theme you like to use. [[File:OpenThemeEditor.jpg]]
# We recommend to use fruity, it is our best theme currently.
# Then extend the theme and give it a name you will recognize. [[File:ExtendTheme.jpg]]
# In the following view you may upload the logo you want to use. [[File:UploadFileTheme.jpg]]
# Select the editor screen `Survey List´ in the Screen dropdown in the top right corner. [[File:OpenScreenSurveyList.jpg]]
# Then select `layout_survey_list.twig´ in the left side menu. [[File:EditLayoutSurveyListTwig.jpg]]
# In the editor scroll to line 126 and change the marked part to the filename of the image you uploaded to the theme before. [[File:ChangeSurveyListHeaderImageEditor.jpg]]
# Save your file. [[File:ThemeEditorSaveChanges.jpg]]
# Change default theme to your extended theme. [[File:ChangeDefaultTheme.jpg]]

=Custom Question Views {{NewIn|3.0}}= 


<div class="simplebox">'''Note:''' This is a temporary feature to be replaced in the future by question object (it will be very easy to move custom views to question object). It is disabled by default.</div>


As of version 2.5, you can create template-specific custom views for questions and some of their incorporated elements. This is useful if you want to modify the HTML layout of a particular question type for one or more surveys.


*In application/config/config.php, find 'config'=>array and add this line to the array : 'allow_templates_to_overwrite_views'=>1
*In /{your_template}/config.xml, set "overwrite_question_views" to true
*Copy application/views/survey/* to template/{your_view_directory}/survey/
*Note that you only need to copy the files that you intend to modify but the file structure must remain the same as in application/views/survey/

=Insert Custom CSS or JavaScript files for template {{NewIn|2.50}}= 


As of version 2.50, you can use the config.xml file to automatically load plugin files.


*Upload your files to the template /css or /scripts folder
*In /{your_template}/config.xml, add the file paths to the <css> or <js> blocks, something like this:<syntaxhighlight lang="xml" enclose="div"><css>
<filename>css/jquery-ui-custom.css</filename>
<filename>css/bootstrap-slider.css</filename>


<filename>css/awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</filename>
<filename>css/flat_and_modern.css</filename>


<filename>css/template.css</filename>


<filename>css/myCustomPlugin.css</filename>
</css>
<js>
<filename>scripts/template.js</filename>
<filename>scripts/bootstrap-slider.js</filename>


<filename>scripts/myCustomPlugin.js</filename>
</js>
</syntaxhighlight>

</translate>

Theme editor

2018-04-04T10:33:13Z

LouisGac:

<languages /> <translate>

=Introduction= 


LimeSurvey has an advanced theme and style system providing to developers an efficient way to customize the survey appearance. Since LS3, we're not speaking anymore about '''"templates"''' like in previous versions, but about '''"themes"'''. The '''themes''' allow control over the look and feel of pages during a survey. A survey administrator can select a default theme that will be used for each survey to further personalize it and improve its look and feel. '''Themes''' come with options that provide to admin without coding skill a simple way to add a logo on the welcome page, to change the background colors, to select a font, etc.


LimeSurvey comes with 3 themes right out of the box. These initial themes are defined by directories located in the LimeSurvey installation "themes/survey/" directory. Each theme has it's own directory. Within the main directory of a theme you'll find a configuration file in XML, and numerous directories containing the views ''themes (.twig)''', '''cascading style sheets (.css)''', '''scripts''', '''images''' ('''.jpg''' or '''.png'''), and maybe others.


Since LimeSurvey 2.50, the theme engine use [http://getbootstrap.com/docs/3.3/ Bootstrap 3] as CSS framework. Bootstrap 3 being a standard framework, developers will find a lot of documentation, tutorials and forum threads about it on Internet.

Since LimeSurvey 3, the theme engine use [https://twig.symfony.com Twig], so the theme developers can change the logic of the survey rendering in a safe and easy way. Twig replace the old system of replacement keywords that was used in the previous versions. The logic that was used to generate the HTML of the keywords are now available inside the theme's views.

Snippet from Vanilla Theme:


<syntaxhighlight lang="twig" enclose="div">
<div class="{{ aSurveyInfo.class.answercontainer }} col-xs-12" {{ aSurveyInfo.attr.answercontainer }}>
{# NOTE: If you want to customize the question rendering, use a question theme #}
{{ aQuestion.answer | raw }}
</div>
</syntaxhighlight>


Themes, being HTML and Twig code, tend to define the positioning and type of text to be displayed and similar structural features of the page. They often reference or include other files. Most of them reference a common cascading style sheets (CSS) file that defines the font style, color, size, background, and similar parameters common to all pages in the survey. Style sheets reference HTML '''class''' parameters that are associated with the various types of objects in the HTML code. This allows the style sheet to describe how to display each of the many types of text or other objects that may appear in multiple places. There are unique classes for each question type in LimeSurvey and thus giving detailed control over the appearance of each. Image files, like logos or special progress-bar constructors, may be referenced as well in the Theme file. Finally, special keywords in curly braces are replaced with text defined in the survey for each language translation correspondent (for example, the 'Survey Title' or 'Question Text' for each language defined).


If you create a new custom theme, please consider contributing it back to the LimeSurvey community and make it available to others. With your help, we can grow our repository of themes, surveys, and other add-ons to make LimeSurvey even better!
See our [https://www.limesurvey.org/index.php?option=com_sobipro&sid=55:Templates&Itemid=729 LimeSurvey template repository] where you can share your templates.

=Creating a new theme= 


To be able to create a new theme (or edit an existing theme), you need [[Manage users#Set global permissions for a user|Template Editing user permission]] in LimeSurvey as well as permission to manipulate the files in the underlying operating system hosting your LimeSurvey installation.


<div class="simplebox"><span style='color:red'>'''Note of Warning:'''</span> If you change themes, you could also affect all the pre-existing surveys from your LimeSurvey installation. Themes are an advanced feature that require experience and HTML knowledge in order to make them running smoothly.</div>


The preferred way to create a new theme is through the '''Theme Editor''' (see below), which is located in the '''Configuration''' dialog. Some people may like to work directly with theme files so that they can use their favorite text editor instead of the web interface. In this case, still use the Theme Editor to first create your new theme. This will create a new base theme with all the files you need in the ''LimeSurvey_web_root/upload/themes/survey/your_new_template'' directory. From there you can use your text editor to manually adjust the template files.


<div class="simplebox">'''Permissions Note:''' on unix/linux systems, these theme files will be owned by the group and user where the web server is running (may be "www" for some systems). So, make sure you have enough access to edit these files, When you save them, make sure they don't change ownership! In this way, you can still use the web Theme Editing interface if needed.</div><br />


A number of 'public' elements of LimeSurvey can be adjusted by a series of themes. The next section provides a very brief explanation of these templates.


{{Note|Themes files may seem complex. Besides HTML, you might also need to understand CSS, Twig, and JavaScript.}}

=The LimeSurvey template editor= 


To ease the understanding and quick update of a Template, LimeSurvey provides a '''Template Editor''' in the main '''administrative''' toolbar of the application. This Template Editor is only available to users [[Manage users#Set global permissions for a user|with the Templates permission]] and to superadministrators.


{{Alert|title=Attention|text=A template that is not correctly constructed can render a survey (that uses the respective template) inoperable. }}


The LimeSurvey template editor allows you to edit the contents of your templates online. Start the Template Editor by clicking on '''Template editor''' in the '''Configuration''' menu.


[[File:templates.png]]


The template editor page allows you to select the template you would like to edit/view.


[[File:Template-editor-2013-7-10_11_38_16.png|center]]

==The template menu== 


The following options are available:


*'''Create''': Allows you to create a new template. In order not to start from scratch, the template 'default' is copied.
*'''Import''': Allows you to import a template from a ZIP file.
*'''Export''': Allows you to export the current template to a ZIP file.
*'''Copy''': Allows you to make a new template by copying the current one.
*'''Rename''': Allows you to change the name of the template. It is generally used after copying or importing a template.
*'''Template''': It is a drop-down list that shows all the available templates that are located in your LimeSurvey installation.


*'''Screen''': It is a drop-down list which allows you to choose which particular survey page of that template you want to look at.
*'''Return to admin panel'''.

==Import/export/copy a template== 


When you '''export '''a template, a ZIP-file archive with all the files your template consists of will be created (.pstpl files, images, css files, ...). You can simply '''import''' the exported zip-file into another LimeSurvey installation by using the import feature or you can manually copy the archive into another LimeSurvey installation and extract it into the corresponding [[Theme editor#Template files location|template directory there]].


However, it is preferred to use the LimeSurvey template import/export/copy functions in the template editor.

==Page Structure / Template Use== 
*'''The Welcome Page:''' startpage.pstpl, welcome.pstpl, privacy.pstpl, navigator.pstpl, endpage.pstpl
*'''The Questions Pages:''' startpage.pstpl, survey.pstpl, startgroup.pstpl, groupdescription.pstpl, question.pstpl, endgroup.pstpl, endpage.pstpl
*'''The Final Page:''' startpage.pstpl, assessment.pstpl, completed.pstpl, endpage.pstpl

==Template Files== 


The following template files are used to produce your public survey and must exist in any new template folder you create:
*'''startpage.pstpl:''' Produces the start of each html page. It starts at the "<head>" tag, and should not contain the "<html>" tag. This 'very beginning' of a standard html page is written by the scripts. Please ensure that your startpage.pstpl files contains a <body> tag. Even though many browsers do not require strict adherence to the W3 HTML standards, the LimeSurvey script needs to find a <body> tag to run certain javascript elements. It is not expected to see many 'keywords' used in the startpage.pstpl file. However, you may wish to put the {SURVEYNAME} into the title. The startpage.pstpl file can contain code that ends in the corresponding endpage.pstpl file. For example, you can start a table in this file and close the table in the endpage.pstpl file. The startpage.pstpl and endpage.pstpl files wrap around every possible page used by LimeSurvey.
*'''survey.pstpl:''' This template is the second used on most pages and provides a space to put the survey name and description. This template does not have a corresponding 'closing' template, and subsequently you should close all tags opened in this template file (i.e.: don't leave a table open here because there is nowhere else to close it).
*'''welcome.pstpl:''' This template is only used in the welcome screen (which is also on the main page for 'all in one' surveys). You can use this to print out the welcome text, and other information that should be provided in the introduction. Like the 'survey.pstpl' file, there is no corresponding 'closing' template, so all tags opened in this template file should be closed as well.
*'''startgroup.pstpl:''' This template can provide a 'summary' wrap around for questions within a group. It has a matching 'endgroup.pstpl' template that can be used to close any opened tags in this file, so you can open a table within this.
*'''groupdescription.pstpl:''' This template file is used to display a description of a group. Please note that in the survey settings (access the ''Presentation & navigation settings'' by clicking on the '''Presentation''' tab) you can set if the group description should be shown or not. If not, then this file is not included at all.
*'''question.pstpl:''' This file contains the question, answer, and help text sections of your survey. In the "group by group" and "all in one" surveys, this template is cycled repeatedly with each question. There is no corresponding closing file for this and all tags should be closed.
*'''question_start.pstpl:''' This file contains the individual elements found at the start of a question. It is included within 'question.pstpl' via the {QUESTION} keyword. It is intended to allow template designers more control over the layout of a question. This template sits outside the normal templating system and '''was superseeded (as of LimeSurvey 1.87)'''. All keywords from this template are now available directly in question.pstpl.
*'''completed.pstpl:''' This page is displayed as the final page when the survey responses have been saved and the survey is over. It can be used to display a "forwarding link" as set in the survey setup.
*'''endgroup.pstpl:''' This file closes the group, and can be used to close off any tags opened in the startgroup.pstpl file
*'''navigator.pstpl:''' This file contains the buttons that navigate through the survey, "next", "prev", "last", "submit", "save so far" and the "clear all" link. It is used in all pages except the completed page.
*'''printanswers.pstpl:''' This file has the HTML wrapper necessary for the print version of the survey.
*'''print_group.pstpl:''' This file is the same as startgroup.pstpl and endgroup.pstpl, but for the print version of the survey.
*'''print_question.pstpl:''' This file is the same as question.pstpl, but for the print version of the survey.
*'''print_survey.pstpl:''' This file is the same as survey.pstpl, but for the print version of the survey.

== CSS and Javascript== 


Two files that are always used in a template are template.css (for CSS) and template.js (for Javascript).
*'''{TEMPLATECSS}:''' Add lines for default css, template.css, and template-rtl.css for rtl language.
*'''{TEMPLATEJS}:''' Add lines for default javascript files, template.js, and all js files needed for LimeSurvey.

=== Using Bootstrap=== 
LimeSurvey has Bootstrap 3 embedded, so you can style all your templates with the well documented Bootstrap classes.
For more information please refer to the [https://getbootstrap.com Bootstrap documentation].


The [https://github.com/flatlogic/awesome-bootstrap-checkbox Awesome-Bootstrap-Checkbox] plugin is also included. With it, you can use the typical Bootstrap color-classes (info,warning,danger,etc.) also with the suffix "-checkbox" or "-radio", though styling checkboxes and radios as you prefer.

=== Replacing default CSS or Javascript=== 


Some questions use specific files for Javascript or CSS. If you need to replace a function, use a cascading system. For javascript function, the last function read is the function used.

==Other Template Files== 


The '''privacy.pstpl''', '''invitationemail.pstpl''', '''reminderemail.pstpl''', and '''confirmationemail.pstpl''' are no longer used by LimeSurvey and defaults are instead set in the applicable language files. The email messages can now be edited on a survey by survey basis.

==Standard Pages== 


There are ten standard pages that a survey participant may see in the course of taking or accessing the LimeSurvey application. Each is constructed from a number of common '''Template''' files from the '''Template''' specified in the settings of the survey. The table below indicates which template files are used in constructing each of these pages.


{| class="wikitable"
! '''Survey Pages/'''<br />'''Template Files'''!!Survey<br />List!!Welcome!!Question!!Completed!!Clear All!!Register!!Load!!Save!!Print<br />Answers!!Print<br />Survey
|-
|SurveyList||align="center" | [[File:check.gif]]|| || || || || || || || ||
|-
|Welcome|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Privacy|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Navigator|| ||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Survey|| || ||align="center" | [[File:check.gif]]|| || ||align="center" | [[File:check.gif]]|| || || ||
|-
|StartGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|GroupDescription|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Question<span style='color:red'>'''*'''</span>|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|EndGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Assessment|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|Completed|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|ClearAll|| || || || ||align="center" | [[File:check.gif]]|| || || || ||
|-
|Register|| || || || || ||align="center" | [[File:check.gif]]|| || || ||
|-
|Load|| || || || || || ||align="center" | [[File:check.gif]]|| || ||
|-
|Save|| || || || || || || ||align="center" | [[File:check.gif]]|| ||
|-
|PrintAnswers|| || || || || || || || ||align="center" | [[File:check.gif]]||
|-
|Print Survey || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Group || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Question || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|StartPage<br />EndPage<br />Template.css||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||
|}


<span style='color:red'>'''*'''</span>NOTE: In version 1.90+, this replaces question.pstpl AND question_start.pstpl. If you are using an old custom template, you need to add the following line to the beginning of question.pstpl:<syntaxhighlight lang="php" enclose="div"><div {QUESTION_ESSENTIALS} class="{QUESTION_CLASS}{QUESTION_MAN_CLASS}{QUESTION_INPUT_ERROR_CLASS}"></syntaxhighlight>And then add the corresponding closing tag to the end of question.pstpl:<syntaxhighlight lang="php" enclose="div"></div></syntaxhighlight>


<span style='color:red'>'''*'''</span>NOTE: In version 1.91 and earlier, LimeSurvey js files are not included in the template. In version 2, '''you have to use {TEMPLATEJS} in one of your template file''' to add the link to the js file. You can add it in startpage.pstpl or in endpage.pstpl. You can remove the {TEMPLATEURL}/template.js line and you have to replace with {TEMPLATEJS} to update a personal template.

==The File Control Section== 


In the "file control" window on the left, you can click on one of the template files that is used to compile the page. You can see the ''Screen part'', JavaScript, and CSS files. The HTML code for that file will then appear in the "Now editing" window in the center. If the template is editable (determined by directory permissions) you can then make any changes and save them.


<center>[[File:File Control Section.png|center]]</center>


The "Other files" window shows a list of all other files from the template directory. You can use the right side to '''upload and select image files (your pics, logos,...) or other files needed to create your template'''.


Instead of using a link for each picture, utilize the field string {TEMPLATEURL}. So, instead of:


<syntaxhighlight lang="html4strict" enclose="div">img src='/limesurvey/templates/yourtemplate/files/mypicture.jpg'</syntaxhighlight>
You can use {{NewIn|2.50}}:
<syntaxhighlight lang="html4strict" enclose="div">img src='{TEMPLATEURL}files/mypicture.jpg'</syntaxhighlight>


In LimeSurvey versions before 2.50 use:
<syntaxhighlight lang="html4strict" enclose="div">img src='{TEMPLATEURL}mypicture.jpg'</syntaxhighlight>


A "sample" of the template page you are editing will be visible in the bottom of the screen. There is no way to delete a template from the template editor. This must be done by accessing the underlying directory and deleting manually the files from there. You also have the possibility to select different screen resolutions in order to better evaluate the feel and look of the template.


<div class="simplebox">'''Note:''' The shipped templates cannot be edited using the template editor. If you want to modify them, create a copy first and edit the copy.</div>

==Template files location== 


LimeSurvey stores each of the 'standard' templates in their own distinct sub-directory within the ''/templates'' directory that is kept in the public directory with the other LimeSurvey public files. Customized user templates are stored in the ''/upload/templates'' directory.


There should '''ALWAYS''' be a "default" directory in the templates directory. This template is used by default and as a fall-back if a template folder doesn't exist, or can't be found. It comes installed by default.


You can use any image files that you upload into the template management area with the help of this syntax:


<syntaxhighlight lang="php" enclose="div">{TEMPLATEURL}filename.xyz</syntaxhighlight>

=Styling questions with CSS= 


Styling of questions in CSS has become much easier. Each question type has now a unique class. The mandatory questions have an additional mandatory class. For example, for a non-mandatory question:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender">
...
</div></syntaxhighlight>


and if the question is mandatory:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory">
...
</div></syntaxhighlight>


and if the question is mandatory, but the user didn't answer it or if there is validation on a question:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory input-error">
...
</div></syntaxhighlight>


and if the question has validation applied, but the user hasn't answered correctly:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question6" class="text-short input-error">
...
</div></syntaxhighlight>

==Global classes for question part== 


These classes are used for each question type. Some question types use only one or two classes, while others may use much more.


{| class="wikitable alternance"
|+ Global classes
|-
! scope="col" | Class name
! scope="col" | Part
! scope="col" | Question type
! scope="col" | Examples
! scope="col" | Note
|-
! scope="row" | .question {{ObsoleteIn|3.0}}
| All question block
| All question type
|<p class="question">, <ul class="question">, <table class="question">
|
|-
! scope="row" | .ls-answers {{NewIn|3.0}}
| All question block
| All question type
|<div class="ls-answers ">, <ul class="ls-answers ">, <table class="ls-answers">
|
|-
! scope="row" | .subquestions-list
| List of subquestion
| Multi choice question, array question type
| <ul class="subquestions-list">, <table class="subquestions-list">
| .questions-list is used too
|-
! scope="row" | .answers-list
| List of answers
| Single choice question, array question type, Multi input text question
| <ul class="answers-list">, <table class="answers-list">
|
|-
! scope="row" | .answer-item
| The answer part: one answer
| Single choice question, array question type, Multi input text question
| <li class="answer-item">, <td class="answer-item">
|
|-
! scope="row" | .noanswer-item
| The answer part for no answer
| Single choice question, array question type
| <li class="noanswer-item">, <td class="noanswer-item">
| No answer is an answer too, then have double class noanswer-item and answer-item
|-
! scope="row" | .question-item
| The question part: one question
| Multi text question, array question type
| <li class="question-item">, <tr class="question-item">
| Some answers are questions too. Then we have a lot of class="question-item answer-item"
|-
! scope="row" | .checkbox-list
| A list of checkbox
| Multi choice question, array number (checkbox) question type
| <ul class="checkbox-list">, <tr class="checkbox-list">
| Some question types use multi-list class, like checkbox with comment: class="checkbox-list text-list"
|-
! scope="row" | .checkbox-array {{NewIn|3.0}}
| A array of checkbox
| Array (numbers) with checkbox option
| <table class="checkbox-list">
|
|-
! scope="row" | .checkbox-item
| The answer part with a checkbox
| Multi choice question, array number (checkbox) question type
| <li class="checkbox-item">, <td class="checkbox-item">
|
|-
! scope="row" | .radio-list
| A list of radio item
| Single choice question, array question type (each row)
| <ul class="radio-list">, <tr class="radio-list">
|
|-
! scope="row" | .radio-array {{NewIn|3.0}}
| A array of radio item
| Array question type
| <table class="radio-array">
|
|-
! scope="row" | .radio-item
| The answer part with a radio
| Single choice question, array question type
| <li class="radio-item">, <td class="radio-item">
|
|-
! scope="row" | .text-list
| A list of text input
| Multi text question type, array of text
| <ul class="text-list">, <tr class="text-list">
|
|-
! scope="row" | .text-item
| The answer part of a text input
| Multi text question type, array of text
| <li class="text-item">, <td class="text-item">
|
|-
! scope="row" | .numeric-list
| A list of text input with numeric only answer
| Multi numeric question type, array of number
| <ul class="text-list numeric-list">, <tr class="text-list numeric-list">
|
|-
! scope="row" | .number-list
| A list of text input with numeric only answer (each row)
| Multi numeric question type, array of number
| <ul class="text-list numeric-list">, <tr class="text-list numeric-list">
|
|-
! scope="row" | .number-array {{NewIn|3.0}}
| The answer part of a numeric input
| Array of number
| <table class="number-array">
|
|-
! scope="row" | .select-list {{ObsoleteIn|2.50}}
| A list of select
| Array numbers, Dual scale array (select)
| <table class="select-list">
|
|-
! scope="row" | .dropdown-list {{NewIn|2.50}}
| A list of select
| Array numbers, Dual scale array (select) (each row)
| <table class="dropdown-list">
|
|-
! scope="row" | .dropdown-array {{NewIn|3.0}}
| A array of dropdown
| Array numbers, Dual scale array (select)
| <table class="dropdown-array">
|
|-
! scope="row" | .select-item {{ObsoleteIn|2.50}}
| The answer part of a select
| Array numbers, Dual scale array (select), single choice with select
| <p class="select-item">, <td class="select-item">
|
|-
! scope="row" | .dropdown-item {{NewIn|2.50}}
| The answer part of a select
| Array numbers, Dual scale array (select), single choice with select
| <p class="dropdown-item">, <td class="dropdown-item">
|
|-
! scope="row" | .hide {{ObsoleteIn|3.0}}
| Used for accessibility: hidden with css but read by screenreader, since 2.50 : you can use sr-only from bootstrap
| Short text question
| <label class="hide">
| Can be used for other purposes
|-
! scope="row" | .ls-js-hidden {{NewIn|3.0}}
| Used for part to be hidden if javascript is activated
| Button for example
| <div class="ls-js-hidden">
| LimeSurvey core used it, but you can use it too in your template
|-
! scope="row" | .ls-js-hidden-sr {{NewIn|3.0}}
| Used for accessibility: hide it if js is activated, but always show if user use a screenreader
| Button for example
| <a class="ls-js-hidden-sr">
| Button
|-
! scope="row" | .ls-no-js-hidden {{NewIn|3.0}}
| Used for part to be hidden if javascript is not activated
| Link
| <a class="ls-no-js-hidden">
| LimeSurvey core used it for inactive link if javascript is not activated
|-
! scope="row" | .ls-label-xs-visibility {{NewIn|3.0}}
| Label to be hidden in big screen, but show with little screen (with no more table) and to screenreader
| label
| <label class="ls-no-js-hidden">
| Used for label inside table cell of array question type
|-
! scope="row" | .ls-input-group-extra {{NewIn|3.0}}
| Same usage of boostrap input-group-addon, but without the border and the background.
| right suffix
| <div class="ls-input-group-extra">
| Used for right and left suffix (global)
|-
! scope="row" | .checkbox {{ObsoleteIn|3.0}}
| input[type=checkbox]
| Question with checkbox
| <input type="checkbox" class="checkbox">
| With modern browser: not needed, but some old browser need this
|-
! scope="row" | .radio {{ObsoleteIn|3.0}}
| input[type=radio]
| Question with radio
| <input type="radio" class="radio">
| With modern browser: not needed, but some old browser need this
|-
! scope="row" | .text
| input[type=text]
| Question with input text, or textarea
| <textarea class="text">
|
|-
! scope="row" | .answertext
| Array question type
| Answer part of array question type
| <th class="answertext">
|
|-
! scope="row" | .col-answers
| Array question type
| Column of answers
| <col class="col-answers">
|
|-
! scope="row" | .odd .even {{ObsoleteIn|2.50}}
| Array question type
| Alternation for column
| <col class="odd">
|
|-
! scope="row" | .array1 .array2 {{ObsoleteIn|3.0}}
| Array question type
| Alternation for line
| <tr class="array1">
|
|-
! scope="row" | .ls-odd .ls-even {{NewIn|3.0}}
| Array question type
| Alternation for sub-question and Y axis
| <tr class="ls-odd">
|
|}

=== Some example of question part with classes=== 


'''Text-short question type:'''
</translate><source lang="html4strict">
<p class="question answer-item text-item ">
<label class="hide label" for="answerSGQA">Answer</label><input type="text" value="" id="answerSGQA" name="SGQA" size="50" class="text empty">
</p>
</source><translate>


'''Multiple short text'''
</translate><source lang="html4strict">
<ul class="subquestions-list questions-list text-list">
<li class="question-item answer-item text-item" id="javatbdSGQA">
<label for="answerSGQA">Some example subquestion</label>
<span><input type="text" value="" id="answerSGQA" name="SGQA" size="20" class="text empty"></span>
</li>
</ul>
</source><translate>


'''Array question type'''
</translate><source lang="html4strict">
<table class="question subquestion-list questions-list ">
<caption class="hide read">Some explanation for accessibility.</caption>
<colgroup class="col-responses">
<col width="50%" class="col-answers">
<col width="25%" class="odd">
<col width="13.3%" class="col-no-answer even">
</colgroup>
<thead>
<tr class="array1 dontread">
<td> </td>
<th>1</th>
<th>No answer</th>
</tr>
</thead>
<tbody>
<tr class="array2 answers-list radio-list" id="javatbdSGQ">
<th width="20%" class="answertext">Some example subquestion
</th>
<td class="answer_cell_001 answer-item radio-item">
<label for="answerSGQA" class="hide read">1</label>
<input type="radio" value="1" id="answerSGQA" name="SGQA" class="radio">
</td>
<td class="answer-item radio-item noanswer-item">
<label for="answerSGQA" class="hide read">No answer</label>
<input type="radio" value="" id="answerSGQA" name="SGQA" class="radio">
</td>
</tr>
</tbody>
</table>
</source><translate>

==The full list of question classes== 


{|
|'''Question Type'''||'''Question Class'''||'''Question ID'''
|-
|5 point choice||.choice-5-pt-radio||5
|-
|Array (10 point choice)||.array-10-pt||B
|-
|Array (5 point choice)||.array-5-pt||A
|-
|Array (Flexible Labels) dual scale||.array-flexible-duel-scale ||1
|-
|Array (Increase, Same, Decrease)||.array-increase-same-decrease||E
|-
|Array (Multi Flexible) (Numbers)||.array-multi-flexi ||:
|-
|Array (Multi Flexible) (Text)||.array-multi-flexi-text||;
|-
|Array (Yes/No/Uncertain)||.array-yes-uncertain-no||C
|-
|Array (flexible labels)||.array-flexible-row ||F
|-
|Array (flexible labels) by column||.array-flexible-column||H
|-
|Boilerplate question||.boilerplate||X
|-
|Date||.date||D
|-
|Gender||.gender||G
|-
|Huge free text||.text-huge||U
|-
|Language switch||.language||I
|-
|List (dropdown)||.list-dropdown||!
|-
|List (radio)||.list-radio||L
|-
|List with comment||.list-with-comment||O
|-
|Long free text||.text-long||T
|-
|Multiple numerical input||.numeric-multi||K
|-
|Multiple options||.multiple-opt||M
|-
|Multiple options with comments||.multiple-opt-comments||P
|-
|Multiple short text||.multiple-short-txt||Q
|-
|Numerical input||.numeric||N
|-
|Ranking||.ranking||R
|-
|Short free text||.text-short||S
|-
|Yes/No||.yes-no||Y
|-
|
|}

==The full list of validation classes== 


<div class="simplebox">Note: Prior to 1.92, only .mandatory and .input-error classes were available.</div>


These apply to the help and/or validation tip messages so that each type can be individually styled.


The .hide-tip option and .input-error options interact by default so that you can have validation tips hidden. However, they do appear when there are validation errors and disappear again when those errors are rectified.


All of these are designed to eliminate the need for pop-up alert messages. Instead, tips can appear/disappear as needed and are color-coded to indicate whether the answers pass the validation criteria.


Furthermore, when you first visit a page that has unmet validation criteria, you can color-code the tips in a pleasing color to show which validation criteria have not been met yet; then re-display the page using a harsher color if the person submits the page with lingering validation errors.


{|
|'''Purpose'''||'''CSS Class'''||'''Description'''
|-
|Mandatory||.mandatory||the question is mandatory
|-
|User input error||.input-error||the question had at least one validation error
|-
|Hide Tip||.hide-tip||added if you use the hide_tip option
|-
|Num answers||.em_num_answers||for for min_answers and max_answers
|-
|Value range||.em_value_range||for min/max_num_value_n and multiflexible_min/max
|-
|Sum range||.em_sum_range||for min/max/equals_num_value
|-
|Regex validation||.em_regex_validation||for regular-expression validation of the question
|-
|Question-level validation function||.em_q_fn_validation||for the em_validation_q option
|-
|Subquestion-level validation function||.em_sq_fn_validation||for the em_validation_sq option
|-
|Other comment mandatory||.em_other_comment_mandatory||for other_comment_mandatory option - shows when "other" is selected but associated comment is missing.
|-
|
|}

==Importing styles into your custom template== 


The custom question styles are near the bottom of each template's CSS file and start with:<syntaxhighlight lang="php" enclose="div">/* --------------------------- START: Question styles ------------------------------ */</syntaxhighlight>


If you're styling your own custom template, you should be able to copy everything after the above one from ''templates/default/template.css'' (for table-based layouts) or ''/templates/limespired/template.css'' (for CSS-based layouts) into your own style sheet without any impact on your other styles.

==Internet Explorer conditional style sheets== 


Because of the marked discrepancies in rendering between IE6 & IE7 and the other browsers, there are special IE conditional style sheets included for each template.


<source lang="html4strict" enclose="div">



</source>


You should include the above code within your '''startpage.pstpl''' and copies of both the IE style sheets from either ''/templates/default/'' or ''/templates/limespired'' for Tables base layout and CSS based layout respectively.


<div class="simplebox">'''Note:''' If you copy the styles into your own style sheet you will almost certainly need to tweak them.</div>

===Alternative solution for Internet explorer=== 


You can put a conditional class for body in startpage.pstpl and use this class in your template.css. This method is used in the citronade template{{ObsoleteIn|2.06}}. Adding a js / no-js class to have javascript / no javascript system.


<source lang="html4strict">



<body id="body" class="lang-{SURVEYLANGUAGE} {SURVEYFORMAT} no-js">
<script type='text/javascript'>/*<![CDATA[*/(function(H){ H.className=H.className.replace(/\bno-js\b/,'js') })(document.getElementsByTagName('body')[0]);/*]]>*/</script></source>


And in template.css use:


<source lang="css">.ie6{/*specific for internet explorer 6*/}
.ielt8{/*specific for internet explorer 6 and 7*/}
.ie{/*specific for all internet explorer */}</source>

== Right-to-Left (RTL) Languages and justify== 


The text editor within LimeSurvey is able to format RTL text. However, the editor itself shows the RTL language in a left to right format when justified. This is just an editor display issue. The RTL and justified question or text will display correctly from right to left, even when justified, in your survey or on preview.

==Keywords== 


{{Deprecated|3.0}}


Keywords within a template file get replaced by the current survey information. They are surrounded by curly brackets, for example: {SURVEYNAME}.


The following strings will be replaced by LimeSurvey when parsing the template file and presenting it to survey users. These field strings will work on almost every template except for the 'Completed Page'. (Most of these strings can be found in the common.php file. If it's not there, look in the index.php file.)


{|class=wikitable
!'''Keyword'''!!'''Template files'''!!'''Description'''
|-
|{SURVEYNAME}||All Files||The survey title
|-
|{SURVEYDESCRIPTION}||All Files||The survey description
|-
|{WELCOME}||All files (mainly for welcome.pstpl)||The survey 'welcome' text
|-
|{PERCENTCOMPLETE}||survey.pstpl||A small graph showing the percentage of the survey completed
|-
|{GROUPNAME}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group name
|-
|{GROUPDESCRIPTION}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group description
|-
|{NUMBEROFQUESTIONS}||welcome.pstpl||Displays the total number of questions in the survey (just the number)
|-
|{THEREAREXQUESTIONS}||welcome.pstpl||Displays the sentence "There are X questions in this survey" - from the relevant language file. The X is replaced with the number of questions. Note that this will also work appropriately for singular or plural. If there is only 1 question, it will print "There is 1 question in this survey".
|-
|{CHECKJAVASCRIPT}||All files (mainly for welcome.pstpl)||Warning message when end-user browser have javascript disabled
|-
|{QUESTION}||Question.pstpl||('''Has been superseeded as of LS1.87''') Displays the current question text (The format of {QUESTION} can customised by editing 'question_start.pstpl') Use the following: {QUESTION_TEXT}, {QUESTION_MANDATORY}, {QUESTION_HELP}, {QUESTION_MAN_MESSAGE}, {QUESTION_VALID_MESSAGE}, {QUESTION_INPUT_ERROR_CLASS}, and appropriate wrapping HTML instead of {QUESTION}
|-
|{ANSWER}||question.pstpl, print_question.pstpl||presents the answer form for the current question
|-
|{SGQ}||question.pstpl, question text||Can be used in the question text itself to reference the input field of the question dynamically by displaying the Survey-Group-Question id for the current question. (as of svn build 9755)
|-
|{QUESTIONHELP}||question.pstpl, print_question.pstpl||Displays help text (predefined tip for question type) for the current question
|-
|{QUESTION_CLASS}||question.pstpl, print_question.pstpl||unique class for each question type. (To be included in the question's wrapping tag.)
|-
|{QUESTION_CODE}||question.pstpl, print_question.pstpl||Displays the current question code
|-
|{QUESTION_ESSENTIALS}||question.pstpl||the question ID and (if a question is conditional), 'style="display:none;"'. (To be included in the question's wrapping tag.)
|-
|{QUESTION_HELP}||question.pstp, question_start.pstpl||Displays the user defined help text for the current question
|-
|{QUESTION_TYPE_HELP}||print_question.pstp||Displays the user defined help text for the current question
|-
|{QUESTION_INPUT_ERROR_CLASS}||question.pstp, question_start.pstpl||Provides a class if there was user input error
|-
|{QUESTION_ID}||print_question.pstp||Provides a unique ID for each question to allow styling for specific questions
|-
|{QUESTION_TEXT}||question.pstp, print_question.pstp, question_start.pstpl||Displays the text for the current question
|-
|{QUESTION_MANDATORY}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' text for the current question
|-
|{QUESTION_MAN_CLASS}||question.pstpl, print_question.pstpl||class if a question is mandatory. (To be included in the question's wrapping tag.)
|-
|{QUESTION_MAN_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' help message text for the current question
|-
|{QUESTION_NUMBER}||print_question.pstpl||Incremental count of questions.
|-
|{QUESTION_VALID_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated valid help message text for the current question
|-
|{QUESTION_SCENARIO}||print_question.pstp||Prints out the 'scenario' text for conditional questions.
|-
|{NAVIGATOR}||navigator.pstpl||Displays navigation buttons (next, prev, last)
|-
|{CLEARALL}||All files (but intended for navigator.pstpl)||Displays the "Exit and Clear Results" link
|-
|{COMPLETED}||completed.pstpl||Displays the 'completed' message for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{URL}||completed.pstpl||Displays the survey 'url' and 'url text'
|-
|{PRIVACYMESSAGE}||privacy.pstpl||The privacy message is shown if you set your survey to be anonymous. [[Translating LimeSurvey|The text can be edited/translated]] in the language files. This can also be changed manually by editing the privacy.pstpl template you wish to use.
|-
|{TEMPLATEURL}||All Files||The URL to the current template location (useful for referencing image files in your template)
|-
|{SURVEYRESOURCESURL}||All Files||The URL to the current uploaded files for this survey location (useful for referencing image files in your question, group, ....)
|-
|{SUBMITCOMPLETE}||endpage.pstpl||The statement (from the language files) that tells the user they have completed the survey, and to press the "Submit" button
|-
|{SUBMITREVIEW}||survey.pstpl||The statement (from the language files) that tells the user they can review/change the answers they have made by clicking "<< prev"
|-
|{SAVEDID}||All Files||Displays 'Response ID' of user
|-
|-
|{QUEXMLPDF}||All Files||Displays button to export the queXML PDF of questionnaire including answers entered up until the point that has been completed in the survey.
|-
|{TOKEN:FIRSTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users first name from the tokens table
|-
|{TOKEN:LASTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users last name from the tokens table***
|-
|{TOKEN:EMAIL}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users email from the tokens table***
|-
|{TOKEN:ATTRIBUTE_1}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_1 from the tokens table***
|-
|{TOKEN:ATTRIBUTE_2}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_2 from the tokens table***
|-
|{ANSWERSCLEARED}||Preferably in navigator.pstpl||The "Answers Cleared" statement from the language files
|-
|{RESTART}||clearall.pstpl||URL to restart the survey
|-
|{REGISTERERROR}||register.pstpl||Shows any error messages in the register page (ie: "You must include an email address")
|-
|{REGISTERMESSAGE1}||register.pstpl||The statement "You must be registered to complete this survey" from the language files
|-
|{REGISTERMESSAGE2}||register.pstpl||Details about registering from the language files
|-
|{REGISTERFORM}||register.pstpl||The actual form for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{SAVE}||Works suitable on navigator.pstpl||Displays the 'Save your responses so far' button to offer the user to save and come back later to continue the survey. If the Save option is deactivated in the survey properties the tag will not be shown and ignored.
|-
|{LANGUAGECHANGER}||survey.pstpl||Displays a switch in multilingual surveys to change the question.
|}

==Input/Buttons== 


Each "input" type in a survey has been given its own class name, so that you can add CSS to your "startpage.pstpl" file and have some control over the appearance of form buttons and inputs. These class names are as follows:
*'''submit''' (Submit Buttons)
*'''text''' (Text Inputs - for short free text, date, and numerical type)
*'''answertext''' (Text of answers)
*'''radio''' (Radio Buttons)
*'''checkbox''' (Check Boxes)
*'''select''' (Select / List Boxes)
*'''textarea''' (Large text inputs - for long free text)
*'''clearall''' (The "Exit and Clear Survey" link)
*'''rank''' (The rank style question. Doesn't set the colour of the select box or the text boxes, but it does allow the changing of background colour, text colour, size etc., for the rest of the ranking question)
*'''graph''' (The "percentage completed" graph table)
*'''innergraph''' (The table inside the graph table - this contains the 0% and 100% text. Use this for changing the size of this text)
*'''question''' (General settings for any question that is displayed within a table. Generally, you should use this to make sure that their font size and color is the same as you have used elsewhere as a default)
*'''mandatory''' (Mandatory questions)
*'''input-error''' (User input error - for if a user has made a mistake with a mandatory question or question with validation)
*'''array1''' and '''array2''' (These two styles are cycled when presenting the range of answers for an array type question. This allows you to set an alternating background color for these question types. '''Array1''' is also used for the column headings in these question types)
*'''errormandatory''' (Sets the color and style of the "This question is mandatory" error message)
*'''warningjs''' (Sets the color and style of the warning message displayed if the participant's browser has javascript disabled)


There are also some elements that can be accessed using the ID of the element ('''#ID''' in CSS):
*'''surveycontact''' (The contact message shown on the start page)
*'''tokenmessage''' (used for messages inside the survey, e.g. the session expired error message)


Because you can edit all the HTML aspects, there's no reason to surround your templates with a
<syntaxhighlight lang="php" enclose="div"><div class='new_name'></div></syntaxhighlight>
and then define a css for that new_name class.

==Styling the progress bar== 


The progress bar appearance can be modified with CSS.


To change the background color of the bar, add something like the following to the end of your template.css file:


<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-header {
background-color: #3300FF;
}</syntaxhighlight>


To change the border color of the bar, add something like the following to the end of your template.css file:


<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-content,
#progress-wrapper .ui-widget-header {
border: 1px solid #FF0000;
}</syntaxhighlight>

==Advanced Features Available to Developers== 


LimeSurvey has integrated some user-made patches that permits some special changes. These very advanced features (generally) require changes to the underlying code base of LimeSurvey and should be done carefully in order not to introduce security holes.

===Support for your own Javascript functions=== 


Some users may need to run Javascript on the survey pages, but calling '''checkconditions()''' in the BODY element made it impossible to do so. This call has been replaced with a small JavaScript function in the HEAD that sniffs for the existence of '''checkconditions()''' and '''template_onload()''' before calling them. In this way, a template author can create his or her own '''template_onload()''' function in the HEAD that replaces the default one.


*Disable XSS filter - in Global settings -> Security, set "Filter HTML for XSS" to No.
*Enter your script in the source of a question or group description.


{{Note|For further details, see the [[Workarounds: Manipulating a survey at runtime using Javascript#How to use Script (eg. JavaScript etc.) in LimeSurvey|workaround section]].}}

=Videos on Templates= 


This video will demonstrate the basic and advanced template functions that are available to all LimeSurvey users. This includes changing the appearance of certain forms and inserting custom graphics. Additionally, it will thoroughly walk you through on how to edit and preview specific page templates, importing/exporting templates, modify appearance of questions in the CSS, and customizing survey description page.


Video - needed

=Tips & Tricks= 

==Some language specific element== 


If you want to have some language specific sentence in a survey, for example a help at the end of each page, you can add in a .pstl file a sentence and hidding it for other language. If we hide it in the template.css, we can use the pseudo selector :lang, but we use some class for better compatibility.


Below, there are two help sentences, in French and English. Put this on endpage.pstpl:


<syntaxhighlight lang="php" enclose="div"><div class="fr" lang="fr">Pour de l'aide en direct appelez le 000000</div>
<div class="en" lang="en">For some help, please call 000000</div></syntaxhighlight>


and in template.css:


<syntaxhighlight lang="php" enclose="div">.lang-fr .en{display:none}
.lang-en .fr{display:none}</syntaxhighlight>

==Change the layout of the survey page== 


After editing and saving a template, it applies to a survey list page only if it is selected from the settings of the survey. To make it the default template, go under the '''General tab''' located in the '''Global settings''' of your LimeSurvey installation and choose the desired template. From now on, all the templates that use the "default" option as template plus the ones that are going to be newly created, will use the newly selected default template.


To use your current template for this page, you have to change the according setting from '''Global settings'''. In older versions, this change can be done by editing the $defaulttemplate setting from the config file: copy this setting from config-defaults.php to config.php which overrides config-defaults.php and edit this setting to <code lang="html">$defaulttemplate = 'yourtemplatename';</code>.

==Import/Export of templates: Mac users== 


<u>Mac users</u>, please note that the Mac OSX default archive utility may have problems with zip folders "generated on the fly".


A workaround is to unix'es unzip from the command line:


$ unzip template.zip -d template


Archive: template.zip


inflating: template/startpage


inflating: ...


Another workaround is to use scripts in their mac-compiled counterparts.

==Replacing the help icon {{ObsoleteIn|2.50}} == 


When a question help text is shown, then an help.gif image is used from the default template folder.


You can replace this image by uploading a new help.gif, help.png or help.jpg in your custom template folder. It will then be automatically used instead of the default help icon.

==Replacing an existing logo {{NewIn|2.50}} {{ObsoleteIn|3.0}}== 


'''Note''': In the '''default'' Template of 2.50, there is no preembedded logo. Read further our [[#Adding_your_own_logo |wiki on how to add your own logo]].


1. To edit the logo go to the ''<u>template.css</u>'' file which you can find it here:


<center>[[File:t1.PNG|200px]]</center>


2. Click the search button to find occurrences of logo related styles and search for ''logo''


<center>[[File:2.png|200px]]</center>


4. Edit the main style file.


You will see something similar to:


<center>[[File:t4.PNG|500px]]</center>


If you want to change the image, just replace logo.gif with another image link. Example: (<u>logo.png</u> or <u>logo.jpg</u>).


If you want to change the image size, adjust width and height (in pixels) like this:


<syntaxhighlight lang="php" enclose="div">width:100px; height:100px;</syntaxhighlight>

==Adding your own logo {{ObsoleteIn|3.0}} == 


1. Find and open the '''startpage.pstpl''' template file.


<center>[[File:startpage.pstpl.png]]</center>


2. After this
<source lang="html4strict" ><div id="topContainer" class="jumbotron"></source>
add this line to '''startpage.pstpl''':
<source lang="html4strict">
<div class="container"><img id='page_logo' src='{TEMPLATEURL}/files/logo.png' class="clearfix pull-right" /></div>
</source>


3. To upload your own logo, go to the template editor and upload your logo.


<center>[[File:uploadyourlogo.png]]</center>


To position your logo, please use one of the following css classes:


*'''If you want the logo to be placed on the left side:'''


<source lang="html">clearfix pull-left</source>


*'''If you want the logo to be placed on the right side:'''


<source lang="html">clearfix pull-right</source>


*'''If you want to center the logo'''


<source lang="html">clearfix center-block</source>

==Use the same template with different logos== 


If you want to use the same template for all surveys and just want to change the logo for each survey, you can use the {SID} placeholder in the template .pstpl file and thereby refer to different images:


<syntaxhighlight lang="php" enclose="div"><img src="{TEMPLATEURL}files/logoImage-{SID}.png"></syntaxhighlight>

==Remove the default help to all question (hide_tip) {{ObsoleteIn|1.92}}== 


There are 3 solutions to remove the default help:
# like a hide_tip attribute but for all question and survey.
# you can remove the {QUESTIONHELP} and its container from the file question.pstl. However, it can be a bad idea for the screenreader.
# for the default template and some other, add this at the end of tempate.css


<syntaxhighlight lang="php" enclose="div">span.questionhelp{display:none;}</syntaxhighlight>

== Display custom favicon== 


A favicon is the little icon you see in the browser's address bar, list of bookmarks or tab. You can display your own icon as follows:
#Create a favicon - google will find you lots of free favicon generators.
#Name your new favicon "favicon.ico" and place it in your template /files directory.
#Add the following code to your '''startpage.pstpl''' before the </head> tag.


<syntaxhighlight lang="html4strict" enclose="div"><link rel="shortcut icon" href="{TEMPLATEURL}files/favicon.ico" type="image/x-icon">
<link rel="icon" href="{TEMPLATEURL}files/favicon.ico" type="image/x-icon"></syntaxhighlight>

== Different appearance for survey-/question-pages== 


If you want LimeSurvey to change the appearance of every second page (i.e. of even and odd survey pages), you can use '''.page-odd''' class in your CSS file to change the appearance of odd pages.


An example from default template of LimeSurvey 1.91+:


<syntaxhighlight lang="php" enclose="div">
.page-odd table.question-group {
background-color: #D2F2D3;
}</syntaxhighlight>


If you do '''not''' want differentiate even and odd pages, find all instances of ''.page-odd'' in template.css and remove those styles.

==Create a vertical separator border for dual scale array== 


To create a vertical separator border for a dual scale array, you can add the following lines to your '''template.css'''-file.


<syntaxhighlight lang="php" enclose="div">
table.question thead td.header_separator,
table.question tbody td.dual_scale_separator
{
border-right:solid 1px #00A8E1;
}
</syntaxhighlight>


''header_separator'' is used to adress the separator for the header "td". The "dual_scale_separator" is used to address the separator column in the dual scale array.

==Hide the survey contact message shown on the start page/survey list {{ObsoleteIn|3.0}} == 


To hide the "Please contact ..." message on the start page (with the survey list), you can add the following to the '''$(document).ready''' function in the '''template.js''' of your used design template:


<syntaxhighlight lang="php" enclose="div">


$('#surveycontact').hide(); //Hides the survey contact message


</syntaxhighlight>

==Remove the survey contact message shown on error messages {{ObsoleteIn|3.0}}== 


If you want to remove the survey contact message from error messages, it'll be trickier. You can add the function from below. It calls the '''$(document).ready''' function in the '''template.css''' of your used design template:


<syntaxhighlight lang="php" enclose="div">
removeContactAdressFromMessage(); //Removes the survey contact message from error messages
</syntaxhighlight>


and add the following function to your *template.js* file


<syntaxhighlight lang="php" enclose="div">
function removeContactAdressFromMessage()
{
if ($('#tokenmessage').length > 0)
{
var oldMessage = $('#tokenmessage').html();
var indexContact = oldMessage.indexOf('Bitte kontaktieren');
var newMessage = oldMessage.substr(0, indexContact);
$('#tokenmessage').html(newMessage);
}
}
</syntaxhighlight>


It will probably not work for a survey in English language and has to be extended when used for multilingual surveys. But it's an idea/tip on how to solve this.

==How to deal with multilingual question attributes {{ObsoleteIn|2.50}}== 


If you have a multilingual survey and e. g. want to use a different string for the "other" field, this could only be done for the base language (until this feature was added at LimeSurvey 2.0). To work around this, paste in the field to change the label for "other":


<syntaxhighlight lang="php" enclose="div"><span class="en">New label</span><span class="fr">Nouveau label</span></syntaxhighlight>


Add in the template.css of your template (at ''/limesurvey/upload/templates/<yourtemplatename>/template.css''):


<syntaxhighlight lang="php" enclose="div">html:lang(en) .fr{display:none}
html:lang(fr) .en{display:none}</syntaxhighlight>

==Adding your own logo to the survey list {{ NewIn|3.0}} == 


# First please open the theme editor for the theme you like to use. [[File:OpenThemeEditor.jpg]]
# We recommend to use fruity, it is our best theme currently.
# Then extend the theme and give it a name you will recognize. [[File:ExtendTheme.jpg]]
# In the following view you may upload the logo you want to use. [[File:UploadFileTheme.jpg]]
# Select the editor screen `Survey List´ in the Screen dropdown in the top right corner. [[File:OpenScreenSurveyList.jpg]]
# Then select `layout_survey_list.twig´ in the left side menu. [[File:EditLayoutSurveyListTwig.jpg]]
# In the editor scroll to line 126 and change the marked part to the filename of the image you uploaded to the theme before. [[File:ChangeSurveyListHeaderImageEditor.jpg]]
# Save your file. [[File:ThemeEditorSaveChanges.jpg]]
# Change default theme to your extended theme. [[File:ChangeDefaultTheme.jpg]]

=Custom Question Views {{NewIn|3.0}}= 


<div class="simplebox">'''Note:''' This is a temporary feature to be replaced in the future by question object (it will be very easy to move custom views to question object). It is disabled by default.</div>


As of version 2.5, you can create template-specific custom views for questions and some of their incorporated elements. This is useful if you want to modify the HTML layout of a particular question type for one or more surveys.


*In application/config/config.php, find 'config'=>array and add this line to the array : 'allow_templates_to_overwrite_views'=>1
*In /{your_template}/config.xml, set "overwrite_question_views" to true
*Copy application/views/survey/* to template/{your_view_directory}/survey/
*Note that you only need to copy the files that you intend to modify but the file structure must remain the same as in application/views/survey/

=Insert Custom CSS or JavaScript files for template {{NewIn|2.50}}= 


As of version 2.50, you can use the config.xml file to automatically load plugin files.


*Upload your files to the template /css or /scripts folder
*In /{your_template}/config.xml, add the file paths to the <css> or <js> blocks, something like this:<syntaxhighlight lang="xml" enclose="div"><css>
<filename>css/jquery-ui-custom.css</filename>
<filename>css/bootstrap-slider.css</filename>


<filename>css/awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</filename>
<filename>css/flat_and_modern.css</filename>


<filename>css/template.css</filename>


<filename>css/myCustomPlugin.css</filename>
</css>
<js>
<filename>scripts/template.js</filename>
<filename>scripts/bootstrap-slider.js</filename>


<filename>scripts/myCustomPlugin.js</filename>
</js>
</syntaxhighlight>

</translate>

Theme editor

2018-04-04T10:25:05Z

LouisGac:

<languages /> <translate>

=Introduction= 


LimeSurvey has an advanced theme and style system providing to developers an efficient way to customize the survey appearance. Since LS3, we're not speaking anymore about '''"templates"''' like in previous versions, but about '''"themes"'''. The '''themes''' allow control over the look and feel of pages during a survey. A survey administrator can select a default theme that will be used for each survey to further personalize it and improve its look and feel. '''Themes''' come with options that provide to admin without coding skill a simple way to add a logo on the welcome page, to change the background colors, to select a font, etc.


LimeSurvey comes with 3 themes right out of the box. These initial themes are defined by directories located in the LimeSurvey installation "themes/survey/" directory. Each theme has it's own directory. Within the main directory of a theme you'll find a configuration file in XML, and numerous directories containing the views ''themes (.twig)''', '''cascading style sheets (.css)''', '''scripts''', '''images''' ('''.jpg''' or '''.png'''), and maybe others.


Since LimeSurvey 2.50, the theme engine use [http://getbootstrap.com/docs/3.3/ Bootstrap 3] as CSS framework. Bootstrap 3 being a standard framework, developers will find a lot of documentation, tutorials and forum threads about it on Internet.

Since LimeSurvey 3, the theme engine use [https://twig.symfony.com Twig], so the theme developers can change the logic of the survey rendering in a safe and easy way. Twig replace the old system of replacement keywords that was used in the previous versions. The logic that was used to generate the HTML of the keywords are now available inside the theme's views.

Snippet from Vanilla Theme:


<syntaxhighlight lang="twig" enclose="div">
<div class="{{ aSurveyInfo.class.answercontainer }} col-xs-12" {{ aSurveyInfo.attr.answercontainer }}>
{# NOTE: If you want to customize the question rendering, use a question theme #}
{{ aQuestion.answer | raw }}
</div>
</syntaxhighlight>


Themes, being HTML and Twig code, tend to define the positioning and type of text to be displayed and similar structural features of the page. They often reference or include other files. Most of them reference a common cascading style sheets (CSS) file that defines the font style, color, size, background, and similar parameters common to all pages in the survey. Style sheets reference HTML '''class''' parameters that are associated with the various types of objects in the HTML code. This allows the style sheet to describe how to display each of the many types of text or other objects that may appear in multiple places. There are unique classes for each question type in LimeSurvey and thus giving detailed control over the appearance of each. Image files, like logos or special progress-bar constructors, may be referenced as well in the Theme file. Finally, special keywords in curly braces are replaced with text defined in the survey for each language translation correspondent (for example, the 'Survey Title' or 'Question Text' for each language defined).


If you create a new custom theme, please consider contributing it back to the LimeSurvey community and make it available to others. With your help, we can grow our repository of themes, surveys, and other add-ons to make LimeSurvey even better!
See our [https://www.limesurvey.org/index.php?option=com_sobipro&sid=55:Templates&Itemid=729 LimeSurvey template repository] where you can share your templates.

=Creating a new template= 


To be able to create a new template (or edit an existing template), you need [[Manage users#Set global permissions for a user|Template Editing user permission]] in LimeSurvey as well as permission to manipulate the files in the underlying operating system hosting your LimeSurvey installation.


<div class="simplebox"><span style='color:red'>'''Note of Warning:'''</span> If you change templates, you could also affect all the pre-existing surveys from your LimeSurvey installation. Templates are an advanced feature that require experience and HTML knowledge in order to make them running smoothly.</div>


The preferred way to create a new template is through the '''Template Editor''' (see below), which is located in the '''Configuration''' dialog. Some people may like to work directly with template files so that they can use their favorite text editor instead of the web interface. In this case, still use the Template Editor to first create your new template. This will create a new base template with all the files you need in the ''LimeSurvey_web_root/upload/templates/your_new_template'' directory. From there you can use your text editor to manually adjust the template files.


<div class="simplebox">'''Permissions Note:''' on unix/linux systems, these template files will be owned by the group and user where the web server is running (may be "www" for some systems). So, make sure you have enough access to edit these files, When you save them, make sure they don't change ownership! In this way, you can still use the web Template Editing interface if needed.</div><br />


A number of 'public' elements of LimeSurvey can be adjusted by a series of templates. The next section provides a very brief explanation of these templates.


{{Note|Template files may seem complex. Besides HTML, you might also need to understand CSS.}}

=The LimeSurvey template editor= 


To ease the understanding and quick update of a Template, LimeSurvey provides a '''Template Editor''' in the main '''administrative''' toolbar of the application. This Template Editor is only available to users [[Manage users#Set global permissions for a user|with the Templates permission]] and to superadministrators.


{{Alert|title=Attention|text=A template that is not correctly constructed can render a survey (that uses the respective template) inoperable. }}


The LimeSurvey template editor allows you to edit the contents of your templates online. Start the Template Editor by clicking on '''Template editor''' in the '''Configuration''' menu.


[[File:templates.png]]


The template editor page allows you to select the template you would like to edit/view.


[[File:Template-editor-2013-7-10_11_38_16.png|center]]

==The template menu== 


The following options are available:


*'''Create''': Allows you to create a new template. In order not to start from scratch, the template 'default' is copied.
*'''Import''': Allows you to import a template from a ZIP file.
*'''Export''': Allows you to export the current template to a ZIP file.
*'''Copy''': Allows you to make a new template by copying the current one.
*'''Rename''': Allows you to change the name of the template. It is generally used after copying or importing a template.
*'''Template''': It is a drop-down list that shows all the available templates that are located in your LimeSurvey installation.


*'''Screen''': It is a drop-down list which allows you to choose which particular survey page of that template you want to look at.
*'''Return to admin panel'''.

==Import/export/copy a template== 


When you '''export '''a template, a ZIP-file archive with all the files your template consists of will be created (.pstpl files, images, css files, ...). You can simply '''import''' the exported zip-file into another LimeSurvey installation by using the import feature or you can manually copy the archive into another LimeSurvey installation and extract it into the corresponding [[Theme editor#Template files location|template directory there]].


However, it is preferred to use the LimeSurvey template import/export/copy functions in the template editor.

==Page Structure / Template Use== 
*'''The Welcome Page:''' startpage.pstpl, welcome.pstpl, privacy.pstpl, navigator.pstpl, endpage.pstpl
*'''The Questions Pages:''' startpage.pstpl, survey.pstpl, startgroup.pstpl, groupdescription.pstpl, question.pstpl, endgroup.pstpl, endpage.pstpl
*'''The Final Page:''' startpage.pstpl, assessment.pstpl, completed.pstpl, endpage.pstpl

==Template Files== 


The following template files are used to produce your public survey and must exist in any new template folder you create:
*'''startpage.pstpl:''' Produces the start of each html page. It starts at the "<head>" tag, and should not contain the "<html>" tag. This 'very beginning' of a standard html page is written by the scripts. Please ensure that your startpage.pstpl files contains a <body> tag. Even though many browsers do not require strict adherence to the W3 HTML standards, the LimeSurvey script needs to find a <body> tag to run certain javascript elements. It is not expected to see many 'keywords' used in the startpage.pstpl file. However, you may wish to put the {SURVEYNAME} into the title. The startpage.pstpl file can contain code that ends in the corresponding endpage.pstpl file. For example, you can start a table in this file and close the table in the endpage.pstpl file. The startpage.pstpl and endpage.pstpl files wrap around every possible page used by LimeSurvey.
*'''survey.pstpl:''' This template is the second used on most pages and provides a space to put the survey name and description. This template does not have a corresponding 'closing' template, and subsequently you should close all tags opened in this template file (i.e.: don't leave a table open here because there is nowhere else to close it).
*'''welcome.pstpl:''' This template is only used in the welcome screen (which is also on the main page for 'all in one' surveys). You can use this to print out the welcome text, and other information that should be provided in the introduction. Like the 'survey.pstpl' file, there is no corresponding 'closing' template, so all tags opened in this template file should be closed as well.
*'''startgroup.pstpl:''' This template can provide a 'summary' wrap around for questions within a group. It has a matching 'endgroup.pstpl' template that can be used to close any opened tags in this file, so you can open a table within this.
*'''groupdescription.pstpl:''' This template file is used to display a description of a group. Please note that in the survey settings (access the ''Presentation & navigation settings'' by clicking on the '''Presentation''' tab) you can set if the group description should be shown or not. If not, then this file is not included at all.
*'''question.pstpl:''' This file contains the question, answer, and help text sections of your survey. In the "group by group" and "all in one" surveys, this template is cycled repeatedly with each question. There is no corresponding closing file for this and all tags should be closed.
*'''question_start.pstpl:''' This file contains the individual elements found at the start of a question. It is included within 'question.pstpl' via the {QUESTION} keyword. It is intended to allow template designers more control over the layout of a question. This template sits outside the normal templating system and '''was superseeded (as of LimeSurvey 1.87)'''. All keywords from this template are now available directly in question.pstpl.
*'''completed.pstpl:''' This page is displayed as the final page when the survey responses have been saved and the survey is over. It can be used to display a "forwarding link" as set in the survey setup.
*'''endgroup.pstpl:''' This file closes the group, and can be used to close off any tags opened in the startgroup.pstpl file
*'''navigator.pstpl:''' This file contains the buttons that navigate through the survey, "next", "prev", "last", "submit", "save so far" and the "clear all" link. It is used in all pages except the completed page.
*'''printanswers.pstpl:''' This file has the HTML wrapper necessary for the print version of the survey.
*'''print_group.pstpl:''' This file is the same as startgroup.pstpl and endgroup.pstpl, but for the print version of the survey.
*'''print_question.pstpl:''' This file is the same as question.pstpl, but for the print version of the survey.
*'''print_survey.pstpl:''' This file is the same as survey.pstpl, but for the print version of the survey.

== CSS and Javascript== 


Two files that are always used in a template are template.css (for CSS) and template.js (for Javascript).
*'''{TEMPLATECSS}:''' Add lines for default css, template.css, and template-rtl.css for rtl language.
*'''{TEMPLATEJS}:''' Add lines for default javascript files, template.js, and all js files needed for LimeSurvey.

=== Using Bootstrap=== 
LimeSurvey has Bootstrap 3 embedded, so you can style all your templates with the well documented Bootstrap classes.
For more information please refer to the [https://getbootstrap.com Bootstrap documentation].


The [https://github.com/flatlogic/awesome-bootstrap-checkbox Awesome-Bootstrap-Checkbox] plugin is also included. With it, you can use the typical Bootstrap color-classes (info,warning,danger,etc.) also with the suffix "-checkbox" or "-radio", though styling checkboxes and radios as you prefer.

=== Replacing default CSS or Javascript=== 


Some questions use specific files for Javascript or CSS. If you need to replace a function, use a cascading system. For javascript function, the last function read is the function used.

==Other Template Files== 


The '''privacy.pstpl''', '''invitationemail.pstpl''', '''reminderemail.pstpl''', and '''confirmationemail.pstpl''' are no longer used by LimeSurvey and defaults are instead set in the applicable language files. The email messages can now be edited on a survey by survey basis.

==Standard Pages== 


There are ten standard pages that a survey participant may see in the course of taking or accessing the LimeSurvey application. Each is constructed from a number of common '''Template''' files from the '''Template''' specified in the settings of the survey. The table below indicates which template files are used in constructing each of these pages.


{| class="wikitable"
! '''Survey Pages/'''<br />'''Template Files'''!!Survey<br />List!!Welcome!!Question!!Completed!!Clear All!!Register!!Load!!Save!!Print<br />Answers!!Print<br />Survey
|-
|SurveyList||align="center" | [[File:check.gif]]|| || || || || || || || ||
|-
|Welcome|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Privacy|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Navigator|| ||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Survey|| || ||align="center" | [[File:check.gif]]|| || ||align="center" | [[File:check.gif]]|| || || ||
|-
|StartGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|GroupDescription|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Question<span style='color:red'>'''*'''</span>|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|EndGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Assessment|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|Completed|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|ClearAll|| || || || ||align="center" | [[File:check.gif]]|| || || || ||
|-
|Register|| || || || || ||align="center" | [[File:check.gif]]|| || || ||
|-
|Load|| || || || || || ||align="center" | [[File:check.gif]]|| || ||
|-
|Save|| || || || || || || ||align="center" | [[File:check.gif]]|| ||
|-
|PrintAnswers|| || || || || || || || ||align="center" | [[File:check.gif]]||
|-
|Print Survey || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Group || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Question || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|StartPage<br />EndPage<br />Template.css||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||
|}


<span style='color:red'>'''*'''</span>NOTE: In version 1.90+, this replaces question.pstpl AND question_start.pstpl. If you are using an old custom template, you need to add the following line to the beginning of question.pstpl:<syntaxhighlight lang="php" enclose="div"><div {QUESTION_ESSENTIALS} class="{QUESTION_CLASS}{QUESTION_MAN_CLASS}{QUESTION_INPUT_ERROR_CLASS}"></syntaxhighlight>And then add the corresponding closing tag to the end of question.pstpl:<syntaxhighlight lang="php" enclose="div"></div></syntaxhighlight>


<span style='color:red'>'''*'''</span>NOTE: In version 1.91 and earlier, LimeSurvey js files are not included in the template. In version 2, '''you have to use {TEMPLATEJS} in one of your template file''' to add the link to the js file. You can add it in startpage.pstpl or in endpage.pstpl. You can remove the {TEMPLATEURL}/template.js line and you have to replace with {TEMPLATEJS} to update a personal template.

==The File Control Section== 


In the "file control" window on the left, you can click on one of the template files that is used to compile the page. You can see the ''Screen part'', JavaScript, and CSS files. The HTML code for that file will then appear in the "Now editing" window in the center. If the template is editable (determined by directory permissions) you can then make any changes and save them.


<center>[[File:File Control Section.png|center]]</center>


The "Other files" window shows a list of all other files from the template directory. You can use the right side to '''upload and select image files (your pics, logos,...) or other files needed to create your template'''.


Instead of using a link for each picture, utilize the field string {TEMPLATEURL}. So, instead of:


<syntaxhighlight lang="html4strict" enclose="div">img src='/limesurvey/templates/yourtemplate/files/mypicture.jpg'</syntaxhighlight>
You can use {{NewIn|2.50}}:
<syntaxhighlight lang="html4strict" enclose="div">img src='{TEMPLATEURL}files/mypicture.jpg'</syntaxhighlight>


In LimeSurvey versions before 2.50 use:
<syntaxhighlight lang="html4strict" enclose="div">img src='{TEMPLATEURL}mypicture.jpg'</syntaxhighlight>


A "sample" of the template page you are editing will be visible in the bottom of the screen. There is no way to delete a template from the template editor. This must be done by accessing the underlying directory and deleting manually the files from there. You also have the possibility to select different screen resolutions in order to better evaluate the feel and look of the template.


<div class="simplebox">'''Note:''' The shipped templates cannot be edited using the template editor. If you want to modify them, create a copy first and edit the copy.</div>

==Template files location== 


LimeSurvey stores each of the 'standard' templates in their own distinct sub-directory within the ''/templates'' directory that is kept in the public directory with the other LimeSurvey public files. Customized user templates are stored in the ''/upload/templates'' directory.


There should '''ALWAYS''' be a "default" directory in the templates directory. This template is used by default and as a fall-back if a template folder doesn't exist, or can't be found. It comes installed by default.


You can use any image files that you upload into the template management area with the help of this syntax:


<syntaxhighlight lang="php" enclose="div">{TEMPLATEURL}filename.xyz</syntaxhighlight>

=Styling questions with CSS= 


Styling of questions in CSS has become much easier. Each question type has now a unique class. The mandatory questions have an additional mandatory class. For example, for a non-mandatory question:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender">
...
</div></syntaxhighlight>


and if the question is mandatory:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory">
...
</div></syntaxhighlight>


and if the question is mandatory, but the user didn't answer it or if there is validation on a question:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory input-error">
...
</div></syntaxhighlight>


and if the question has validation applied, but the user hasn't answered correctly:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question6" class="text-short input-error">
...
</div></syntaxhighlight>

==Global classes for question part== 


These classes are used for each question type. Some question types use only one or two classes, while others may use much more.


{| class="wikitable alternance"
|+ Global classes
|-
! scope="col" | Class name
! scope="col" | Part
! scope="col" | Question type
! scope="col" | Examples
! scope="col" | Note
|-
! scope="row" | .question {{ObsoleteIn|3.0}}
| All question block
| All question type
|<p class="question">, <ul class="question">, <table class="question">
|
|-
! scope="row" | .ls-answers {{NewIn|3.0}}
| All question block
| All question type
|<div class="ls-answers ">, <ul class="ls-answers ">, <table class="ls-answers">
|
|-
! scope="row" | .subquestions-list
| List of subquestion
| Multi choice question, array question type
| <ul class="subquestions-list">, <table class="subquestions-list">
| .questions-list is used too
|-
! scope="row" | .answers-list
| List of answers
| Single choice question, array question type, Multi input text question
| <ul class="answers-list">, <table class="answers-list">
|
|-
! scope="row" | .answer-item
| The answer part: one answer
| Single choice question, array question type, Multi input text question
| <li class="answer-item">, <td class="answer-item">
|
|-
! scope="row" | .noanswer-item
| The answer part for no answer
| Single choice question, array question type
| <li class="noanswer-item">, <td class="noanswer-item">
| No answer is an answer too, then have double class noanswer-item and answer-item
|-
! scope="row" | .question-item
| The question part: one question
| Multi text question, array question type
| <li class="question-item">, <tr class="question-item">
| Some answers are questions too. Then we have a lot of class="question-item answer-item"
|-
! scope="row" | .checkbox-list
| A list of checkbox
| Multi choice question, array number (checkbox) question type
| <ul class="checkbox-list">, <tr class="checkbox-list">
| Some question types use multi-list class, like checkbox with comment: class="checkbox-list text-list"
|-
! scope="row" | .checkbox-array {{NewIn|3.0}}
| A array of checkbox
| Array (numbers) with checkbox option
| <table class="checkbox-list">
|
|-
! scope="row" | .checkbox-item
| The answer part with a checkbox
| Multi choice question, array number (checkbox) question type
| <li class="checkbox-item">, <td class="checkbox-item">
|
|-
! scope="row" | .radio-list
| A list of radio item
| Single choice question, array question type (each row)
| <ul class="radio-list">, <tr class="radio-list">
|
|-
! scope="row" | .radio-array {{NewIn|3.0}}
| A array of radio item
| Array question type
| <table class="radio-array">
|
|-
! scope="row" | .radio-item
| The answer part with a radio
| Single choice question, array question type
| <li class="radio-item">, <td class="radio-item">
|
|-
! scope="row" | .text-list
| A list of text input
| Multi text question type, array of text
| <ul class="text-list">, <tr class="text-list">
|
|-
! scope="row" | .text-item
| The answer part of a text input
| Multi text question type, array of text
| <li class="text-item">, <td class="text-item">
|
|-
! scope="row" | .numeric-list
| A list of text input with numeric only answer
| Multi numeric question type, array of number
| <ul class="text-list numeric-list">, <tr class="text-list numeric-list">
|
|-
! scope="row" | .number-list
| A list of text input with numeric only answer (each row)
| Multi numeric question type, array of number
| <ul class="text-list numeric-list">, <tr class="text-list numeric-list">
|
|-
! scope="row" | .number-array {{NewIn|3.0}}
| The answer part of a numeric input
| Array of number
| <table class="number-array">
|
|-
! scope="row" | .select-list {{ObsoleteIn|2.50}}
| A list of select
| Array numbers, Dual scale array (select)
| <table class="select-list">
|
|-
! scope="row" | .dropdown-list {{NewIn|2.50}}
| A list of select
| Array numbers, Dual scale array (select) (each row)
| <table class="dropdown-list">
|
|-
! scope="row" | .dropdown-array {{NewIn|3.0}}
| A array of dropdown
| Array numbers, Dual scale array (select)
| <table class="dropdown-array">
|
|-
! scope="row" | .select-item {{ObsoleteIn|2.50}}
| The answer part of a select
| Array numbers, Dual scale array (select), single choice with select
| <p class="select-item">, <td class="select-item">
|
|-
! scope="row" | .dropdown-item {{NewIn|2.50}}
| The answer part of a select
| Array numbers, Dual scale array (select), single choice with select
| <p class="dropdown-item">, <td class="dropdown-item">
|
|-
! scope="row" | .hide {{ObsoleteIn|3.0}}
| Used for accessibility: hidden with css but read by screenreader, since 2.50 : you can use sr-only from bootstrap
| Short text question
| <label class="hide">
| Can be used for other purposes
|-
! scope="row" | .ls-js-hidden {{NewIn|3.0}}
| Used for part to be hidden if javascript is activated
| Button for example
| <div class="ls-js-hidden">
| LimeSurvey core used it, but you can use it too in your template
|-
! scope="row" | .ls-js-hidden-sr {{NewIn|3.0}}
| Used for accessibility: hide it if js is activated, but always show if user use a screenreader
| Button for example
| <a class="ls-js-hidden-sr">
| Button
|-
! scope="row" | .ls-no-js-hidden {{NewIn|3.0}}
| Used for part to be hidden if javascript is not activated
| Link
| <a class="ls-no-js-hidden">
| LimeSurvey core used it for inactive link if javascript is not activated
|-
! scope="row" | .ls-label-xs-visibility {{NewIn|3.0}}
| Label to be hidden in big screen, but show with little screen (with no more table) and to screenreader
| label
| <label class="ls-no-js-hidden">
| Used for label inside table cell of array question type
|-
! scope="row" | .ls-input-group-extra {{NewIn|3.0}}
| Same usage of boostrap input-group-addon, but without the border and the background.
| right suffix
| <div class="ls-input-group-extra">
| Used for right and left suffix (global)
|-
! scope="row" | .checkbox {{ObsoleteIn|3.0}}
| input[type=checkbox]
| Question with checkbox
| <input type="checkbox" class="checkbox">
| With modern browser: not needed, but some old browser need this
|-
! scope="row" | .radio {{ObsoleteIn|3.0}}
| input[type=radio]
| Question with radio
| <input type="radio" class="radio">
| With modern browser: not needed, but some old browser need this
|-
! scope="row" | .text
| input[type=text]
| Question with input text, or textarea
| <textarea class="text">
|
|-
! scope="row" | .answertext
| Array question type
| Answer part of array question type
| <th class="answertext">
|
|-
! scope="row" | .col-answers
| Array question type
| Column of answers
| <col class="col-answers">
|
|-
! scope="row" | .odd .even {{ObsoleteIn|2.50}}
| Array question type
| Alternation for column
| <col class="odd">
|
|-
! scope="row" | .array1 .array2 {{ObsoleteIn|3.0}}
| Array question type
| Alternation for line
| <tr class="array1">
|
|-
! scope="row" | .ls-odd .ls-even {{NewIn|3.0}}
| Array question type
| Alternation for sub-question and Y axis
| <tr class="ls-odd">
|
|}

=== Some example of question part with classes=== 


'''Text-short question type:'''
</translate><source lang="html4strict">
<p class="question answer-item text-item ">
<label class="hide label" for="answerSGQA">Answer</label><input type="text" value="" id="answerSGQA" name="SGQA" size="50" class="text empty">
</p>
</source><translate>


'''Multiple short text'''
</translate><source lang="html4strict">
<ul class="subquestions-list questions-list text-list">
<li class="question-item answer-item text-item" id="javatbdSGQA">
<label for="answerSGQA">Some example subquestion</label>
<span><input type="text" value="" id="answerSGQA" name="SGQA" size="20" class="text empty"></span>
</li>
</ul>
</source><translate>


'''Array question type'''
</translate><source lang="html4strict">
<table class="question subquestion-list questions-list ">
<caption class="hide read">Some explanation for accessibility.</caption>
<colgroup class="col-responses">
<col width="50%" class="col-answers">
<col width="25%" class="odd">
<col width="13.3%" class="col-no-answer even">
</colgroup>
<thead>
<tr class="array1 dontread">
<td> </td>
<th>1</th>
<th>No answer</th>
</tr>
</thead>
<tbody>
<tr class="array2 answers-list radio-list" id="javatbdSGQ">
<th width="20%" class="answertext">Some example subquestion
</th>
<td class="answer_cell_001 answer-item radio-item">
<label for="answerSGQA" class="hide read">1</label>
<input type="radio" value="1" id="answerSGQA" name="SGQA" class="radio">
</td>
<td class="answer-item radio-item noanswer-item">
<label for="answerSGQA" class="hide read">No answer</label>
<input type="radio" value="" id="answerSGQA" name="SGQA" class="radio">
</td>
</tr>
</tbody>
</table>
</source><translate>

==The full list of question classes== 


{|
|'''Question Type'''||'''Question Class'''||'''Question ID'''
|-
|5 point choice||.choice-5-pt-radio||5
|-
|Array (10 point choice)||.array-10-pt||B
|-
|Array (5 point choice)||.array-5-pt||A
|-
|Array (Flexible Labels) dual scale||.array-flexible-duel-scale ||1
|-
|Array (Increase, Same, Decrease)||.array-increase-same-decrease||E
|-
|Array (Multi Flexible) (Numbers)||.array-multi-flexi ||:
|-
|Array (Multi Flexible) (Text)||.array-multi-flexi-text||;
|-
|Array (Yes/No/Uncertain)||.array-yes-uncertain-no||C
|-
|Array (flexible labels)||.array-flexible-row ||F
|-
|Array (flexible labels) by column||.array-flexible-column||H
|-
|Boilerplate question||.boilerplate||X
|-
|Date||.date||D
|-
|Gender||.gender||G
|-
|Huge free text||.text-huge||U
|-
|Language switch||.language||I
|-
|List (dropdown)||.list-dropdown||!
|-
|List (radio)||.list-radio||L
|-
|List with comment||.list-with-comment||O
|-
|Long free text||.text-long||T
|-
|Multiple numerical input||.numeric-multi||K
|-
|Multiple options||.multiple-opt||M
|-
|Multiple options with comments||.multiple-opt-comments||P
|-
|Multiple short text||.multiple-short-txt||Q
|-
|Numerical input||.numeric||N
|-
|Ranking||.ranking||R
|-
|Short free text||.text-short||S
|-
|Yes/No||.yes-no||Y
|-
|
|}

==The full list of validation classes== 


<div class="simplebox">Note: Prior to 1.92, only .mandatory and .input-error classes were available.</div>


These apply to the help and/or validation tip messages so that each type can be individually styled.


The .hide-tip option and .input-error options interact by default so that you can have validation tips hidden. However, they do appear when there are validation errors and disappear again when those errors are rectified.


All of these are designed to eliminate the need for pop-up alert messages. Instead, tips can appear/disappear as needed and are color-coded to indicate whether the answers pass the validation criteria.


Furthermore, when you first visit a page that has unmet validation criteria, you can color-code the tips in a pleasing color to show which validation criteria have not been met yet; then re-display the page using a harsher color if the person submits the page with lingering validation errors.


{|
|'''Purpose'''||'''CSS Class'''||'''Description'''
|-
|Mandatory||.mandatory||the question is mandatory
|-
|User input error||.input-error||the question had at least one validation error
|-
|Hide Tip||.hide-tip||added if you use the hide_tip option
|-
|Num answers||.em_num_answers||for for min_answers and max_answers
|-
|Value range||.em_value_range||for min/max_num_value_n and multiflexible_min/max
|-
|Sum range||.em_sum_range||for min/max/equals_num_value
|-
|Regex validation||.em_regex_validation||for regular-expression validation of the question
|-
|Question-level validation function||.em_q_fn_validation||for the em_validation_q option
|-
|Subquestion-level validation function||.em_sq_fn_validation||for the em_validation_sq option
|-
|Other comment mandatory||.em_other_comment_mandatory||for other_comment_mandatory option - shows when "other" is selected but associated comment is missing.
|-
|
|}

==Importing styles into your custom template== 


The custom question styles are near the bottom of each template's CSS file and start with:<syntaxhighlight lang="php" enclose="div">/* --------------------------- START: Question styles ------------------------------ */</syntaxhighlight>


If you're styling your own custom template, you should be able to copy everything after the above one from ''templates/default/template.css'' (for table-based layouts) or ''/templates/limespired/template.css'' (for CSS-based layouts) into your own style sheet without any impact on your other styles.

==Internet Explorer conditional style sheets== 


Because of the marked discrepancies in rendering between IE6 & IE7 and the other browsers, there are special IE conditional style sheets included for each template.


<source lang="html4strict" enclose="div">



</source>


You should include the above code within your '''startpage.pstpl''' and copies of both the IE style sheets from either ''/templates/default/'' or ''/templates/limespired'' for Tables base layout and CSS based layout respectively.


<div class="simplebox">'''Note:''' If you copy the styles into your own style sheet you will almost certainly need to tweak them.</div>

===Alternative solution for Internet explorer=== 


You can put a conditional class for body in startpage.pstpl and use this class in your template.css. This method is used in the citronade template{{ObsoleteIn|2.06}}. Adding a js / no-js class to have javascript / no javascript system.


<source lang="html4strict">



<body id="body" class="lang-{SURVEYLANGUAGE} {SURVEYFORMAT} no-js">
<script type='text/javascript'>/*<![CDATA[*/(function(H){ H.className=H.className.replace(/\bno-js\b/,'js') })(document.getElementsByTagName('body')[0]);/*]]>*/</script></source>


And in template.css use:


<source lang="css">.ie6{/*specific for internet explorer 6*/}
.ielt8{/*specific for internet explorer 6 and 7*/}
.ie{/*specific for all internet explorer */}</source>

== Right-to-Left (RTL) Languages and justify== 


The text editor within LimeSurvey is able to format RTL text. However, the editor itself shows the RTL language in a left to right format when justified. This is just an editor display issue. The RTL and justified question or text will display correctly from right to left, even when justified, in your survey or on preview.

==Keywords== 


{{Deprecated|3.0}}


Keywords within a template file get replaced by the current survey information. They are surrounded by curly brackets, for example: {SURVEYNAME}.


The following strings will be replaced by LimeSurvey when parsing the template file and presenting it to survey users. These field strings will work on almost every template except for the 'Completed Page'. (Most of these strings can be found in the common.php file. If it's not there, look in the index.php file.)


{|class=wikitable
!'''Keyword'''!!'''Template files'''!!'''Description'''
|-
|{SURVEYNAME}||All Files||The survey title
|-
|{SURVEYDESCRIPTION}||All Files||The survey description
|-
|{WELCOME}||All files (mainly for welcome.pstpl)||The survey 'welcome' text
|-
|{PERCENTCOMPLETE}||survey.pstpl||A small graph showing the percentage of the survey completed
|-
|{GROUPNAME}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group name
|-
|{GROUPDESCRIPTION}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group description
|-
|{NUMBEROFQUESTIONS}||welcome.pstpl||Displays the total number of questions in the survey (just the number)
|-
|{THEREAREXQUESTIONS}||welcome.pstpl||Displays the sentence "There are X questions in this survey" - from the relevant language file. The X is replaced with the number of questions. Note that this will also work appropriately for singular or plural. If there is only 1 question, it will print "There is 1 question in this survey".
|-
|{CHECKJAVASCRIPT}||All files (mainly for welcome.pstpl)||Warning message when end-user browser have javascript disabled
|-
|{QUESTION}||Question.pstpl||('''Has been superseeded as of LS1.87''') Displays the current question text (The format of {QUESTION} can customised by editing 'question_start.pstpl') Use the following: {QUESTION_TEXT}, {QUESTION_MANDATORY}, {QUESTION_HELP}, {QUESTION_MAN_MESSAGE}, {QUESTION_VALID_MESSAGE}, {QUESTION_INPUT_ERROR_CLASS}, and appropriate wrapping HTML instead of {QUESTION}
|-
|{ANSWER}||question.pstpl, print_question.pstpl||presents the answer form for the current question
|-
|{SGQ}||question.pstpl, question text||Can be used in the question text itself to reference the input field of the question dynamically by displaying the Survey-Group-Question id for the current question. (as of svn build 9755)
|-
|{QUESTIONHELP}||question.pstpl, print_question.pstpl||Displays help text (predefined tip for question type) for the current question
|-
|{QUESTION_CLASS}||question.pstpl, print_question.pstpl||unique class for each question type. (To be included in the question's wrapping tag.)
|-
|{QUESTION_CODE}||question.pstpl, print_question.pstpl||Displays the current question code
|-
|{QUESTION_ESSENTIALS}||question.pstpl||the question ID and (if a question is conditional), 'style="display:none;"'. (To be included in the question's wrapping tag.)
|-
|{QUESTION_HELP}||question.pstp, question_start.pstpl||Displays the user defined help text for the current question
|-
|{QUESTION_TYPE_HELP}||print_question.pstp||Displays the user defined help text for the current question
|-
|{QUESTION_INPUT_ERROR_CLASS}||question.pstp, question_start.pstpl||Provides a class if there was user input error
|-
|{QUESTION_ID}||print_question.pstp||Provides a unique ID for each question to allow styling for specific questions
|-
|{QUESTION_TEXT}||question.pstp, print_question.pstp, question_start.pstpl||Displays the text for the current question
|-
|{QUESTION_MANDATORY}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' text for the current question
|-
|{QUESTION_MAN_CLASS}||question.pstpl, print_question.pstpl||class if a question is mandatory. (To be included in the question's wrapping tag.)
|-
|{QUESTION_MAN_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' help message text for the current question
|-
|{QUESTION_NUMBER}||print_question.pstpl||Incremental count of questions.
|-
|{QUESTION_VALID_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated valid help message text for the current question
|-
|{QUESTION_SCENARIO}||print_question.pstp||Prints out the 'scenario' text for conditional questions.
|-
|{NAVIGATOR}||navigator.pstpl||Displays navigation buttons (next, prev, last)
|-
|{CLEARALL}||All files (but intended for navigator.pstpl)||Displays the "Exit and Clear Results" link
|-
|{COMPLETED}||completed.pstpl||Displays the 'completed' message for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{URL}||completed.pstpl||Displays the survey 'url' and 'url text'
|-
|{PRIVACYMESSAGE}||privacy.pstpl||The privacy message is shown if you set your survey to be anonymous. [[Translating LimeSurvey|The text can be edited/translated]] in the language files. This can also be changed manually by editing the privacy.pstpl template you wish to use.
|-
|{TEMPLATEURL}||All Files||The URL to the current template location (useful for referencing image files in your template)
|-
|{SURVEYRESOURCESURL}||All Files||The URL to the current uploaded files for this survey location (useful for referencing image files in your question, group, ....)
|-
|{SUBMITCOMPLETE}||endpage.pstpl||The statement (from the language files) that tells the user they have completed the survey, and to press the "Submit" button
|-
|{SUBMITREVIEW}||survey.pstpl||The statement (from the language files) that tells the user they can review/change the answers they have made by clicking "<< prev"
|-
|{SAVEDID}||All Files||Displays 'Response ID' of user
|-
|-
|{QUEXMLPDF}||All Files||Displays button to export the queXML PDF of questionnaire including answers entered up until the point that has been completed in the survey.
|-
|{TOKEN:FIRSTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users first name from the tokens table
|-
|{TOKEN:LASTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users last name from the tokens table***
|-
|{TOKEN:EMAIL}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users email from the tokens table***
|-
|{TOKEN:ATTRIBUTE_1}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_1 from the tokens table***
|-
|{TOKEN:ATTRIBUTE_2}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_2 from the tokens table***
|-
|{ANSWERSCLEARED}||Preferably in navigator.pstpl||The "Answers Cleared" statement from the language files
|-
|{RESTART}||clearall.pstpl||URL to restart the survey
|-
|{REGISTERERROR}||register.pstpl||Shows any error messages in the register page (ie: "You must include an email address")
|-
|{REGISTERMESSAGE1}||register.pstpl||The statement "You must be registered to complete this survey" from the language files
|-
|{REGISTERMESSAGE2}||register.pstpl||Details about registering from the language files
|-
|{REGISTERFORM}||register.pstpl||The actual form for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{SAVE}||Works suitable on navigator.pstpl||Displays the 'Save your responses so far' button to offer the user to save and come back later to continue the survey. If the Save option is deactivated in the survey properties the tag will not be shown and ignored.
|-
|{LANGUAGECHANGER}||survey.pstpl||Displays a switch in multilingual surveys to change the question.
|}

==Input/Buttons== 


Each "input" type in a survey has been given its own class name, so that you can add CSS to your "startpage.pstpl" file and have some control over the appearance of form buttons and inputs. These class names are as follows:
*'''submit''' (Submit Buttons)
*'''text''' (Text Inputs - for short free text, date, and numerical type)
*'''answertext''' (Text of answers)
*'''radio''' (Radio Buttons)
*'''checkbox''' (Check Boxes)
*'''select''' (Select / List Boxes)
*'''textarea''' (Large text inputs - for long free text)
*'''clearall''' (The "Exit and Clear Survey" link)
*'''rank''' (The rank style question. Doesn't set the colour of the select box or the text boxes, but it does allow the changing of background colour, text colour, size etc., for the rest of the ranking question)
*'''graph''' (The "percentage completed" graph table)
*'''innergraph''' (The table inside the graph table - this contains the 0% and 100% text. Use this for changing the size of this text)
*'''question''' (General settings for any question that is displayed within a table. Generally, you should use this to make sure that their font size and color is the same as you have used elsewhere as a default)
*'''mandatory''' (Mandatory questions)
*'''input-error''' (User input error - for if a user has made a mistake with a mandatory question or question with validation)
*'''array1''' and '''array2''' (These two styles are cycled when presenting the range of answers for an array type question. This allows you to set an alternating background color for these question types. '''Array1''' is also used for the column headings in these question types)
*'''errormandatory''' (Sets the color and style of the "This question is mandatory" error message)
*'''warningjs''' (Sets the color and style of the warning message displayed if the participant's browser has javascript disabled)


There are also some elements that can be accessed using the ID of the element ('''#ID''' in CSS):
*'''surveycontact''' (The contact message shown on the start page)
*'''tokenmessage''' (used for messages inside the survey, e.g. the session expired error message)


Because you can edit all the HTML aspects, there's no reason to surround your templates with a
<syntaxhighlight lang="php" enclose="div"><div class='new_name'></div></syntaxhighlight>
and then define a css for that new_name class.

==Styling the progress bar== 


The progress bar appearance can be modified with CSS.


To change the background color of the bar, add something like the following to the end of your template.css file:


<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-header {
background-color: #3300FF;
}</syntaxhighlight>


To change the border color of the bar, add something like the following to the end of your template.css file:


<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-content,
#progress-wrapper .ui-widget-header {
border: 1px solid #FF0000;
}</syntaxhighlight>

==Advanced Features Available to Developers== 


LimeSurvey has integrated some user-made patches that permits some special changes. These very advanced features (generally) require changes to the underlying code base of LimeSurvey and should be done carefully in order not to introduce security holes.

===Support for your own Javascript functions=== 


Some users may need to run Javascript on the survey pages, but calling '''checkconditions()''' in the BODY element made it impossible to do so. This call has been replaced with a small JavaScript function in the HEAD that sniffs for the existence of '''checkconditions()''' and '''template_onload()''' before calling them. In this way, a template author can create his or her own '''template_onload()''' function in the HEAD that replaces the default one.


*Disable XSS filter - in Global settings -> Security, set "Filter HTML for XSS" to No.
*Enter your script in the source of a question or group description.


{{Note|For further details, see the [[Workarounds: Manipulating a survey at runtime using Javascript#How to use Script (eg. JavaScript etc.) in LimeSurvey|workaround section]].}}

=Videos on Templates= 


This video will demonstrate the basic and advanced template functions that are available to all LimeSurvey users. This includes changing the appearance of certain forms and inserting custom graphics. Additionally, it will thoroughly walk you through on how to edit and preview specific page templates, importing/exporting templates, modify appearance of questions in the CSS, and customizing survey description page.


Video - needed

=Tips & Tricks= 

==Some language specific element== 


If you want to have some language specific sentence in a survey, for example a help at the end of each page, you can add in a .pstl file a sentence and hidding it for other language. If we hide it in the template.css, we can use the pseudo selector :lang, but we use some class for better compatibility.


Below, there are two help sentences, in French and English. Put this on endpage.pstpl:


<syntaxhighlight lang="php" enclose="div"><div class="fr" lang="fr">Pour de l'aide en direct appelez le 000000</div>
<div class="en" lang="en">For some help, please call 000000</div></syntaxhighlight>


and in template.css:


<syntaxhighlight lang="php" enclose="div">.lang-fr .en{display:none}
.lang-en .fr{display:none}</syntaxhighlight>

==Change the layout of the survey page== 


After editing and saving a template, it applies to a survey list page only if it is selected from the settings of the survey. To make it the default template, go under the '''General tab''' located in the '''Global settings''' of your LimeSurvey installation and choose the desired template. From now on, all the templates that use the "default" option as template plus the ones that are going to be newly created, will use the newly selected default template.


To use your current template for this page, you have to change the according setting from '''Global settings'''. In older versions, this change can be done by editing the $defaulttemplate setting from the config file: copy this setting from config-defaults.php to config.php which overrides config-defaults.php and edit this setting to <code lang="html">$defaulttemplate = 'yourtemplatename';</code>.

==Import/Export of templates: Mac users== 


<u>Mac users</u>, please note that the Mac OSX default archive utility may have problems with zip folders "generated on the fly".


A workaround is to unix'es unzip from the command line:


$ unzip template.zip -d template


Archive: template.zip


inflating: template/startpage


inflating: ...


Another workaround is to use scripts in their mac-compiled counterparts.

==Replacing the help icon {{ObsoleteIn|2.50}} == 


When a question help text is shown, then an help.gif image is used from the default template folder.


You can replace this image by uploading a new help.gif, help.png or help.jpg in your custom template folder. It will then be automatically used instead of the default help icon.

==Replacing an existing logo {{NewIn|2.50}} {{ObsoleteIn|3.0}}== 


'''Note''': In the '''default'' Template of 2.50, there is no preembedded logo. Read further our [[#Adding_your_own_logo |wiki on how to add your own logo]].


1. To edit the logo go to the ''<u>template.css</u>'' file which you can find it here:


<center>[[File:t1.PNG|200px]]</center>


2. Click the search button to find occurrences of logo related styles and search for ''logo''


<center>[[File:2.png|200px]]</center>


4. Edit the main style file.


You will see something similar to:


<center>[[File:t4.PNG|500px]]</center>


If you want to change the image, just replace logo.gif with another image link. Example: (<u>logo.png</u> or <u>logo.jpg</u>).


If you want to change the image size, adjust width and height (in pixels) like this:


<syntaxhighlight lang="php" enclose="div">width:100px; height:100px;</syntaxhighlight>

==Adding your own logo {{ObsoleteIn|3.0}} == 


1. Find and open the '''startpage.pstpl''' template file.


<center>[[File:startpage.pstpl.png]]</center>


2. After this
<source lang="html4strict" ><div id="topContainer" class="jumbotron"></source>
add this line to '''startpage.pstpl''':
<source lang="html4strict">
<div class="container"><img id='page_logo' src='{TEMPLATEURL}/files/logo.png' class="clearfix pull-right" /></div>
</source>


3. To upload your own logo, go to the template editor and upload your logo.


<center>[[File:uploadyourlogo.png]]</center>


To position your logo, please use one of the following css classes:


*'''If you want the logo to be placed on the left side:'''


<source lang="html">clearfix pull-left</source>


*'''If you want the logo to be placed on the right side:'''


<source lang="html">clearfix pull-right</source>


*'''If you want to center the logo'''


<source lang="html">clearfix center-block</source>

==Use the same template with different logos== 


If you want to use the same template for all surveys and just want to change the logo for each survey, you can use the {SID} placeholder in the template .pstpl file and thereby refer to different images:


<syntaxhighlight lang="php" enclose="div"><img src="{TEMPLATEURL}files/logoImage-{SID}.png"></syntaxhighlight>

==Remove the default help to all question (hide_tip) {{ObsoleteIn|1.92}}== 


There are 3 solutions to remove the default help:
# like a hide_tip attribute but for all question and survey.
# you can remove the {QUESTIONHELP} and its container from the file question.pstl. However, it can be a bad idea for the screenreader.
# for the default template and some other, add this at the end of tempate.css


<syntaxhighlight lang="php" enclose="div">span.questionhelp{display:none;}</syntaxhighlight>

== Display custom favicon== 


A favicon is the little icon you see in the browser's address bar, list of bookmarks or tab. You can display your own icon as follows:
#Create a favicon - google will find you lots of free favicon generators.
#Name your new favicon "favicon.ico" and place it in your template /files directory.
#Add the following code to your '''startpage.pstpl''' before the </head> tag.


<syntaxhighlight lang="html4strict" enclose="div"><link rel="shortcut icon" href="{TEMPLATEURL}files/favicon.ico" type="image/x-icon">
<link rel="icon" href="{TEMPLATEURL}files/favicon.ico" type="image/x-icon"></syntaxhighlight>

== Different appearance for survey-/question-pages== 


If you want LimeSurvey to change the appearance of every second page (i.e. of even and odd survey pages), you can use '''.page-odd''' class in your CSS file to change the appearance of odd pages.


An example from default template of LimeSurvey 1.91+:


<syntaxhighlight lang="php" enclose="div">
.page-odd table.question-group {
background-color: #D2F2D3;
}</syntaxhighlight>


If you do '''not''' want differentiate even and odd pages, find all instances of ''.page-odd'' in template.css and remove those styles.

==Create a vertical separator border for dual scale array== 


To create a vertical separator border for a dual scale array, you can add the following lines to your '''template.css'''-file.


<syntaxhighlight lang="php" enclose="div">
table.question thead td.header_separator,
table.question tbody td.dual_scale_separator
{
border-right:solid 1px #00A8E1;
}
</syntaxhighlight>


''header_separator'' is used to adress the separator for the header "td". The "dual_scale_separator" is used to address the separator column in the dual scale array.

==Hide the survey contact message shown on the start page/survey list {{ObsoleteIn|3.0}} == 


To hide the "Please contact ..." message on the start page (with the survey list), you can add the following to the '''$(document).ready''' function in the '''template.js''' of your used design template:


<syntaxhighlight lang="php" enclose="div">


$('#surveycontact').hide(); //Hides the survey contact message


</syntaxhighlight>

==Remove the survey contact message shown on error messages {{ObsoleteIn|3.0}}== 


If you want to remove the survey contact message from error messages, it'll be trickier. You can add the function from below. It calls the '''$(document).ready''' function in the '''template.css''' of your used design template:


<syntaxhighlight lang="php" enclose="div">
removeContactAdressFromMessage(); //Removes the survey contact message from error messages
</syntaxhighlight>


and add the following function to your *template.js* file


<syntaxhighlight lang="php" enclose="div">
function removeContactAdressFromMessage()
{
if ($('#tokenmessage').length > 0)
{
var oldMessage = $('#tokenmessage').html();
var indexContact = oldMessage.indexOf('Bitte kontaktieren');
var newMessage = oldMessage.substr(0, indexContact);
$('#tokenmessage').html(newMessage);
}
}
</syntaxhighlight>


It will probably not work for a survey in English language and has to be extended when used for multilingual surveys. But it's an idea/tip on how to solve this.

==How to deal with multilingual question attributes {{ObsoleteIn|2.50}}== 


If you have a multilingual survey and e. g. want to use a different string for the "other" field, this could only be done for the base language (until this feature was added at LimeSurvey 2.0). To work around this, paste in the field to change the label for "other":


<syntaxhighlight lang="php" enclose="div"><span class="en">New label</span><span class="fr">Nouveau label</span></syntaxhighlight>


Add in the template.css of your template (at ''/limesurvey/upload/templates/<yourtemplatename>/template.css''):


<syntaxhighlight lang="php" enclose="div">html:lang(en) .fr{display:none}
html:lang(fr) .en{display:none}</syntaxhighlight>

==Adding your own logo to the survey list {{ NewIn|3.0}} == 


# First please open the theme editor for the theme you like to use. [[File:OpenThemeEditor.jpg]]
# We recommend to use fruity, it is our best theme currently.
# Then extend the theme and give it a name you will recognize. [[File:ExtendTheme.jpg]]
# In the following view you may upload the logo you want to use. [[File:UploadFileTheme.jpg]]
# Select the editor screen `Survey List´ in the Screen dropdown in the top right corner. [[File:OpenScreenSurveyList.jpg]]
# Then select `layout_survey_list.twig´ in the left side menu. [[File:EditLayoutSurveyListTwig.jpg]]
# In the editor scroll to line 126 and change the marked part to the filename of the image you uploaded to the theme before. [[File:ChangeSurveyListHeaderImageEditor.jpg]]
# Save your file. [[File:ThemeEditorSaveChanges.jpg]]
# Change default theme to your extended theme. [[File:ChangeDefaultTheme.jpg]]

=Custom Question Views {{NewIn|3.0}}= 


<div class="simplebox">'''Note:''' This is a temporary feature to be replaced in the future by question object (it will be very easy to move custom views to question object). It is disabled by default.</div>


As of version 2.5, you can create template-specific custom views for questions and some of their incorporated elements. This is useful if you want to modify the HTML layout of a particular question type for one or more surveys.


*In application/config/config.php, find 'config'=>array and add this line to the array : 'allow_templates_to_overwrite_views'=>1
*In /{your_template}/config.xml, set "overwrite_question_views" to true
*Copy application/views/survey/* to template/{your_view_directory}/survey/
*Note that you only need to copy the files that you intend to modify but the file structure must remain the same as in application/views/survey/

=Insert Custom CSS or JavaScript files for template {{NewIn|2.50}}= 


As of version 2.50, you can use the config.xml file to automatically load plugin files.


*Upload your files to the template /css or /scripts folder
*In /{your_template}/config.xml, add the file paths to the <css> or <js> blocks, something like this:<syntaxhighlight lang="xml" enclose="div"><css>
<filename>css/jquery-ui-custom.css</filename>
<filename>css/bootstrap-slider.css</filename>


<filename>css/awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</filename>
<filename>css/flat_and_modern.css</filename>


<filename>css/template.css</filename>


<filename>css/myCustomPlugin.css</filename>
</css>
<js>
<filename>scripts/template.js</filename>
<filename>scripts/bootstrap-slider.js</filename>


<filename>scripts/myCustomPlugin.js</filename>
</js>
</syntaxhighlight>

</translate>

Theme editor

2018-04-04T10:17:30Z

LouisGac:

<languages /> <translate>

=Introduction= 


LimeSurvey has an advanced theme and style system providing to developers an efficient way to customize the survey appearance. Since LS3, we're not speaking anymore about '''"templates"''' like in previous versions, but about '''"themes"'''. The '''themes''' allow control over the look and feel of pages during a survey. A survey administrator can select a default theme that will be used for each survey to further personalize it and improve its look and feel. '''Themes''' come with options that provide to admin without coding skill a simple way to add a logo on the welcome page, to change the background colors, to select a font, etc.


LimeSurvey comes with 3 themes right out of the box. These initial themes are defined by directories located in the LimeSurvey installation "themes/survey/" directory. Each theme has it's own directory. Within the main directory of a theme you'll find a configuration file in XML, and numerous directories containing the views ''themes (.twig)''', '''cascading style sheets (.css)''', '''scripts''', '''images''' ('''.jpg''' or '''.png'''), and maybe others.


Since LimeSurvey 2.50, the theme engine use [http://getbootstrap.com/docs/3.3/ Bootstrap 3] as CSS framework. Bootstrap 3 being a standard framework, developers will find a lot of documentation, tutorials and forum threads about it on Internet.

Since LimeSurvey 3, the theme engine use [https://twig.symfony.com Twig], so the theme developers can change the logic of the survey rendering in a safe and easy way. Twig replace the old system of replacement keywords that was used in the previous versions. The logic that was used to generate the HTML of the keywords are now available inside the theme's views.

Snippet from Vanilla Theme:


<syntaxhighlight lang="twig" enclose="div">
<div class="{{ aSurveyInfo.class.answercontainer }} col-xs-12" {{ aSurveyInfo.attr.answercontainer }}>
{# NOTE: If you want to customize the question rendering, use a question theme #}
{{ aQuestion.answer | raw }}
</div>
</syntaxhighlight>


One gets a result that looks like:


<div class="simplebox"><div style='text-align: center;'><span style='color:red'>My New Survey</span></div>
<div style='text-align: center;'><span style='color:red'>This is a survey written by me to find out what sort of chocolate people like.</span></div></div>


Templates, being HTML code, tend to define the positioning and type of text to be displayed and similar structural features of the page. They often reference or include other files. Most of them reference a common cascading style sheets (CSS) file that defines the font style, color, size, background, and similar parameters common to all pages in the survey. Style sheets reference HTML '''class''' parameters that are associated with the various types of objects in the HTML code. This allows the style sheet to describe how to display each of the many types of text or other objects that may appear in multiple places. There are unique classes for each question type in LimeSurvey and thus giving detailed control over the appearance of each. Image files, like logos or special progress-bar constructors, may be referenced as well in the Template file. Finally, special keywords in curly braces are replaced with text defined in the survey for each language translation correspondent (for example, the 'Survey Title' or 'Question Text' for each language defined).


If you create a new custom template, please consider contributing it back to the LimeSurvey community and make it available to others. With your help, we can grow our repository of templates, surveys, and other add-ons to make LimeSurvey even better!
See our [https://www.limesurvey.org/index.php?option=com_sobipro&sid=55:Templates&Itemid=729 LimeSurvey template repository] where you can share your templates.

=Creating a new template= 


To be able to create a new template (or edit an existing template), you need [[Manage users#Set global permissions for a user|Template Editing user permission]] in LimeSurvey as well as permission to manipulate the files in the underlying operating system hosting your LimeSurvey installation.


<div class="simplebox"><span style='color:red'>'''Note of Warning:'''</span> If you change templates, you could also affect all the pre-existing surveys from your LimeSurvey installation. Templates are an advanced feature that require experience and HTML knowledge in order to make them running smoothly.</div>


The preferred way to create a new template is through the '''Template Editor''' (see below), which is located in the '''Configuration''' dialog. Some people may like to work directly with template files so that they can use their favorite text editor instead of the web interface. In this case, still use the Template Editor to first create your new template. This will create a new base template with all the files you need in the ''LimeSurvey_web_root/upload/templates/your_new_template'' directory. From there you can use your text editor to manually adjust the template files.


<div class="simplebox">'''Permissions Note:''' on unix/linux systems, these template files will be owned by the group and user where the web server is running (may be "www" for some systems). So, make sure you have enough access to edit these files, When you save them, make sure they don't change ownership! In this way, you can still use the web Template Editing interface if needed.</div><br />


A number of 'public' elements of LimeSurvey can be adjusted by a series of templates. The next section provides a very brief explanation of these templates.


{{Note|Template files may seem complex. Besides HTML, you might also need to understand CSS.}}

=The LimeSurvey template editor= 


To ease the understanding and quick update of a Template, LimeSurvey provides a '''Template Editor''' in the main '''administrative''' toolbar of the application. This Template Editor is only available to users [[Manage users#Set global permissions for a user|with the Templates permission]] and to superadministrators.


{{Alert|title=Attention|text=A template that is not correctly constructed can render a survey (that uses the respective template) inoperable. }}


The LimeSurvey template editor allows you to edit the contents of your templates online. Start the Template Editor by clicking on '''Template editor''' in the '''Configuration''' menu.


[[File:templates.png]]


The template editor page allows you to select the template you would like to edit/view.


[[File:Template-editor-2013-7-10_11_38_16.png|center]]

==The template menu== 


The following options are available:


*'''Create''': Allows you to create a new template. In order not to start from scratch, the template 'default' is copied.
*'''Import''': Allows you to import a template from a ZIP file.
*'''Export''': Allows you to export the current template to a ZIP file.
*'''Copy''': Allows you to make a new template by copying the current one.
*'''Rename''': Allows you to change the name of the template. It is generally used after copying or importing a template.
*'''Template''': It is a drop-down list that shows all the available templates that are located in your LimeSurvey installation.


*'''Screen''': It is a drop-down list which allows you to choose which particular survey page of that template you want to look at.
*'''Return to admin panel'''.

==Import/export/copy a template== 


When you '''export '''a template, a ZIP-file archive with all the files your template consists of will be created (.pstpl files, images, css files, ...). You can simply '''import''' the exported zip-file into another LimeSurvey installation by using the import feature or you can manually copy the archive into another LimeSurvey installation and extract it into the corresponding [[Theme editor#Template files location|template directory there]].


However, it is preferred to use the LimeSurvey template import/export/copy functions in the template editor.

==Page Structure / Template Use== 
*'''The Welcome Page:''' startpage.pstpl, welcome.pstpl, privacy.pstpl, navigator.pstpl, endpage.pstpl
*'''The Questions Pages:''' startpage.pstpl, survey.pstpl, startgroup.pstpl, groupdescription.pstpl, question.pstpl, endgroup.pstpl, endpage.pstpl
*'''The Final Page:''' startpage.pstpl, assessment.pstpl, completed.pstpl, endpage.pstpl

==Template Files== 


The following template files are used to produce your public survey and must exist in any new template folder you create:
*'''startpage.pstpl:''' Produces the start of each html page. It starts at the "<head>" tag, and should not contain the "<html>" tag. This 'very beginning' of a standard html page is written by the scripts. Please ensure that your startpage.pstpl files contains a <body> tag. Even though many browsers do not require strict adherence to the W3 HTML standards, the LimeSurvey script needs to find a <body> tag to run certain javascript elements. It is not expected to see many 'keywords' used in the startpage.pstpl file. However, you may wish to put the {SURVEYNAME} into the title. The startpage.pstpl file can contain code that ends in the corresponding endpage.pstpl file. For example, you can start a table in this file and close the table in the endpage.pstpl file. The startpage.pstpl and endpage.pstpl files wrap around every possible page used by LimeSurvey.
*'''survey.pstpl:''' This template is the second used on most pages and provides a space to put the survey name and description. This template does not have a corresponding 'closing' template, and subsequently you should close all tags opened in this template file (i.e.: don't leave a table open here because there is nowhere else to close it).
*'''welcome.pstpl:''' This template is only used in the welcome screen (which is also on the main page for 'all in one' surveys). You can use this to print out the welcome text, and other information that should be provided in the introduction. Like the 'survey.pstpl' file, there is no corresponding 'closing' template, so all tags opened in this template file should be closed as well.
*'''startgroup.pstpl:''' This template can provide a 'summary' wrap around for questions within a group. It has a matching 'endgroup.pstpl' template that can be used to close any opened tags in this file, so you can open a table within this.
*'''groupdescription.pstpl:''' This template file is used to display a description of a group. Please note that in the survey settings (access the ''Presentation & navigation settings'' by clicking on the '''Presentation''' tab) you can set if the group description should be shown or not. If not, then this file is not included at all.
*'''question.pstpl:''' This file contains the question, answer, and help text sections of your survey. In the "group by group" and "all in one" surveys, this template is cycled repeatedly with each question. There is no corresponding closing file for this and all tags should be closed.
*'''question_start.pstpl:''' This file contains the individual elements found at the start of a question. It is included within 'question.pstpl' via the {QUESTION} keyword. It is intended to allow template designers more control over the layout of a question. This template sits outside the normal templating system and '''was superseeded (as of LimeSurvey 1.87)'''. All keywords from this template are now available directly in question.pstpl.
*'''completed.pstpl:''' This page is displayed as the final page when the survey responses have been saved and the survey is over. It can be used to display a "forwarding link" as set in the survey setup.
*'''endgroup.pstpl:''' This file closes the group, and can be used to close off any tags opened in the startgroup.pstpl file
*'''navigator.pstpl:''' This file contains the buttons that navigate through the survey, "next", "prev", "last", "submit", "save so far" and the "clear all" link. It is used in all pages except the completed page.
*'''printanswers.pstpl:''' This file has the HTML wrapper necessary for the print version of the survey.
*'''print_group.pstpl:''' This file is the same as startgroup.pstpl and endgroup.pstpl, but for the print version of the survey.
*'''print_question.pstpl:''' This file is the same as question.pstpl, but for the print version of the survey.
*'''print_survey.pstpl:''' This file is the same as survey.pstpl, but for the print version of the survey.

== CSS and Javascript== 


Two files that are always used in a template are template.css (for CSS) and template.js (for Javascript).
*'''{TEMPLATECSS}:''' Add lines for default css, template.css, and template-rtl.css for rtl language.
*'''{TEMPLATEJS}:''' Add lines for default javascript files, template.js, and all js files needed for LimeSurvey.

=== Using Bootstrap=== 
LimeSurvey has Bootstrap 3 embedded, so you can style all your templates with the well documented Bootstrap classes.
For more information please refer to the [https://getbootstrap.com Bootstrap documentation].


The [https://github.com/flatlogic/awesome-bootstrap-checkbox Awesome-Bootstrap-Checkbox] plugin is also included. With it, you can use the typical Bootstrap color-classes (info,warning,danger,etc.) also with the suffix "-checkbox" or "-radio", though styling checkboxes and radios as you prefer.

=== Replacing default CSS or Javascript=== 


Some questions use specific files for Javascript or CSS. If you need to replace a function, use a cascading system. For javascript function, the last function read is the function used.

==Other Template Files== 


The '''privacy.pstpl''', '''invitationemail.pstpl''', '''reminderemail.pstpl''', and '''confirmationemail.pstpl''' are no longer used by LimeSurvey and defaults are instead set in the applicable language files. The email messages can now be edited on a survey by survey basis.

==Standard Pages== 


There are ten standard pages that a survey participant may see in the course of taking or accessing the LimeSurvey application. Each is constructed from a number of common '''Template''' files from the '''Template''' specified in the settings of the survey. The table below indicates which template files are used in constructing each of these pages.


{| class="wikitable"
! '''Survey Pages/'''<br />'''Template Files'''!!Survey<br />List!!Welcome!!Question!!Completed!!Clear All!!Register!!Load!!Save!!Print<br />Answers!!Print<br />Survey
|-
|SurveyList||align="center" | [[File:check.gif]]|| || || || || || || || ||
|-
|Welcome|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Privacy|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Navigator|| ||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Survey|| || ||align="center" | [[File:check.gif]]|| || ||align="center" | [[File:check.gif]]|| || || ||
|-
|StartGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|GroupDescription|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Question<span style='color:red'>'''*'''</span>|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|EndGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Assessment|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|Completed|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|ClearAll|| || || || ||align="center" | [[File:check.gif]]|| || || || ||
|-
|Register|| || || || || ||align="center" | [[File:check.gif]]|| || || ||
|-
|Load|| || || || || || ||align="center" | [[File:check.gif]]|| || ||
|-
|Save|| || || || || || || ||align="center" | [[File:check.gif]]|| ||
|-
|PrintAnswers|| || || || || || || || ||align="center" | [[File:check.gif]]||
|-
|Print Survey || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Group || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Question || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|StartPage<br />EndPage<br />Template.css||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||
|}


<span style='color:red'>'''*'''</span>NOTE: In version 1.90+, this replaces question.pstpl AND question_start.pstpl. If you are using an old custom template, you need to add the following line to the beginning of question.pstpl:<syntaxhighlight lang="php" enclose="div"><div {QUESTION_ESSENTIALS} class="{QUESTION_CLASS}{QUESTION_MAN_CLASS}{QUESTION_INPUT_ERROR_CLASS}"></syntaxhighlight>And then add the corresponding closing tag to the end of question.pstpl:<syntaxhighlight lang="php" enclose="div"></div></syntaxhighlight>


<span style='color:red'>'''*'''</span>NOTE: In version 1.91 and earlier, LimeSurvey js files are not included in the template. In version 2, '''you have to use {TEMPLATEJS} in one of your template file''' to add the link to the js file. You can add it in startpage.pstpl or in endpage.pstpl. You can remove the {TEMPLATEURL}/template.js line and you have to replace with {TEMPLATEJS} to update a personal template.

==The File Control Section== 


In the "file control" window on the left, you can click on one of the template files that is used to compile the page. You can see the ''Screen part'', JavaScript, and CSS files. The HTML code for that file will then appear in the "Now editing" window in the center. If the template is editable (determined by directory permissions) you can then make any changes and save them.


<center>[[File:File Control Section.png|center]]</center>


The "Other files" window shows a list of all other files from the template directory. You can use the right side to '''upload and select image files (your pics, logos,...) or other files needed to create your template'''.


Instead of using a link for each picture, utilize the field string {TEMPLATEURL}. So, instead of:


<syntaxhighlight lang="html4strict" enclose="div">img src='/limesurvey/templates/yourtemplate/files/mypicture.jpg'</syntaxhighlight>
You can use {{NewIn|2.50}}:
<syntaxhighlight lang="html4strict" enclose="div">img src='{TEMPLATEURL}files/mypicture.jpg'</syntaxhighlight>


In LimeSurvey versions before 2.50 use:
<syntaxhighlight lang="html4strict" enclose="div">img src='{TEMPLATEURL}mypicture.jpg'</syntaxhighlight>


A "sample" of the template page you are editing will be visible in the bottom of the screen. There is no way to delete a template from the template editor. This must be done by accessing the underlying directory and deleting manually the files from there. You also have the possibility to select different screen resolutions in order to better evaluate the feel and look of the template.


<div class="simplebox">'''Note:''' The shipped templates cannot be edited using the template editor. If you want to modify them, create a copy first and edit the copy.</div>

==Template files location== 


LimeSurvey stores each of the 'standard' templates in their own distinct sub-directory within the ''/templates'' directory that is kept in the public directory with the other LimeSurvey public files. Customized user templates are stored in the ''/upload/templates'' directory.


There should '''ALWAYS''' be a "default" directory in the templates directory. This template is used by default and as a fall-back if a template folder doesn't exist, or can't be found. It comes installed by default.


You can use any image files that you upload into the template management area with the help of this syntax:


<syntaxhighlight lang="php" enclose="div">{TEMPLATEURL}filename.xyz</syntaxhighlight>

=Styling questions with CSS= 


Styling of questions in CSS has become much easier. Each question type has now a unique class. The mandatory questions have an additional mandatory class. For example, for a non-mandatory question:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender">
...
</div></syntaxhighlight>


and if the question is mandatory:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory">
...
</div></syntaxhighlight>


and if the question is mandatory, but the user didn't answer it or if there is validation on a question:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory input-error">
...
</div></syntaxhighlight>


and if the question has validation applied, but the user hasn't answered correctly:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question6" class="text-short input-error">
...
</div></syntaxhighlight>

==Global classes for question part== 


These classes are used for each question type. Some question types use only one or two classes, while others may use much more.


{| class="wikitable alternance"
|+ Global classes
|-
! scope="col" | Class name
! scope="col" | Part
! scope="col" | Question type
! scope="col" | Examples
! scope="col" | Note
|-
! scope="row" | .question {{ObsoleteIn|3.0}}
| All question block
| All question type
|<p class="question">, <ul class="question">, <table class="question">
|
|-
! scope="row" | .ls-answers {{NewIn|3.0}}
| All question block
| All question type
|<div class="ls-answers ">, <ul class="ls-answers ">, <table class="ls-answers">
|
|-
! scope="row" | .subquestions-list
| List of subquestion
| Multi choice question, array question type
| <ul class="subquestions-list">, <table class="subquestions-list">
| .questions-list is used too
|-
! scope="row" | .answers-list
| List of answers
| Single choice question, array question type, Multi input text question
| <ul class="answers-list">, <table class="answers-list">
|
|-
! scope="row" | .answer-item
| The answer part: one answer
| Single choice question, array question type, Multi input text question
| <li class="answer-item">, <td class="answer-item">
|
|-
! scope="row" | .noanswer-item
| The answer part for no answer
| Single choice question, array question type
| <li class="noanswer-item">, <td class="noanswer-item">
| No answer is an answer too, then have double class noanswer-item and answer-item
|-
! scope="row" | .question-item
| The question part: one question
| Multi text question, array question type
| <li class="question-item">, <tr class="question-item">
| Some answers are questions too. Then we have a lot of class="question-item answer-item"
|-
! scope="row" | .checkbox-list
| A list of checkbox
| Multi choice question, array number (checkbox) question type
| <ul class="checkbox-list">, <tr class="checkbox-list">
| Some question types use multi-list class, like checkbox with comment: class="checkbox-list text-list"
|-
! scope="row" | .checkbox-array {{NewIn|3.0}}
| A array of checkbox
| Array (numbers) with checkbox option
| <table class="checkbox-list">
|
|-
! scope="row" | .checkbox-item
| The answer part with a checkbox
| Multi choice question, array number (checkbox) question type
| <li class="checkbox-item">, <td class="checkbox-item">
|
|-
! scope="row" | .radio-list
| A list of radio item
| Single choice question, array question type (each row)
| <ul class="radio-list">, <tr class="radio-list">
|
|-
! scope="row" | .radio-array {{NewIn|3.0}}
| A array of radio item
| Array question type
| <table class="radio-array">
|
|-
! scope="row" | .radio-item
| The answer part with a radio
| Single choice question, array question type
| <li class="radio-item">, <td class="radio-item">
|
|-
! scope="row" | .text-list
| A list of text input
| Multi text question type, array of text
| <ul class="text-list">, <tr class="text-list">
|
|-
! scope="row" | .text-item
| The answer part of a text input
| Multi text question type, array of text
| <li class="text-item">, <td class="text-item">
|
|-
! scope="row" | .numeric-list
| A list of text input with numeric only answer
| Multi numeric question type, array of number
| <ul class="text-list numeric-list">, <tr class="text-list numeric-list">
|
|-
! scope="row" | .number-list
| A list of text input with numeric only answer (each row)
| Multi numeric question type, array of number
| <ul class="text-list numeric-list">, <tr class="text-list numeric-list">
|
|-
! scope="row" | .number-array {{NewIn|3.0}}
| The answer part of a numeric input
| Array of number
| <table class="number-array">
|
|-
! scope="row" | .select-list {{ObsoleteIn|2.50}}
| A list of select
| Array numbers, Dual scale array (select)
| <table class="select-list">
|
|-
! scope="row" | .dropdown-list {{NewIn|2.50}}
| A list of select
| Array numbers, Dual scale array (select) (each row)
| <table class="dropdown-list">
|
|-
! scope="row" | .dropdown-array {{NewIn|3.0}}
| A array of dropdown
| Array numbers, Dual scale array (select)
| <table class="dropdown-array">
|
|-
! scope="row" | .select-item {{ObsoleteIn|2.50}}
| The answer part of a select
| Array numbers, Dual scale array (select), single choice with select
| <p class="select-item">, <td class="select-item">
|
|-
! scope="row" | .dropdown-item {{NewIn|2.50}}
| The answer part of a select
| Array numbers, Dual scale array (select), single choice with select
| <p class="dropdown-item">, <td class="dropdown-item">
|
|-
! scope="row" | .hide {{ObsoleteIn|3.0}}
| Used for accessibility: hidden with css but read by screenreader, since 2.50 : you can use sr-only from bootstrap
| Short text question
| <label class="hide">
| Can be used for other purposes
|-
! scope="row" | .ls-js-hidden {{NewIn|3.0}}
| Used for part to be hidden if javascript is activated
| Button for example
| <div class="ls-js-hidden">
| LimeSurvey core used it, but you can use it too in your template
|-
! scope="row" | .ls-js-hidden-sr {{NewIn|3.0}}
| Used for accessibility: hide it if js is activated, but always show if user use a screenreader
| Button for example
| <a class="ls-js-hidden-sr">
| Button
|-
! scope="row" | .ls-no-js-hidden {{NewIn|3.0}}
| Used for part to be hidden if javascript is not activated
| Link
| <a class="ls-no-js-hidden">
| LimeSurvey core used it for inactive link if javascript is not activated
|-
! scope="row" | .ls-label-xs-visibility {{NewIn|3.0}}
| Label to be hidden in big screen, but show with little screen (with no more table) and to screenreader
| label
| <label class="ls-no-js-hidden">
| Used for label inside table cell of array question type
|-
! scope="row" | .ls-input-group-extra {{NewIn|3.0}}
| Same usage of boostrap input-group-addon, but without the border and the background.
| right suffix
| <div class="ls-input-group-extra">
| Used for right and left suffix (global)
|-
! scope="row" | .checkbox {{ObsoleteIn|3.0}}
| input[type=checkbox]
| Question with checkbox
| <input type="checkbox" class="checkbox">
| With modern browser: not needed, but some old browser need this
|-
! scope="row" | .radio {{ObsoleteIn|3.0}}
| input[type=radio]
| Question with radio
| <input type="radio" class="radio">
| With modern browser: not needed, but some old browser need this
|-
! scope="row" | .text
| input[type=text]
| Question with input text, or textarea
| <textarea class="text">
|
|-
! scope="row" | .answertext
| Array question type
| Answer part of array question type
| <th class="answertext">
|
|-
! scope="row" | .col-answers
| Array question type
| Column of answers
| <col class="col-answers">
|
|-
! scope="row" | .odd .even {{ObsoleteIn|2.50}}
| Array question type
| Alternation for column
| <col class="odd">
|
|-
! scope="row" | .array1 .array2 {{ObsoleteIn|3.0}}
| Array question type
| Alternation for line
| <tr class="array1">
|
|-
! scope="row" | .ls-odd .ls-even {{NewIn|3.0}}
| Array question type
| Alternation for sub-question and Y axis
| <tr class="ls-odd">
|
|}

=== Some example of question part with classes=== 


'''Text-short question type:'''
</translate><source lang="html4strict">
<p class="question answer-item text-item ">
<label class="hide label" for="answerSGQA">Answer</label><input type="text" value="" id="answerSGQA" name="SGQA" size="50" class="text empty">
</p>
</source><translate>


'''Multiple short text'''
</translate><source lang="html4strict">
<ul class="subquestions-list questions-list text-list">
<li class="question-item answer-item text-item" id="javatbdSGQA">
<label for="answerSGQA">Some example subquestion</label>
<span><input type="text" value="" id="answerSGQA" name="SGQA" size="20" class="text empty"></span>
</li>
</ul>
</source><translate>


'''Array question type'''
</translate><source lang="html4strict">
<table class="question subquestion-list questions-list ">
<caption class="hide read">Some explanation for accessibility.</caption>
<colgroup class="col-responses">
<col width="50%" class="col-answers">
<col width="25%" class="odd">
<col width="13.3%" class="col-no-answer even">
</colgroup>
<thead>
<tr class="array1 dontread">
<td> </td>
<th>1</th>
<th>No answer</th>
</tr>
</thead>
<tbody>
<tr class="array2 answers-list radio-list" id="javatbdSGQ">
<th width="20%" class="answertext">Some example subquestion
</th>
<td class="answer_cell_001 answer-item radio-item">
<label for="answerSGQA" class="hide read">1</label>
<input type="radio" value="1" id="answerSGQA" name="SGQA" class="radio">
</td>
<td class="answer-item radio-item noanswer-item">
<label for="answerSGQA" class="hide read">No answer</label>
<input type="radio" value="" id="answerSGQA" name="SGQA" class="radio">
</td>
</tr>
</tbody>
</table>
</source><translate>

==The full list of question classes== 


{|
|'''Question Type'''||'''Question Class'''||'''Question ID'''
|-
|5 point choice||.choice-5-pt-radio||5
|-
|Array (10 point choice)||.array-10-pt||B
|-
|Array (5 point choice)||.array-5-pt||A
|-
|Array (Flexible Labels) dual scale||.array-flexible-duel-scale ||1
|-
|Array (Increase, Same, Decrease)||.array-increase-same-decrease||E
|-
|Array (Multi Flexible) (Numbers)||.array-multi-flexi ||:
|-
|Array (Multi Flexible) (Text)||.array-multi-flexi-text||;
|-
|Array (Yes/No/Uncertain)||.array-yes-uncertain-no||C
|-
|Array (flexible labels)||.array-flexible-row ||F
|-
|Array (flexible labels) by column||.array-flexible-column||H
|-
|Boilerplate question||.boilerplate||X
|-
|Date||.date||D
|-
|Gender||.gender||G
|-
|Huge free text||.text-huge||U
|-
|Language switch||.language||I
|-
|List (dropdown)||.list-dropdown||!
|-
|List (radio)||.list-radio||L
|-
|List with comment||.list-with-comment||O
|-
|Long free text||.text-long||T
|-
|Multiple numerical input||.numeric-multi||K
|-
|Multiple options||.multiple-opt||M
|-
|Multiple options with comments||.multiple-opt-comments||P
|-
|Multiple short text||.multiple-short-txt||Q
|-
|Numerical input||.numeric||N
|-
|Ranking||.ranking||R
|-
|Short free text||.text-short||S
|-
|Yes/No||.yes-no||Y
|-
|
|}

==The full list of validation classes== 


<div class="simplebox">Note: Prior to 1.92, only .mandatory and .input-error classes were available.</div>


These apply to the help and/or validation tip messages so that each type can be individually styled.


The .hide-tip option and .input-error options interact by default so that you can have validation tips hidden. However, they do appear when there are validation errors and disappear again when those errors are rectified.


All of these are designed to eliminate the need for pop-up alert messages. Instead, tips can appear/disappear as needed and are color-coded to indicate whether the answers pass the validation criteria.


Furthermore, when you first visit a page that has unmet validation criteria, you can color-code the tips in a pleasing color to show which validation criteria have not been met yet; then re-display the page using a harsher color if the person submits the page with lingering validation errors.


{|
|'''Purpose'''||'''CSS Class'''||'''Description'''
|-
|Mandatory||.mandatory||the question is mandatory
|-
|User input error||.input-error||the question had at least one validation error
|-
|Hide Tip||.hide-tip||added if you use the hide_tip option
|-
|Num answers||.em_num_answers||for for min_answers and max_answers
|-
|Value range||.em_value_range||for min/max_num_value_n and multiflexible_min/max
|-
|Sum range||.em_sum_range||for min/max/equals_num_value
|-
|Regex validation||.em_regex_validation||for regular-expression validation of the question
|-
|Question-level validation function||.em_q_fn_validation||for the em_validation_q option
|-
|Subquestion-level validation function||.em_sq_fn_validation||for the em_validation_sq option
|-
|Other comment mandatory||.em_other_comment_mandatory||for other_comment_mandatory option - shows when "other" is selected but associated comment is missing.
|-
|
|}

==Importing styles into your custom template== 


The custom question styles are near the bottom of each template's CSS file and start with:<syntaxhighlight lang="php" enclose="div">/* --------------------------- START: Question styles ------------------------------ */</syntaxhighlight>


If you're styling your own custom template, you should be able to copy everything after the above one from ''templates/default/template.css'' (for table-based layouts) or ''/templates/limespired/template.css'' (for CSS-based layouts) into your own style sheet without any impact on your other styles.

==Internet Explorer conditional style sheets== 


Because of the marked discrepancies in rendering between IE6 & IE7 and the other browsers, there are special IE conditional style sheets included for each template.


<source lang="html4strict" enclose="div">



</source>


You should include the above code within your '''startpage.pstpl''' and copies of both the IE style sheets from either ''/templates/default/'' or ''/templates/limespired'' for Tables base layout and CSS based layout respectively.


<div class="simplebox">'''Note:''' If you copy the styles into your own style sheet you will almost certainly need to tweak them.</div>

===Alternative solution for Internet explorer=== 


You can put a conditional class for body in startpage.pstpl and use this class in your template.css. This method is used in the citronade template{{ObsoleteIn|2.06}}. Adding a js / no-js class to have javascript / no javascript system.


<source lang="html4strict">



<body id="body" class="lang-{SURVEYLANGUAGE} {SURVEYFORMAT} no-js">
<script type='text/javascript'>/*<![CDATA[*/(function(H){ H.className=H.className.replace(/\bno-js\b/,'js') })(document.getElementsByTagName('body')[0]);/*]]>*/</script></source>


And in template.css use:


<source lang="css">.ie6{/*specific for internet explorer 6*/}
.ielt8{/*specific for internet explorer 6 and 7*/}
.ie{/*specific for all internet explorer */}</source>

== Right-to-Left (RTL) Languages and justify== 


The text editor within LimeSurvey is able to format RTL text. However, the editor itself shows the RTL language in a left to right format when justified. This is just an editor display issue. The RTL and justified question or text will display correctly from right to left, even when justified, in your survey or on preview.

==Keywords== 


{{Deprecated|3.0}}


Keywords within a template file get replaced by the current survey information. They are surrounded by curly brackets, for example: {SURVEYNAME}.


The following strings will be replaced by LimeSurvey when parsing the template file and presenting it to survey users. These field strings will work on almost every template except for the 'Completed Page'. (Most of these strings can be found in the common.php file. If it's not there, look in the index.php file.)


{|class=wikitable
!'''Keyword'''!!'''Template files'''!!'''Description'''
|-
|{SURVEYNAME}||All Files||The survey title
|-
|{SURVEYDESCRIPTION}||All Files||The survey description
|-
|{WELCOME}||All files (mainly for welcome.pstpl)||The survey 'welcome' text
|-
|{PERCENTCOMPLETE}||survey.pstpl||A small graph showing the percentage of the survey completed
|-
|{GROUPNAME}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group name
|-
|{GROUPDESCRIPTION}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group description
|-
|{NUMBEROFQUESTIONS}||welcome.pstpl||Displays the total number of questions in the survey (just the number)
|-
|{THEREAREXQUESTIONS}||welcome.pstpl||Displays the sentence "There are X questions in this survey" - from the relevant language file. The X is replaced with the number of questions. Note that this will also work appropriately for singular or plural. If there is only 1 question, it will print "There is 1 question in this survey".
|-
|{CHECKJAVASCRIPT}||All files (mainly for welcome.pstpl)||Warning message when end-user browser have javascript disabled
|-
|{QUESTION}||Question.pstpl||('''Has been superseeded as of LS1.87''') Displays the current question text (The format of {QUESTION} can customised by editing 'question_start.pstpl') Use the following: {QUESTION_TEXT}, {QUESTION_MANDATORY}, {QUESTION_HELP}, {QUESTION_MAN_MESSAGE}, {QUESTION_VALID_MESSAGE}, {QUESTION_INPUT_ERROR_CLASS}, and appropriate wrapping HTML instead of {QUESTION}
|-
|{ANSWER}||question.pstpl, print_question.pstpl||presents the answer form for the current question
|-
|{SGQ}||question.pstpl, question text||Can be used in the question text itself to reference the input field of the question dynamically by displaying the Survey-Group-Question id for the current question. (as of svn build 9755)
|-
|{QUESTIONHELP}||question.pstpl, print_question.pstpl||Displays help text (predefined tip for question type) for the current question
|-
|{QUESTION_CLASS}||question.pstpl, print_question.pstpl||unique class for each question type. (To be included in the question's wrapping tag.)
|-
|{QUESTION_CODE}||question.pstpl, print_question.pstpl||Displays the current question code
|-
|{QUESTION_ESSENTIALS}||question.pstpl||the question ID and (if a question is conditional), 'style="display:none;"'. (To be included in the question's wrapping tag.)
|-
|{QUESTION_HELP}||question.pstp, question_start.pstpl||Displays the user defined help text for the current question
|-
|{QUESTION_TYPE_HELP}||print_question.pstp||Displays the user defined help text for the current question
|-
|{QUESTION_INPUT_ERROR_CLASS}||question.pstp, question_start.pstpl||Provides a class if there was user input error
|-
|{QUESTION_ID}||print_question.pstp||Provides a unique ID for each question to allow styling for specific questions
|-
|{QUESTION_TEXT}||question.pstp, print_question.pstp, question_start.pstpl||Displays the text for the current question
|-
|{QUESTION_MANDATORY}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' text for the current question
|-
|{QUESTION_MAN_CLASS}||question.pstpl, print_question.pstpl||class if a question is mandatory. (To be included in the question's wrapping tag.)
|-
|{QUESTION_MAN_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' help message text for the current question
|-
|{QUESTION_NUMBER}||print_question.pstpl||Incremental count of questions.
|-
|{QUESTION_VALID_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated valid help message text for the current question
|-
|{QUESTION_SCENARIO}||print_question.pstp||Prints out the 'scenario' text for conditional questions.
|-
|{NAVIGATOR}||navigator.pstpl||Displays navigation buttons (next, prev, last)
|-
|{CLEARALL}||All files (but intended for navigator.pstpl)||Displays the "Exit and Clear Results" link
|-
|{COMPLETED}||completed.pstpl||Displays the 'completed' message for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{URL}||completed.pstpl||Displays the survey 'url' and 'url text'
|-
|{PRIVACYMESSAGE}||privacy.pstpl||The privacy message is shown if you set your survey to be anonymous. [[Translating LimeSurvey|The text can be edited/translated]] in the language files. This can also be changed manually by editing the privacy.pstpl template you wish to use.
|-
|{TEMPLATEURL}||All Files||The URL to the current template location (useful for referencing image files in your template)
|-
|{SURVEYRESOURCESURL}||All Files||The URL to the current uploaded files for this survey location (useful for referencing image files in your question, group, ....)
|-
|{SUBMITCOMPLETE}||endpage.pstpl||The statement (from the language files) that tells the user they have completed the survey, and to press the "Submit" button
|-
|{SUBMITREVIEW}||survey.pstpl||The statement (from the language files) that tells the user they can review/change the answers they have made by clicking "<< prev"
|-
|{SAVEDID}||All Files||Displays 'Response ID' of user
|-
|-
|{QUEXMLPDF}||All Files||Displays button to export the queXML PDF of questionnaire including answers entered up until the point that has been completed in the survey.
|-
|{TOKEN:FIRSTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users first name from the tokens table
|-
|{TOKEN:LASTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users last name from the tokens table***
|-
|{TOKEN:EMAIL}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users email from the tokens table***
|-
|{TOKEN:ATTRIBUTE_1}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_1 from the tokens table***
|-
|{TOKEN:ATTRIBUTE_2}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_2 from the tokens table***
|-
|{ANSWERSCLEARED}||Preferably in navigator.pstpl||The "Answers Cleared" statement from the language files
|-
|{RESTART}||clearall.pstpl||URL to restart the survey
|-
|{REGISTERERROR}||register.pstpl||Shows any error messages in the register page (ie: "You must include an email address")
|-
|{REGISTERMESSAGE1}||register.pstpl||The statement "You must be registered to complete this survey" from the language files
|-
|{REGISTERMESSAGE2}||register.pstpl||Details about registering from the language files
|-
|{REGISTERFORM}||register.pstpl||The actual form for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{SAVE}||Works suitable on navigator.pstpl||Displays the 'Save your responses so far' button to offer the user to save and come back later to continue the survey. If the Save option is deactivated in the survey properties the tag will not be shown and ignored.
|-
|{LANGUAGECHANGER}||survey.pstpl||Displays a switch in multilingual surveys to change the question.
|}

==Input/Buttons== 


Each "input" type in a survey has been given its own class name, so that you can add CSS to your "startpage.pstpl" file and have some control over the appearance of form buttons and inputs. These class names are as follows:
*'''submit''' (Submit Buttons)
*'''text''' (Text Inputs - for short free text, date, and numerical type)
*'''answertext''' (Text of answers)
*'''radio''' (Radio Buttons)
*'''checkbox''' (Check Boxes)
*'''select''' (Select / List Boxes)
*'''textarea''' (Large text inputs - for long free text)
*'''clearall''' (The "Exit and Clear Survey" link)
*'''rank''' (The rank style question. Doesn't set the colour of the select box or the text boxes, but it does allow the changing of background colour, text colour, size etc., for the rest of the ranking question)
*'''graph''' (The "percentage completed" graph table)
*'''innergraph''' (The table inside the graph table - this contains the 0% and 100% text. Use this for changing the size of this text)
*'''question''' (General settings for any question that is displayed within a table. Generally, you should use this to make sure that their font size and color is the same as you have used elsewhere as a default)
*'''mandatory''' (Mandatory questions)
*'''input-error''' (User input error - for if a user has made a mistake with a mandatory question or question with validation)
*'''array1''' and '''array2''' (These two styles are cycled when presenting the range of answers for an array type question. This allows you to set an alternating background color for these question types. '''Array1''' is also used for the column headings in these question types)
*'''errormandatory''' (Sets the color and style of the "This question is mandatory" error message)
*'''warningjs''' (Sets the color and style of the warning message displayed if the participant's browser has javascript disabled)


There are also some elements that can be accessed using the ID of the element ('''#ID''' in CSS):
*'''surveycontact''' (The contact message shown on the start page)
*'''tokenmessage''' (used for messages inside the survey, e.g. the session expired error message)


Because you can edit all the HTML aspects, there's no reason to surround your templates with a
<syntaxhighlight lang="php" enclose="div"><div class='new_name'></div></syntaxhighlight>
and then define a css for that new_name class.

==Styling the progress bar== 


The progress bar appearance can be modified with CSS.


To change the background color of the bar, add something like the following to the end of your template.css file:


<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-header {
background-color: #3300FF;
}</syntaxhighlight>


To change the border color of the bar, add something like the following to the end of your template.css file:


<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-content,
#progress-wrapper .ui-widget-header {
border: 1px solid #FF0000;
}</syntaxhighlight>

==Advanced Features Available to Developers== 


LimeSurvey has integrated some user-made patches that permits some special changes. These very advanced features (generally) require changes to the underlying code base of LimeSurvey and should be done carefully in order not to introduce security holes.

===Support for your own Javascript functions=== 


Some users may need to run Javascript on the survey pages, but calling '''checkconditions()''' in the BODY element made it impossible to do so. This call has been replaced with a small JavaScript function in the HEAD that sniffs for the existence of '''checkconditions()''' and '''template_onload()''' before calling them. In this way, a template author can create his or her own '''template_onload()''' function in the HEAD that replaces the default one.


*Disable XSS filter - in Global settings -> Security, set "Filter HTML for XSS" to No.
*Enter your script in the source of a question or group description.


{{Note|For further details, see the [[Workarounds: Manipulating a survey at runtime using Javascript#How to use Script (eg. JavaScript etc.) in LimeSurvey|workaround section]].}}

=Videos on Templates= 


This video will demonstrate the basic and advanced template functions that are available to all LimeSurvey users. This includes changing the appearance of certain forms and inserting custom graphics. Additionally, it will thoroughly walk you through on how to edit and preview specific page templates, importing/exporting templates, modify appearance of questions in the CSS, and customizing survey description page.


Video - needed

=Tips & Tricks= 

==Some language specific element== 


If you want to have some language specific sentence in a survey, for example a help at the end of each page, you can add in a .pstl file a sentence and hidding it for other language. If we hide it in the template.css, we can use the pseudo selector :lang, but we use some class for better compatibility.


Below, there are two help sentences, in French and English. Put this on endpage.pstpl:


<syntaxhighlight lang="php" enclose="div"><div class="fr" lang="fr">Pour de l'aide en direct appelez le 000000</div>
<div class="en" lang="en">For some help, please call 000000</div></syntaxhighlight>


and in template.css:


<syntaxhighlight lang="php" enclose="div">.lang-fr .en{display:none}
.lang-en .fr{display:none}</syntaxhighlight>

==Change the layout of the survey page== 


After editing and saving a template, it applies to a survey list page only if it is selected from the settings of the survey. To make it the default template, go under the '''General tab''' located in the '''Global settings''' of your LimeSurvey installation and choose the desired template. From now on, all the templates that use the "default" option as template plus the ones that are going to be newly created, will use the newly selected default template.


To use your current template for this page, you have to change the according setting from '''Global settings'''. In older versions, this change can be done by editing the $defaulttemplate setting from the config file: copy this setting from config-defaults.php to config.php which overrides config-defaults.php and edit this setting to <code lang="html">$defaulttemplate = 'yourtemplatename';</code>.

==Import/Export of templates: Mac users== 


<u>Mac users</u>, please note that the Mac OSX default archive utility may have problems with zip folders "generated on the fly".


A workaround is to unix'es unzip from the command line:


$ unzip template.zip -d template


Archive: template.zip


inflating: template/startpage


inflating: ...


Another workaround is to use scripts in their mac-compiled counterparts.

==Replacing the help icon {{ObsoleteIn|2.50}} == 


When a question help text is shown, then an help.gif image is used from the default template folder.


You can replace this image by uploading a new help.gif, help.png or help.jpg in your custom template folder. It will then be automatically used instead of the default help icon.

==Replacing an existing logo {{NewIn|2.50}} {{ObsoleteIn|3.0}}== 


'''Note''': In the '''default'' Template of 2.50, there is no preembedded logo. Read further our [[#Adding_your_own_logo |wiki on how to add your own logo]].


1. To edit the logo go to the ''<u>template.css</u>'' file which you can find it here:


<center>[[File:t1.PNG|200px]]</center>


2. Click the search button to find occurrences of logo related styles and search for ''logo''


<center>[[File:2.png|200px]]</center>


4. Edit the main style file.


You will see something similar to:


<center>[[File:t4.PNG|500px]]</center>


If you want to change the image, just replace logo.gif with another image link. Example: (<u>logo.png</u> or <u>logo.jpg</u>).


If you want to change the image size, adjust width and height (in pixels) like this:


<syntaxhighlight lang="php" enclose="div">width:100px; height:100px;</syntaxhighlight>

==Adding your own logo {{ObsoleteIn|3.0}} == 


1. Find and open the '''startpage.pstpl''' template file.


<center>[[File:startpage.pstpl.png]]</center>


2. After this
<source lang="html4strict" ><div id="topContainer" class="jumbotron"></source>
add this line to '''startpage.pstpl''':
<source lang="html4strict">
<div class="container"><img id='page_logo' src='{TEMPLATEURL}/files/logo.png' class="clearfix pull-right" /></div>
</source>


3. To upload your own logo, go to the template editor and upload your logo.


<center>[[File:uploadyourlogo.png]]</center>


To position your logo, please use one of the following css classes:


*'''If you want the logo to be placed on the left side:'''


<source lang="html">clearfix pull-left</source>


*'''If you want the logo to be placed on the right side:'''


<source lang="html">clearfix pull-right</source>


*'''If you want to center the logo'''


<source lang="html">clearfix center-block</source>

==Use the same template with different logos== 


If you want to use the same template for all surveys and just want to change the logo for each survey, you can use the {SID} placeholder in the template .pstpl file and thereby refer to different images:


<syntaxhighlight lang="php" enclose="div"><img src="{TEMPLATEURL}files/logoImage-{SID}.png"></syntaxhighlight>

==Remove the default help to all question (hide_tip) {{ObsoleteIn|1.92}}== 


There are 3 solutions to remove the default help:
# like a hide_tip attribute but for all question and survey.
# you can remove the {QUESTIONHELP} and its container from the file question.pstl. However, it can be a bad idea for the screenreader.
# for the default template and some other, add this at the end of tempate.css


<syntaxhighlight lang="php" enclose="div">span.questionhelp{display:none;}</syntaxhighlight>

== Display custom favicon== 


A favicon is the little icon you see in the browser's address bar, list of bookmarks or tab. You can display your own icon as follows:
#Create a favicon - google will find you lots of free favicon generators.
#Name your new favicon "favicon.ico" and place it in your template /files directory.
#Add the following code to your '''startpage.pstpl''' before the </head> tag.


<syntaxhighlight lang="html4strict" enclose="div"><link rel="shortcut icon" href="{TEMPLATEURL}files/favicon.ico" type="image/x-icon">
<link rel="icon" href="{TEMPLATEURL}files/favicon.ico" type="image/x-icon"></syntaxhighlight>

== Different appearance for survey-/question-pages== 


If you want LimeSurvey to change the appearance of every second page (i.e. of even and odd survey pages), you can use '''.page-odd''' class in your CSS file to change the appearance of odd pages.


An example from default template of LimeSurvey 1.91+:


<syntaxhighlight lang="php" enclose="div">
.page-odd table.question-group {
background-color: #D2F2D3;
}</syntaxhighlight>


If you do '''not''' want differentiate even and odd pages, find all instances of ''.page-odd'' in template.css and remove those styles.

==Create a vertical separator border for dual scale array== 


To create a vertical separator border for a dual scale array, you can add the following lines to your '''template.css'''-file.


<syntaxhighlight lang="php" enclose="div">
table.question thead td.header_separator,
table.question tbody td.dual_scale_separator
{
border-right:solid 1px #00A8E1;
}
</syntaxhighlight>


''header_separator'' is used to adress the separator for the header "td". The "dual_scale_separator" is used to address the separator column in the dual scale array.

==Hide the survey contact message shown on the start page/survey list {{ObsoleteIn|3.0}} == 


To hide the "Please contact ..." message on the start page (with the survey list), you can add the following to the '''$(document).ready''' function in the '''template.js''' of your used design template:


<syntaxhighlight lang="php" enclose="div">


$('#surveycontact').hide(); //Hides the survey contact message


</syntaxhighlight>

==Remove the survey contact message shown on error messages {{ObsoleteIn|3.0}}== 


If you want to remove the survey contact message from error messages, it'll be trickier. You can add the function from below. It calls the '''$(document).ready''' function in the '''template.css''' of your used design template:


<syntaxhighlight lang="php" enclose="div">
removeContactAdressFromMessage(); //Removes the survey contact message from error messages
</syntaxhighlight>


and add the following function to your *template.js* file


<syntaxhighlight lang="php" enclose="div">
function removeContactAdressFromMessage()
{
if ($('#tokenmessage').length > 0)
{
var oldMessage = $('#tokenmessage').html();
var indexContact = oldMessage.indexOf('Bitte kontaktieren');
var newMessage = oldMessage.substr(0, indexContact);
$('#tokenmessage').html(newMessage);
}
}
</syntaxhighlight>


It will probably not work for a survey in English language and has to be extended when used for multilingual surveys. But it's an idea/tip on how to solve this.

==How to deal with multilingual question attributes {{ObsoleteIn|2.50}}== 


If you have a multilingual survey and e. g. want to use a different string for the "other" field, this could only be done for the base language (until this feature was added at LimeSurvey 2.0). To work around this, paste in the field to change the label for "other":


<syntaxhighlight lang="php" enclose="div"><span class="en">New label</span><span class="fr">Nouveau label</span></syntaxhighlight>


Add in the template.css of your template (at ''/limesurvey/upload/templates/<yourtemplatename>/template.css''):


<syntaxhighlight lang="php" enclose="div">html:lang(en) .fr{display:none}
html:lang(fr) .en{display:none}</syntaxhighlight>

==Adding your own logo to the survey list {{ NewIn|3.0}} == 


# First please open the theme editor for the theme you like to use. [[File:OpenThemeEditor.jpg]]
# We recommend to use fruity, it is our best theme currently.
# Then extend the theme and give it a name you will recognize. [[File:ExtendTheme.jpg]]
# In the following view you may upload the logo you want to use. [[File:UploadFileTheme.jpg]]
# Select the editor screen `Survey List´ in the Screen dropdown in the top right corner. [[File:OpenScreenSurveyList.jpg]]
# Then select `layout_survey_list.twig´ in the left side menu. [[File:EditLayoutSurveyListTwig.jpg]]
# In the editor scroll to line 126 and change the marked part to the filename of the image you uploaded to the theme before. [[File:ChangeSurveyListHeaderImageEditor.jpg]]
# Save your file. [[File:ThemeEditorSaveChanges.jpg]]
# Change default theme to your extended theme. [[File:ChangeDefaultTheme.jpg]]

=Custom Question Views {{NewIn|3.0}}= 


<div class="simplebox">'''Note:''' This is a temporary feature to be replaced in the future by question object (it will be very easy to move custom views to question object). It is disabled by default.</div>


As of version 2.5, you can create template-specific custom views for questions and some of their incorporated elements. This is useful if you want to modify the HTML layout of a particular question type for one or more surveys.


*In application/config/config.php, find 'config'=>array and add this line to the array : 'allow_templates_to_overwrite_views'=>1
*In /{your_template}/config.xml, set "overwrite_question_views" to true
*Copy application/views/survey/* to template/{your_view_directory}/survey/
*Note that you only need to copy the files that you intend to modify but the file structure must remain the same as in application/views/survey/

=Insert Custom CSS or JavaScript files for template {{NewIn|2.50}}= 


As of version 2.50, you can use the config.xml file to automatically load plugin files.


*Upload your files to the template /css or /scripts folder
*In /{your_template}/config.xml, add the file paths to the <css> or <js> blocks, something like this:<syntaxhighlight lang="xml" enclose="div"><css>
<filename>css/jquery-ui-custom.css</filename>
<filename>css/bootstrap-slider.css</filename>


<filename>css/awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</filename>
<filename>css/flat_and_modern.css</filename>


<filename>css/template.css</filename>


<filename>css/myCustomPlugin.css</filename>
</css>
<js>
<filename>scripts/template.js</filename>
<filename>scripts/bootstrap-slider.js</filename>


<filename>scripts/myCustomPlugin.js</filename>
</js>
</syntaxhighlight>

</translate>

Theme editor

2018-04-04T10:16:47Z

LouisGac:

<languages /> <translate>

=Introduction= 


LimeSurvey has an advanced theme and style system providing to developers an efficient way to customize the survey appearance. Since LS3, we're not speaking anymore about '''"templates"''' like in previous versions, but about '''"themes"'''. The '''themes''' allow control over the look and feel of pages during a survey. A survey administrator can select a default theme that will be used for each survey to further personalize it and improve its look and feel. '''Themes''' come with options that provide to admin without coding skill a simple way to add a logo on the welcome page, to change the background colors, to select a font, etc.


LimeSurvey comes with 3 themes right out of the box. These initial themes are defined by directories located in the LimeSurvey installation "themes/survey/" directory. Each theme has it's own directory. Within the main directory of a theme you'll find a configuration file in XML, and numerous directories containing the views ''themes (.twig)''', '''cascading style sheets (.css)''', '''scripts''', '''images''' ('''.jpg''' or '''.png'''), and maybe others.


Since LimeSurvey 2.50, the theme engine use [http://getbootstrap.com/docs/3.3/ Bootstrap 3] as CSS framework. Bootstrap 3 being a standard framework, developers will find a lot of documentation, tutorials and forum threads about it on Internet.

Since LimeSurvey 3, the theme engine use [https://twig.symfony.com Twig], so the theme developers can change the logic of the survey rendering in a safe and easy way. Twig replace the old system of replacement keywords that was used in the previous versions. The logic that was used to generate the HTML of the keywords are now available inside the theme's views.

Snippet from Vanilla Theme:


<syntaxhighlight lang="twig" enclose="div">
<div class="{{ aSurveyInfo.class.answercontainer }} col-xs-12" {{ aSurveyInfo.attr.answercontainer }}>
{# NOTE: If you want to customize the question rendering, use a question theme #}
{{ aQuestion.answer | raw }}
</div>
</syntaxhighlight>


One gets a result that looks like:


<div class="simplebox"><div style='text-align: center;'><span style='color:red'>My New Survey</span></div>
<div style='text-align: center;'><span style='color:red'>This is a survey written by me to find out what sort of chocolate people like.</span></div></div>


Templates, being HTML code, tend to define the positioning and type of text to be displayed and similar structural features of the page. They often reference or include other files. Most of them reference a common cascading style sheets (CSS) file that defines the font style, color, size, background, and similar parameters common to all pages in the survey. Style sheets reference HTML '''class''' parameters that are associated with the various types of objects in the HTML code. This allows the style sheet to describe how to display each of the many types of text or other objects that may appear in multiple places. There are unique classes for each question type in LimeSurvey and thus giving detailed control over the appearance of each. Image files, like logos or special progress-bar constructors, may be referenced as well in the Template file. Finally, special keywords in curly braces are replaced with text defined in the survey for each language translation correspondent (for example, the 'Survey Title' or 'Question Text' for each language defined).


If you create a new custom template, please consider contributing it back to the LimeSurvey community and make it available to others. With your help, we can grow our repository of templates, surveys, and other add-ons to make LimeSurvey even better!
See our [https://www.limesurvey.org/index.php?option=com_sobipro&sid=55:Templates&Itemid=729 LimeSurvey template repository] where you can share your templates.

=Creating a new template= 


To be able to create a new template (or edit an existing template), you need [[Manage users#Set global permissions for a user|Template Editing user permission]] in LimeSurvey as well as permission to manipulate the files in the underlying operating system hosting your LimeSurvey installation.


<div class="simplebox"><span style='color:red'>'''Note of Warning:'''</span> If you change templates, you could also affect all the pre-existing surveys from your LimeSurvey installation. Templates are an advanced feature that require experience and HTML knowledge in order to make them running smoothly.</div>


The preferred way to create a new template is through the '''Template Editor''' (see below), which is located in the '''Configuration''' dialog. Some people may like to work directly with template files so that they can use their favorite text editor instead of the web interface. In this case, still use the Template Editor to first create your new template. This will create a new base template with all the files you need in the ''LimeSurvey_web_root/upload/templates/your_new_template'' directory. From there you can use your text editor to manually adjust the template files.


<div class="simplebox">'''Permissions Note:''' on unix/linux systems, these template files will be owned by the group and user where the web server is running (may be "www" for some systems). So, make sure you have enough access to edit these files, When you save them, make sure they don't change ownership! In this way, you can still use the web Template Editing interface if needed.</div><br />


A number of 'public' elements of LimeSurvey can be adjusted by a series of templates. The next section provides a very brief explanation of these templates.


{{Note|Template files may seem complex. Besides HTML, you might also need to understand CSS.}}

=The LimeSurvey template editor= 


To ease the understanding and quick update of a Template, LimeSurvey provides a '''Template Editor''' in the main '''administrative''' toolbar of the application. This Template Editor is only available to users [[Manage users#Set global permissions for a user|with the Templates permission]] and to superadministrators.


{{Alert|title=Attention|text=A template that is not correctly constructed can render a survey (that uses the respective template) inoperable. }}


The LimeSurvey template editor allows you to edit the contents of your templates online. Start the Template Editor by clicking on '''Template editor''' in the '''Configuration''' menu.


[[File:templates.png]]


The template editor page allows you to select the template you would like to edit/view.


[[File:Template-editor-2013-7-10_11_38_16.png|center]]

==The template menu== 


The following options are available:


*'''Create''': Allows you to create a new template. In order not to start from scratch, the template 'default' is copied.
*'''Import''': Allows you to import a template from a ZIP file.
*'''Export''': Allows you to export the current template to a ZIP file.
*'''Copy''': Allows you to make a new template by copying the current one.
*'''Rename''': Allows you to change the name of the template. It is generally used after copying or importing a template.
*'''Template''': It is a drop-down list that shows all the available templates that are located in your LimeSurvey installation.


*'''Screen''': It is a drop-down list which allows you to choose which particular survey page of that template you want to look at.
*'''Return to admin panel'''.

==Import/export/copy a template== 


When you '''export '''a template, a ZIP-file archive with all the files your template consists of will be created (.pstpl files, images, css files, ...). You can simply '''import''' the exported zip-file into another LimeSurvey installation by using the import feature or you can manually copy the archive into another LimeSurvey installation and extract it into the corresponding [[Theme editor#Template files location|template directory there]].


However, it is preferred to use the LimeSurvey template import/export/copy functions in the template editor.

==Page Structure / Template Use== 
*'''The Welcome Page:''' startpage.pstpl, welcome.pstpl, privacy.pstpl, navigator.pstpl, endpage.pstpl
*'''The Questions Pages:''' startpage.pstpl, survey.pstpl, startgroup.pstpl, groupdescription.pstpl, question.pstpl, endgroup.pstpl, endpage.pstpl
*'''The Final Page:''' startpage.pstpl, assessment.pstpl, completed.pstpl, endpage.pstpl

==Template Files== 


The following template files are used to produce your public survey and must exist in any new template folder you create:
*'''startpage.pstpl:''' Produces the start of each html page. It starts at the "<head>" tag, and should not contain the "<html>" tag. This 'very beginning' of a standard html page is written by the scripts. Please ensure that your startpage.pstpl files contains a <body> tag. Even though many browsers do not require strict adherence to the W3 HTML standards, the LimeSurvey script needs to find a <body> tag to run certain javascript elements. It is not expected to see many 'keywords' used in the startpage.pstpl file. However, you may wish to put the {SURVEYNAME} into the title. The startpage.pstpl file can contain code that ends in the corresponding endpage.pstpl file. For example, you can start a table in this file and close the table in the endpage.pstpl file. The startpage.pstpl and endpage.pstpl files wrap around every possible page used by LimeSurvey.
*'''survey.pstpl:''' This template is the second used on most pages and provides a space to put the survey name and description. This template does not have a corresponding 'closing' template, and subsequently you should close all tags opened in this template file (i.e.: don't leave a table open here because there is nowhere else to close it).
*'''welcome.pstpl:''' This template is only used in the welcome screen (which is also on the main page for 'all in one' surveys). You can use this to print out the welcome text, and other information that should be provided in the introduction. Like the 'survey.pstpl' file, there is no corresponding 'closing' template, so all tags opened in this template file should be closed as well.
*'''startgroup.pstpl:''' This template can provide a 'summary' wrap around for questions within a group. It has a matching 'endgroup.pstpl' template that can be used to close any opened tags in this file, so you can open a table within this.
*'''groupdescription.pstpl:''' This template file is used to display a description of a group. Please note that in the survey settings (access the ''Presentation & navigation settings'' by clicking on the '''Presentation''' tab) you can set if the group description should be shown or not. If not, then this file is not included at all.
*'''question.pstpl:''' This file contains the question, answer, and help text sections of your survey. In the "group by group" and "all in one" surveys, this template is cycled repeatedly with each question. There is no corresponding closing file for this and all tags should be closed.
*'''question_start.pstpl:''' This file contains the individual elements found at the start of a question. It is included within 'question.pstpl' via the {QUESTION} keyword. It is intended to allow template designers more control over the layout of a question. This template sits outside the normal templating system and '''was superseeded (as of LimeSurvey 1.87)'''. All keywords from this template are now available directly in question.pstpl.
*'''completed.pstpl:''' This page is displayed as the final page when the survey responses have been saved and the survey is over. It can be used to display a "forwarding link" as set in the survey setup.
*'''endgroup.pstpl:''' This file closes the group, and can be used to close off any tags opened in the startgroup.pstpl file
*'''navigator.pstpl:''' This file contains the buttons that navigate through the survey, "next", "prev", "last", "submit", "save so far" and the "clear all" link. It is used in all pages except the completed page.
*'''printanswers.pstpl:''' This file has the HTML wrapper necessary for the print version of the survey.
*'''print_group.pstpl:''' This file is the same as startgroup.pstpl and endgroup.pstpl, but for the print version of the survey.
*'''print_question.pstpl:''' This file is the same as question.pstpl, but for the print version of the survey.
*'''print_survey.pstpl:''' This file is the same as survey.pstpl, but for the print version of the survey.

== CSS and Javascript== 


Two files that are always used in a template are template.css (for CSS) and template.js (for Javascript).
*'''{TEMPLATECSS}:''' Add lines for default css, template.css, and template-rtl.css for rtl language.
*'''{TEMPLATEJS}:''' Add lines for default javascript files, template.js, and all js files needed for LimeSurvey.

=== Using Bootstrap=== 
LimeSurvey has Bootstrap 3 embedded, so you can style all your templates with the well documented Bootstrap classes.
For more information please refer to the [https://getbootstrap.com Bootstrap documentation].


The [https://github.com/flatlogic/awesome-bootstrap-checkbox Awesome-Bootstrap-Checkbox] plugin is also included. With it, you can use the typical Bootstrap color-classes (info,warning,danger,etc.) also with the suffix "-checkbox" or "-radio", though styling checkboxes and radios as you prefer.

=== Replacing default CSS or Javascript=== 


Some questions use specific files for Javascript or CSS. If you need to replace a function, use a cascading system. For javascript function, the last function read is the function used.

==Other Template Files== 


The '''privacy.pstpl''', '''invitationemail.pstpl''', '''reminderemail.pstpl''', and '''confirmationemail.pstpl''' are no longer used by LimeSurvey and defaults are instead set in the applicable language files. The email messages can now be edited on a survey by survey basis.

==Standard Pages== 


There are ten standard pages that a survey participant may see in the course of taking or accessing the LimeSurvey application. Each is constructed from a number of common '''Template''' files from the '''Template''' specified in the settings of the survey. The table below indicates which template files are used in constructing each of these pages.


{| class="wikitable"
! '''Survey Pages/'''<br />'''Template Files'''!!Survey<br />List!!Welcome!!Question!!Completed!!Clear All!!Register!!Load!!Save!!Print<br />Answers!!Print<br />Survey
|-
|SurveyList||align="center" | [[File:check.gif]]|| || || || || || || || ||
|-
|Welcome|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Privacy|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Navigator|| ||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Survey|| || ||align="center" | [[File:check.gif]]|| || ||align="center" | [[File:check.gif]]|| || || ||
|-
|StartGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|GroupDescription|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Question<span style='color:red'>'''*'''</span>|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|EndGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Assessment|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|Completed|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|ClearAll|| || || || ||align="center" | [[File:check.gif]]|| || || || ||
|-
|Register|| || || || || ||align="center" | [[File:check.gif]]|| || || ||
|-
|Load|| || || || || || ||align="center" | [[File:check.gif]]|| || ||
|-
|Save|| || || || || || || ||align="center" | [[File:check.gif]]|| ||
|-
|PrintAnswers|| || || || || || || || ||align="center" | [[File:check.gif]]||
|-
|Print Survey || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Group || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Question || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|StartPage<br />EndPage<br />Template.css||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||
|}


<span style='color:red'>'''*'''</span>NOTE: In version 1.90+, this replaces question.pstpl AND question_start.pstpl. If you are using an old custom template, you need to add the following line to the beginning of question.pstpl:<syntaxhighlight lang="php" enclose="div"><div {QUESTION_ESSENTIALS} class="{QUESTION_CLASS}{QUESTION_MAN_CLASS}{QUESTION_INPUT_ERROR_CLASS}"></syntaxhighlight>And then add the corresponding closing tag to the end of question.pstpl:<syntaxhighlight lang="php" enclose="div"></div></syntaxhighlight>


<span style='color:red'>'''*'''</span>NOTE: In version 1.91 and earlier, LimeSurvey js files are not included in the template. In version 2, '''you have to use {TEMPLATEJS} in one of your template file''' to add the link to the js file. You can add it in startpage.pstpl or in endpage.pstpl. You can remove the {TEMPLATEURL}/template.js line and you have to replace with {TEMPLATEJS} to update a personal template.

==The File Control Section== 


In the "file control" window on the left, you can click on one of the template files that is used to compile the page. You can see the ''Screen part'', JavaScript, and CSS files. The HTML code for that file will then appear in the "Now editing" window in the center. If the template is editable (determined by directory permissions) you can then make any changes and save them.


<center>[[File:File Control Section.png|center]]</center>


The "Other files" window shows a list of all other files from the template directory. You can use the right side to '''upload and select image files (your pics, logos,...) or other files needed to create your template'''.


Instead of using a link for each picture, utilize the field string {TEMPLATEURL}. So, instead of:


<syntaxhighlight lang="html4strict" enclose="div">img src='/limesurvey/templates/yourtemplate/files/mypicture.jpg'</syntaxhighlight>
You can use {{NewIn|2.50}}:
<syntaxhighlight lang="html4strict" enclose="div">img src='{TEMPLATEURL}files/mypicture.jpg'</syntaxhighlight>


In LimeSurvey versions before 2.50 use:
<syntaxhighlight lang="html4strict" enclose="div">img src='{TEMPLATEURL}mypicture.jpg'</syntaxhighlight>


A "sample" of the template page you are editing will be visible in the bottom of the screen. There is no way to delete a template from the template editor. This must be done by accessing the underlying directory and deleting manually the files from there. You also have the possibility to select different screen resolutions in order to better evaluate the feel and look of the template.


<div class="simplebox">'''Note:''' The shipped templates cannot be edited using the template editor. If you want to modify them, create a copy first and edit the copy.</div>

==Template files location== 


LimeSurvey stores each of the 'standard' templates in their own distinct sub-directory within the ''/templates'' directory that is kept in the public directory with the other LimeSurvey public files. Customized user templates are stored in the ''/upload/templates'' directory.


There should '''ALWAYS''' be a "default" directory in the templates directory. This template is used by default and as a fall-back if a template folder doesn't exist, or can't be found. It comes installed by default.


You can use any image files that you upload into the template management area with the help of this syntax:


<syntaxhighlight lang="php" enclose="div">{TEMPLATEURL}filename.xyz</syntaxhighlight>

=Styling questions with CSS= 


Styling of questions in CSS has become much easier. Each question type has now a unique class. The mandatory questions have an additional mandatory class. For example, for a non-mandatory question:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender">
...
</div></syntaxhighlight>


and if the question is mandatory:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory">
...
</div></syntaxhighlight>


and if the question is mandatory, but the user didn't answer it or if there is validation on a question:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory input-error">
...
</div></syntaxhighlight>


and if the question has validation applied, but the user hasn't answered correctly:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question6" class="text-short input-error">
...
</div></syntaxhighlight>

==Global classes for question part== 


These classes are used for each question type. Some question types use only one or two classes, while others may use much more.


{| class="wikitable alternance"
|+ Global classes
|-
! scope="col" | Class name
! scope="col" | Part
! scope="col" | Question type
! scope="col" | Examples
! scope="col" | Note
|-
! scope="row" | .question {{ObsoleteIn|3.0}}
| All question block
| All question type
|<p class="question">, <ul class="question">, <table class="question">
|
|-
! scope="row" | .ls-answers {{NewIn|3.0}}
| All question block
| All question type
|<div class="ls-answers ">, <ul class="ls-answers ">, <table class="ls-answers">
|
|-
! scope="row" | .subquestions-list
| List of subquestion
| Multi choice question, array question type
| <ul class="subquestions-list">, <table class="subquestions-list">
| .questions-list is used too
|-
! scope="row" | .answers-list
| List of answers
| Single choice question, array question type, Multi input text question
| <ul class="answers-list">, <table class="answers-list">
|
|-
! scope="row" | .answer-item
| The answer part: one answer
| Single choice question, array question type, Multi input text question
| <li class="answer-item">, <td class="answer-item">
|
|-
! scope="row" | .noanswer-item
| The answer part for no answer
| Single choice question, array question type
| <li class="noanswer-item">, <td class="noanswer-item">
| No answer is an answer too, then have double class noanswer-item and answer-item
|-
! scope="row" | .question-item
| The question part: one question
| Multi text question, array question type
| <li class="question-item">, <tr class="question-item">
| Some answers are questions too. Then we have a lot of class="question-item answer-item"
|-
! scope="row" | .checkbox-list
| A list of checkbox
| Multi choice question, array number (checkbox) question type
| <ul class="checkbox-list">, <tr class="checkbox-list">
| Some question types use multi-list class, like checkbox with comment: class="checkbox-list text-list"
|-
! scope="row" | .checkbox-array {{NewIn|3.0}}
| A array of checkbox
| Array (numbers) with checkbox option
| <table class="checkbox-list">
|
|-
! scope="row" | .checkbox-item
| The answer part with a checkbox
| Multi choice question, array number (checkbox) question type
| <li class="checkbox-item">, <td class="checkbox-item">
|
|-
! scope="row" | .radio-list
| A list of radio item
| Single choice question, array question type (each row)
| <ul class="radio-list">, <tr class="radio-list">
|
|-
! scope="row" | .radio-array {{NewIn|3.0}}
| A array of radio item
| Array question type
| <table class="radio-array">
|
|-
! scope="row" | .radio-item
| The answer part with a radio
| Single choice question, array question type
| <li class="radio-item">, <td class="radio-item">
|
|-
! scope="row" | .text-list
| A list of text input
| Multi text question type, array of text
| <ul class="text-list">, <tr class="text-list">
|
|-
! scope="row" | .text-item
| The answer part of a text input
| Multi text question type, array of text
| <li class="text-item">, <td class="text-item">
|
|-
! scope="row" | .numeric-list
| A list of text input with numeric only answer
| Multi numeric question type, array of number
| <ul class="text-list numeric-list">, <tr class="text-list numeric-list">
|
|-
! scope="row" | .number-list
| A list of text input with numeric only answer (each row)
| Multi numeric question type, array of number
| <ul class="text-list numeric-list">, <tr class="text-list numeric-list">
|
|-
! scope="row" | .number-array {{NewIn|3.0}}
| The answer part of a numeric input
| Array of number
| <table class="number-array">
|
|-
! scope="row" | .select-list {{ObsoleteIn|2.50}}
| A list of select
| Array numbers, Dual scale array (select)
| <table class="select-list">
|
|-
! scope="row" | .dropdown-list {{NewIn|2.50}}
| A list of select
| Array numbers, Dual scale array (select) (each row)
| <table class="dropdown-list">
|
|-
! scope="row" | .dropdown-array {{NewIn|3.0}}
| A array of dropdown
| Array numbers, Dual scale array (select)
| <table class="dropdown-array">
|
|-
! scope="row" | .select-item {{ObsoleteIn|2.50}}
| The answer part of a select
| Array numbers, Dual scale array (select), single choice with select
| <p class="select-item">, <td class="select-item">
|
|-
! scope="row" | .dropdown-item {{NewIn|2.50}}
| The answer part of a select
| Array numbers, Dual scale array (select), single choice with select
| <p class="dropdown-item">, <td class="dropdown-item">
|
|-
! scope="row" | .hide {{ObsoleteIn|3.0}}
| Used for accessibility: hidden with css but read by screenreader, since 2.50 : you can use sr-only from bootstrap
| Short text question
| <label class="hide">
| Can be used for other purposes
|-
! scope="row" | .ls-js-hidden {{NewIn|3.0}}
| Used for part to be hidden if javascript is activated
| Button for example
| <div class="ls-js-hidden">
| LimeSurvey core used it, but you can use it too in your template
|-
! scope="row" | .ls-js-hidden-sr {{NewIn|3.0}}
| Used for accessibility: hide it if js is activated, but always show if user use a screenreader
| Button for example
| <a class="ls-js-hidden-sr">
| Button
|-
! scope="row" | .ls-no-js-hidden {{NewIn|3.0}}
| Used for part to be hidden if javascript is not activated
| Link
| <a class="ls-no-js-hidden">
| LimeSurvey core used it for inactive link if javascript is not activated
|-
! scope="row" | .ls-label-xs-visibility {{NewIn|3.0}}
| Label to be hidden in big screen, but show with little screen (with no more table) and to screenreader
| label
| <label class="ls-no-js-hidden">
| Used for label inside table cell of array question type
|-
! scope="row" | .ls-input-group-extra {{NewIn|3.0}}
| Same usage of boostrap input-group-addon, but without the border and the background.
| right suffix
| <div class="ls-input-group-extra">
| Used for right and left suffix (global)
|-
! scope="row" | .checkbox {{ObsoleteIn|3.0}}
| input[type=checkbox]
| Question with checkbox
| <input type="checkbox" class="checkbox">
| With modern browser: not needed, but some old browser need this
|-
! scope="row" | .radio {{ObsoleteIn|3.0}}
| input[type=radio]
| Question with radio
| <input type="radio" class="radio">
| With modern browser: not needed, but some old browser need this
|-
! scope="row" | .text
| input[type=text]
| Question with input text, or textarea
| <textarea class="text">
|
|-
! scope="row" | .answertext
| Array question type
| Answer part of array question type
| <th class="answertext">
|
|-
! scope="row" | .col-answers
| Array question type
| Column of answers
| <col class="col-answers">
|
|-
! scope="row" | .odd .even {{ObsoleteIn|2.50}}
| Array question type
| Alternation for column
| <col class="odd">
|
|-
! scope="row" | .array1 .array2 {{ObsoleteIn|3.0}}
| Array question type
| Alternation for line
| <tr class="array1">
|
|-
! scope="row" | .ls-odd .ls-even {{NewIn|3.0}}
| Array question type
| Alternation for sub-question and Y axis
| <tr class="ls-odd">
|
|}

=== Some example of question part with classes=== 


'''Text-short question type:'''
</translate><source lang="html4strict">
<p class="question answer-item text-item ">
<label class="hide label" for="answerSGQA">Answer</label><input type="text" value="" id="answerSGQA" name="SGQA" size="50" class="text empty">
</p>
</source><translate>


'''Multiple short text'''
</translate><source lang="html4strict">
<ul class="subquestions-list questions-list text-list">
<li class="question-item answer-item text-item" id="javatbdSGQA">
<label for="answerSGQA">Some example subquestion</label>
<span><input type="text" value="" id="answerSGQA" name="SGQA" size="20" class="text empty"></span>
</li>
</ul>
</source><translate>


'''Array question type'''
</translate><source lang="html4strict">
<table class="question subquestion-list questions-list ">
<caption class="hide read">Some explanation for accessibility.</caption>
<colgroup class="col-responses">
<col width="50%" class="col-answers">
<col width="25%" class="odd">
<col width="13.3%" class="col-no-answer even">
</colgroup>
<thead>
<tr class="array1 dontread">
<td> </td>
<th>1</th>
<th>No answer</th>
</tr>
</thead>
<tbody>
<tr class="array2 answers-list radio-list" id="javatbdSGQ">
<th width="20%" class="answertext">Some example subquestion
</th>
<td class="answer_cell_001 answer-item radio-item">
<label for="answerSGQA" class="hide read">1</label>
<input type="radio" value="1" id="answerSGQA" name="SGQA" class="radio">
</td>
<td class="answer-item radio-item noanswer-item">
<label for="answerSGQA" class="hide read">No answer</label>
<input type="radio" value="" id="answerSGQA" name="SGQA" class="radio">
</td>
</tr>
</tbody>
</table>
</source><translate>

==The full list of question classes== 


{|
|'''Question Type'''||'''Question Class'''||'''Question ID'''
|-
|5 point choice||.choice-5-pt-radio||5
|-
|Array (10 point choice)||.array-10-pt||B
|-
|Array (5 point choice)||.array-5-pt||A
|-
|Array (Flexible Labels) dual scale||.array-flexible-duel-scale ||1
|-
|Array (Increase, Same, Decrease)||.array-increase-same-decrease||E
|-
|Array (Multi Flexible) (Numbers)||.array-multi-flexi ||:
|-
|Array (Multi Flexible) (Text)||.array-multi-flexi-text||;
|-
|Array (Yes/No/Uncertain)||.array-yes-uncertain-no||C
|-
|Array (flexible labels)||.array-flexible-row ||F
|-
|Array (flexible labels) by column||.array-flexible-column||H
|-
|Boilerplate question||.boilerplate||X
|-
|Date||.date||D
|-
|Gender||.gender||G
|-
|Huge free text||.text-huge||U
|-
|Language switch||.language||I
|-
|List (dropdown)||.list-dropdown||!
|-
|List (radio)||.list-radio||L
|-
|List with comment||.list-with-comment||O
|-
|Long free text||.text-long||T
|-
|Multiple numerical input||.numeric-multi||K
|-
|Multiple options||.multiple-opt||M
|-
|Multiple options with comments||.multiple-opt-comments||P
|-
|Multiple short text||.multiple-short-txt||Q
|-
|Numerical input||.numeric||N
|-
|Ranking||.ranking||R
|-
|Short free text||.text-short||S
|-
|Yes/No||.yes-no||Y
|-
|
|}

==The full list of validation classes== 


<div class="simplebox">Note: Prior to 1.92, only .mandatory and .input-error classes were available.</div>


These apply to the help and/or validation tip messages so that each type can be individually styled.


The .hide-tip option and .input-error options interact by default so that you can have validation tips hidden. However, they do appear when there are validation errors and disappear again when those errors are rectified.


All of these are designed to eliminate the need for pop-up alert messages. Instead, tips can appear/disappear as needed and are color-coded to indicate whether the answers pass the validation criteria.


Furthermore, when you first visit a page that has unmet validation criteria, you can color-code the tips in a pleasing color to show which validation criteria have not been met yet; then re-display the page using a harsher color if the person submits the page with lingering validation errors.


{|
|'''Purpose'''||'''CSS Class'''||'''Description'''
|-
|Mandatory||.mandatory||the question is mandatory
|-
|User input error||.input-error||the question had at least one validation error
|-
|Hide Tip||.hide-tip||added if you use the hide_tip option
|-
|Num answers||.em_num_answers||for for min_answers and max_answers
|-
|Value range||.em_value_range||for min/max_num_value_n and multiflexible_min/max
|-
|Sum range||.em_sum_range||for min/max/equals_num_value
|-
|Regex validation||.em_regex_validation||for regular-expression validation of the question
|-
|Question-level validation function||.em_q_fn_validation||for the em_validation_q option
|-
|Subquestion-level validation function||.em_sq_fn_validation||for the em_validation_sq option
|-
|Other comment mandatory||.em_other_comment_mandatory||for other_comment_mandatory option - shows when "other" is selected but associated comment is missing.
|-
|
|}

==Importing styles into your custom template== 


The custom question styles are near the bottom of each template's CSS file and start with:<syntaxhighlight lang="php" enclose="div">/* --------------------------- START: Question styles ------------------------------ */</syntaxhighlight>


If you're styling your own custom template, you should be able to copy everything after the above one from ''templates/default/template.css'' (for table-based layouts) or ''/templates/limespired/template.css'' (for CSS-based layouts) into your own style sheet without any impact on your other styles.

==Internet Explorer conditional style sheets== 


Because of the marked discrepancies in rendering between IE6 & IE7 and the other browsers, there are special IE conditional style sheets included for each template.


<source lang="html4strict" enclose="div">



</source>


You should include the above code within your '''startpage.pstpl''' and copies of both the IE style sheets from either ''/templates/default/'' or ''/templates/limespired'' for Tables base layout and CSS based layout respectively.


<div class="simplebox">'''Note:''' If you copy the styles into your own style sheet you will almost certainly need to tweak them.</div>

===Alternative solution for Internet explorer=== 


You can put a conditional class for body in startpage.pstpl and use this class in your template.css. This method is used in the citronade template{{ObsoleteIn|2.06}}. Adding a js / no-js class to have javascript / no javascript system.


<source lang="html4strict">



<body id="body" class="lang-{SURVEYLANGUAGE} {SURVEYFORMAT} no-js">
<script type='text/javascript'>/*<![CDATA[*/(function(H){ H.className=H.className.replace(/\bno-js\b/,'js') })(document.getElementsByTagName('body')[0]);/*]]>*/</script></source>


And in template.css use:


<source lang="css">.ie6{/*specific for internet explorer 6*/}
.ielt8{/*specific for internet explorer 6 and 7*/}
.ie{/*specific for all internet explorer */}</source>

== Right-to-Left (RTL) Languages and justify== 


The text editor within LimeSurvey is able to format RTL text. However, the editor itself shows the RTL language in a left to right format when justified. This is just an editor display issue. The RTL and justified question or text will display correctly from right to left, even when justified, in your survey or on preview.

==Keywords== 


{{Deprecated|3.0}}


Keywords within a template file get replaced by the current survey information. They are surrounded by curly brackets, for example: {SURVEYNAME}.


The following strings will be replaced by LimeSurvey when parsing the template file and presenting it to survey users. These field strings will work on almost every template except for the 'Completed Page'. (Most of these strings can be found in the common.php file. If it's not there, look in the index.php file.)


{|class=wikitable
!'''Keyword'''!!'''Template files'''!!'''Description'''
|-
|{SURVEYNAME}||All Files||The survey title
|-
|{SURVEYDESCRIPTION}||All Files||The survey description
|-
|{WELCOME}||All files (mainly for welcome.pstpl)||The survey 'welcome' text
|-
|{PERCENTCOMPLETE}||survey.pstpl||A small graph showing the percentage of the survey completed
|-
|{GROUPNAME}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group name
|-
|{GROUPDESCRIPTION}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group description
|-
|{NUMBEROFQUESTIONS}||welcome.pstpl||Displays the total number of questions in the survey (just the number)
|-
|{THEREAREXQUESTIONS}||welcome.pstpl||Displays the sentence "There are X questions in this survey" - from the relevant language file. The X is replaced with the number of questions. Note that this will also work appropriately for singular or plural. If there is only 1 question, it will print "There is 1 question in this survey".
|-
|{CHECKJAVASCRIPT}||All files (mainly for welcome.pstpl)||Warning message when end-user browser have javascript disabled
|-
|{QUESTION}||Question.pstpl||('''Has been superseeded as of LS1.87''') Displays the current question text (The format of {QUESTION} can customised by editing 'question_start.pstpl') Use the following: {QUESTION_TEXT}, {QUESTION_MANDATORY}, {QUESTION_HELP}, {QUESTION_MAN_MESSAGE}, {QUESTION_VALID_MESSAGE}, {QUESTION_INPUT_ERROR_CLASS}, and appropriate wrapping HTML instead of {QUESTION}
|-
|{ANSWER}||question.pstpl, print_question.pstpl||presents the answer form for the current question
|-
|{SGQ}||question.pstpl, question text||Can be used in the question text itself to reference the input field of the question dynamically by displaying the Survey-Group-Question id for the current question. (as of svn build 9755)
|-
|{QUESTIONHELP}||question.pstpl, print_question.pstpl||Displays help text (predefined tip for question type) for the current question
|-
|{QUESTION_CLASS}||question.pstpl, print_question.pstpl||unique class for each question type. (To be included in the question's wrapping tag.)
|-
|{QUESTION_CODE}||question.pstpl, print_question.pstpl||Displays the current question code
|-
|{QUESTION_ESSENTIALS}||question.pstpl||the question ID and (if a question is conditional), 'style="display:none;"'. (To be included in the question's wrapping tag.)
|-
|{QUESTION_HELP}||question.pstp, question_start.pstpl||Displays the user defined help text for the current question
|-
|{QUESTION_TYPE_HELP}||print_question.pstp||Displays the user defined help text for the current question
|-
|{QUESTION_INPUT_ERROR_CLASS}||question.pstp, question_start.pstpl||Provides a class if there was user input error
|-
|{QUESTION_ID}||print_question.pstp||Provides a unique ID for each question to allow styling for specific questions
|-
|{QUESTION_TEXT}||question.pstp, print_question.pstp, question_start.pstpl||Displays the text for the current question
|-
|{QUESTION_MANDATORY}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' text for the current question
|-
|{QUESTION_MAN_CLASS}||question.pstpl, print_question.pstpl||class if a question is mandatory. (To be included in the question's wrapping tag.)
|-
|{QUESTION_MAN_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' help message text for the current question
|-
|{QUESTION_NUMBER}||print_question.pstpl||Incremental count of questions.
|-
|{QUESTION_VALID_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated valid help message text for the current question
|-
|{QUESTION_SCENARIO}||print_question.pstp||Prints out the 'scenario' text for conditional questions.
|-
|{NAVIGATOR}||navigator.pstpl||Displays navigation buttons (next, prev, last)
|-
|{CLEARALL}||All files (but intended for navigator.pstpl)||Displays the "Exit and Clear Results" link
|-
|{COMPLETED}||completed.pstpl||Displays the 'completed' message for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{URL}||completed.pstpl||Displays the survey 'url' and 'url text'
|-
|{PRIVACYMESSAGE}||privacy.pstpl||The privacy message is shown if you set your survey to be anonymous. [[Translating LimeSurvey|The text can be edited/translated]] in the language files. This can also be changed manually by editing the privacy.pstpl template you wish to use.
|-
|{TEMPLATEURL}||All Files||The URL to the current template location (useful for referencing image files in your template)
|-
|{SURVEYRESOURCESURL}||All Files||The URL to the current uploaded files for this survey location (useful for referencing image files in your question, group, ....)
|-
|{SUBMITCOMPLETE}||endpage.pstpl||The statement (from the language files) that tells the user they have completed the survey, and to press the "Submit" button
|-
|{SUBMITREVIEW}||survey.pstpl||The statement (from the language files) that tells the user they can review/change the answers they have made by clicking "<< prev"
|-
|{SAVEDID}||All Files||Displays 'Response ID' of user
|-
|-
|{QUEXMLPDF}||All Files||Displays button to export the queXML PDF of questionnaire including answers entered up until the point that has been completed in the survey.
|-
|{TOKEN:FIRSTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users first name from the tokens table
|-
|{TOKEN:LASTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users last name from the tokens table***
|-
|{TOKEN:EMAIL}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users email from the tokens table***
|-
|{TOKEN:ATTRIBUTE_1}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_1 from the tokens table***
|-
|{TOKEN:ATTRIBUTE_2}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_2 from the tokens table***
|-
|{ANSWERSCLEARED}||Preferably in navigator.pstpl||The "Answers Cleared" statement from the language files
|-
|{RESTART}||clearall.pstpl||URL to restart the survey
|-
|{REGISTERERROR}||register.pstpl||Shows any error messages in the register page (ie: "You must include an email address")
|-
|{REGISTERMESSAGE1}||register.pstpl||The statement "You must be registered to complete this survey" from the language files
|-
|{REGISTERMESSAGE2}||register.pstpl||Details about registering from the language files
|-
|{REGISTERFORM}||register.pstpl||The actual form for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{SAVE}||Works suitable on navigator.pstpl||Displays the 'Save your responses so far' button to offer the user to save and come back later to continue the survey. If the Save option is deactivated in the survey properties the tag will not be shown and ignored.
|-
|{LANGUAGECHANGER}||survey.pstpl||Displays a switch in multilingual surveys to change the question.
|}

==Input/Buttons== 


Each "input" type in a survey has been given its own class name, so that you can add CSS to your "startpage.pstpl" file and have some control over the appearance of form buttons and inputs. These class names are as follows:
*'''submit''' (Submit Buttons)
*'''text''' (Text Inputs - for short free text, date, and numerical type)
*'''answertext''' (Text of answers)
*'''radio''' (Radio Buttons)
*'''checkbox''' (Check Boxes)
*'''select''' (Select / List Boxes)
*'''textarea''' (Large text inputs - for long free text)
*'''clearall''' (The "Exit and Clear Survey" link)
*'''rank''' (The rank style question. Doesn't set the colour of the select box or the text boxes, but it does allow the changing of background colour, text colour, size etc., for the rest of the ranking question)
*'''graph''' (The "percentage completed" graph table)
*'''innergraph''' (The table inside the graph table - this contains the 0% and 100% text. Use this for changing the size of this text)
*'''question''' (General settings for any question that is displayed within a table. Generally, you should use this to make sure that their font size and color is the same as you have used elsewhere as a default)
*'''mandatory''' (Mandatory questions)
*'''input-error''' (User input error - for if a user has made a mistake with a mandatory question or question with validation)
*'''array1''' and '''array2''' (These two styles are cycled when presenting the range of answers for an array type question. This allows you to set an alternating background color for these question types. '''Array1''' is also used for the column headings in these question types)
*'''errormandatory''' (Sets the color and style of the "This question is mandatory" error message)
*'''warningjs''' (Sets the color and style of the warning message displayed if the participant's browser has javascript disabled)


There are also some elements that can be accessed using the ID of the element ('''#ID''' in CSS):
*'''surveycontact''' (The contact message shown on the start page)
*'''tokenmessage''' (used for messages inside the survey, e.g. the session expired error message)


Because you can edit all the HTML aspects, there's no reason to surround your templates with a
<syntaxhighlight lang="php" enclose="div"><div class='new_name'></div></syntaxhighlight>
and then define a css for that new_name class.

==Styling the progress bar== 


The progress bar appearance can be modified with CSS.


To change the background color of the bar, add something like the following to the end of your template.css file:


<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-header {
background-color: #3300FF;
}</syntaxhighlight>


To change the border color of the bar, add something like the following to the end of your template.css file:


<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-content,
#progress-wrapper .ui-widget-header {
border: 1px solid #FF0000;
}</syntaxhighlight>

==Advanced Features Available to Developers== 


LimeSurvey has integrated some user-made patches that permits some special changes. These very advanced features (generally) require changes to the underlying code base of LimeSurvey and should be done carefully in order not to introduce security holes.

===Support for your own Javascript functions=== 


Some users may need to run Javascript on the survey pages, but calling '''checkconditions()''' in the BODY element made it impossible to do so. This call has been replaced with a small JavaScript function in the HEAD that sniffs for the existence of '''checkconditions()''' and '''template_onload()''' before calling them. In this way, a template author can create his or her own '''template_onload()''' function in the HEAD that replaces the default one.


*Disable XSS filter - in Global settings -> Security, set "Filter HTML for XSS" to No.
*Enter your script in the source of a question or group description.


{{Note|For further details, see the [[Workarounds: Manipulating a survey at runtime using Javascript#How to use Script (eg. JavaScript etc.) in LimeSurvey|workaround section]].}}

=Videos on Templates= 


This video will demonstrate the basic and advanced template functions that are available to all LimeSurvey users. This includes changing the appearance of certain forms and inserting custom graphics. Additionally, it will thoroughly walk you through on how to edit and preview specific page templates, importing/exporting templates, modify appearance of questions in the CSS, and customizing survey description page.


Video - needed

=Tips & Tricks= 

==Some language specific element== 


If you want to have some language specific sentence in a survey, for example a help at the end of each page, you can add in a .pstl file a sentence and hidding it for other language. If we hide it in the template.css, we can use the pseudo selector :lang, but we use some class for better compatibility.


Below, there are two help sentences, in French and English. Put this on endpage.pstpl:


<syntaxhighlight lang="php" enclose="div"><div class="fr" lang="fr">Pour de l'aide en direct appelez le 000000</div>
<div class="en" lang="en">For some help, please call 000000</div></syntaxhighlight>


and in template.css:


<syntaxhighlight lang="php" enclose="div">.lang-fr .en{display:none}
.lang-en .fr{display:none}</syntaxhighlight>

==Change the layout of the survey page== 


After editing and saving a template, it applies to a survey list page only if it is selected from the settings of the survey. To make it the default template, go under the '''General tab''' located in the '''Global settings''' of your LimeSurvey installation and choose the desired template. From now on, all the templates that use the "default" option as template plus the ones that are going to be newly created, will use the newly selected default template.


To use your current template for this page, you have to change the according setting from '''Global settings'''. In older versions, this change can be done by editing the $defaulttemplate setting from the config file: copy this setting from config-defaults.php to config.php which overrides config-defaults.php and edit this setting to <code lang="html">$defaulttemplate = 'yourtemplatename';</code>.

==Import/Export of templates: Mac users== 


<u>Mac users</u>, please note that the Mac OSX default archive utility may have problems with zip folders "generated on the fly".


A workaround is to unix'es unzip from the command line:


$ unzip template.zip -d template


Archive: template.zip


inflating: template/startpage


inflating: ...


Another workaround is to use scripts in their mac-compiled counterparts.

==Replacing the help icon {{ObsoleteIn|2.50}} == 


When a question help text is shown, then an help.gif image is used from the default template folder.


You can replace this image by uploading a new help.gif, help.png or help.jpg in your custom template folder. It will then be automatically used instead of the default help icon.

==Replacing an existing logo {{NewIn|2.50}} {{ObsoleteIn|3.0}}== 


'''Note''': In the '''default'' Template of 2.50, there is no preembedded logo. Read further our [[#Adding_your_own_logo |wiki on how to add your own logo]].


1. To edit the logo go to the ''<u>template.css</u>'' file which you can find it here:


<center>[[File:t1.PNG|200px]]</center>


2. Click the search button to find occurrences of logo related styles and search for ''logo''


<center>[[File:2.png|200px]]</center>


4. Edit the main style file.


You will see something similar to:


<center>[[File:t4.PNG|500px]]</center>


If you want to change the image, just replace logo.gif with another image link. Example: (<u>logo.png</u> or <u>logo.jpg</u>).


If you want to change the image size, adjust width and height (in pixels) like this:


<syntaxhighlight lang="php" enclose="div">width:100px; height:100px;</syntaxhighlight>

==Adding your own logo {{ObsoleteIn|3.0}} == 


1. Find and open the '''startpage.pstpl''' template file.


<center>[[File:startpage.pstpl.png]]</center>


2. After this
<source lang="html4strict" ><div id="topContainer" class="jumbotron"></source>
add this line to '''startpage.pstpl''':
<source lang="html4strict">
<div class="container"><img id='page_logo' src='{TEMPLATEURL}/files/logo.png' class="clearfix pull-right" /></div>
</source>


3. To upload your own logo, go to the template editor and upload your logo.


<center>[[File:uploadyourlogo.png]]</center>


To position your logo, please use one of the following css classes:


*'''If you want the logo to be placed on the left side:'''


<source lang="html">clearfix pull-left</source>


*'''If you want the logo to be placed on the right side:'''


<source lang="html">clearfix pull-right</source>


*'''If you want to center the logo'''


<source lang="html">clearfix center-block</source>

==Use the same template with different logos== 


If you want to use the same template for all surveys and just want to change the logo for each survey, you can use the {SID} placeholder in the template .pstpl file and thereby refer to different images:


<syntaxhighlight lang="php" enclose="div"><img src="{TEMPLATEURL}files/logoImage-{SID}.png"></syntaxhighlight>

==Remove the default help to all question (hide_tip) {{ObsoleteIn|1.92}}== 


There are 3 solutions to remove the default help:
# like a hide_tip attribute but for all question and survey.
# you can remove the {QUESTIONHELP} and its container from the file question.pstl. However, it can be a bad idea for the screenreader.
# for the default template and some other, add this at the end of tempate.css


<syntaxhighlight lang="php" enclose="div">span.questionhelp{display:none;}</syntaxhighlight>

== Display custom favicon== 


A favicon is the little icon you see in the browser's address bar, list of bookmarks or tab. You can display your own icon as follows:
#Create a favicon - google will find you lots of free favicon generators.
#Name your new favicon "favicon.ico" and place it in your template /files directory.
#Add the following code to your '''startpage.pstpl''' before the </head> tag.


<syntaxhighlight lang="html4strict" enclose="div"><link rel="shortcut icon" href="{TEMPLATEURL}files/favicon.ico" type="image/x-icon">
<link rel="icon" href="{TEMPLATEURL}files/favicon.ico" type="image/x-icon"></syntaxhighlight>

== Different appearance for survey-/question-pages== 


If you want LimeSurvey to change the appearance of every second page (i.e. of even and odd survey pages), you can use '''.page-odd''' class in your CSS file to change the appearance of odd pages.


An example from default template of LimeSurvey 1.91+:


<syntaxhighlight lang="php" enclose="div">
.page-odd table.question-group {
background-color: #D2F2D3;
}</syntaxhighlight>


If you do '''not''' want differentiate even and odd pages, find all instances of ''.page-odd'' in template.css and remove those styles.

==Create a vertical separator border for dual scale array== 


To create a vertical separator border for a dual scale array, you can add the following lines to your '''template.css'''-file.


<syntaxhighlight lang="php" enclose="div">
table.question thead td.header_separator,
table.question tbody td.dual_scale_separator
{
border-right:solid 1px #00A8E1;
}
</syntaxhighlight>


''header_separator'' is used to adress the separator for the header "td". The "dual_scale_separator" is used to address the separator column in the dual scale array.

==Hide the survey contact message shown on the start page/survey list {{ObsoleteIn|3.0}} == 


To hide the "Please contact ..." message on the start page (with the survey list), you can add the following to the '''$(document).ready''' function in the '''template.js''' of your used design template:


<syntaxhighlight lang="php" enclose="div">


$('#surveycontact').hide(); //Hides the survey contact message


</syntaxhighlight>

==Remove the survey contact message shown on error messages {{ObsoleteIn|3.0}}== 


If you want to remove the survey contact message from error messages, it'll be trickier. You can add the function from below. It calls the '''$(document).ready''' function in the '''template.css''' of your used design template:


<syntaxhighlight lang="php" enclose="div">
removeContactAdressFromMessage(); //Removes the survey contact message from error messages
</syntaxhighlight>


and add the following function to your *template.js* file


<syntaxhighlight lang="php" enclose="div">
function removeContactAdressFromMessage()
{
if ($('#tokenmessage').length > 0)
{
var oldMessage = $('#tokenmessage').html();
var indexContact = oldMessage.indexOf('Bitte kontaktieren');
var newMessage = oldMessage.substr(0, indexContact);
$('#tokenmessage').html(newMessage);
}
}
</syntaxhighlight>


It will probably not work for a survey in English language and has to be extended when used for multilingual surveys. But it's an idea/tip on how to solve this.

==How to deal with multilingual question attributes {{ObsoleteIn|2.50}}== 


If you have a multilingual survey and e. g. want to use a different string for the "other" field, this could only be done for the base language (until this feature was added at LimeSurvey 2.0). To work around this, paste in the field to change the label for "other":


<syntaxhighlight lang="php" enclose="div"><span class="en">New label</span><span class="fr">Nouveau label</span></syntaxhighlight>


Add in the template.css of your template (at ''/limesurvey/upload/templates/<yourtemplatename>/template.css''):


<syntaxhighlight lang="php" enclose="div">html:lang(en) .fr{display:none}
html:lang(fr) .en{display:none}</syntaxhighlight>

==Adding your own logo to the survey list {{ NewIn|3.0}} == 


# First please open the theme editor for the theme you like to use. [[File:OpenThemeEditor.jpg]]
# We recommend to use fruity, it is our best theme currently.
# Then extend the theme and give it a name you will recognize. [[File:ExtendTheme.jpg]]
# In the following view you may upload the logo you want to use. [[File:UploadFileTheme.jpg]]
# Select the editor screen `Survey List´ in the Screen dropdown in the top right corner. [[File:OpenScreenSurveyList.jpg]]
# Then select `layout_survey_list.twig´ in the left side menu. [[File:EditLayoutSurveyListTwig.jpg]]
# In the editor scroll to line 126 and change the marked part to the filename of the image you uploaded to the theme before. [[File:ChangeSurveyListHeaderImageEditor.jpg]]
# Save your file. [[File:ThemeEditorSaveChanges.jpg]]
# Change default theme to your extended theme. [[File:ChangeDefaultTheme.jpg]]

=Custom Question Views {{NewIn|3.0}}= 


<div class="simplebox">'''Note:''' This is a temporary feature to be replaced in the future by question object (it will be very easy to move custom views to question object). It is disabled by default.</div>


As of version 2.5, you can create template-specific custom views for questions and some of their incorporated elements. This is useful if you want to modify the HTML layout of a particular question type for one or more surveys.


*In application/config/config.php, find 'config'=>array and add this line to the array : 'allow_templates_to_overwrite_views'=>1
*In /{your_template}/config.xml, set "overwrite_question_views" to true
*Copy application/views/survey/* to template/{your_view_directory}/survey/
*Note that you only need to copy the files that you intend to modify but the file structure must remain the same as in application/views/survey/

=Insert Custom CSS or JavaScript files for template {{NewIn|2.50}}= 


As of version 2.50, you can use the config.xml file to automatically load plugin files.


*Upload your files to the template /css or /scripts folder
*In /{your_template}/config.xml, add the file paths to the <css> or <js> blocks, something like this:<syntaxhighlight lang="xml" enclose="div"><css>
<filename>css/jquery-ui-custom.css</filename>
<filename>css/bootstrap-slider.css</filename>


<filename>css/awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</filename>
<filename>css/flat_and_modern.css</filename>


<filename>css/template.css</filename>


<filename>css/myCustomPlugin.css</filename>
</css>
<js>
<filename>scripts/template.js</filename>
<filename>scripts/bootstrap-slider.js</filename>


<filename>scripts/myCustomPlugin.js</filename>
</js>
</syntaxhighlight>

</translate>

Theme editor

2018-04-04T10:06:21Z

LouisGac: updating to LS3

<languages /> <translate>

=Introduction= 


LimeSurvey has an advanced theme and style system providing to developers an efficient way to customize the survey appearance. Since LS3, we're not speaking anymore about '''"templates"''' like in previous versions, but about '''"themes"'''. The '''themes''' allow control over the look and feel of pages during a survey. A survey administrator can select a default theme that will be used for each survey to further personalize it and improve its look and feel. '''"Themes"''' come with options that provide to admin without coding skill a simple way to add a logo on the welcome page, to change the background colors, to select a font, etc.


LimeSurvey comes with 3 themes right out of the box. These initial themes are defined by directories located in the LimeSurvey installation "themes/survey/" directory. Each theme has it's own directory. Within the main directory of a theme you'll find a configuration file in XML, and numerous directories containing the views ''themes (.twig)''', '''cascading style sheets (.css)''', '''scripts''', '''images''' ('''.jpg''' or '''.png'''), and maybe others.


Like in other theme-based systems, fragments of HTML code are stored in the .pstpl template files. These fragments are read and used to construct the page to be display to the end user (survey participant). Often '''keywords''' surrounded by curly braces are included in the files that are then replaced with the relevant text. You may find below an example of a template file content and its result when used in a survey page:


<syntaxhighlight lang="html4strict" enclose="div">
<div style='text-align: center;'><span style='color:red'>My New Survey</span></div>
<div style='text-align: center;'><span style='color:red'>This is a survey written by me to find out what sort of chocolate people like.</span></div>
</syntaxhighlight>


One gets a result that looks like:


<div class="simplebox"><div style='text-align: center;'><span style='color:red'>My New Survey</span></div>
<div style='text-align: center;'><span style='color:red'>This is a survey written by me to find out what sort of chocolate people like.</span></div></div>


Templates, being HTML code, tend to define the positioning and type of text to be displayed and similar structural features of the page. They often reference or include other files. Most of them reference a common cascading style sheets (CSS) file that defines the font style, color, size, background, and similar parameters common to all pages in the survey. Style sheets reference HTML '''class''' parameters that are associated with the various types of objects in the HTML code. This allows the style sheet to describe how to display each of the many types of text or other objects that may appear in multiple places. There are unique classes for each question type in LimeSurvey and thus giving detailed control over the appearance of each. Image files, like logos or special progress-bar constructors, may be referenced as well in the Template file. Finally, special keywords in curly braces are replaced with text defined in the survey for each language translation correspondent (for example, the 'Survey Title' or 'Question Text' for each language defined).


If you create a new custom template, please consider contributing it back to the LimeSurvey community and make it available to others. With your help, we can grow our repository of templates, surveys, and other add-ons to make LimeSurvey even better!
See our [https://www.limesurvey.org/index.php?option=com_sobipro&sid=55:Templates&Itemid=729 LimeSurvey template repository] where you can share your templates.

=Creating a new template= 


To be able to create a new template (or edit an existing template), you need [[Manage users#Set global permissions for a user|Template Editing user permission]] in LimeSurvey as well as permission to manipulate the files in the underlying operating system hosting your LimeSurvey installation.


<div class="simplebox"><span style='color:red'>'''Note of Warning:'''</span> If you change templates, you could also affect all the pre-existing surveys from your LimeSurvey installation. Templates are an advanced feature that require experience and HTML knowledge in order to make them running smoothly.</div>


The preferred way to create a new template is through the '''Template Editor''' (see below), which is located in the '''Configuration''' dialog. Some people may like to work directly with template files so that they can use their favorite text editor instead of the web interface. In this case, still use the Template Editor to first create your new template. This will create a new base template with all the files you need in the ''LimeSurvey_web_root/upload/templates/your_new_template'' directory. From there you can use your text editor to manually adjust the template files.


<div class="simplebox">'''Permissions Note:''' on unix/linux systems, these template files will be owned by the group and user where the web server is running (may be "www" for some systems). So, make sure you have enough access to edit these files, When you save them, make sure they don't change ownership! In this way, you can still use the web Template Editing interface if needed.</div><br />


A number of 'public' elements of LimeSurvey can be adjusted by a series of templates. The next section provides a very brief explanation of these templates.


{{Note|Template files may seem complex. Besides HTML, you might also need to understand CSS.}}

=The LimeSurvey template editor= 


To ease the understanding and quick update of a Template, LimeSurvey provides a '''Template Editor''' in the main '''administrative''' toolbar of the application. This Template Editor is only available to users [[Manage users#Set global permissions for a user|with the Templates permission]] and to superadministrators.


{{Alert|title=Attention|text=A template that is not correctly constructed can render a survey (that uses the respective template) inoperable. }}


The LimeSurvey template editor allows you to edit the contents of your templates online. Start the Template Editor by clicking on '''Template editor''' in the '''Configuration''' menu.


[[File:templates.png]]


The template editor page allows you to select the template you would like to edit/view.


[[File:Template-editor-2013-7-10_11_38_16.png|center]]

==The template menu== 


The following options are available:


*'''Create''': Allows you to create a new template. In order not to start from scratch, the template 'default' is copied.
*'''Import''': Allows you to import a template from a ZIP file.
*'''Export''': Allows you to export the current template to a ZIP file.
*'''Copy''': Allows you to make a new template by copying the current one.
*'''Rename''': Allows you to change the name of the template. It is generally used after copying or importing a template.
*'''Template''': It is a drop-down list that shows all the available templates that are located in your LimeSurvey installation.


*'''Screen''': It is a drop-down list which allows you to choose which particular survey page of that template you want to look at.
*'''Return to admin panel'''.

==Import/export/copy a template== 


When you '''export '''a template, a ZIP-file archive with all the files your template consists of will be created (.pstpl files, images, css files, ...). You can simply '''import''' the exported zip-file into another LimeSurvey installation by using the import feature or you can manually copy the archive into another LimeSurvey installation and extract it into the corresponding [[Theme editor#Template files location|template directory there]].


However, it is preferred to use the LimeSurvey template import/export/copy functions in the template editor.

==Page Structure / Template Use== 
*'''The Welcome Page:''' startpage.pstpl, welcome.pstpl, privacy.pstpl, navigator.pstpl, endpage.pstpl
*'''The Questions Pages:''' startpage.pstpl, survey.pstpl, startgroup.pstpl, groupdescription.pstpl, question.pstpl, endgroup.pstpl, endpage.pstpl
*'''The Final Page:''' startpage.pstpl, assessment.pstpl, completed.pstpl, endpage.pstpl

==Template Files== 


The following template files are used to produce your public survey and must exist in any new template folder you create:
*'''startpage.pstpl:''' Produces the start of each html page. It starts at the "<head>" tag, and should not contain the "<html>" tag. This 'very beginning' of a standard html page is written by the scripts. Please ensure that your startpage.pstpl files contains a <body> tag. Even though many browsers do not require strict adherence to the W3 HTML standards, the LimeSurvey script needs to find a <body> tag to run certain javascript elements. It is not expected to see many 'keywords' used in the startpage.pstpl file. However, you may wish to put the {SURVEYNAME} into the title. The startpage.pstpl file can contain code that ends in the corresponding endpage.pstpl file. For example, you can start a table in this file and close the table in the endpage.pstpl file. The startpage.pstpl and endpage.pstpl files wrap around every possible page used by LimeSurvey.
*'''survey.pstpl:''' This template is the second used on most pages and provides a space to put the survey name and description. This template does not have a corresponding 'closing' template, and subsequently you should close all tags opened in this template file (i.e.: don't leave a table open here because there is nowhere else to close it).
*'''welcome.pstpl:''' This template is only used in the welcome screen (which is also on the main page for 'all in one' surveys). You can use this to print out the welcome text, and other information that should be provided in the introduction. Like the 'survey.pstpl' file, there is no corresponding 'closing' template, so all tags opened in this template file should be closed as well.
*'''startgroup.pstpl:''' This template can provide a 'summary' wrap around for questions within a group. It has a matching 'endgroup.pstpl' template that can be used to close any opened tags in this file, so you can open a table within this.
*'''groupdescription.pstpl:''' This template file is used to display a description of a group. Please note that in the survey settings (access the ''Presentation & navigation settings'' by clicking on the '''Presentation''' tab) you can set if the group description should be shown or not. If not, then this file is not included at all.
*'''question.pstpl:''' This file contains the question, answer, and help text sections of your survey. In the "group by group" and "all in one" surveys, this template is cycled repeatedly with each question. There is no corresponding closing file for this and all tags should be closed.
*'''question_start.pstpl:''' This file contains the individual elements found at the start of a question. It is included within 'question.pstpl' via the {QUESTION} keyword. It is intended to allow template designers more control over the layout of a question. This template sits outside the normal templating system and '''was superseeded (as of LimeSurvey 1.87)'''. All keywords from this template are now available directly in question.pstpl.
*'''completed.pstpl:''' This page is displayed as the final page when the survey responses have been saved and the survey is over. It can be used to display a "forwarding link" as set in the survey setup.
*'''endgroup.pstpl:''' This file closes the group, and can be used to close off any tags opened in the startgroup.pstpl file
*'''navigator.pstpl:''' This file contains the buttons that navigate through the survey, "next", "prev", "last", "submit", "save so far" and the "clear all" link. It is used in all pages except the completed page.
*'''printanswers.pstpl:''' This file has the HTML wrapper necessary for the print version of the survey.
*'''print_group.pstpl:''' This file is the same as startgroup.pstpl and endgroup.pstpl, but for the print version of the survey.
*'''print_question.pstpl:''' This file is the same as question.pstpl, but for the print version of the survey.
*'''print_survey.pstpl:''' This file is the same as survey.pstpl, but for the print version of the survey.

== CSS and Javascript== 


Two files that are always used in a template are template.css (for CSS) and template.js (for Javascript).
*'''{TEMPLATECSS}:''' Add lines for default css, template.css, and template-rtl.css for rtl language.
*'''{TEMPLATEJS}:''' Add lines for default javascript files, template.js, and all js files needed for LimeSurvey.

=== Using Bootstrap=== 
LimeSurvey has Bootstrap 3 embedded, so you can style all your templates with the well documented Bootstrap classes.
For more information please refer to the [https://getbootstrap.com Bootstrap documentation].


The [https://github.com/flatlogic/awesome-bootstrap-checkbox Awesome-Bootstrap-Checkbox] plugin is also included. With it, you can use the typical Bootstrap color-classes (info,warning,danger,etc.) also with the suffix "-checkbox" or "-radio", though styling checkboxes and radios as you prefer.

=== Replacing default CSS or Javascript=== 


Some questions use specific files for Javascript or CSS. If you need to replace a function, use a cascading system. For javascript function, the last function read is the function used.

==Other Template Files== 


The '''privacy.pstpl''', '''invitationemail.pstpl''', '''reminderemail.pstpl''', and '''confirmationemail.pstpl''' are no longer used by LimeSurvey and defaults are instead set in the applicable language files. The email messages can now be edited on a survey by survey basis.

==Standard Pages== 


There are ten standard pages that a survey participant may see in the course of taking or accessing the LimeSurvey application. Each is constructed from a number of common '''Template''' files from the '''Template''' specified in the settings of the survey. The table below indicates which template files are used in constructing each of these pages.


{| class="wikitable"
! '''Survey Pages/'''<br />'''Template Files'''!!Survey<br />List!!Welcome!!Question!!Completed!!Clear All!!Register!!Load!!Save!!Print<br />Answers!!Print<br />Survey
|-
|SurveyList||align="center" | [[File:check.gif]]|| || || || || || || || ||
|-
|Welcome|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Privacy|| ||align="center" | [[File:check.gif]]|| || || || || || || ||
|-
|Navigator|| ||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Survey|| || ||align="center" | [[File:check.gif]]|| || ||align="center" | [[File:check.gif]]|| || || ||
|-
|StartGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|GroupDescription|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Question<span style='color:red'>'''*'''</span>|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|EndGroup|| || ||align="center" | [[File:check.gif]]|| || || || || || ||
|-
|Assessment|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|Completed|| || || ||align="center" | [[File:check.gif]]|| || || || || ||
|-
|ClearAll|| || || || ||align="center" | [[File:check.gif]]|| || || || ||
|-
|Register|| || || || || ||align="center" | [[File:check.gif]]|| || || ||
|-
|Load|| || || || || || ||align="center" | [[File:check.gif]]|| || ||
|-
|Save|| || || || || || || ||align="center" | [[File:check.gif]]|| ||
|-
|PrintAnswers|| || || || || || || || ||align="center" | [[File:check.gif]]||
|-
|Print Survey || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Group || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|Print Question || || || || || || || || || ||align="center" | [[File:check.gif]]
|-
|StartPage<br />EndPage<br />Template.css||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||align="center" | [[File:check.gif]]||
|}


<span style='color:red'>'''*'''</span>NOTE: In version 1.90+, this replaces question.pstpl AND question_start.pstpl. If you are using an old custom template, you need to add the following line to the beginning of question.pstpl:<syntaxhighlight lang="php" enclose="div"><div {QUESTION_ESSENTIALS} class="{QUESTION_CLASS}{QUESTION_MAN_CLASS}{QUESTION_INPUT_ERROR_CLASS}"></syntaxhighlight>And then add the corresponding closing tag to the end of question.pstpl:<syntaxhighlight lang="php" enclose="div"></div></syntaxhighlight>


<span style='color:red'>'''*'''</span>NOTE: In version 1.91 and earlier, LimeSurvey js files are not included in the template. In version 2, '''you have to use {TEMPLATEJS} in one of your template file''' to add the link to the js file. You can add it in startpage.pstpl or in endpage.pstpl. You can remove the {TEMPLATEURL}/template.js line and you have to replace with {TEMPLATEJS} to update a personal template.

==The File Control Section== 


In the "file control" window on the left, you can click on one of the template files that is used to compile the page. You can see the ''Screen part'', JavaScript, and CSS files. The HTML code for that file will then appear in the "Now editing" window in the center. If the template is editable (determined by directory permissions) you can then make any changes and save them.


<center>[[File:File Control Section.png|center]]</center>


The "Other files" window shows a list of all other files from the template directory. You can use the right side to '''upload and select image files (your pics, logos,...) or other files needed to create your template'''.


Instead of using a link for each picture, utilize the field string {TEMPLATEURL}. So, instead of:


<syntaxhighlight lang="html4strict" enclose="div">img src='/limesurvey/templates/yourtemplate/files/mypicture.jpg'</syntaxhighlight>
You can use {{NewIn|2.50}}:
<syntaxhighlight lang="html4strict" enclose="div">img src='{TEMPLATEURL}files/mypicture.jpg'</syntaxhighlight>


In LimeSurvey versions before 2.50 use:
<syntaxhighlight lang="html4strict" enclose="div">img src='{TEMPLATEURL}mypicture.jpg'</syntaxhighlight>


A "sample" of the template page you are editing will be visible in the bottom of the screen. There is no way to delete a template from the template editor. This must be done by accessing the underlying directory and deleting manually the files from there. You also have the possibility to select different screen resolutions in order to better evaluate the feel and look of the template.


<div class="simplebox">'''Note:''' The shipped templates cannot be edited using the template editor. If you want to modify them, create a copy first and edit the copy.</div>

==Template files location== 


LimeSurvey stores each of the 'standard' templates in their own distinct sub-directory within the ''/templates'' directory that is kept in the public directory with the other LimeSurvey public files. Customized user templates are stored in the ''/upload/templates'' directory.


There should '''ALWAYS''' be a "default" directory in the templates directory. This template is used by default and as a fall-back if a template folder doesn't exist, or can't be found. It comes installed by default.


You can use any image files that you upload into the template management area with the help of this syntax:


<syntaxhighlight lang="php" enclose="div">{TEMPLATEURL}filename.xyz</syntaxhighlight>

=Styling questions with CSS= 


Styling of questions in CSS has become much easier. Each question type has now a unique class. The mandatory questions have an additional mandatory class. For example, for a non-mandatory question:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender">
...
</div></syntaxhighlight>


and if the question is mandatory:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory">
...
</div></syntaxhighlight>


and if the question is mandatory, but the user didn't answer it or if there is validation on a question:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question5" class="gender mandatory input-error">
...
</div></syntaxhighlight>


and if the question has validation applied, but the user hasn't answered correctly:


<syntaxhighlight lang="html4strict" enclose="div"><div id="question6" class="text-short input-error">
...
</div></syntaxhighlight>

==Global classes for question part== 


These classes are used for each question type. Some question types use only one or two classes, while others may use much more.


{| class="wikitable alternance"
|+ Global classes
|-
! scope="col" | Class name
! scope="col" | Part
! scope="col" | Question type
! scope="col" | Examples
! scope="col" | Note
|-
! scope="row" | .question {{ObsoleteIn|3.0}}
| All question block
| All question type
|<p class="question">, <ul class="question">, <table class="question">
|
|-
! scope="row" | .ls-answers {{NewIn|3.0}}
| All question block
| All question type
|<div class="ls-answers ">, <ul class="ls-answers ">, <table class="ls-answers">
|
|-
! scope="row" | .subquestions-list
| List of subquestion
| Multi choice question, array question type
| <ul class="subquestions-list">, <table class="subquestions-list">
| .questions-list is used too
|-
! scope="row" | .answers-list
| List of answers
| Single choice question, array question type, Multi input text question
| <ul class="answers-list">, <table class="answers-list">
|
|-
! scope="row" | .answer-item
| The answer part: one answer
| Single choice question, array question type, Multi input text question
| <li class="answer-item">, <td class="answer-item">
|
|-
! scope="row" | .noanswer-item
| The answer part for no answer
| Single choice question, array question type
| <li class="noanswer-item">, <td class="noanswer-item">
| No answer is an answer too, then have double class noanswer-item and answer-item
|-
! scope="row" | .question-item
| The question part: one question
| Multi text question, array question type
| <li class="question-item">, <tr class="question-item">
| Some answers are questions too. Then we have a lot of class="question-item answer-item"
|-
! scope="row" | .checkbox-list
| A list of checkbox
| Multi choice question, array number (checkbox) question type
| <ul class="checkbox-list">, <tr class="checkbox-list">
| Some question types use multi-list class, like checkbox with comment: class="checkbox-list text-list"
|-
! scope="row" | .checkbox-array {{NewIn|3.0}}
| A array of checkbox
| Array (numbers) with checkbox option
| <table class="checkbox-list">
|
|-
! scope="row" | .checkbox-item
| The answer part with a checkbox
| Multi choice question, array number (checkbox) question type
| <li class="checkbox-item">, <td class="checkbox-item">
|
|-
! scope="row" | .radio-list
| A list of radio item
| Single choice question, array question type (each row)
| <ul class="radio-list">, <tr class="radio-list">
|
|-
! scope="row" | .radio-array {{NewIn|3.0}}
| A array of radio item
| Array question type
| <table class="radio-array">
|
|-
! scope="row" | .radio-item
| The answer part with a radio
| Single choice question, array question type
| <li class="radio-item">, <td class="radio-item">
|
|-
! scope="row" | .text-list
| A list of text input
| Multi text question type, array of text
| <ul class="text-list">, <tr class="text-list">
|
|-
! scope="row" | .text-item
| The answer part of a text input
| Multi text question type, array of text
| <li class="text-item">, <td class="text-item">
|
|-
! scope="row" | .numeric-list
| A list of text input with numeric only answer
| Multi numeric question type, array of number
| <ul class="text-list numeric-list">, <tr class="text-list numeric-list">
|
|-
! scope="row" | .number-list
| A list of text input with numeric only answer (each row)
| Multi numeric question type, array of number
| <ul class="text-list numeric-list">, <tr class="text-list numeric-list">
|
|-
! scope="row" | .number-array {{NewIn|3.0}}
| The answer part of a numeric input
| Array of number
| <table class="number-array">
|
|-
! scope="row" | .select-list {{ObsoleteIn|2.50}}
| A list of select
| Array numbers, Dual scale array (select)
| <table class="select-list">
|
|-
! scope="row" | .dropdown-list {{NewIn|2.50}}
| A list of select
| Array numbers, Dual scale array (select) (each row)
| <table class="dropdown-list">
|
|-
! scope="row" | .dropdown-array {{NewIn|3.0}}
| A array of dropdown
| Array numbers, Dual scale array (select)
| <table class="dropdown-array">
|
|-
! scope="row" | .select-item {{ObsoleteIn|2.50}}
| The answer part of a select
| Array numbers, Dual scale array (select), single choice with select
| <p class="select-item">, <td class="select-item">
|
|-
! scope="row" | .dropdown-item {{NewIn|2.50}}
| The answer part of a select
| Array numbers, Dual scale array (select), single choice with select
| <p class="dropdown-item">, <td class="dropdown-item">
|
|-
! scope="row" | .hide {{ObsoleteIn|3.0}}
| Used for accessibility: hidden with css but read by screenreader, since 2.50 : you can use sr-only from bootstrap
| Short text question
| <label class="hide">
| Can be used for other purposes
|-
! scope="row" | .ls-js-hidden {{NewIn|3.0}}
| Used for part to be hidden if javascript is activated
| Button for example
| <div class="ls-js-hidden">
| LimeSurvey core used it, but you can use it too in your template
|-
! scope="row" | .ls-js-hidden-sr {{NewIn|3.0}}
| Used for accessibility: hide it if js is activated, but always show if user use a screenreader
| Button for example
| <a class="ls-js-hidden-sr">
| Button
|-
! scope="row" | .ls-no-js-hidden {{NewIn|3.0}}
| Used for part to be hidden if javascript is not activated
| Link
| <a class="ls-no-js-hidden">
| LimeSurvey core used it for inactive link if javascript is not activated
|-
! scope="row" | .ls-label-xs-visibility {{NewIn|3.0}}
| Label to be hidden in big screen, but show with little screen (with no more table) and to screenreader
| label
| <label class="ls-no-js-hidden">
| Used for label inside table cell of array question type
|-
! scope="row" | .ls-input-group-extra {{NewIn|3.0}}
| Same usage of boostrap input-group-addon, but without the border and the background.
| right suffix
| <div class="ls-input-group-extra">
| Used for right and left suffix (global)
|-
! scope="row" | .checkbox {{ObsoleteIn|3.0}}
| input[type=checkbox]
| Question with checkbox
| <input type="checkbox" class="checkbox">
| With modern browser: not needed, but some old browser need this
|-
! scope="row" | .radio {{ObsoleteIn|3.0}}
| input[type=radio]
| Question with radio
| <input type="radio" class="radio">
| With modern browser: not needed, but some old browser need this
|-
! scope="row" | .text
| input[type=text]
| Question with input text, or textarea
| <textarea class="text">
|
|-
! scope="row" | .answertext
| Array question type
| Answer part of array question type
| <th class="answertext">
|
|-
! scope="row" | .col-answers
| Array question type
| Column of answers
| <col class="col-answers">
|
|-
! scope="row" | .odd .even {{ObsoleteIn|2.50}}
| Array question type
| Alternation for column
| <col class="odd">
|
|-
! scope="row" | .array1 .array2 {{ObsoleteIn|3.0}}
| Array question type
| Alternation for line
| <tr class="array1">
|
|-
! scope="row" | .ls-odd .ls-even {{NewIn|3.0}}
| Array question type
| Alternation for sub-question and Y axis
| <tr class="ls-odd">
|
|}

=== Some example of question part with classes=== 


'''Text-short question type:'''
</translate><source lang="html4strict">
<p class="question answer-item text-item ">
<label class="hide label" for="answerSGQA">Answer</label><input type="text" value="" id="answerSGQA" name="SGQA" size="50" class="text empty">
</p>
</source><translate>


'''Multiple short text'''
</translate><source lang="html4strict">
<ul class="subquestions-list questions-list text-list">
<li class="question-item answer-item text-item" id="javatbdSGQA">
<label for="answerSGQA">Some example subquestion</label>
<span><input type="text" value="" id="answerSGQA" name="SGQA" size="20" class="text empty"></span>
</li>
</ul>
</source><translate>


'''Array question type'''
</translate><source lang="html4strict">
<table class="question subquestion-list questions-list ">
<caption class="hide read">Some explanation for accessibility.</caption>
<colgroup class="col-responses">
<col width="50%" class="col-answers">
<col width="25%" class="odd">
<col width="13.3%" class="col-no-answer even">
</colgroup>
<thead>
<tr class="array1 dontread">
<td> </td>
<th>1</th>
<th>No answer</th>
</tr>
</thead>
<tbody>
<tr class="array2 answers-list radio-list" id="javatbdSGQ">
<th width="20%" class="answertext">Some example subquestion
</th>
<td class="answer_cell_001 answer-item radio-item">
<label for="answerSGQA" class="hide read">1</label>
<input type="radio" value="1" id="answerSGQA" name="SGQA" class="radio">
</td>
<td class="answer-item radio-item noanswer-item">
<label for="answerSGQA" class="hide read">No answer</label>
<input type="radio" value="" id="answerSGQA" name="SGQA" class="radio">
</td>
</tr>
</tbody>
</table>
</source><translate>

==The full list of question classes== 


{|
|'''Question Type'''||'''Question Class'''||'''Question ID'''
|-
|5 point choice||.choice-5-pt-radio||5
|-
|Array (10 point choice)||.array-10-pt||B
|-
|Array (5 point choice)||.array-5-pt||A
|-
|Array (Flexible Labels) dual scale||.array-flexible-duel-scale ||1
|-
|Array (Increase, Same, Decrease)||.array-increase-same-decrease||E
|-
|Array (Multi Flexible) (Numbers)||.array-multi-flexi ||:
|-
|Array (Multi Flexible) (Text)||.array-multi-flexi-text||;
|-
|Array (Yes/No/Uncertain)||.array-yes-uncertain-no||C
|-
|Array (flexible labels)||.array-flexible-row ||F
|-
|Array (flexible labels) by column||.array-flexible-column||H
|-
|Boilerplate question||.boilerplate||X
|-
|Date||.date||D
|-
|Gender||.gender||G
|-
|Huge free text||.text-huge||U
|-
|Language switch||.language||I
|-
|List (dropdown)||.list-dropdown||!
|-
|List (radio)||.list-radio||L
|-
|List with comment||.list-with-comment||O
|-
|Long free text||.text-long||T
|-
|Multiple numerical input||.numeric-multi||K
|-
|Multiple options||.multiple-opt||M
|-
|Multiple options with comments||.multiple-opt-comments||P
|-
|Multiple short text||.multiple-short-txt||Q
|-
|Numerical input||.numeric||N
|-
|Ranking||.ranking||R
|-
|Short free text||.text-short||S
|-
|Yes/No||.yes-no||Y
|-
|
|}

==The full list of validation classes== 


<div class="simplebox">Note: Prior to 1.92, only .mandatory and .input-error classes were available.</div>


These apply to the help and/or validation tip messages so that each type can be individually styled.


The .hide-tip option and .input-error options interact by default so that you can have validation tips hidden. However, they do appear when there are validation errors and disappear again when those errors are rectified.


All of these are designed to eliminate the need for pop-up alert messages. Instead, tips can appear/disappear as needed and are color-coded to indicate whether the answers pass the validation criteria.


Furthermore, when you first visit a page that has unmet validation criteria, you can color-code the tips in a pleasing color to show which validation criteria have not been met yet; then re-display the page using a harsher color if the person submits the page with lingering validation errors.


{|
|'''Purpose'''||'''CSS Class'''||'''Description'''
|-
|Mandatory||.mandatory||the question is mandatory
|-
|User input error||.input-error||the question had at least one validation error
|-
|Hide Tip||.hide-tip||added if you use the hide_tip option
|-
|Num answers||.em_num_answers||for for min_answers and max_answers
|-
|Value range||.em_value_range||for min/max_num_value_n and multiflexible_min/max
|-
|Sum range||.em_sum_range||for min/max/equals_num_value
|-
|Regex validation||.em_regex_validation||for regular-expression validation of the question
|-
|Question-level validation function||.em_q_fn_validation||for the em_validation_q option
|-
|Subquestion-level validation function||.em_sq_fn_validation||for the em_validation_sq option
|-
|Other comment mandatory||.em_other_comment_mandatory||for other_comment_mandatory option - shows when "other" is selected but associated comment is missing.
|-
|
|}

==Importing styles into your custom template== 


The custom question styles are near the bottom of each template's CSS file and start with:<syntaxhighlight lang="php" enclose="div">/* --------------------------- START: Question styles ------------------------------ */</syntaxhighlight>


If you're styling your own custom template, you should be able to copy everything after the above one from ''templates/default/template.css'' (for table-based layouts) or ''/templates/limespired/template.css'' (for CSS-based layouts) into your own style sheet without any impact on your other styles.

==Internet Explorer conditional style sheets== 


Because of the marked discrepancies in rendering between IE6 & IE7 and the other browsers, there are special IE conditional style sheets included for each template.


<source lang="html4strict" enclose="div">



</source>


You should include the above code within your '''startpage.pstpl''' and copies of both the IE style sheets from either ''/templates/default/'' or ''/templates/limespired'' for Tables base layout and CSS based layout respectively.


<div class="simplebox">'''Note:''' If you copy the styles into your own style sheet you will almost certainly need to tweak them.</div>

===Alternative solution for Internet explorer=== 


You can put a conditional class for body in startpage.pstpl and use this class in your template.css. This method is used in the citronade template{{ObsoleteIn|2.06}}. Adding a js / no-js class to have javascript / no javascript system.


<source lang="html4strict">



<body id="body" class="lang-{SURVEYLANGUAGE} {SURVEYFORMAT} no-js">
<script type='text/javascript'>/*<![CDATA[*/(function(H){ H.className=H.className.replace(/\bno-js\b/,'js') })(document.getElementsByTagName('body')[0]);/*]]>*/</script></source>


And in template.css use:


<source lang="css">.ie6{/*specific for internet explorer 6*/}
.ielt8{/*specific for internet explorer 6 and 7*/}
.ie{/*specific for all internet explorer */}</source>

== Right-to-Left (RTL) Languages and justify== 


The text editor within LimeSurvey is able to format RTL text. However, the editor itself shows the RTL language in a left to right format when justified. This is just an editor display issue. The RTL and justified question or text will display correctly from right to left, even when justified, in your survey or on preview.

==Keywords== 


{{Deprecated|3.0}}


Keywords within a template file get replaced by the current survey information. They are surrounded by curly brackets, for example: {SURVEYNAME}.


The following strings will be replaced by LimeSurvey when parsing the template file and presenting it to survey users. These field strings will work on almost every template except for the 'Completed Page'. (Most of these strings can be found in the common.php file. If it's not there, look in the index.php file.)


{|class=wikitable
!'''Keyword'''!!'''Template files'''!!'''Description'''
|-
|{SURVEYNAME}||All Files||The survey title
|-
|{SURVEYDESCRIPTION}||All Files||The survey description
|-
|{WELCOME}||All files (mainly for welcome.pstpl)||The survey 'welcome' text
|-
|{PERCENTCOMPLETE}||survey.pstpl||A small graph showing the percentage of the survey completed
|-
|{GROUPNAME}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group name
|-
|{GROUPDESCRIPTION}||startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl||Displays the current group description
|-
|{NUMBEROFQUESTIONS}||welcome.pstpl||Displays the total number of questions in the survey (just the number)
|-
|{THEREAREXQUESTIONS}||welcome.pstpl||Displays the sentence "There are X questions in this survey" - from the relevant language file. The X is replaced with the number of questions. Note that this will also work appropriately for singular or plural. If there is only 1 question, it will print "There is 1 question in this survey".
|-
|{CHECKJAVASCRIPT}||All files (mainly for welcome.pstpl)||Warning message when end-user browser have javascript disabled
|-
|{QUESTION}||Question.pstpl||('''Has been superseeded as of LS1.87''') Displays the current question text (The format of {QUESTION} can customised by editing 'question_start.pstpl') Use the following: {QUESTION_TEXT}, {QUESTION_MANDATORY}, {QUESTION_HELP}, {QUESTION_MAN_MESSAGE}, {QUESTION_VALID_MESSAGE}, {QUESTION_INPUT_ERROR_CLASS}, and appropriate wrapping HTML instead of {QUESTION}
|-
|{ANSWER}||question.pstpl, print_question.pstpl||presents the answer form for the current question
|-
|{SGQ}||question.pstpl, question text||Can be used in the question text itself to reference the input field of the question dynamically by displaying the Survey-Group-Question id for the current question. (as of svn build 9755)
|-
|{QUESTIONHELP}||question.pstpl, print_question.pstpl||Displays help text (predefined tip for question type) for the current question
|-
|{QUESTION_CLASS}||question.pstpl, print_question.pstpl||unique class for each question type. (To be included in the question's wrapping tag.)
|-
|{QUESTION_CODE}||question.pstpl, print_question.pstpl||Displays the current question code
|-
|{QUESTION_ESSENTIALS}||question.pstpl||the question ID and (if a question is conditional), 'style="display:none;"'. (To be included in the question's wrapping tag.)
|-
|{QUESTION_HELP}||question.pstp, question_start.pstpl||Displays the user defined help text for the current question
|-
|{QUESTION_TYPE_HELP}||print_question.pstp||Displays the user defined help text for the current question
|-
|{QUESTION_INPUT_ERROR_CLASS}||question.pstp, question_start.pstpl||Provides a class if there was user input error
|-
|{QUESTION_ID}||print_question.pstp||Provides a unique ID for each question to allow styling for specific questions
|-
|{QUESTION_TEXT}||question.pstp, print_question.pstp, question_start.pstpl||Displays the text for the current question
|-
|{QUESTION_MANDATORY}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' text for the current question
|-
|{QUESTION_MAN_CLASS}||question.pstpl, print_question.pstpl||class if a question is mandatory. (To be included in the question's wrapping tag.)
|-
|{QUESTION_MAN_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated 'Mandatory' help message text for the current question
|-
|{QUESTION_NUMBER}||print_question.pstpl||Incremental count of questions.
|-
|{QUESTION_VALID_MESSAGE}||question.pstp, print_question.pstp, question_start.pstpl||Displays the translated valid help message text for the current question
|-
|{QUESTION_SCENARIO}||print_question.pstp||Prints out the 'scenario' text for conditional questions.
|-
|{NAVIGATOR}||navigator.pstpl||Displays navigation buttons (next, prev, last)
|-
|{CLEARALL}||All files (but intended for navigator.pstpl)||Displays the "Exit and Clear Results" link
|-
|{COMPLETED}||completed.pstpl||Displays the 'completed' message for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{URL}||completed.pstpl||Displays the survey 'url' and 'url text'
|-
|{PRIVACYMESSAGE}||privacy.pstpl||The privacy message is shown if you set your survey to be anonymous. [[Translating LimeSurvey|The text can be edited/translated]] in the language files. This can also be changed manually by editing the privacy.pstpl template you wish to use.
|-
|{TEMPLATEURL}||All Files||The URL to the current template location (useful for referencing image files in your template)
|-
|{SURVEYRESOURCESURL}||All Files||The URL to the current uploaded files for this survey location (useful for referencing image files in your question, group, ....)
|-
|{SUBMITCOMPLETE}||endpage.pstpl||The statement (from the language files) that tells the user they have completed the survey, and to press the "Submit" button
|-
|{SUBMITREVIEW}||survey.pstpl||The statement (from the language files) that tells the user they can review/change the answers they have made by clicking "<< prev"
|-
|{SAVEDID}||All Files||Displays 'Response ID' of user
|-
|-
|{QUEXMLPDF}||All Files||Displays button to export the queXML PDF of questionnaire including answers entered up until the point that has been completed in the survey.
|-
|{TOKEN:FIRSTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users first name from the tokens table
|-
|{TOKEN:LASTNAME}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users last name from the tokens table***
|-
|{TOKEN:EMAIL}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users email from the tokens table***
|-
|{TOKEN:ATTRIBUTE_1}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_1 from the tokens table***
|-
|{TOKEN:ATTRIBUTE_2}||All Files||***If survey answers are NOT ANONYMOUS - gets replaced with the users attribute_2 from the tokens table***
|-
|{ANSWERSCLEARED}||Preferably in navigator.pstpl||The "Answers Cleared" statement from the language files
|-
|{RESTART}||clearall.pstpl||URL to restart the survey
|-
|{REGISTERERROR}||register.pstpl||Shows any error messages in the register page (ie: "You must include an email address")
|-
|{REGISTERMESSAGE1}||register.pstpl||The statement "You must be registered to complete this survey" from the language files
|-
|{REGISTERMESSAGE2}||register.pstpl||Details about registering from the language files
|-
|{REGISTERFORM}||register.pstpl||The actual form for registering, will change depending on whether the attribute_1 and attribute_2 fields are set.
|-
|{SAVE}||Works suitable on navigator.pstpl||Displays the 'Save your responses so far' button to offer the user to save and come back later to continue the survey. If the Save option is deactivated in the survey properties the tag will not be shown and ignored.
|-
|{LANGUAGECHANGER}||survey.pstpl||Displays a switch in multilingual surveys to change the question.
|}

==Input/Buttons== 


Each "input" type in a survey has been given its own class name, so that you can add CSS to your "startpage.pstpl" file and have some control over the appearance of form buttons and inputs. These class names are as follows:
*'''submit''' (Submit Buttons)
*'''text''' (Text Inputs - for short free text, date, and numerical type)
*'''answertext''' (Text of answers)
*'''radio''' (Radio Buttons)
*'''checkbox''' (Check Boxes)
*'''select''' (Select / List Boxes)
*'''textarea''' (Large text inputs - for long free text)
*'''clearall''' (The "Exit and Clear Survey" link)
*'''rank''' (The rank style question. Doesn't set the colour of the select box or the text boxes, but it does allow the changing of background colour, text colour, size etc., for the rest of the ranking question)
*'''graph''' (The "percentage completed" graph table)
*'''innergraph''' (The table inside the graph table - this contains the 0% and 100% text. Use this for changing the size of this text)
*'''question''' (General settings for any question that is displayed within a table. Generally, you should use this to make sure that their font size and color is the same as you have used elsewhere as a default)
*'''mandatory''' (Mandatory questions)
*'''input-error''' (User input error - for if a user has made a mistake with a mandatory question or question with validation)
*'''array1''' and '''array2''' (These two styles are cycled when presenting the range of answers for an array type question. This allows you to set an alternating background color for these question types. '''Array1''' is also used for the column headings in these question types)
*'''errormandatory''' (Sets the color and style of the "This question is mandatory" error message)
*'''warningjs''' (Sets the color and style of the warning message displayed if the participant's browser has javascript disabled)


There are also some elements that can be accessed using the ID of the element ('''#ID''' in CSS):
*'''surveycontact''' (The contact message shown on the start page)
*'''tokenmessage''' (used for messages inside the survey, e.g. the session expired error message)


Because you can edit all the HTML aspects, there's no reason to surround your templates with a
<syntaxhighlight lang="php" enclose="div"><div class='new_name'></div></syntaxhighlight>
and then define a css for that new_name class.

==Styling the progress bar== 


The progress bar appearance can be modified with CSS.


To change the background color of the bar, add something like the following to the end of your template.css file:


<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-header {
background-color: #3300FF;
}</syntaxhighlight>


To change the border color of the bar, add something like the following to the end of your template.css file:


<syntaxhighlight lang="php" enclose="div">#progress-wrapper .ui-widget-content,
#progress-wrapper .ui-widget-header {
border: 1px solid #FF0000;
}</syntaxhighlight>

==Advanced Features Available to Developers== 


LimeSurvey has integrated some user-made patches that permits some special changes. These very advanced features (generally) require changes to the underlying code base of LimeSurvey and should be done carefully in order not to introduce security holes.

===Support for your own Javascript functions=== 


Some users may need to run Javascript on the survey pages, but calling '''checkconditions()''' in the BODY element made it impossible to do so. This call has been replaced with a small JavaScript function in the HEAD that sniffs for the existence of '''checkconditions()''' and '''template_onload()''' before calling them. In this way, a template author can create his or her own '''template_onload()''' function in the HEAD that replaces the default one.


*Disable XSS filter - in Global settings -> Security, set "Filter HTML for XSS" to No.
*Enter your script in the source of a question or group description.


{{Note|For further details, see the [[Workarounds: Manipulating a survey at runtime using Javascript#How to use Script (eg. JavaScript etc.) in LimeSurvey|workaround section]].}}

=Videos on Templates= 


This video will demonstrate the basic and advanced template functions that are available to all LimeSurvey users. This includes changing the appearance of certain forms and inserting custom graphics. Additionally, it will thoroughly walk you through on how to edit and preview specific page templates, importing/exporting templates, modify appearance of questions in the CSS, and customizing survey description page.


Video - needed

=Tips & Tricks= 

==Some language specific element== 


If you want to have some language specific sentence in a survey, for example a help at the end of each page, you can add in a .pstl file a sentence and hidding it for other language. If we hide it in the template.css, we can use the pseudo selector :lang, but we use some class for better compatibility.


Below, there are two help sentences, in French and English. Put this on endpage.pstpl:


<syntaxhighlight lang="php" enclose="div"><div class="fr" lang="fr">Pour de l'aide en direct appelez le 000000</div>
<div class="en" lang="en">For some help, please call 000000</div></syntaxhighlight>


and in template.css:


<syntaxhighlight lang="php" enclose="div">.lang-fr .en{display:none}
.lang-en .fr{display:none}</syntaxhighlight>

==Change the layout of the survey page== 


After editing and saving a template, it applies to a survey list page only if it is selected from the settings of the survey. To make it the default template, go under the '''General tab''' located in the '''Global settings''' of your LimeSurvey installation and choose the desired template. From now on, all the templates that use the "default" option as template plus the ones that are going to be newly created, will use the newly selected default template.


To use your current template for this page, you have to change the according setting from '''Global settings'''. In older versions, this change can be done by editing the $defaulttemplate setting from the config file: copy this setting from config-defaults.php to config.php which overrides config-defaults.php and edit this setting to <code lang="html">$defaulttemplate = 'yourtemplatename';</code>.

==Import/Export of templates: Mac users== 


<u>Mac users</u>, please note that the Mac OSX default archive utility may have problems with zip folders "generated on the fly".


A workaround is to unix'es unzip from the command line:


$ unzip template.zip -d template


Archive: template.zip


inflating: template/startpage


inflating: ...


Another workaround is to use scripts in their mac-compiled counterparts.

==Replacing the help icon {{ObsoleteIn|2.50}} == 


When a question help text is shown, then an help.gif image is used from the default template folder.


You can replace this image by uploading a new help.gif, help.png or help.jpg in your custom template folder. It will then be automatically used instead of the default help icon.

==Replacing an existing logo {{NewIn|2.50}} {{ObsoleteIn|3.0}}== 


'''Note''': In the '''default'' Template of 2.50, there is no preembedded logo. Read further our [[#Adding_your_own_logo |wiki on how to add your own logo]].


1. To edit the logo go to the ''<u>template.css</u>'' file which you can find it here:


<center>[[File:t1.PNG|200px]]</center>


2. Click the search button to find occurrences of logo related styles and search for ''logo''


<center>[[File:2.png|200px]]</center>


4. Edit the main style file.


You will see something similar to:


<center>[[File:t4.PNG|500px]]</center>


If you want to change the image, just replace logo.gif with another image link. Example: (<u>logo.png</u> or <u>logo.jpg</u>).


If you want to change the image size, adjust width and height (in pixels) like this:


<syntaxhighlight lang="php" enclose="div">width:100px; height:100px;</syntaxhighlight>

==Adding your own logo {{ObsoleteIn|3.0}} == 


1. Find and open the '''startpage.pstpl''' template file.


<center>[[File:startpage.pstpl.png]]</center>


2. After this
<source lang="html4strict" ><div id="topContainer" class="jumbotron"></source>
add this line to '''startpage.pstpl''':
<source lang="html4strict">
<div class="container"><img id='page_logo' src='{TEMPLATEURL}/files/logo.png' class="clearfix pull-right" /></div>
</source>


3. To upload your own logo, go to the template editor and upload your logo.


<center>[[File:uploadyourlogo.png]]</center>


To position your logo, please use one of the following css classes:


*'''If you want the logo to be placed on the left side:'''


<source lang="html">clearfix pull-left</source>


*'''If you want the logo to be placed on the right side:'''


<source lang="html">clearfix pull-right</source>


*'''If you want to center the logo'''


<source lang="html">clearfix center-block</source>

==Use the same template with different logos== 


If you want to use the same template for all surveys and just want to change the logo for each survey, you can use the {SID} placeholder in the template .pstpl file and thereby refer to different images:


<syntaxhighlight lang="php" enclose="div"><img src="{TEMPLATEURL}files/logoImage-{SID}.png"></syntaxhighlight>

==Remove the default help to all question (hide_tip) {{ObsoleteIn|1.92}}== 


There are 3 solutions to remove the default help:
# like a hide_tip attribute but for all question and survey.
# you can remove the {QUESTIONHELP} and its container from the file question.pstl. However, it can be a bad idea for the screenreader.
# for the default template and some other, add this at the end of tempate.css


<syntaxhighlight lang="php" enclose="div">span.questionhelp{display:none;}</syntaxhighlight>

== Display custom favicon== 


A favicon is the little icon you see in the browser's address bar, list of bookmarks or tab. You can display your own icon as follows:
#Create a favicon - google will find you lots of free favicon generators.
#Name your new favicon "favicon.ico" and place it in your template /files directory.
#Add the following code to your '''startpage.pstpl''' before the </head> tag.


<syntaxhighlight lang="html4strict" enclose="div"><link rel="shortcut icon" href="{TEMPLATEURL}files/favicon.ico" type="image/x-icon">
<link rel="icon" href="{TEMPLATEURL}files/favicon.ico" type="image/x-icon"></syntaxhighlight>

== Different appearance for survey-/question-pages== 


If you want LimeSurvey to change the appearance of every second page (i.e. of even and odd survey pages), you can use '''.page-odd''' class in your CSS file to change the appearance of odd pages.


An example from default template of LimeSurvey 1.91+:


<syntaxhighlight lang="php" enclose="div">
.page-odd table.question-group {
background-color: #D2F2D3;
}</syntaxhighlight>


If you do '''not''' want differentiate even and odd pages, find all instances of ''.page-odd'' in template.css and remove those styles.

==Create a vertical separator border for dual scale array== 


To create a vertical separator border for a dual scale array, you can add the following lines to your '''template.css'''-file.


<syntaxhighlight lang="php" enclose="div">
table.question thead td.header_separator,
table.question tbody td.dual_scale_separator
{
border-right:solid 1px #00A8E1;
}
</syntaxhighlight>


''header_separator'' is used to adress the separator for the header "td". The "dual_scale_separator" is used to address the separator column in the dual scale array.

==Hide the survey contact message shown on the start page/survey list {{ObsoleteIn|3.0}} == 


To hide the "Please contact ..." message on the start page (with the survey list), you can add the following to the '''$(document).ready''' function in the '''template.js''' of your used design template:


<syntaxhighlight lang="php" enclose="div">


$('#surveycontact').hide(); //Hides the survey contact message


</syntaxhighlight>

==Remove the survey contact message shown on error messages {{ObsoleteIn|3.0}}== 


If you want to remove the survey contact message from error messages, it'll be trickier. You can add the function from below. It calls the '''$(document).ready''' function in the '''template.css''' of your used design template:


<syntaxhighlight lang="php" enclose="div">
removeContactAdressFromMessage(); //Removes the survey contact message from error messages
</syntaxhighlight>


and add the following function to your *template.js* file


<syntaxhighlight lang="php" enclose="div">
function removeContactAdressFromMessage()
{
if ($('#tokenmessage').length > 0)
{
var oldMessage = $('#tokenmessage').html();
var indexContact = oldMessage.indexOf('Bitte kontaktieren');
var newMessage = oldMessage.substr(0, indexContact);
$('#tokenmessage').html(newMessage);
}
}
</syntaxhighlight>


It will probably not work for a survey in English language and has to be extended when used for multilingual surveys. But it's an idea/tip on how to solve this.

==How to deal with multilingual question attributes {{ObsoleteIn|2.50}}== 


If you have a multilingual survey and e. g. want to use a different string for the "other" field, this could only be done for the base language (until this feature was added at LimeSurvey 2.0). To work around this, paste in the field to change the label for "other":


<syntaxhighlight lang="php" enclose="div"><span class="en">New label</span><span class="fr">Nouveau label</span></syntaxhighlight>


Add in the template.css of your template (at ''/limesurvey/upload/templates/<yourtemplatename>/template.css''):


<syntaxhighlight lang="php" enclose="div">html:lang(en) .fr{display:none}
html:lang(fr) .en{display:none}</syntaxhighlight>

==Adding your own logo to the survey list {{ NewIn|3.0}} == 


# First please open the theme editor for the theme you like to use. [[File:OpenThemeEditor.jpg]]
# We recommend to use fruity, it is our best theme currently.
# Then extend the theme and give it a name you will recognize. [[File:ExtendTheme.jpg]]
# In the following view you may upload the logo you want to use. [[File:UploadFileTheme.jpg]]
# Select the editor screen `Survey List´ in the Screen dropdown in the top right corner. [[File:OpenScreenSurveyList.jpg]]
# Then select `layout_survey_list.twig´ in the left side menu. [[File:EditLayoutSurveyListTwig.jpg]]
# In the editor scroll to line 126 and change the marked part to the filename of the image you uploaded to the theme before. [[File:ChangeSurveyListHeaderImageEditor.jpg]]
# Save your file. [[File:ThemeEditorSaveChanges.jpg]]
# Change default theme to your extended theme. [[File:ChangeDefaultTheme.jpg]]

=Custom Question Views {{NewIn|3.0}}= 


<div class="simplebox">'''Note:''' This is a temporary feature to be replaced in the future by question object (it will be very easy to move custom views to question object). It is disabled by default.</div>


As of version 2.5, you can create template-specific custom views for questions and some of their incorporated elements. This is useful if you want to modify the HTML layout of a particular question type for one or more surveys.


*In application/config/config.php, find 'config'=>array and add this line to the array : 'allow_templates_to_overwrite_views'=>1
*In /{your_template}/config.xml, set "overwrite_question_views" to true
*Copy application/views/survey/* to template/{your_view_directory}/survey/
*Note that you only need to copy the files that you intend to modify but the file structure must remain the same as in application/views/survey/

=Insert Custom CSS or JavaScript files for template {{NewIn|2.50}}= 


As of version 2.50, you can use the config.xml file to automatically load plugin files.


*Upload your files to the template /css or /scripts folder
*In /{your_template}/config.xml, add the file paths to the <css> or <js> blocks, something like this:<syntaxhighlight lang="xml" enclose="div"><css>
<filename>css/jquery-ui-custom.css</filename>
<filename>css/bootstrap-slider.css</filename>


<filename>css/awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</filename>
<filename>css/flat_and_modern.css</filename>


<filename>css/template.css</filename>


<filename>css/myCustomPlugin.css</filename>
</css>
<js>
<filename>scripts/template.js</filename>
<filename>scripts/bootstrap-slider.js</filename>


<filename>scripts/myCustomPlugin.js</filename>
</js>
</syntaxhighlight>

</translate>

New Template System in LS3.x

2018-02-15T17:50:20Z

LouisGac: /* Creating a template from scratch */

<languages />
<translate>

__TOC__
=Introduction=

On this page you'll learn how to:

* Use the new template system of LimeSurvey 3.0.
* Use inheritance to manage your own templates.
* Add a picture to your template
* Manage template options for your surveys and survey groups

<hr/>

LimeSurvey 3 introduces a complete new template engine system, based on Twig 1.29, Bootstrap, and allowing template inheritance and template options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old template system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A template designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new template engine.

<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Template Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface=
==Template list==
On the admin dashboard, there is now a box to access the template list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The template list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the template: it’s just a picture file called “preview.png” at the root of the template
* the “name” of the template: the directory name of the template. Before we release the LS3 master, it will become the template “Title” (can be different from directory name, and it can contain special cgunnarhars)
* the description of the template: a string set in its manifest
* the type of template: Core template (provided with LimeSurvey), User template (added in upload directory), XML template (not loaded in database)
* Extends: if the template extends another template, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a template to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a template in the database
** Template editor: it will redirect you to the template editor
** Template option: it will lead you the global configuration of template options

==Template Editor==
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' template'']]

====A quick overview of the concept of template inheritance====

In LS3, a template can now inherit from another template, it can “extend” another template. This means that the template directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of templates for your different users without having to maintain a lot of different templates. For example: you can have your own home-made template, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom template, all the templates that inherit from it will be updated automatically. Note that the inheritance is recursive: a template can extend a template that extends another one etc.

<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core templates of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface====

To extend the Monochrome template of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome template. Then, click on “extend” and validate the new name “extends_monochrome”.

If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/templates/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this template as a normal one from a survey and it will look exactly like the monochrome template.

[[File:Extends monochrome empty.jpg|center|baseline|border|''The template tree (directory and files) just after its creation. It's practically empty'']]

<div class="simplebox">[[File:help.png]] The ressources (jpg, png etc.) from the original template are copied when extending a template. This is because if you copy a CSS file from the original template locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current template path. </div>

The template editor for the extends_monochrome template looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome template'']]
<br /><br />
There is no big difference with the old template editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the template directory and that the file from the original template will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to template views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local template and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ====

The button '''Copy to local template and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the template you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button ''' Copy to local template and save changes ''''|]]
<br>
If you open a file explorer and go to the directory upload/templates/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your template'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).

<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the template to find the image. If the template you’re working on is extended to another template, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local template, it will loop through the template inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your template. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/

<div class="simplebox">
So, to add a picture to your template:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''

* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}

* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list====
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which template the current one extends (if any)

==Template options==
Another novelty of LS3 is the template option page. As we’ll see later, template creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the template options at global level: click on “template options” in the template list
====Advanced options====

{{QS:Theme editor - advanced options}}

====Simple options====

The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the template/options/ directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options
<div class="simplebox">[[File:help.png]] This page can be completely different from a template to another, and template providers are strongly encouraged to create their own look & feel. </div>

[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from

{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core templates:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a template provider could add his own animation library or no animation library at all.

<div class="simplebox">[[File:help.png]] The monochrome templates use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for template providers.</div>

====Inheritance system====

In the previous part, we’ve seen that a template can extend another template. A template configuration can also inherit from another template configuration. It means that for a given template, you can have a configuration at

* global level (the one we’ve just seen accessible from the template list)
* at survey group level
* a last one at survey level.

Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

======At survey group level======

Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of templates than in the template list, except that here only the option button is visible (template editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]

<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

======At survey level======
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example==
Let’s say you’re using a single template for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core template. But of course, if you are a template provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization =

You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS: deal with the asset manager ("why my changes are not applied?") ==
<br />

If you're trying to update the CSS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.

<br />

Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />

It moves the CSS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css. Else, they would have to clean their browser cache.

<br />

Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.

<br />

Here the CSS links in header when asset manager is on:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.

<br />

<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>

So, when you're editing CSS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache

[[File:Clearassets-ls3 3.png]]

<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>

Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme ==
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how ti works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css

<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>

Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>

You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font ===
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>

You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.

Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options ===
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>

* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %}
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>

<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector ===
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">

'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}

</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79

<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>

Of course, the XML file only contains the default values for your template configuration. But indeed, those values are defined and read inside the database (table "template_configuration") as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174

So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

=Creating a template from scratch=
Documentation coming soon...

'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.

'''NOTE''': to avoid that, you can force the use to the XML rather than DB. In config.php turn debug mode on and uncommment:

'force_xmlsettings_for_survey_rendering' => true, // Uncomment if you want to force the use of the XML file rather than DB (for easy theme development)

Becareful: everything will be loaded from the XML (included options, etc)

'''NOTE''': if you manually edit the CSS/JS files (without using the Teeme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache:"

</translate>

New Template System in LS3.x

2018-02-14T13:21:55Z

LouisGac: /* Customizing CSS: deal with the asset manager ("why my changes are not applied?") */

<languages />
<translate>

__TOC__
=Introduction=

On this page you'll learn how to:

* Use the new template system of LimeSurvey 3.0.
* Use inheritance to manage your own templates.
* Add a picture to your template
* Manage template options for your surveys and survey groups

<hr/>

LimeSurvey 3 introduces a complete new template engine system, based on Twig 1.29, Bootstrap, and allowing template inheritance and template options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old template system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A template designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new template engine.

<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Template Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface=
==Template list==
On the admin dashboard, there is now a box to access the template list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The template list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the template: it’s just a picture file called “preview.png” at the root of the template
* the “name” of the template: the directory name of the template. Before we release the LS3 master, it will become the template “Title” (can be different from directory name, and it can contain special cgunnarhars)
* the description of the template: a string set in its manifest
* the type of template: Core template (provided with LimeSurvey), User template (added in upload directory), XML template (not loaded in database)
* Extends: if the template extends another template, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a template to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a template in the database
** Template editor: it will redirect you to the template editor
** Template option: it will lead you the global configuration of template options

==Template Editor==
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' template'']]

====A quick overview of the concept of template inheritance====

In LS3, a template can now inherit from another template, it can “extend” another template. This means that the template directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of templates for your different users without having to maintain a lot of different templates. For example: you can have your own home-made template, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom template, all the templates that inherit from it will be updated automatically. Note that the inheritance is recursive: a template can extend a template that extends another one etc.

<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core templates of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface====

To extend the Monochrome template of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome template. Then, click on “extend” and validate the new name “extends_monochrome”.

If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/templates/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this template as a normal one from a survey and it will look exactly like the monochrome template.

[[File:Extends monochrome empty.jpg|center|baseline|border|''The template tree (directory and files) just after its creation. It's practically empty'']]

<div class="simplebox">[[File:help.png]] The ressources (jpg, png etc.) from the original template are copied when extending a template. This is because if you copy a CSS file from the original template locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current template path. </div>

The template editor for the extends_monochrome template looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome template'']]
<br /><br />
There is no big difference with the old template editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the template directory and that the file from the original template will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to template views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local template and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ====

The button '''Copy to local template and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the template you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button ''' Copy to local template and save changes ''''|]]
<br>
If you open a file explorer and go to the directory upload/templates/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your template'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).

<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the template to find the image. If the template you’re working on is extended to another template, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local template, it will loop through the template inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your template. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/

<div class="simplebox">
So, to add a picture to your template:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''

* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}

* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list====
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which template the current one extends (if any)

==Template options==
Another novelty of LS3 is the template option page. As we’ll see later, template creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the template options at global level: click on “template options” in the template list
====Advanced options====

{{QS:Theme editor - advanced options}}

====Simple options====

The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the template/options/ directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options
<div class="simplebox">[[File:help.png]] This page can be completely different from a template to another, and template providers are strongly encouraged to create their own look & feel. </div>

[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from

{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core templates:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a template provider could add his own animation library or no animation library at all.

<div class="simplebox">[[File:help.png]] The monochrome templates use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for template providers.</div>

====Inheritance system====

In the previous part, we’ve seen that a template can extend another template. A template configuration can also inherit from another template configuration. It means that for a given template, you can have a configuration at

* global level (the one we’ve just seen accessible from the template list)
* at survey group level
* a last one at survey level.

Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

======At survey group level======

Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of templates than in the template list, except that here only the option button is visible (template editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]

<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

======At survey level======
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example==
Let’s say you’re using a single template for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core template. But of course, if you are a template provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization =

You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS: deal with the asset manager ("why my changes are not applied?") ==
<br />

If you're trying to update the CSS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.

<br />

Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />

It moves the CSS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css. Else, they would have to clean their browser cache.

<br />

Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.

<br />

Here the CSS links in header when asset manager is on:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.

<br />

<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>

So, when you're editing CSS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache

[[File:Clearassets-ls3 3.png]]

<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>

Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme ==
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how ti works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css

<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>

Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>

You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font ===
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>

You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.

Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options ===
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>

* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %}
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>

<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector ===
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">

'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}

</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79

<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>

Of course, the XML file only contains the default values for your template configuration. But indeed, those values are defined and read inside the database (table "template_configuration") as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174

So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

=Creating a template from scratch=
Documentation coming soon...

'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.

'''NOTE''': if you manually edit the CSS/JS files (without using the Teeme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache:"

</translate>

File:Clearassets-ls3 3.png

2018-02-14T09:55:45Z

LouisGac: clear assets button in global settings in LS 3.3.0

clear assets button in global settings in LS 3.3.0

New Template System in LS3.x

2018-02-14T09:39:36Z

LouisGac: /* Customizing CSS: deal with the asset manager ("why my changes are not applied?") */

<languages />
<translate>

__TOC__
=Introduction=

On this page you'll learn how to:

* Use the new template system of LimeSurvey 3.0.
* Use inheritance to manage your own templates.
* Add a picture to your template
* Manage template options for your surveys and survey groups

<hr/>

LimeSurvey 3 introduces a complete new template engine system, based on Twig 1.29, Bootstrap, and allowing template inheritance and template options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old template system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A template designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new template engine.

<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Template Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface=
==Template list==
On the admin dashboard, there is now a box to access the template list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The template list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the template: it’s just a picture file called “preview.png” at the root of the template
* the “name” of the template: the directory name of the template. Before we release the LS3 master, it will become the template “Title” (can be different from directory name, and it can contain special cgunnarhars)
* the description of the template: a string set in its manifest
* the type of template: Core template (provided with LimeSurvey), User template (added in upload directory), XML template (not loaded in database)
* Extends: if the template extends another template, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a template to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a template in the database
** Template editor: it will redirect you to the template editor
** Template option: it will lead you the global configuration of template options

==Template Editor==
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' template'']]

====A quick overview of the concept of template inheritance====

In LS3, a template can now inherit from another template, it can “extend” another template. This means that the template directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of templates for your different users without having to maintain a lot of different templates. For example: you can have your own home-made template, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom template, all the templates that inherit from it will be updated automatically. Note that the inheritance is recursive: a template can extend a template that extends another one etc.

<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core templates of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface====

To extend the Monochrome template of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome template. Then, click on “extend” and validate the new name “extends_monochrome”.

If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/templates/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this template as a normal one from a survey and it will look exactly like the monochrome template.

[[File:Extends monochrome empty.jpg|center|baseline|border|''The template tree (directory and files) just after its creation. It's practically empty'']]

<div class="simplebox">[[File:help.png]] The ressources (jpg, png etc.) from the original template are copied when extending a template. This is because if you copy a CSS file from the original template locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current template path. </div>

The template editor for the extends_monochrome template looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome template'']]
<br /><br />
There is no big difference with the old template editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the template directory and that the file from the original template will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to template views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local template and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ====

The button '''Copy to local template and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the template you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button ''' Copy to local template and save changes ''''|]]
<br>
If you open a file explorer and go to the directory upload/templates/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your template'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).

<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the template to find the image. If the template you’re working on is extended to another template, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local template, it will loop through the template inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your template. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/

<div class="simplebox">
So, to add a picture to your template:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''

* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}

* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list====
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which template the current one extends (if any)

==Template options==
Another novelty of LS3 is the template option page. As we’ll see later, template creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the template options at global level: click on “template options” in the template list
====Advanced options====

{{QS:Theme editor - advanced options}}

====Simple options====

The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the template/options/ directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options
<div class="simplebox">[[File:help.png]] This page can be completely different from a template to another, and template providers are strongly encouraged to create their own look & feel. </div>

[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from

{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core templates:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a template provider could add his own animation library or no animation library at all.

<div class="simplebox">[[File:help.png]] The monochrome templates use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for template providers.</div>

====Inheritance system====

In the previous part, we’ve seen that a template can extend another template. A template configuration can also inherit from another template configuration. It means that for a given template, you can have a configuration at

* global level (the one we’ve just seen accessible from the template list)
* at survey group level
* a last one at survey level.

Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

======At survey group level======

Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of templates than in the template list, except that here only the option button is visible (template editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]

<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

======At survey level======
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example==
Let’s say you’re using a single template for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core template. But of course, if you are a template provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization =

You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS: deal with the asset manager ("why my changes are not applied?") ==
<br />

If you're trying to update the CSS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.

<br />

Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />

It moves the CSS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css. Else, they would have to clean their browser cache.

<br />

Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.

<br />

Here the CSS links in header when asset manager is on:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.

<br />

<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>

So, when you're editing CSS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can refresh the assets cache''': from Global Settings -> General -> Clear asset cache

<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>

Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme ==
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how ti works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css

<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>

Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>

You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font ===
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>

You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.

Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options ===
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>

* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %}
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>

<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector ===
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">

'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}

</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79

<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>

Of course, the XML file only contains the default values for your template configuration. But indeed, those values are defined and read inside the database (table "template_configuration") as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174

So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

=Creating a template from scratch=
Documentation coming soon...

'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.

'''NOTE''': if you manually edit the CSS/JS files (without using the Teeme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache:"

</translate>

New Template System in LS3.x

2018-02-14T09:35:30Z

LouisGac: /* Creating a template from scratch */

<languages />
<translate>

__TOC__
=Introduction=

On this page you'll learn how to:

* Use the new template system of LimeSurvey 3.0.
* Use inheritance to manage your own templates.
* Add a picture to your template
* Manage template options for your surveys and survey groups

<hr/>

LimeSurvey 3 introduces a complete new template engine system, based on Twig 1.29, Bootstrap, and allowing template inheritance and template options. It completely removes the old replacement keywords system. So now, 100% of the frontend HTML can be customized. For example, in the old template system, there was a keyword {ASSESSMENTS} that was replaced by the assessment HTML at execution time. A template designer had no way to customize this HTML (other than using JavaScript). Now, there is a file called assessments.twig that contains the logic (written in Twig) to generate this HTML. In these pages, we will give you some explanation about how to use this new template engine.

<div class="simplebox">[[File:help.png]] We will not detail here how Twig works. It’s kind of very simplified PHP that offers a high level of security thanks to the “sandbox” system (we’ll see that in more detail in the part about the Template Engine Core code). If you already know PHP, it will be extremely easy for you to master. If you don’t know PHP, it still should be pretty easy to learn. Please, have a look to the Twig 1.X documentation:
https://twig.symfony.com/ </div>

=Editing Using the Admin Interface=
==Template list==
On the admin dashboard, there is now a box to access the template list:
[[File:Template list.jpg|thumb|800px|center|baseline|border|''The template list after a fresh install of RC3'']]
<br />
The list is divided in 5 columns:
* a preview of the template: it’s just a picture file called “preview.png” at the root of the template
* the “name” of the template: the directory name of the template. Before we release the LS3 master, it will become the template “Title” (can be different from directory name, and it can contain special cgunnarhars)
* the description of the template: a string set in its manifest
* the type of template: Core template (provided with LimeSurvey), User template (added in upload directory), XML template (not loaded in database)
* Extends: if the template extends another template, its name will be indicated here
* Some action buttons:
** Install: it will load the manifest of a template to add it to database and make it available for selection at the survey level
** Uninstall: it will delete the configuration entries of a template in the database
** Template editor: it will redirect you to the template editor
** Template option: it will lead you the global configuration of template options

==Template Editor==
<div class="simplebox">[[File:help.png]] This documentation supposes you already know how to use the Template Editor in the previous version of LS. </div>
<br>
The Template Editor has been kept as close as possible to the original one. So, when you open a Core Template, you can’t edit it. But now, instead of a “copy” button, you have an “extend button”.
<br>
[[File:Extends default.png|center|baseline|border|''Now you '''extend''' template'']]

====A quick overview of the concept of template inheritance====

In LS3, a template can now inherit from another template, it can “extend” another template. This means that the template directory will be practically empty, it will only contain the files (views, style sheets, scripts, resources etc.) that differ from the original ones. Doing so, it will be easy for you to create a fleet of templates for your different users without having to maintain a lot of different templates. For example: you can have your own home-made template, and then a version for a company (with its logo, its style, maybe a link to its website on the footer etc.), another version for another company etc. If then you update the CSS or the global layout of your custom template, all the templates that inherit from it will be updated automatically. Note that the inheritance is recursive: a template can extend a template that extends another one etc.

<div class="simplebox">[[File:help.png]] It also means that if you extend one of the core templates of LimeSurvey, you will still benefit from its updates.</div>

====Novelties in the user interface====

To extend the Monochrome template of LimeSurvey, go to the Template list, click on the button “Template Editor” of the Monochrome template. Then, click on “extend” and validate the new name “extends_monochrome”.

If you now go to the upload directory (with your file/ftp client), you’ll see that a new directory has been created: '''upload/templates/extends_monochrome'''
It contains an XML file and directories, but most directories are empty. It has neither views nor CSS nor JS. But, you can still select this template as a normal one from a survey and it will look exactly like the monochrome template.

[[File:Extends monochrome empty.jpg|center|baseline|border|''The template tree (directory and files) just after its creation. It's practically empty'']]

<div class="simplebox">[[File:help.png]] The ressources (jpg, png etc.) from the original template are copied when extending a template. This is because if you copy a CSS file from the original template locally, and if it refers to those files (like in background-image statement), it will need to find those pictures in the current template path. </div>

The template editor for the extends_monochrome template looks like that:
[[File:Editing extends monochrome.jpg|center|baseline|border|'' Editing extends_monochrome template'']]
<br /><br />
There is no big difference with the old template editor. Let’s list the main ones:
<br />
* The keyword '''inherited''' on the file list. It means that the file is not present in the template directory and that the file from the original template will be used.
[[File:Inherited.jpg|center]]
<br>
* The main editor ( [https://ace.c9.io ACE editor ] ) shows the content of the selected file. The files not only contain HTML, CSS or JS, but also Twig statements. Those Twig statements give us the possibility to push some logic to template views that were located deep in the core before, and that now can be customized.
[[File:Twig code in editor.jpg|center|''Some twig code, for Survey List'']]
<br>
* This is why you have more screen types available in the dropdown selector of the top menu now. You’ll notice pages such as ‘Survey List’, ‘Load’, ‘Save’, ‘Error’, ‘Registration’, ‘Assessments’, ‘Print Answers’ that weren’t available before, or that you couldn’t really be customized before.
[[File:Newscreens editables.jpg|195px|center|''Now, you can customize all screens'']]
<br />
* The ‘tip’ link at the bottom of the file list gives you the Twig way to add a picture in your HTML
[[File:Tip picture.png|605px|center]]
<br />
* The button ‘save changes’ becomes a button '''Copy to local template and save changes'''
[[File:Copytolocal.png|360px|center]]

====Quick example: adding a picture ====

The button '''Copy to local template and save changes''' will do exactly what it says: if you edit anything inside the file and then click on that button, it will copy the file to the template you’re editing, and save your changes.
<br>
For example: click on the file layout_global.twig, then just before the block content ( {% block content %}) add the text “TEST” and click the button. You can see that the label of the file changed from “inherited” to “local” and now the button is a simple button '''save changes'''.
[[File:After edition.png|center|''just after clicking on the button ''' Copy to local template and save changes ''''|]]
<br>
If you open a file explorer and go to the directory upload/templates/extends_monochrome/views/, you will see that it contains only one file, the file layout_global.twig and that the string “TEST” is there.
[[File:Tree with layout global arrow.png|center|''Now the file is present in your template'']]
<br><br>
Now instead of addind a random text, we will add a picture. If you click on the tip link, it will tell you:
<br>
To use a picture in a .twig file:
'''{{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}'''
<br>
If you have read the Twig documentation (and you should have done so at this point), you know that '''{{ function( ) }}<nowiki />''' will echo the result of a function on screen. Here, the function is image( ).

<div class="simplebox">[[File:help.png]] If you’re curious to know what it does, you can find it in the code here (version of RC3): [https://github.com/LimeSurvey/LimeSurvey/blob/f3737a75e428f604d68d2e5ba958f3eba3eba2e1/application/core/LS_Twig_Extension.php#L219-L237 image() function in RC3]
If you don’t understand the code: don’t worry, you don’t need to know how it works, but why to use it and how to use it.
</div>
<br>
You should use the function image() for two reasons:
* The function image loops through the template to find the image. If the template you’re working on is extended to another template, and if you copy the file to where you inserted the picture locally, but that picture is not copied in the local template, it will loop through the template inheritance tree to find where that picture is.
* It will use the asset manager, so it will improve the performance of your template. See the Yii Asset Manager documentation for more information about it: http://www.yiiframework.com/wiki/148/understanding-assets/

<div class="simplebox">
So, to add a picture to your template:
* just upload it as usual with the file uploader on the right and then add it to where you want it in any twig file:
'''{{ image('./files/myfile.png') }}'''

* If you want to add an alternate text for your picture (for screen readers and HTML validation), add:
{{ image('./files/myfile.png'), ''' ‘my alternative text’ ''' }}

* If you want to add a class attribute and add an id to it:
{{ image('./files/myfile.png'), ‘my alternative text’, ''' {“class”: “a_nice_css_class”, “id”: “any_id”} ''' }}
</div>

====Some things on our TO-DO list====
* Give users the possibility to upload a custom preview file from the editor itself
* Add a button to delete the local file and return to the inherited statement
* Only copy the picture used in the CSS files (by listing them in the manifest as file to copy)
* Remind which template the current one extends (if any)

==Template options==
Another novelty of LS3 is the template option page. As we’ll see later, template creators can create their own options and even their own admin option page. Here, we’ll quickly see how the option page of the Core Templates work. To access the template options at global level: click on “template options” in the template list
====Advanced options====

{{QS:Theme editor - advanced options}}

====Simple options====

The Simple option page comes from the Template itself. It’s made via a twig file and some javascript inside the template/options/ directory:
https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options
<div class="simplebox">[[File:help.png]] This page can be completely different from a template to another, and template providers are strongly encouraged to create their own look & feel. </div>

[[File:Options.png|thumb|750px|center]]
<br><br>
The simple option page simply fills in the advanced form inputs. You can see it by turning on or off a setting in the simple page, and see how the related input in the advanced form is modified accordingly. For example, in Default Template’s simple options,, if you change the Bootswatch theme to “Darkly” and then click on the tab for advanced options (even without saving) you’ll see that the field “Cssframework Css” changed from

{"replace": [["css/bootstrap.css","css/flatly.css"]]}<br>
to<br>
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
<br>
Here are the different simple options for the Core templates:
*'''Ajax mode:''' Should the next page be loaded via ajax (faster) or via page reload (better for debugging purpose)
*'''Background image:''' if set to Yes, the image called pattern.png will be loaded (will be replaced by a file selector in Master)
*'''Box container:''' if set to No, the questions will not be contained in a box (so you can use large arrays bigger than the screen width)
*'''Brandlogo:''' if set to no, the name of the survey will be shown in top bar, else, you can select one of the pictures inside the file directory to be used as logo picture.
*'''Animate body:''' if set to yes, you can choose one of the animations to apply when the body of the survey is loaded
*'''Animate question:''' same with questions
*'''Animate alerts:''' same with alerts
*'''Bootstrap theme:''' here, you can choose a Bootstrap theme to load. They come from Bootswatch https://bootswatch.com/3/
<br>
The library used for animations is animate.css: https://daneden.github.io/animate.css/
Of course, a template provider could add his own animation library or no animation library at all.

<div class="simplebox">[[File:help.png]] The monochrome templates use the same bootstrap color theme as the admin user interface. They’re not using the css framework replacement system, but simply add a CSS file. So, it illustrates another way to deal with custom themes for template providers.</div>

====Inheritance system====

In the previous part, we’ve seen that a template can extend another template. A template configuration can also inherit from another template configuration. It means that for a given template, you can have a configuration at

* global level (the one we’ve just seen accessible from the template list)
* at survey group level
* a last one at survey level.

Each parameter at a certain level can inherit from the upper level: survey group inheritance. First, let’s see the survey group level.

======At survey group level======

Indeed, one of the other great novelties of LS3 is the survey group system. You can now create different groups to organize your surveys. To access it, go to the survey list and then click on the survey group tab:
[[File:Surveygroup.png|thumb|800px|center|''The survey groups tab'']]
<br>
In this list, you have two action buttons. If the group is empty, you can delete it. Else, you can always edit it. By clicking on the edit button, you reach the Survey Group configuration page:
[[File:Surveygroupedit.png|thumb|800px|center|''Editing Default Survey Group'']]
<br>
The third tab of this page is called “Template options for this survey group”. If you click on it, you’ll see the same list of templates than in the template list, except that here only the option button is visible (template editor can be reached only from the main list).
<br>
Now, if you click on the option for Default Template, you’ll see this:
[[File:Option group inherit.png|thumb|800px|center|''At Survey Group, Template Options are inherited by default'']]
<br>
* '''Inherit everything''' means that all the configuration will be inherited from the Global configuration level.
* If you go to the '''advanced options page''', you’ll see that all the fields are set to inherit.
* If you click on "no" for "Inherit everything" in the simple options, you’ll again see a very similar page to the global option page. The only difference is that for each field, you can set it to yes, no, or inherit; and each dropdown selector has an ''inherit''' value.
[[File:Inherit group.png|thumb|800px|center|''Each setting can have a inherited value'']]

<div class="simplebox">[[File:help.png]] A survey group can be a child of another group. In this case, it will inherit from its parent.</div>

======At survey level======
When editing a survey, in the left bar menu, you’ll see a new entry “Template Options”. It will lead you to the option page of the Template selected for the current survey. You’ll find the same inheritance system as in the survey group, but this time, inherit means that the setting will be inherited from the Survey Group of the survey.
[[File:Options survey.png|thumb|800px|center|''Template Options at Survey Level'']]

==Use case example==
Let’s say you’re using a single template for different companies (A and B). You set your favorites options at global level (e.g.: ajax on, animate body with a slide in, alerts with a pulse). Then you create a survey group for each company: a survey group for company A that will host all the surveys for this company, and a survey for company B that will host all the surveys for company B. At this level, you’ll set the logo and the background only, and you will let the other options to inherit. So, all the surveys in group A will use the logo from the company A, and all the survey from group B the logo from company B. For one of the surveys of company A, you could use a different background in relation with the topic of the survey: you just change the background in options at survey level. If someone in company B tells you that the pulsing alert is too aggressive and he would prefer something smoother like a fade in, you just change the alert animation at the Survey Group B level and all the surveys of this group will now use this animation. If the company A changes its logo, you can change it at the level of Survey Group A, and all the surveys of this group will use the new logo.
<br>
<div class="simplebox">Those examples are based on the current options of the core template. But of course, if you are a template provider, or if you’re able to script a bit with twig, you can add your own options. For example, you could add an option “info footer” where you could add data like the company website or a phone number for help. Then, if company A has different departments, with different phone numbers, you can just create one sub-group for each department in Survey Group A. Each subgroup will have its own phone number in these options.</div>

= FAQ about theme customization =

You'll find here some answers to questions that have been asked in the forum and that could help you to customize your theme.

==Customizing CSS: deal with the asset manager ("why my changes are not applied?") ==
<br />

If you're trying to update the CSS of a theme by directly editing the code with your favorite editor, you could be surprised that your changes are not applied.

<br />

Since 2.50, LS use the Yii asset manager:
[http://www.yiiframework.com/wiki/148/understanding-assets/ Yii Documentation about Assets]
<br />

It moves the CSS files of a theme to a tmp/ sub-directory with a random string (eg: "tmp/1ef64ml/"). So if you make any change to a css file, and tell it to the asset manager, the files are copied to a new sub-directory with a new name so the user browser's cache is updated and they see the new css. Else, they would have to clean their browser cache.

<br />

Here the CSS links in header when asset manager is on:
<br />
[[File:Assets on vanilla.jpg]]
<br />As you can see they all refer to the tmp/ subfolders.

<br />

Here the CSS links in header when asset manager is on:
<br />
[[File:Asset off.png]]
<br />As you can see they point to the real files of the theme.

<br />

<div class="simplebox">[[File:help.png]] Of course, if the Asset Manager doesn't know you changed the file, the old file from the old tmp/directory remain unchanged, and your changes will never be applied..</div>

So, when you're editing CSS of a theme you have various possibilities:
*'''You can use the the LS Theme Editor:''' it deals with the asset manager and you don't have to worry about anything
*'''You can turn debug mode on:''' it will turn asset manager off, so the real css/js files of your themes are called (but then, you have to refresh your browser cache at each load)
* '''You can change the asset version number''': it will efresh all the tmp directories ( increase or decrease) [https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/application/config/version.php#L19 asset version number in 3.0.4]

<div class="simplebox">[[File:help.png]] '''Using the theme editor to edit the custom CSS is by far the best solution.''' </div>

Using the theme editor will help you to understand the architecture of the new theme engine.
Also, if your customizing fruity, be careful with CSS specifity: most of the definitions use the selector ".fruity" (one of the class of the body element)

== Adding custom fonts to my theme ==
=== The easy way: using Google Font CDN ===
Bootswatch Survey Theme uses Google Font CDN. Let's have a look to how ti works:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css

<syntaxhighlight lang="css" enclose="div">
@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");
</syntaxhighlight>

Then the Lato font is used via CSS rules:
https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72
<syntaxhighlight lang="css" enclose="div">
body {
...
font-family: "Lato";
...
}
</syntaxhighlight>

You can use any google font that way in your custom theme. Of course, you should remove the font selector from the options of your theme. Delete those lines in options.twig:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

=== Using local font ===
Of course, you can also download the font files and use them from local server rather than from Google CDN (better for privacy). To have an example of how to it, here our local version of noto font:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
font-weight: 300;
font-style: normal;
src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...
</syntaxhighlight>

You can use a very similar definition in your theme css file, and then by copying the file NotoSans-Regular.ttf in your theme css/font-src/ folder.

Then, apply that font to your body (or any other element) like above, and remove the default option font selector.

=== Creating your own font selector in options ===
For now, you can't easily use the core font selector to add your own font in options. We need first to give the possibility to end user to upload custom packages (see next paragraph: A look into the Fruity Font Selector )
<br>
Here how to proceed:
<br>
*Add two fonts (my_custom_font and my_custom_other_font) into your theme, using CDN or local server
*Then, in your css file, add two new classes:
<br>
<syntaxhighlight lang="css" enclose="div">
.font-my_custom_font {
font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
font-family: 'my_custom_other_font';
}
</syntaxhighlight>
*In the XML file of your theme, add a font option (default one will be my_custom_font) :
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>my_custom_font</font>
</options>
</syntaxhighlight>

* in option.twig, add you font picker adding those lines (untested for now, so come complain to the forum if it doesn't work):
<syntaxhighlight lang="html" enclose="div">

<div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
<hr/>
</div>
<div class='row action_hide_on_inherit'>
<div class='col-sm-12'>
<div class='panel panel-default'>
<div class='panel-heading'>{{ "My custom fonts" | t }}</div>
<div class='panel-body'>
<div class='form-group row'>
<label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
<div class='col-sm-12'>
<select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
{% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %}
{% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
{% endif %}
<optgroup label="{{ "My Custom fonts" | t }}">
<option class="font-my_custom_font" value="custom_font" data-font-package="" >Custom</option>
<option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package="" >Other</option>
</optgroup>

</select>
</div>
</div>
</div>
</div>
</div>
</div>
</syntaxhighlight>

<br>
Now your users should be able to choose between those two fonts.

=== A look into the Fruity Font Selector ===
In the future, we'll give the possibility to final user to upload their own asset packages, including font packages. It will make very easy any customization of fonts.
<br>
To understand Yii Packages:
<br>
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail
<br>
<br>
LimeSurvey packages are defined in different files. Fonts packages are defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
<br>
For example, the Noto font package is defined here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53
<br>
<syntaxhighlight lang="php" enclose="div">

'font-noto' => array(
'devBaseUrl' => 'assets/fonts/',
'basePath' => 'fonts',
'css' => array(
'noto.css',
),
),
</syntaxhighlight>
<br>
The noto.css file it contains is here:
https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
<br>
Notice the definition of the css class ".font-noto" at the end of it:
<syntaxhighlight lang="css" enclose="div">
@font-face {
font-family: 'Noto Sans';
...
}
...
.font-noto{
font-family: 'Noto Sans';
}

</syntaxhighlight>
<br>
Then, in Vanilla Theme, noto font is used by adding the noto package and defining the font option to noto:
<br>
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79

<syntaxhighlight lang="xml" enclose="div">
<packages>
....
<add>font-noto</add>
</packages>
</syntaxhighlight >
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58
<br>
<syntaxhighlight lang="xml" enclose="div">
<options>
....
<font>noto</font>
</options>
</syntaxhighlight>
<br>
Then, the body class font is defined using this value:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76
<syntaxhighlight lang="html" enclose="div">
<body class=" ... font-{{ aSurveyInfo.options.font }} ... " ... >
</syntaxhighlight>

Of course, the XML file only contains the default values for your template configuration. But indeed, those values are defined and read inside the database (table "template_configuration") as json strings. The option.js file just use the value of the font selector of the simple option to change the value inside the advanced tab form:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174

So when the "upload asset package" functionality will be available, it will be easy to add a script that scan all the existing font packages to add them in the selector.

=Creating a template from scratch=
Documentation coming soon...

'''NOTE''': if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.

'''NOTE''': if you manually edit the CSS/JS files (without using the Teeme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache:"

</translate>