Create A Theme

Use the Create A Theme feature to apply your own custom theme to your online or phone project. After creating your own theme, you can use the Select A Theme feature to upload and apply your newly created theme to your questionnaire.

You can now upload a theme for an environment regardless of the interviewing mode.

Creating a Default Shop Theme

You can create a default shop theme for all of studies. This will be applied automatically without having to Select a Theme for each study. Upon uploading your theme, name it User_default.

Make sure you name it specifically User_default and case does matter.

Placeholders vs. Html Defines

Placeholders are used by the Create A Theme and Select A Theme functions to allow the console to replace elements in the index and template files with other information. Required placeholders can be found in each individual html/tmpl file. HTML defines are used to both control behavior in the tmpl files and to present information in them. HyperText Markup Language or HTML defines are controlled from the .QPX file.

Placeholders are written in CAPS, separated by underscores and contain an underscore both before and after the placeholder.

_THIS_IS_A_PLACEHOLDER_

Placeholders checks are all case sensitive

For example, the MAILTO input tag value in the index page is passed to the tmpl files through the cgi and then used to fill in the define @mailto. However, specifying the email with its proper placeholder _MAILTO_ in the index page, allows the console function “Create Index” to modify its value on a study basis.

You may need to add specific placeholders to each of the tmpl and index files you upload in Create A Theme.

CSS Files

If the script does not detect any css file in the index or pagetop files, a warning will be issued. Any relative or absolute pathing will be retained. The only time the console will replace a path is when there is only file name without any type of pathing attached.

The following code will not be changed: background:#f4f4ed url(../images/silver-left.jpg) repeat-y;

The following code will be changed:

FROM: background:#f4f4ed url(silver-left.jpg) repeat-y;

TO: background:#f4f4ed url(/acme/themes/sstone/silver-left.jpg) repeat-y;

The path inserted is relative to the environment and the theme name.

Links that start with “http:” or “/” will be preserved:

background:#eee url(http://wiki.survoxinc.com/cfmc/pub/themes/triad/images/blue-100-foot.jpg) repeat-x;

Logo Images

The script will enforce a logo tag on the index and pagetop pages. The logo is changed from the modify index screen. A div with id logo and an img tag with id logoimg is needed. The same rules for the paths apply for logo images.

This uses style=”display:none” to hide the image; the src property has an empty value. This will have the effect of no logo being displayed, unless selected in modify index.

The first has a full path to an image and the div is not hidden. The path will not be changed.

The second has a relative path to an image. The path will not be changed.

The third has no path at all just the image file name. The path will be inserted by create a theme.

In this case, if no image is selected in create index, then the theme will use this image by default.
For report themes the logo must be named logo_reports.jpg/png/gif.

Image Files

If the script finds other image tags it will apply the same rule that applies to css link tags: if there is a relative or absolute path or the path starts with “/” the pathing will not be changed. If it is a simple path, then the console will change it to the correct path.

All images uploaded to be used in a look need to have the correct links and paths in the indexp, indexnp and pagetop.tmpl. These links are the actual console links where the images will reside. Supporting images, if any, are used throughout your web pages or css file.

Custom Theme Files

There is no differentiation between online and phone. All uploaded files must contain files for both webSurvent and webCATI. The following files are always required. Even if you just want to update one file for a specific theme you already created, you still need to upload all required files again.

Required Files

File	Description
indexnp.html	Index file presented at the start of the webSurvent survey (without password entry).
indexp.html	Index file presented at the start of the webSurvent survey (with password entry).
indexwc.html	Index file presented at the start of the webCATI survey.
buttons.tmpl	Includes the buttons that appear on the bottom of the survey.
complete.tmpl	Thanks respondents and tells them the interview is completed.
error.tmpl	Tells respondents that an error has occurred.
pagebtm.tmpl	Information that appears on the bottom of each interviewer page. Such information can include graphic images or text such as: email contact and the status bar so the respondent knows their progress.
pagetop.tmpl	Information that appears on the top of each interviewer page. Such information can include graphic images or text such as: logos, images, fonts or backgrounds. You can also assign JavaScript designation to be executed for every question.
qprompt.tmpl	Information that appears between each interview. Such information includes: Start Interview, Quit Interview, Go on Lunch, Go on Break and Go on Meeting. WebCATI ONLY.
suspend.tmpl	Tells respondents that the interview has been suspended, provides a username and password so they can come back in the future to finish it.
terminat.tmpl	Tells respondents that the interview has been terminated.

