Templates
The Survox template files allow programmers to control the layout for all pages of their web surveys by displaying several external files. Templates are used as a framework for web pages where survey questions or status screens will appear. webSurvent clients typically build sets of these templates, or themes, with different layouts, colors, and branding. By providing most of the survey’s aesthetics in these themes, programmers can keep actual specs clean of these types of HTML elements, and focus primarily on question formatting.
How do templates work?
A template (or theme) directory is specified on the index page of every web study, via a hidden TMPL_DIR input. The .tmpl files located in that directory are used to frame every page of the web survey, as well as format the splash page for completes, terminates, and suspends. If a study requires custom template files in addition to the default files, they can also be placed in the project’s study directory, specified with the hidden input STUDY_DIR. A template file located in the study directory will always override the TMPL_DIR directory. Studies that require custom javascripts or panel company redirects typically make use of this feature.
Create new themes for Webutil/Wcatutil
For Webutil, create a subdirectory in the following locations with the name of your new theme:
/$CFMC/websurv/tmpl/themes/ /$CFMC/websurv/archive/themes/
For Wcatutil, create a subdirectory in the following location:
/$CFMC/websurv/tmpl/WC_themes/ /$CFMC/websurv/archive/WC_themes/
The TMPL directory holds the default templates for your new theme. Besides the pagetop.tmpl, all template files should be placed in this directory. The Webutil / Wcatutil scripts do not manipulate files in this directory.
The ARCHIVE directory holds the actual files copied by Webutil / Wcatutil. Two additional subdirectories, /html/ and /tmpl/ also must be created within your theme directory:
The HTML directory will hold indexp.html, indexnp.html, and retired.html for webSurvent and indexnp.html for webCati. These pages are the template files for a closed study (indexp), an open/webCati study (indexnp), and a placeholder page that is used when a study is taken down (retired).
The TMPL directory is for tmpl files that may be edited by Wcatutil:
-
pagetop.tmpl (unique for each study, required)
When running Webutil / Wcatutil, the above files are modified depending on placeholders that must be present. Placeholders are upper-case, and begin and end with an underscore:
-
_TITLE_ – Title of the study, piped into index.html and pagetop.tmpl
-
_WEBVARS_ – Hidden Survox variables used in the index page to configure study
-
_MAILTO_ – Contact name and e-mail address, used in some themes to display email anchor element
-
_STUDYCODE_ – The study code for the survey, useful in email link to determine respondent’s study
Once you have all of the appropriate files in place, you will be able to select this new theme when running the Webutil / Wcatutil scripts, and the index and templates will be used for your study. To provide a description of your new theme, add a description.txt file to the theme directory under /archive/ with a text description, and it will appear in the list of available themes, like below:
Please choose from the following themes: 01. WC_Blue: Blue and white webCati theme, designed after the Survox Services webSurvent 'theme 9'. 02. Client1: This is the new client theme I just created. Enter corresponding number or press Enter for default (WC_default)
All other related web files, such as javascript or stylesheets to determine theme formatting, must be uploaded to the Apache web area. Permissions on web files must be world readable or the files will be inaccessible from a browser.