Expression Functions

Clearsilver has some built-in functions for expressions. These functions allow access and manipulation of expression arguments. Currently, all functions return string or numeric values. Functions can be used in expressions anywhere a variable could be used.

subcount(var)An HDF variable Returns the number of child nodes for the HDF variable
name(local)A local variable Returns the HDF variable name for a local variable alias
first(local)A local variable Returns true iff the local variable is the first in a loop or each
last(local)A local variable Returns true iff the local variable is the last in a loop or each
abs(expr)A numeric expression Returns the absolute value of the numeric expressions
max(expr, expr)Two numeric expressions Returns the larger of two numeric expressions
min(expr, expr)Two numeric expressions Returns the smaller of two numeric expressions
string.slice(expr, start, end)A string expression, and two numeric expressions Returns the string slice starting at start and ending at end, similar to the Python slice operator
string.find(string, substr)Two string expressions Returns the numeric position of the substring in the string (if found), otherwise returns -1 similar to the Python string.find method
string.length(expr)A string expression Returns the length of the string expression
_(expr)A string expression Only available if compiled with gettext support, returns the translated version of the string expression as returned by gettext()

Template Filters

The Clearsilver API allows the user to add string manipulation functions to the built-in functions. These functions can take just one string argument and return a string. The Clearsilver CGI Kit has several Web specific filters that are added to Clearsilver. These filters can be added in C via the cgi_register_strfuncs() function, and are included by default in the CS layer of most of the language wrappers.

url_escape This URL encodes the string. This converts characters such as ?, &, and = into their URL safe equivilants using the %hh syntax.
html_escape This HTML escapes the string. This converts characters such as >, <, and & into their HTML safe equivilants such as &gt;, &lt;, and &amp;.
js_escape This Javascript escapes the string so it will be valid data for placement into a Javascript string. This converts characters such as ", ', and \ into their Javascript string safe equivilants \", \', and \\.
text_html This pretty-formats normal text into an HTML fragment, attempting to detect paragraph boundaries and allowing it to wrap reasonably.
html_strip This removes all HTML tags and then converts any & based HTML escaped data into normal text. Combine this with html_escape() if you would like to strip the HTML tags from text and display the result in an HTML safe way.
url_validate Function to validate a URL for protecting against XSS. Ensures that the URL is a relative URL or an absolute url with a safe scheme (currently http, https, ftp or mailto). This is to avoid dangerous schemes like javascript. It then HTML escapes the URL. An unsafe URL is replaced by '#'.
css_url_validate Similar to url_validate except it escapes the URL for use in CSS.
null_escape This escape function just outputs the given string as is. The auto-escape system assumes that anything explicitly escaped is correctly escaped.

These filters can be used anywhere in an expression. This makes them extremely useful for composing URLs or forcing data to be HTML safe. Here are some examples:

<?cs var:html_escape(Page.Title) ?>
<?cs set:url = "" + url_escape(Query.q) ?>

<IMG onclick="handleClick('<?cs var:js_escape(url)')" SRC="foo.gif">

<A HREF="/newurl?_done=<?cs var:url_escape(url) ?>">click here</A>