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.

Function	Arguments	Description
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 = "http://www.google.com/q=" + 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>