(*
* <COPYRIGHT>
* Copyright 2002 Joachim Schrod Network and Publication Consultance GmbH, Gerd Stolpmann
*
* <GPL>
* This file is part of WDialog.
*
* WDialog is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* WDialog is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with WDialog; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
* </>
*)
(* $Id: wd_template.mli,v 3.5 2003-03-21 20:57:54 stolpmann Exp $
* ----------------------------------------------------------------------
*
*)
(** User access to the template definitions *)
open Wd_types
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 : application_type -> string -> template
(** [get app n]: looks up the template with name [n], or raise
* [Template_not_found].
*)
val apply :
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 ->
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 : 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 : 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 : application_type -> tree
(** A tree node which expands to the empty string. *)
val text : 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 : 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 {b 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 : 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 {b not} a popup page.
*)
(* ======================================================================
* History:
*
* $Log: wd_template.mli,v $
* Revision 3.5 2003-03-21 20:57:54 stolpmann
* ocamldoc problems
*
* Revision 3.4 2003/03/21 14:23:44 stolpmann
* ocamldoc updated
*
* Revision 3.3 2002/02/16 17:29:45 stolpmann
* mostly ocamldoc.
*
* Revision 3.2 2002/02/14 16:15:21 stolpmann
* Added copyright notice.
*
* Revision 3.1 2002/02/12 20:29:23 stolpmann
* Initial release at sourceforge.
*
* Revision 1.5 2002/01/31 23:06:39 gerd
* Revised conditional expansion (ui:if, ui:ifvar, ui:iflang,
* ui:cond).
* Added some support for internationalization (xml:lang).
*
* Revision 1.4 2002/01/24 23:35:30 gerd
* Updated comments
*
* Revision 1.3 2002/01/14 15:03:24 gerd
* Major change: Typing has been completely revised, and almost
* every tiny thing has now a new type. Also renamed a lot.
*
* Revision 1.2 2000/12/06 15:28:20 gerd
* to_string: (Still buggy) support for the ~self_url parameter.
* html: Implemented for the first time
*
* Revision 1.1 2000/04/13 17:42:58 gerd
* Initial revision.
*
*
*)
