Using special characters in HTMPL forms

Document ID : KB000111907
Last Modified Date : 22/08/2018
Show Technical Document Details
Introduction:
When customizing HTMPL forms, you may find it necessary to include special characters in fields that will be passed to the web interface of Service Desk Manager. As an example, you may put a default "additional where clause" on a contact search that features the wildcard character '%', perhaps to exclude results from some similarly-named groups. As HTMPL is parsed similarly to HTML, many special characters need to be escaped, such as slashes or single quotes within strings; other characters, like '%', have special meaning to the parser and need to be converted to their ASCII equivalents in order to be read properly.
Instructions:
Continuing our example above, let's assume that we are adding the additional clause as follows:
extraURL="ADDITIONAL_WHERE=last_name NOT LIKE 'Exclude%'

This clause, if manually run through the contact search page (list_cnt.htmpl), will exclude any groups beginning with "Exclude". However, as HTMPL parsing treats the '%' specially, this same clause will yield an error if inserted directly into the HTMPL form as seen below:
[date] [time] [hostname] web:local 3596 ERROR session.c 5456 expand_string() failed for name 'ADDITIONAL_WHERE' or value 'last_name%20NOT%20LIKE%20%27Exclude%%27'

As seen in the error, the single quote characters are parsed as their ASCII hex equivalent, '%27'. The '%' character, however, is not parsed properly, as '%' is expected to be part of the ASCII equivalent of another character. To work around this limitation, we can intentionally replace '%' with its' ASCII equivalent, '%25' - doing so allows the parser to unambiguously treat the '%25' as if it were just "the character %", which is what we want for this purpose. The additional where clause now looks like the following:
extraURL="ADDITIONAL_WHERE=last_name NOT LIKE 'Exclude%25'
Additional Information:
If you encounter similar errors with other special characters, you may need to replace them with their equivalent ASCII hex codes within your HTMPL forms. Consult an ASCII character table to locate your special character, and replace it with the equivalent hex code as listed, preceded by a '%' character. An example ASCII character table is linked below.
https://en.wikipedia.org/wiki/ASCII#Printable_characters