includes/cbt/README

   1 Template syntax
   2 ---------------
   3
   4 There are two modes: text mode and function mode. The brace characters "{"
   5 and "}" are the only reserved characters. Either one of them will switch from
   6 text mode to function mode wherever they appear, no exceptions.
   7
   8 In text mode, all characters are passed through to the output. In function
   9 mode, text is split into tokens, delimited either by whitespace or by
  10 matching pairs of braces. The first token is taken to be a function name. The
  11 other tokens are first processed in function mode themselves, then they are
  12 passed to the named function as parameters. The return value of the function
  13 is passed through to the output.
  14
  15 Example:
  16    {escape {"hello"}}
  17
  18 First brace switches to function mode. The function name is escape, the first
  19 and only parameter is {"hello"}. This parameter is executed. The braces around
  20 the parameter cause the parser to switch to text mode, thus the string "hello",
  21 including the quotes, is passed back and used as an argument to the escape
  22 function.
  23
  24 Example:
  25    {if title {<h1>{title}</h1>}}
  26
  27 The function name is "if". The first parameter is the result of calling the
  28 function "title". The second parameter is a level 1 HTML heading containing
  29 the result of the function "title". "if" is a built-in function which will
  30 return the second parameter only if the first is non-blank, so the effect of
  31 this is to return a heading element only if a title exists.
  32
  33 As a shortcut for generation of HTML attributes, if a function mode segment is
  34 surrounded by double quotes, quote characters in the return value will be
  35 escaped. This only applies if the quote character immediately precedes the
  36 opening brace, and immediately follows the closing brace, with no whitespace.
  37
  38 User callback functions are defined by passing a function object to the
  39 template processor. Function names appearing in the text are first checked
  40 against built-in function names, then against the method names in the function
  41 object. The function object forms a sandbox for execution of the template, so
  42 security-conscious users may wish to avoid including functions that allow
  43 arbitrary filesystem access or code execution.
  44
  45 The callback function will receive its parameters as strings. If the
  46 result of the function depends only on the arguments, and certain things
  47 understood to be "static", such as the source code, then the callback function
  48 should return a string. If the result depends on other things, then the function
  49 should return an object:
  50
  51    return new CBTValue( $text, $deps );
  52
  53 where $deps is an array of string tokens, each one naming a dependency. As a
  54 shortcut, if there is only one dependency, $deps may be a string.
  55