Optional Files

File	Description
help.html	A pop up HTML page with survey instructions.
retired.html	Disallows new respondents from getting into the study. When a study is retired, this file replaces the index.html letting the respondent know that the survey has been discontinued and completed.
submit_timers.tmpl	Allows you to pass a time in seconds to the page through the use of a DISPLAY,KEYBOARD_WAIT, DISPLAY,TIMED_WAIT, SPECIAL,PAUSE or SPECIAL,FILL_NEXT_QUESTION_IF_IDLE type question. When that time has expired, the page is automatically submitted.
<filename>.css	Cascading Style Sheet used to format the layout of your web pages.
Image Files	Supporting images, if any, used throughout your web pages.

Template Placeholders

BUTTONS.TMPL

The buttons.tmpl file includes the buttons that appear on the bottom of the survey and allows the respondent to navigate through the survey. Typical buttons include: next, previous and suspend. The only input that is required is the input for the next button. For any other buttons you will get warnings if they are missing but those buttons are optional.

There are no placeholders that need to be added to buttons.tmpl. The buttons should look like a standard submit button.

ALL BUTTON INPUTS MUST HAVE “ID=” ON THEM. If the ID= is missing, you will receive errors!

You may need to add a </div> as the last line of the template depending on what theme you are using.

Example:

</div>

COMPLETE.TMPL
The complete.tmpl thanks respondents and tells them the interview is completed and they may return to their browser. The placeholder _COMPLETE_FORM_ is required for the complete.tmpl file. The MAILTO structure is optional using HTML defines.

Placeholder

Placeholder	Description
_COMPLETE_FORM_	The script will substitute complete_form

Change:
<form name=”complete_form”>
<input type=”hidden” name=”comp” value=”true” />
</form>

To: _COMPLETE_FORM_

ERROR.TMPL
The error.tmpl tells respondents that an error has occurred and displays error numbers and text. The ERROR CODE and ERROR TEXT should use HTML defines. The MAILTO structure is optional using HTML defines.

In the error.tmpl, there needs to be a path set to point to the CSS that is being used. The CSS reference is typically placed within the <head> tags at the top of the page.

CSS Example:

PAGEBTM.TMPL
The pagebtm.tmpl contains information that appears on the bottom of each interviewer page. Such information can include graphic images or text such as: email contact and the status bar so the respondent knows their progress. The placeholder _STATBAR_ is required if you want the status bar to appear and function properly. Keep in mind, the console uses CSS based statbars by default. If you want to use image based statbars then you will need to modify your user_settings.js for every study. The status bar can be placed in the pagebtm.tmpl or the pagetop.tmpl or both. The MAILTO structure is optional using HTML defines.

Placeholder:

Placeholder	Description
_STATBAR_	Status Bar. In order to work, this has to be defined either in pagetop.tmpl or pagebtm.tmpl or both. If not found in either, an error will be produced. This is necessary for the status bar to work.

_STATBAR_

Change:

</form>

To: _STATBAR_

PAGETOP.TMPL
The pagetop.tmpl contains information that appears on the top of each interviewer page. Such information can include graphic images or text such as: logos, images, fonts or backgrounds. You can also assign JavaScript designation to be executed for every question. For proper detection of the mode being used by the Survox javascripts, you need to add a span id for the mode. This is typically placed at the bottom of the pagetop.tmpl file.

Span Id Example:
<span id=“websurvent”></span\>
<span id=“webcati”></span\>

In addition, the placeholder _STATBAR_ is required if you want the status bar to appear and function properly. Keep in mind, the console uses CSS based statbars by default. If you want to use image based statbars then you will need to modify your user_settings.js for every study. The status bar can be placed in the pagebtm.tmpl or the pagetop.tmpl or both. By default the title is the project name of the project. If you want to use a different title, it can be changed on the Modify Index Page.

