Wizards

Wizards consist of program code that initiates a sequence of dialogs in the HTML GUI of the Content Manager. Such a dialog sequence enables editors to solve a task in a series of predefined, optionally correctable steps. Wizards are implemented as Tcl scripts and thus can make use of all of the Content Manager's functionality. As examples and templates for developing your own wizards, you can use the wizards included in the Fiona Demo Content.

As with simple Tcl procedures, wizards are integrated into the Content Navigator by means of a definition in the file contentMenu.xml. This file can be found in the instance-specific config directory (see Configuring Custom Commands). In the definition, set the dialog property to true to distinguish it from a simple custom command.

The wizards delivered with the CMS are defined in the itemRegistry.xml file located in the instance-specific webapps/GUI/WEB-INF directory.

When the custom command is called in the GUI, the latter sends a corresponding XML request to the Content Management Server. From this request the server extracts the name of the custom command and of the Tcl procedure and executes the procedure passing to it the arguments from the request. The procedure then evaluates the arguments passed to it and outputs the result as HTML text to the standard output device. This text is sent as the response to the request to the GUI which processes it and finally sends it to the browser.

The HTML wizard page generated by the Tcl script is displayed by the GUI as a form whose elements are filled in by the user (in order to move to the next processing round). Since the Tcl script needs to assign a name to the page to be displayed and since the user submits the form it contains using a submit button, the Tcl script receives the information it requires to advance to the next step or terminate the dialog sequence. The script can end this circle by responding with an empty result (containing nothing or just spaces). (Technically spoken, the GUI and the Tcl script form a state machine in which the current state is defined by the page name and the desired change of state by the submit action).

Page Generation

The Tcl procedure generates a dialog page by writing its HTML text into the standard output device. Since the GUI embeds this HTML text in a form contained in a page it must not use the elements body, head and form.

The page name must be set using the following element:

<npsPage name="PageName" title="Title">
  <!-- Contents of the page: HTML code plus wizard tags -->
</npsPage>

The value of the optional title field is used by the GUI as page title. When the form is submitted, the title, among other values (see below), is passed to the wizard.

Interaction with the User

The Tcl code can use the commonly known HTML form elements (i. e. output them to the standard channel) for collecting the user's input.

By means of several wizard tags, you can access functions of the Content Navigator, for example for displaying buttons, making use of selection dialogs and more.

Parameter Transfer

When the user calls a wizard, the corresponding procedure is called with two arguments. The procedure needs to be defined as follows:

proc wizardCommand {paramList args} {
   ...
}

The paramlist argument contains a list of name-value pairs that contain the variable names and the corresponding values stored in the session. The list is not newly created for each form. It is reused instead, meaning that all dialogs share one name space. Thus, form fields must be unique across all dialogs to be able to call them in any order.

Initially, the list contains the following named values:

Name Meaning
wizard.page Name of the page generated using npsPorm name="..." from which the input originates. At the first execution of the wizard code, i. e. after the user has called the wizard, this parameter has the value init. By the value of this parameter the wizard code can determine the page on which the user has clicked a submit button.
wizard.button Name of the submit button pressed last (generated using npsButton name="..."). When the wizard's Tcl code is called for the first time, this parameter has the value init. By means of the value of this button, the Tcl code can determine which action the user has chosen.
wizard.tickets A list containing pairs of names and values. The names are identifiers, the values are ticket IDs. By means of these values, editors such as the HTML editor can be called from within wizards and a main content or the contents of an HTML field can be passed to them.
wizard.language The user's language setting (de, en etc.)
wizard.attributeName When editing a field, the name of the field is passed to the wizard in this variable..
wizard.contentId When editing a field, the ID of the version concerned is passed to the wizard in this variable.

Every time the user clicks a submit button, this list of name-value pairs is updated and extended with the values of fields unknown until then. The GUI does not remove field names from the list that are not referenced in the current form.

As the second argument, args, the IDs of the files to be processed by the wizard are passed to it, depending on the wizard's menu item configuration. For menu items with the selectionType single, args is the ID of the file currently selected. For an extended selectionType, args is the list of IDs of the files selected on a GUI page that allows several files to be selected.

The following table summarizes the arguments passed to the wizard, depending on the selectionType:

Menu Arguments
none
  • List of name-value-pairs (wizard.language, wizard.button, wizard.page as well as input field names).
single
  • List of name-value-pairs (like above).
  • ID of the file concerned.
extended
  • List of name-value-pairs (like above).
  • A list containing the IDs of the files concerned.

Helper Procedures

Fiona includes a wizard library (share/script/cm/serverCmds/wizardLib.tcl) and a WizardController (share/script/cm/serverCmds/wizards/lib/wizardController.tcl) that make it much easier to create wizards.