PHPSurveyor Templates & Style Guide
|
|
INDEX
|
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.
|