Wizards

From ISPWiki
Jump to: navigation, search

Introduction

A COREmanager Wizard is a number of form fields. Wizard steps can be added by different modules of the control panel. Operations are performed within one transaction allowing for correct rollback in case of errors.

Wizard at work

In addition to calls that can be addressed to common forms, the Wizard steps can be called by:

  • get
    • generate a list of steps. It is called after every update of the Wizard (when the Wizard is displayed or when you switch between steps). In this case the checkonly=on parameter is passed to the function. The function will return the XML containing <messages> (the @title step name will be taken from those messages). The function may return a number of non-required elements: next, skip, unavailable (see description below).
  • set
    • save form data. It is defined with the snext=ok parameter (beside the sok=ok parameter) It is called when a user clicks "Next". The checkonly=on parameter is passed to the function.The function will check that data provided are correct, and form additional parameters, which values will be saved when a user enters data into the form and can be used in further steps. At this moment the function must not modify the server data.
    • perform operations. Similar to set, and is called when the user clicks "ok" on the Wizard form. The form must perform all required operations.

Before performing operations, the Wizard will collect data. All parameters are saved in the form fields. If the form doesn't contain a field with the corresponding name, a hidden input field will be added.

Calling a Wizard

A wizard function should have a unique name. Every step of the Wizard is a function, which should have a name as well. We recommend that step names start with the Wizard name dot separated.

The Wizard can be named either according to the Wizard name, in this case the first step will open, or according to the step name. Or the step name can be passed by the Wizard function in the step parameter.

For example, we have the following Wizard (all steps are active):

Wizard: master

  1. first step: master.first
  2. second step: master.second
  3. third step: master.third
  • Open the first step of the Wizard
    • by the name of the master: func=master
    • by the name of the step: func=master.first
  • Open the second step of the Wizard
    • by the name of the master: func=master&step=master.second
    • by the name of the step: func=master.second
  • Create the master: func=master&sok=ok&param1=value1&param2=value2. In this case we need to pass parameters of all steps. Parameters, which values are not specified, will get default values.
  • Open the Wizard step, enter the value of the param field into value: func=master&param=value

Result

The Wizard must form a result depending on the operation it was called for.

Performing an action

The result, as in a common form, is the <ok> element or an error. The ok element may contain the name of the form or, the list that will open after completing the Wizard steps. The first non-empty result of <ok> will be accepted. The Wizard steps are completed in the same order as they are displayed.

Saving data

The step may contain a number of XML elements, which values will be saved like other parameters.

E.g.: <param>some value</param> - a value of the param parameter will be set to '"some value".

Now it can return the <next> element with the name of the next step. In this case the specified step will be shown next.

For example, if the Wizard's step master.first, described above returned <next>master.third</next>, clicking "Next" on the first step will pass us to the third step omitting the first step. You can switch to next step only frontwards. E.g., if the second step returns <next>master.first</next>, this step will be the last one.

List of steps

This call can form a result similar to get. However, only the step name will be taken (the wizard_title message). If this message is not present, the title message will be used.

The function can also return:

  • the <next>..</next> element described above
  • the <skip/> element - show this step as inactive. You cannot switch to this step.
  • the <unavailable/> element - the step is not available to a user. It won't be shown on the list, and the user won't be able to switch to that step.

Examples

You can use the isp_api::Wizard class to work with Wizards via API.

To create a Wizard, describe the mechanisms of its steps. Creating any step of the Wizard will automatically create the Wizard itself. E.g. the following code will creat the mywizard Wizard with the mywizard.first_step step:

#include <api/wizard.h>
#include <api/module.h>
 
namespace {
class MyWizardFirstStep : public iso_api::Wizard {
public:
  MyWizardFirstStep() : isp_api::Wizard("mywizard", "mywizard.first_step", AccessAdmin) {}
  virtual void WizDone(Session &ses) const {
    /* code implementing your step */
  }
};
 
MODULE_INIT(mywizard, "") {
  new MyWizardFirstStep();
}
} // end of private namespace