includes/cbt/README

   1 Overview
   2 --------
   3
   4 CBT (callback-based templates) is an experimental system for improving skin
   5 rendering time in MediaWiki and similar applications. The fundamental concept is
   6 a template language which contains tags which pull text from PHP callbacks.
   7 These PHP callbacks do not simply return text, they also return a description of
   8 the dependencies -- the global data upon which the returned text depends. This
   9 allows a compiler to produce a template optimised for a certain context. For
  10 example, a user-dependent template can be produced, with the username replaced
  11 by static text, as well as all user preference dependent text.
  12
  13 This was an experimental project to prove the concept -- to explore possible
  14 efficiency gains and techniques. TemplateProcessor was the first element of this
  15 experiment. It is a class written in PHP which parses a template, and produces
  16 either an optimised template with dependencies removed, or the output text
  17 itself. I found that even with a heavily optimised template, this processor was
  18 not fast enough to match the speed of the original MonoBook.
  19
  20 To improve the efficiency, I wrote TemplateCompiler, which takes a template,
  21 preferably pre-optimised by TemplateProcessor, and generates PHP code from it.
  22 The generated code is a single expression, concatenating static text and
  23 callback results. This approach turned out to be very efficient, making
  24 significant time savings compared to the original MonoBook.
  25
  26 Despite this success, the code has been shelved for the time being. There were
  27 a number of unresolved implementation problems, and I felt that there were more
  28 pressing priorities for MediaWiki development than solving them and bringing
  29 this module to completion. I also believe that more research is needed into
  30 other possible template architectures. There is nothing fundamentally wrong with
  31 the CBT concept, and I would encourage others to continue its development.
  32
  33 The problems I saw were:
  34
  35 * Extensibility. Can non-Wikimedia installations easily extend and modify CBT
  36   skins? Patching seems to be necessary, is this acceptable? MediaWiki
  37   extensions are another problem. Unless the interfaces allow them to return
  38   dependencies, any hooks will have to be marked dynamic and thus inefficient.
  39
  40 * Cache invalidation. This is a simple implementation issue, although it would
  41   require extensive modification to the MediaWiki core.
  42
  43 * Syntax. The syntax is minimalistic and easy to parse, but can be quite ugly.
  44   Will generations of MediaWiki users curse my name?
  45
  46 * Security. The code produced by TemplateCompiler is best stored in memcached
  47   and executed with eval(). This allows anyone with access to the memcached port
  48   to run code as the apache user.
  49
  50
  51 Template syntax
  52 ---------------
  53
  54 There are two modes: text mode and function mode. The brace characters "{"
  55 and "}" are the only reserved characters. Either one of them will switch from
  56 text mode to function mode wherever they appear, no exceptions.
  57
  58 In text mode, all characters are passed through to the output. In function
  59 mode, text is split into tokens, delimited either by whitespace or by
  60 matching pairs of braces. The first token is taken to be a function name. The
  61 other tokens are first processed in function mode themselves, then they are
  62 passed to the named function as parameters. The return value of the function
  63 is passed through to the output.
  64
  65 Example:
  66    {escape {"hello"}}
  67
  68 First brace switches to function mode. The function name is escape, the first
  69 and only parameter is {"hello"}. This parameter is executed. The braces around
  70 the parameter cause the parser to switch to text mode, thus the string "hello",
  71 including the quotes, is passed back and used as an argument to the escape
  72 function.
  73
  74 Example:
  75    {if title {<h1>{title}</h1>}}
  76
  77 The function name is "if". The first parameter is the result of calling the
  78 function "title". The second parameter is a level 1 HTML heading containing
  79 the result of the function "title". "if" is a built-in function which will
  80 return the second parameter only if the first is non-blank, so the effect of
  81 this is to return a heading element only if a title exists.
  82
  83 As a shortcut for generation of HTML attributes, if a function mode segment is
  84 surrounded by double quotes, quote characters in the return value will be
  85 escaped. This only applies if the quote character immediately precedes the
  86 opening brace, and immediately follows the closing brace, with no whitespace.
  87
  88 User callback functions are defined by passing a function object to the
  89 template processor. Function names appearing in the text are first checked
  90 against built-in function names, then against the method names in the function
  91 object. The function object forms a sandbox for execution of the template, so
  92 security-conscious users may wish to avoid including functions that allow
  93 arbitrary filesystem access or code execution.
  94
  95 The callback function will receive its parameters as strings. If the
  96 result of the function depends only on the arguments, and certain things
  97 understood to be "static", such as the source code, then the callback function
  98 should return a string. If the result depends on other things, then the function
  99 should call cbt_value() to get a return value:
 100
 101    return cbt_value( $text, $deps );
 102
 103 where $deps is an array of string tokens, each one naming a dependency. As a
 104 shortcut, if there is only one dependency, $deps may be a string.
 105
 106
 107 ---------------------
 108 Tim Starling 2006