PHPS urveyor Templates & Style Guide

INDEX

- Introduction
- Location of Template Files
- Template Files
- Keywords
- CSS
- Other Template Files
- Specialties for Developers

Introduction

LimeSurvey uses a series of template files to create its public survey screens. The templating system used by LimeSurvey is relatively basic, but allows fairly comprehensive control over the look and style of your surveys.

The templates consist of standard HTML code, within which you can put keywords surrounded by curly-brackets that will be replaced during a survey with relevant text. The following gives an example of the method:

Template File
<center><font face='verdana' size='2'><b>{SURVEYNAME}</b></font><br /> <font face='verdana' size='1'><u><i>{SURVEYDESCRIPTION}</u></i></center>
Looks Like This
My New Survey This is a survey written by me to find out what sort of chocolate people like.

LimeSurvey comes with two templates, and we plan to make other templates by other people available.

These instructions may make the template files within LimeSurvey seem overly complex. You will probably find it easiest to create new template files by copying an existing template to a new directory, and then playing around with the files. It should start to make sense fairly quickly after that.

Location of Template Files

LimeSurvey expects templates to exist in their own distinct sub-directory within a templates directory that is kept in the public directory with the other LimeSurvey public files.

To create a new template, you should create a new directory in the templates directory and give the directory the name you want the template to be. So, for example, if the directory is called "Silly", that template will be called "Silly", and will be available in the admin scripts under that name.

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. The "default" directory comes with the package.

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 stanards, the LimeSurvey script needs to find a <body> tag, to run certain javascript elements. It is not expected that many 'keywords' will be 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, so 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 (ie: 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. It is separate to the startgroup.pstpl file because in a "question by question" survey it will be displayed on its own unique page in between groups, whereas in a "group by group" or "all in one" survey it provides a header to the subsequent questions. groupdescription.pstpl does not have a corresponding 'closing' template file, so all tags should be closed.
- question.pstpl
  This file contains the question, answer and help text sections of your survey, and 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.
- submit.pstpl (and privacy.pstpl)
  This page is the penultimate page for all types of survey (except the "all in one" type) where the participant is given an option to review questions before submitting their responses. It provides privacy information where a survey is anonymous, which it extracts from the privacy.pstpl file.
- 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.

Page Structure / Template Use

The Welcome Page:

startpage.pstpl
welcome.pstpl
navigator.pstpl
endpage.pstpl

The Questions Pages:

startpage.pstpl
survey.pstpl
startgroup.pstpl
groupdescription.pstpl
question.pstpl
endgroup.pstpl
navigator.pstpl
endpage.pstpl

The Submit Page:

startpage.pstpl
survey.pstpl
submit.pstpl (privacy.pstpl)
navigator.pstpl
endpage.pstpl

The Final Page:

startpage.pstpl
completed.pstpl
endpage.pstpl

KEYWORDS

Keywords are words within a template file that get replaced by survey information during a survey. The are all surrounded by curly brackets (like this: {SURVEYNAME}

Any keyword can be placed in any template file, although if the script has not yet developed the replacement text it will simply be removed and nothing will display in the survey. This means, for example, that it would be pointless to put the {QUESTION} keyword in the startpage.pstpl file, because the scripts will not yet have the question to put there.

The following table lists the keywords you can use, and the template files where they will work properly.

KEYWORD | TEMPLATE FILES | DESCRIPTION
{SURVEYNAME} | All files | The survey title
{SURVEYDESCRIPTION} | All files | The survey description
{PERCENTCOMPLETE} | survey.pstpl | A small graph showing the percentage of the survey completed
{WELCOME} | All files (mainly for welcome.pstpl) | The survey 'welcome' text
{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".
{GROUPNAME} | startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl | Displays the current group name
{GROUPDESCRIPTION} | startgroup.pstpl, groupdescription.pstpl, endgroup.pstpl | Displays the current group description
{QUESTION} | question.pstpl | Displays the current question text
{QUESTION_CODE} | question.pstpl | Displays the current question code
{ANSWER} | question.pstpl | Presents the answer form for the current question
{QUESTIONHELP} | question.pstpl | Displays help text for the current question
{NAVIGATOR} | navigator.pstpl | Displays navigation buttons (next, prev, last)
{CLEARALL} | All files (but intended for navigator.pstpl) | Displays the "Exit and Clear Results" link
{SUBMITBUTTON} | submit.pstpl | Displays the final submit button
{COMPLETED} | completed.pstpl | Displays the 'completed' message
{URL} | completed.pstpl | Displays the survey 'url' and 'url text'
{PRIVACY} | submit.pstpl | Displays privacy information when survey is anonymous
{TEMPLATEURL} | All files | Replaces with the http URL location of your template files. Use this of insertion of graphics into your template. ie: instead of: <img src='http://your.domain.com/surveyor/templates/mytemplate/me.jpg'> you could put <img src='{TEMPLATEURL}me.jpg'> Note that the replacement string includes the trailing slash.
{SAVE} | All files (but intended for 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.

CSS / Cascading Style Sheets

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)
- 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 (these are set by relevant section above) but does allow changing of background colour, text colour and 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 colour is the same as you have used elsewhere as a default)
- 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 colour for these question types. Array 1 is also used for the column headings in these question types.
- errormandatory sets the colour and style of the "This question is mandatory" error message.

An example of using these classes with style sheets can be found in the "bubblegum" template that comes with the package.

Of course, because you can edit all the other HTML aspects, there's no reason why you should surround various parts of your template with a <div class='scarey'> and then set your own css with that.

Other Template Files

The chart.jpg file is a simple 1pixel image file which is used to create the progress bar image in the 'PERCENTCOMPLETE' table. If it does not exist, LimeSurvey will use the default 'maroon' coloured image in the public directory, however if you want to create one to match your own colour scheme (which would make sense really), then you should save it here. Remember it should be a jpeg file, and 1 pixel x 1 pixel, in whichever colour you want.

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.

Specialties for Developers
Starting with version 0.99 LimeSurvey has integrated some user-made patches, which will be described here.
Basic CMS Integration support
To be able to integrate LimeSurvey into another CMS use the following options in config.php:
// Set $embedded to true and specify the header and footer functions if the survey is to be displayed embedded in a CMS
$embedded = false;
$embedded_inc = ""; // path to the header to include if any
$embedded_headerfunc = ""; // e.g. COM_siteHeader for geeklog
$embedded_footerfunc = ""; // e.g. COM_siteFooter for geeklog
Set $embedded to true to enable CMS-embedding. By using the $embedded_inc variable you can include own php files.
By setting $embedded_headerfunc oder $embedded_footerfunc you can call functions from your included files that output the according headers or footers instead of LimeSurveys own ones.
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 tie in any custom code.
This call was replaced with a small JS function in the HEAD that sniffs for the existence of checkconditions() and template_onload() before calling each.
This way a template author can create his/her own template_onload() function in the HEAD.