In the pagetop.tmpl, there needs to be a path set to point to the CSS that is being used. If you are using a Logo, you also need to add a link to the logo image.

CSS and Logo Example:

Placeholders

Placeholder	Description
_TITLE_	This is placed inside the <title></title> tags and will be managed by Create/Modify Index.
_STATBAR_	Status Bar. In order to work, this has to be defined either in pagetop.tmpl or pagebtm.tmpl or both. If not found in either, an error will be produced. This placeholder is necessary for the status bar to work.

_TITLE_

Change:

<title>Your title here</title>

To: <title>_TITLE_</title>

_STATBAR_

Change:

</form>

To:

_STATBAR_

QPROMPT.TMPL (WebCATI ONLY)
The qprompt.tmpl is accessed in-between interviews and contains information that appears between each interview. Such information includes: Start Interview, Quit Interview, Go on Lunch, Go on Break and Go on Meeting. No placeholders are required for the qprompt.tmpl file.

SUSPEND.TMPL
The suspend.tmpl is accessed when a respondent suspends a survey to be completed at another time. The suspend.tmpl can provide a URL, username, studycode and password so they can come back to the survey another time to finish it. Either the placeholder _SUSPEND_FORM_ or the HTML for the form is required for the suspend.tmpl. The CFMCLOGIN_FORM should be in place as an HTML define if you want the users to be able to immediately resume a survey from the suspend page. The URL, Name, Studycode and Password structure are all optional HTML defines.

Placeholders

Placeholder	Description
_SUSPEND_FORM_	The script will substitute the suspend form.

_SUSPEND_FORM_

Change:

</form>

To: _SUSPEND_FORM_

TERMINAT.TMPL
The terminat.tmpl gets accessed when the respondent screens out of the survey. The placeholder _TERMINAT_FORM_ is required for the terminat.tmpl file. Mailto structure is optional using HTML defines.

Placeholders

Placeholder	Description
_TERMINAT_FORM_	The Script will substitute the terminate form.

_TERMINAT_FORM_

Change:

</form>

To: _TERMINAT_FORM_

Index HTML Placeholders

INDEXP.HTML/INDEXNP.HTML/INDEXWC.HTML
The Index file is presented at the start of the survey. When creating a theme, indexp.html is used for a webSurvent study using passwords, indexnp.html is used for a webSurvent study using no passwords, and indexwc.html is used for a webCATI study. Whichever file you use, it will automatically be converted to an index.html file during the create a theme process. By default the title is the project name of the project. If you want to use a different title it can be changed on the Modify Index Page. The MAILTO structure should use placeholders.

In the index files, there needs to be a path set to point to the CSS that is being used. If you are using a Logo, you should use a filename unless you specifically want to reference a logo that has not been uploaded with the theme.

CSS and LOGO Example:

<title>_TITLE_</title>

Placeholders

Placeholder	Description
_TITLE_	This is placed inside the <title></title> tags and will be managed by the Create/Modify Index Page.
_CGINAME_	This is to get the correct cgi for the environment.
_WEBVARS_	The script will replace with your web variables.
_MAILTO_	If found, the script will substitute @mailto. (optional)
_STUDYCODE_	If found, the script will substitute @studycode. (optional)
_PM_	The script will replace with the name of your Project Manager (when the study is created)

_TITLE_

Change:

<title>Your title here</title>

To: <title>_TITLE_</title>

_CGINAME_

Change:

To: <form name=”cfmclogin” method=”post” action=”_CGINAME_” />

_WEBVARS_

Change:

To: _WEBVARS_

_MAILTO_ and _STUDYCODE_ and _PM_

Change:

If you have any questions or problems, please contact _PM_ by e-mail at: <br>

<a href=”mailto: support@invite.survoxinc.com?subject=online10 index”>Questions/Comments?</a>

To:

If you have any questions or problems, please contact _PM_ by e-mail at: <br>

<a href=”MAILTO:_MAILTO_?subject=_STUDYCODE_Index”> Questions/Comments? <span id=”pm”> _PM_ </span></a><br/>

Downloading Files Through Create A Theme

Click on the Project Setup Tab
Click Modify Web Options
Click Create A Theme
Select an environment from the drop down menu
1. This step is essential as looks are applied to environments
Select the theme to download/modify in the Select a Theme drop down menu
Click the “Download Theme” button to download the zipped file
Modify files as needed

