Templates can be accessed by the O'Caml code of the application. The module Template has the following signature:

exception Template_not_found of string

type template
type tree

val get          : application_type -> string -> template
val apply        : dialog_type -> template -> (string * tree) list -> tree
val apply_byname : ?localized:bool -> dialog_type -> string -> (string * tree) list -> tree
val apply_lazily : dialog_type -> string -> (string * tree) list -> tree
val concat       : application_type -> tree -> tree list -> tree
val empty        : application_type -> tree
val text         : application_type -> string -> tree
val html         : application_type -> string -> tree
val to_string    : dialog_type -> tree -> string

The type template is the abstract handle of the representation of the template definition. It is possible to get such template handles from the current UI definition, but they are read-only, and they cannot be constructed manually (i.e. without reference to the UI definition). A template should be considered as an XML tree with placeholders (dollar notation).

The type tree stands for an XML tree without placeholders, or better, for an XML tree where the placeholders have already been resolved. There are several ways to get such a tree: It is possible to form trivial trees (an empty tree, or a tree consisting only of one data node), or to apply a template by replacing the placeholders with subtrees, or to concatenate several trees. Note that the term "tree" has been chosen because the underlying data structure are actually XML trees; however, there are no real tree operations, and I hope that the name is not too confusing.

There are two other types playing a role here: application_type and dialog_type. The first abstracts the UI definition file, and the latter is the type of the dialog objects. Templates can only be used in the scope of a UI definition (because they may refer to other templates, and these are defined for the UI definition), and template application even needs a dialog object (because the template may refer to dialog variables).

Description:

• Template_not_found: This exception is raised by one of the functions accessing templates by name if there is no template with the searched name. The argument is the name of the missing template.

• get app n: Returns the abstract handle to the template with the name n defined in the application app (or raises Template_not_found).

• apply dlg t p: Instantiates the parameters of the template t with the passed trees p, and returns the resulting instantiated template tree. If a parameter is missing, but the template defines a default value, this default value will be taken as the parameter value. If a parameter is missing, and there is no default value, an error will be reported. (This means that this function does not support dynamic contexts as alternate source for parameter values.)

  This function does not perform further expansion of templates; only the passed template is instantiated.

• apply_byname dlg n p: This is the same as a get followed by an apply:

  let apply_byname dlg n p = apply dlg (get dlg#application n) p
  

  The optional boolean argument ~localized (default: true) selects whether the template for the current language is preferred over the generic template. (See also the chapter about Internationalization.)

• apply_lazily dlg n p: This function forms a new tree which is guaranteed to expand the template n in the same manner as apply_byname by passing the parameters p; however the instantiation is not performed immediately but deferred until it is really necessary.

• concat app s tl: Concatenates all the trees of the passed tree list tl and separates the trees by s. This means, if tl = [t1; t2;...;tN] the resulting structure is the same as if t1 s t2 s ... s tN had been written in order. (Don't be confused that the result cannot be a tree (but perhaps a forest) - we have never said that tree behaves exactly as a tree structure; tree is only a metaphor.)

• empty app: Creates an empty tree.

• text app s: Creates a tree with one data node containing the string s. When the tree is expanded to HTML, the problematic characters are converted to the corresponding HTML entities such that the text s appears in the user interface.

• html app s: Creates a tree with one data node containing the string s. When the tree is expanded to HTML, the string s is left as it is without any conversion.

• to_string dlg t: Converts the tree t to HTML in the context of the dialog object dlg. Templates are now expanded until no more templates remain. The ui:xxx elements are expanded, too. It is possible to access the object variables of obj. Furthermore, if interactors are expanded, the necessary management infos will be entered into dlg. (However, there is currently a conceptual bug which makes it impossible to expand ui:form elements in a reasonable way.)