Module Wd_template

module Wd_template: sig .. end

User access to the template definitions

exception Template_not_found of string

Raised when a template cannot be found. The argument is the name of the missing template

type template

The type of template definitions

type tree

The type of instantiated templates ("XML trees")

Many of the following functions either have an Wd_types.application_type object as first argument or a Wd_types.dialog_type object. These objects contain "background information" that are necessary to do their job.

Note that the base dialog class Wd_dialog.dialog defines a number of private methods that correspond to the following functions, but that know the first argument implicitly. For example, you can call

self#t_to_string tree

instead of

Wd_template.to_string self tree

val get : Wd_types.application_type -> string -> template

get app n: looks up the template with name n, or raise Template_not_found.

val apply : Wd_types.dialog_type ->
       template -> (string * tree) list -> tree

apply dlg t params: instantiates the template t with parameters params and returns the result. If more parameters are supplied than actually referenced in the template, these are silently ignored. If parameters are referenced that are missing in params, an Wd_types.Instantiation_error happens.

val apply_byname : ?localized:bool ->
       Wd_types.dialog_type ->
       string -> (string * tree) list -> tree

apply_byname dlg n params = apply (get n) params: instantiates the template with name n with parameters params and returns the result. See apply for the possible exceptions.

~localized: If true (default), the localized template is returned, if available. If false, exactly the template is returned that has been requested.

val apply_lazily : Wd_types.dialog_type ->
       string -> (string * tree) list -> tree

apply_lazily dlg n params: creates a tree node which applies the template n by instantiating the parameters params. The tree node is simply a "<ui:use template=...>...</ui:use>" node, and it is expanded only when needed.

val concat : Wd_types.application_type ->
       tree -> tree list -> tree

concat app sep l: if l = [n1;n2;...;nN], the concatenation n1 . sep . n2 . sep ... sep . nN is formed.

val empty : Wd_types.application_type -> tree

A tree node which expands to the empty string.

val text : Wd_types.application_type -> string -> tree

text app s: Forms a tree node which expands to the text s. This means if s contains meta characters (esp. <, >, &) these are converted to their corresponding entities (< > & etc)

val html : Wd_types.application_type -> string -> tree

html app s: Forms a tree node which expands exactly to s. This means that if s contains HTML meta characters these are left as they are. Because of this it is possible to include HTML elements. The string s is not parsed.

NOTE: It is not possible to create ui:* elements with this function that will be interpreted. If you want to create such elements you must instantiate templates containing them.

Internally, this function creates a ui:special node.

val to_string : Wd_types.dialog_type -> tree -> string

to_string dlg t: converts the tree representation t to its string representation. You need this function to put a tree into a string variable. You can then insert this variable into your document by using <ui:dynamic variable="name-of-variable" special="yes"/>.

For convenience, dialogs have a method put_tree putting a tree into string variable.

NOTE: The expansion process assumes that the generated HTML code will be inserted into a main page and not a popup page.