Uploading Files Through Create a Theme

After the tmpl and html files have been modified, you are now ready to upload your files as a new theme or overwrite an existing custom theme. During the upload process, the console will read the files to make sure the proper formatting has been included for each tmpl or html file. If a placeholder is missing, specific errors will appear on the screen and the upload will be aborted.

You cannot overwrite one of the default themes.

Click on the Project Setup Tab
Click Modify Web Options
Click Create A Theme
Select an environment from the drop down menu
1. This step is essential as looks are applied to environments
Type in a new name for your theme in the New Theme text box if you are uploading for the first time
Select an existing theme to overwrite and update from the Update Existing drop down menu
Browse to the zipped file to upload
1. When naming your theme, there CANNOT be spaces in the names. These will get converted to underscores
Click on the “Upload Files(s)” button to upload the zipped file as a new theme or overwrite an existing theme
Your results will appear on the screen. If errors are produced, repeat after making your corrections.

Uploading Multiple File Formats

The following formats are supported for uploading:

.zip
.tar
.tgz
.tar.gz

Once uploaded, the console will properly extract and read the files for errors. When you download a theme file you will see a main directory with a css file, description.txt and image files. You will also see a subdirectory for html, wc_tmpl, and ws_tmpl.

When uploading a new theme the structure of the zip file must be the same.

When uploading a new theme, the name should be in lower-case.

Applying the Theme You Just Created

Now that you’ve edited and uploaded all of the necessary files, you can apply that theme to any existing or future study in the Survox Console. You can also apply that theme to the reports. You will be prompted for whether the theme is for a survey or reports. You will be able to define a User Default for all studies by simply creating a theme called User_Default.

Click on the Project Setup Tab
Click Modify Web Options
Click Select A Theme
Select a study from the drop down menu
Click “Go”
Your new theme will now be added to the standard themes that already exist
Choose your new theme
Click the “Select Theme” button

Creating Slide Show Images

Each standard theme in Select a Theme supports a slide show so you can get an idea of how that theme looks. When your new branding is added to the library of themes, it will appear without an image but you can easily incorporate a slide show of images associated with your newly created theme.

Create 3 to 4 images/screenshots of your new theme and save them as thumbnails with a gif/png/jpg file extension.

There are specific image naming conventions for slide show images for both the survey theme and reports and these are all optional:

Survey themes must have the following naming convention: <theme_name>_1, <theme_name>_2 etc. (Can be gif/png/jpg and need to be lowercase)
Report themes have the following naming conventions:
OnDemand.jpg
Verbatims.gif
WebTables.jpg
PhoneReport.jpg
QuotaReport.jpg
SessionReport.jpg
WebResponseReport.jpg

Then upload these files through Create A Theme. Your new images will appear along with your new branding in the list of themes. Also, make sure that your description.txt file is included to add a description of what your new theme is.

CSS Classes for Surveys

Whether you are using the composer to create your survey or uploading your own survey specifications, you can upload a custom CSS file to define your survey’s theme elements. However, Survox Console requires that you follow these simple rules:

Rules:

When using custom CSS with a console-composed survey, the class names below, must be used and cannot be altered
When using a custom survey spec file (e.g. not composed in the Console) and you want to use a default theme then these classes need to be used in your survey specifications (qpx)
A console-composed qpx can be edited to include classes in a custom CSS file, however new classes will not be recognized by the default themes included: a custom CSS will be required
If changes are made to a default theme, it is up to you to test those changes

Also note: The html cannot be changed in the Composer utility.

