Chapter 4.19:  CML Page Functions

[TOP] [UP] [PREV] [NEXT]

One of the most challenging tasks in creating sophisticated interfaces in CML is keeping track of where the user has been.  For example, a user may start at page A, go to page B to fill out a form, which in turn is processed by page C... which should return the user to page A.  If page B may be invoked from many different places, this task (remembering where to return to after page C) can get quite complicated.

This section details the CML functions which make this capability possible.

$page_save(refresh cmlfile arglist fragment description)

This function "saves" a CML page reference in a table inside the CML interpreter.  It evaluates to (i.e., returns) a slot number in that table, which may be used by the other $page_... functions to access the saved page.  The arguments to $page_save() define a page reference in such a way that the reference can be used later to easily "return to" that page later.

Cmlfile is the name of the CML file.  Arglist is the list of arguments to that file that should be remembered.  (Arglist must be one word, so typically the arguments are specified in their URL form, i.e. with plus signs separating the individual arguments.)  Fragment is the anchor point where that document should be re-entered, e.g. "#here".  (If there is no such anchor point, fragment should just be "#".)  Description is just ordinary text that describes that page; it may be any number of words, including none.

The "Caucus Center" page shown in the example CML file in section 3 uses $page_save() to save the current location in a table slot:

set nxt $page_save (1 center.cml \
        $arg(2)+$arg(3)+$arg(4)+$arg(5)+$arg(6)+$arg(7)+$arg(8) \
                # $(center_name) )

This CML code fragment saves the current page (center.cml), with its list of arguments ($arg(2)+...), no fragment ("#"), and a text description (contained inside the variable center_name).  The saved page reference is stored in a slot, and the slot number is stored (by the "set" statement) in variable nxt.

The refresh argument is somewhat complicated.  The slot table in the CML interpreter has a fixed size... which means that slots that haven't been touched in a while will get automatically recycled.  Refresh is a number that refers to the arguments in arglist.  If refresh has a value of N, then the N'th argument in arglist is assumed to be a slot number, and that slot is refreshed -- that is, protected from being recycled until the rest of the slots in the table have been recycled.   See the previously mentioned Programmer's Guide for more information.

$page_get(slot)

Evaluates to the entire string saved in slot (by $page_save()).  The first word of the result is the page name, the second word is the argument list, the third word is the fragment (anchor name, with "#"), and the fourth through last words are the page description.

$page_return(slot  #override  empty)

Evaluates to a string that can be used in an HTTP "Location:" directive to "return to" a page saved in slot.  #override is a fragment anchor that may be used to override the anchor that was saved (with $page_save()).  If it is just "#", the original (saved) anchor is used, otherwise #override is used.  Empty should be a full CML page reference, to be used only if there is no page saved at slot.

Here is an example from the Caucus 3.1 additemf.cml file, which processes adding a new item to a conference, and then returns to the page which invoked "create a new item":

   "Location: $(href)/$page_return($arg(2) # \
                           center.cml?$(nch)+0+x+x+x+x+x+x)

In this case, $arg(2) is the slot number of the page that originally invoked "create a new item".  There is no override on the saved fragment anchor, and the default page (in case there was no saved "calling" page) is center.cml, the "Caucus Center" page.

$page_caller(which slot)

Evaluates to the slot number of the page which "called" the page saved at slot.  Assumes that the caller of a page is stored in the argument list to that page, in argument number which.