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.
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.
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.