[UP]
Modules

Wd_interactor

Wd_run_jserv

Wd_run_fcgi

Wd_stdlib

WDialog API for Objective Caml: Wd_interactor

Module Wd_interactor

module Wd_interactor: sig .. end

This module provides a data type for containers of interactor descriptions.

The background of the module is that interactors (such as input elements, hyperlinks, buttons) are referred to by two different naming schemes. On the one hand, the interactor elements in the ui file have a name and and optionally an index; e.g.

<ui:button label="Press here" name="my_button" index="1"/>

<ui:text variable="x" index="5"/>

Often the name/index pair is actually a variable/index pair because the interactor is bound to a certain instance variable of the uiobject. - On the other hand, the interactors are transformed to HTML code, and the HTML/CGI name is different. For example the following HTML output might have been generated:

<input type="button" name="xbutton_25" value="Press here">

<input type="text" name="var_12" value="...">

Obviously, the HTML/CGI names are automatically chosen. Of course, there is a bijective mapping from the internal names to the HTML/CGI names, and the task of the Interactor.t type is to manage these mappings.

A value of type Interactor.t contains the following:

A list of name/index pairs
The corresponding HTML/CGI identifiers. Only the identifier after the prefix (such as "var_" or "xbutton_") is stored.
The bijection which name/index pair corresponds to which identifier.
For every name/index pair (or every identifier) there may be another arbitrary value which can store additional information related to the interactor

Example

let ia = create();;    (* : unit Interactor.t *)
...
let id = add ia "my_button" "1" None ();;   (* = "25" *)

Note that the "25" is an automatically created identifier (just the next free number), and that the HTML/CGI name will be composed of a prefix indicating the type of the interactor and the identifier, e.g. "xbutton_25".

If we try to add the same name/index pair a second time, the add operation raises an exception:

add ia "my_button" "1" None ();;

==> raises Element_exists "25"

When the incoming CGI parameters are analyzed, it must be possible to look up the name/index pair for a given identifier. For example:

let (name,index,value) = lookup ia "25";; (* = ("my_button", "1", () *)

There is no reverse lookup operation. However, it is at least possible to test the existence of a given name/index pair:

exists ia "my_button" "1" yields true

As a last resort, it is possible to iterate over all members of the ia value:

let print id name index value =
printf "ID=%s name=%s index=%sn" id name index
in
iter print ia

Selecting the identifier manually

If the ui element contains the cgi="keep" attribute, and there is no index component, the CGI name retains the orignal name. For example:

<ui:button label="Press here" name="press" cgi="keep"/>

The generated HTML code:

<input type="button" name="button_press" value="Press here">

Such an interactor would be added as follows:

let id = add ia "press" "" (Some "press") ();;   (* = "press" *)

I.e. you can determine the identifier by passing it as fourth argument. Of course, in this case it is checked whether the identifier is still free; and add fails if the identifier was already previously used.

Representation

Note that the representation of Interactor.t is optimized for efficient serialization (using the Marshal module). Especially, if there are many name/index pairs differing only in the index component, the name component is stored only once.

Further information

See Wd_types.interactors

type 'a t

The type of interactors

type id = string

Interactors are identified by strings

exception Element_exists of id

Raised by some functions if there is already a component with the ID

val create : 'a -> 'a t

create x: Creates a new interactor manager. The value x must only be passed because of typing restrictions.

val clear : 'a t -> unit

clear ia: Removes all entries from the interactor. The sequence generator for the automatic IDs is not reset, however.

val add : 'a t ->
       string -> string -> id option -> 'a -> id

add ia name index opt_id value: adds the triple (name,index,value) to ia; if opt_id is None, the triple gets an automatically selected numerical ID; if opt_id is Some id, the triple has the ID id. The function returns the ID.

Fails with Element_exists if the pair (name,index) is already contained. The argument of this exception is the ID.

val lookup : 'a t -> id -> string * string * 'a

lookup ia id: looks up the triple (name,index,value) for the ID id within ia.

Fails with "Interactor.lookup" if the id cannot be associated.

val exists : 'a t -> string -> string -> bool

exists ia name index: returns whether the pair (name,index) exists in ia.

val iter : (id -> string -> string -> 'a -> 'b) ->
       'a t -> unit

iter f ia: iterates over the elements of ia and invoke the function f for every element by f id name index value.

val serialize : ('a -> string) -> Buffer.t -> 'a t -> unit

serialize f b ia: Writes the serialization of ia to buffer b. Contained values are serialized by calling f.

val unserialize : (('a, 'b, 'c) Wd_serialize_types.poly_ds_buf -> 'd) ->
       ('a, 'b, 'c) Wd_serialize_types.poly_ds_buf -> 'd t

unserialize f buf: Reads the serialized string from buf and reconstructs the interactors. Values are read by calling f.