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.
Pass this filter a number and it will insert commas for every thousand marker. For instance:
[% 1234567890 | commify %]
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:
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.
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.
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.
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.
This function will take formatted HTML text and escape the dangerous characters, such as <, >, ", &, etc. For example:
[% '<b>test</b>' | escapeHTML %]
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.
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.
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 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 %]
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.
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.