For Standard Screens
Class Name	Description
errorPrefix	Used for page and question specific errors
Example For Page Errors	<div class=“error”><div>
Example For Question Specific Errors	<span class=“error”></span><br/><br/>
Class Name	Description
qtext	Used to format the text of a question
Example	<div class=“qtext”></div><br/>
Note	Once the new code is in place users will be able to add html to the text inside of this div tag
Class Name	Description
qlabel	Used to format the response text of FLD and CAT questions
Example	<span class=“qlabel”></span><br/>
Class Name	Description
qcomment	Used to format comment responses for FLD and CAT questions
Example	<span class=“qcomment”></span><br/>
Class Name	Description
qnum	Format used to surround the input tags of NUMERIC type questions
Example	<span class=“qnum”></span><br/><br/>
Class Name	Description
qnumexp	Format used to surround the exception codes of NUMERIC questions
Example	<span class=“qnumexp”></span>
Class Name	Description
qvar	Format used to surround the inputs tags of VAR type questions
Example	<span class=“qvar”> </span><br/><br/>
Class Name	Description
qtex	Format used to surround the inputs tags of TEXT type questions
Example	<span class=“qtex”> </span><br/><br/>

For Attribute/Rating Lists
Class Name	Description
errorPrefix	Used for question specific errors
Example	<tr><td colspan=“6” class=“error”></td></tr>
Note	colspan= is set based on the scale being used
Class Name	Description
rating	Used for the entire html table
Example
	<table class=’rating’>
	<thead>
	<tr>
	<td rowspan=’2′> </td>
	<th>Strongly Disagree</th>
	<th>Disagree Somewhat</th>
	<th>Neither agree nor disagree</th>
	<th>Agree Somewhat</th>
	<th>Strongly Agree</th>
	</tr>
	</thead>
	<tbody>
	</table>
item	Used for the column that contains the text of the items being rated
Example	<td class=“item”></td>

For Constant Sum Screens
Class Name	Description
errorPrefix	Used for page and question specific errors
Example	<tr><td colspan=“2” class=“error”></td></tr>
Note	colspan= is set based on the number of columns needed
Class Name	Description
NumTable	Used for the entire html table
Example
	<table class=“NumTable”>
	<thead>
	<tr>
	<th> Attributes </th>
	<th> Percent </th>
	</tr>
	</thead>
	<tbody>
	</table>
Class Name	Description
item	Used for the column that contains the text of the items being rated
Example	<td class=“item”></td>

CSS Classes for Reports

You can upload a custom CSS file to define your report’s theme elements. However, the Survox Console requires you to follow a few simple rules:

Rules:

Place a file called NavReports.css in the main directory of the theme zip file.
The reports and tables created by the console use specific blocks of html with specific classes assigned to them. In order for a css file to work with these files, it must use the same classes and id’s.
Each page is contained in a div tag with an id named for that page. This allows the user to fine-tune control for specific reports.

Page ID	Description
SessionReport	For output of all Session Reports
PhoneReport	For output of the Phone Report
QuotaReport	For output of the Quota Report
WebResponseReport	For output of the Web Reports
VerbatimsTable	For output of Verbatims
WebTables	For output of Web Tables
OndemandTables	For output of OnDemand Tables

Inside the page div tag there is also a div tag with the class “container”. This allows you to set specific margins for the entire page. Within these two div tags there are several blocks of code.
The header block shows the title and image each contained in it’s own div (itbtm and itlogo respectively). This allows you to control the layout of the title and logo. If no title or logo are used, these blocks are set to not display.
Some pages contain a PageHeader and PageFooter that show up at the top and bottom of the page. The look of these are controlled with a class of the same name.
Some pages contain a TableHeader and TableFooter that show up above and below the table. The look of these are controlled with a class of the same name.
Some pages contain a table with the class “TableofContents” which is displayed at the top of the page.
All pages except the Verbatims page contain a table or tables with the class “DataTable”. This is where the primary information for that report or data table is displayed.
There are subclasses used to control the look of the header, footer, and specific columns and rows. When using custom CSS with a console-composed survey, the class names below, must be used and cannot be altered
There are four more universal classes used. Two define alternating background colors on the table of contents (“altcolor” and “altcolor2”) and two define a new background color for the column and row of a clicked table cell (“tableColHighlight” and “tableRowHighlight”).
All of the above structures can be set and applied to all reporting pages.
In addition, properties of all of the above can be changed or altered by basing the class on the id of the table.

For Example:

#WebTables .DataTable
{ width: 80%;
margin: 0 10% 0 10%; }

would change the width and margins for only the web tables page. Each page has it’s own section in the style sheet that can be used for page specific variations. Some sections have specific classes that are only used for that report.

Next Topic