SurveyFactory Documentation Documentation Custom template filters
Custom template filters

The following are custom template filters that you can use in your templates and template-enabled fields in the survey, publication and question editors. These are in addition to all of the standard template filters defined by Template-Toolkit. You may also want to look at the custom template functions that are available.

commify

Pass this filter a number and it will insert commas for every thousand marker. For instance:

[% 1234567890 | commify %]

would output:

1,234,567,890

countryName

Pass this filter a two letter country abbreviation, such as that used in survey.response.country and it will output the English language name of the country. We hope to convert this filter into recognizing language files in the near future.

[% survey.response.country | countryName %]

would output the name of the country the respondent last accessed the survey from. If survey.response.country was 'FR', it would output:

France

dateDuration

Pass this filter two dates and it will output a concise string that describes the duration between those two dates. If the duration is longer than a month, it will simply print out "> # months". Otherwise, if the duration is greater than 1 day, it will print out "> # days". If the duration is less than a day, but greater than an hour, it will print out "# hours # minutes" and finally, if it is less than an hour, it will print out "# minutes # seconds".

This is commonly used to show the amount of time that the respondent took completing the survey, which you could print using:

[% survey.response.lastmodifiedon | dateDuration(survey.response.startedon %]

The words used for months, days, hours, minutes and seconds are pulled from the appropriate language file.

dateFormat

The dateFormat filter is used on a date or time string to convert it to the appropriate time zone and print it in a specific format. All dates and times (not including responses to Dates and Times question types) are stored internally using UTC and will need to use this function in order to be properly displayed to the viewer.

This function takes three optional arguments, the format, timezone and locale. If you call the function within the arguments:

[% survey.response.startedon | dateFormat %]

it would be identical to calling it with:

[% survey.response.startedon | dateFormat('%F %T', survey.timezone,
     survey.languagefile.datelocale) %]

The default format of '%F %T' will print the date as YYYY-MM-DD HH:MM:SS, the timezone defaults to that which is configured for the survey and the date locale (which is used if you choose a format that prints month or weekday names) will be pulled from the language file currently in use by the respondent.

To see a full list of formats you can use, please see the strftime patterns for DateTime which ultimately prints the formatted date.

displayText

This function will attempt to parse the HTML and strip out any formatting, leaving just plain text. You will still want to call escapeHTML on the result, as it could include HTML tags, especially if this function fails to identify any plain text in the HTML code it is passed.

[% '<b>check out this</b> <img src="..." alt="image">' | displayText | escapeHTML %]

would print to the screen:

check out this image

This function is used in the table of contents of standard templates to create safe page titles in case they have HTML included in them. It is also used on the account side when displaying results graphs so that it can strip HTML used in question titles and answer choices.

escape

This function will perform a URI escape on any text passed to it. It is not commonly used in templates, but is available if needed.

escapeHTML

This function will take formatted HTML text and escape the dangerous characters, such as <, >, ", &, etc. For example:

[% '<b>test</b>' | escapeHTML %]

would output:

<b>test</b>

This makes the value safe to place into the value="" attribute of a form element. All f_value template variables have already had this performed on them, so you do not need to use this function for input fields that set the value="" to a f_value template variable. A common place this is used is on the HTML or Text Content type, if the designer has chosen to enter plain text. Our standard templates, then do:

[% question.content | eval | escapeHTML | pre; %]

which will output the evaluated content (in case they are using any template toolkit tags), escaped so that no HTML tags that happen to be in there will interfere with the page.

filesize

This function will print out a nicely formatted string that describes an uploaded file's size. For instance, to print out the file size of all files uploaded for a question, you could do:

[% FOREACH uploadfield IN question.answers;
     FOREACH file IN uploadfield.files;
       file.size | filesize; '<br>';
     END;
 END; %]

This function will currently use the labels B, KB, MB and GB to describe the file size and will either print an integer if the number is greater than 100, or use or two decimal places if less than that.

[% 1024 | filesize %] would print '1.00 KB'
[% 1000000 | filesize %] would print '976 KB'

Presently, these functions do not utilize the language file, although they may in the future.

pre

This function will take a portion of text and substitute line breaks with a <br> tag, tabs with two spaces, and any set of multiple spaces with &nbsp; entities so that it will display as it was formatted in plain text. Normally, if you just placed a piece of plain text into an HTML document, it will lose any line breaks and space formatting associated with it. Currently, this is used in standard templates for the HTML or Text Content question type if the survey designer has chosen to enter plain text:

[% IF question.content_type == 'text';
   question.content | eval | escapeHTML | pre;
END %]

staticFile

The staticFile filter should be used when you are referencing a static file that is part of your template package, such as an image, CSS or JavaScript file. For instance, if you have a JavaScript file that is part of your template package called 'base.js', you would include it using:

<script type="text/javascript" src="[% 'base.js' | staticFile %]"></script>

This filter does several things. The first is that it will prepend the survey.config.templateurl template variable to the filename so that it will load properly. The second thing is that it will append a timestamp based on when this file was last modified. This will tell our server to allow the file to be cached for long periods of time (up to a year), speeding up your survey load times. Furthermore, if you are to ever change something important like the JavaScript, CSS or image that you are referencing, it will be immediately updated in the user's browser, as the link to that resource will update in the source.

Therefore, this can be a very beneficial filter to use. We recommend against using this filter on static objects when you reference that resource many, many times and that resource is small and unlikely to change (such as an invisible dot used for layout purposes). We also recommend against using this filter for code that will appear outside of the survey, such as popup dialog code, as it will be hosted elsewhere and the timestamps will not be updated should you change items.

unescapeHTML

This filter should only be used in very specific instances, when the default escape for user-provided information is not needed. Currently, the only reason to use this filter is when implementing Custom redirects with response data. It performs the opposite of escapeHTML.