Wizard file syntax

The wizard xml files are similar to form files, but intended for data entry and due to that will accept more than one table at a time. There's also some process control function to allow the wizard to go to different pages depending on what you want to enter. Here's an example of a simple wizard.

<wizard>

  <page id="default">
    <set group="1" table="cust_entity" id="cust_type" record="cust_type"/>
    <when field="cust_type" equals="P">
      <field group="1" table="cust_entity" id="title"/>
      <field group="1" table="cust_entity" id="name2"/>
      <field group="1" table="cust_entity" id="name" label="Surname"/>
    </when>
    <when field="cust_type" equals="C">
      <field group="1" table="cust_entity" id="cust_class_no"/>
      <field group="1" table="cust_entity" id="vat_id"/>
      <field group="1" table="cust_entity" id="name"/>
      <field group="1" table="cust_entity" id="def_payment_term"/>
    </when>
    <field group="2" table="eaddress" id="eaddress_type_no"/>
    <field group="2" table="eaddress" id="eaddress_code"/>
    <field group="3" table="eaddress" id="eaddress_type_no"/>
    <field group="3" table="eaddress" id="eaddress_code"/>
    <field group="4" table="eaddress" id="eaddress_type_no"/>
    <field group="4" table="eaddress" id="eaddress_code"/>
    <field group="5" table="address" id="address_type_no"/>
    <field group="5" table="address" id="line1"/>
    <field group="5" table="address" id="line2"/>
    <field group="5" table="address" id="line3"/>
    <field group="5" table="address" id="line4"/>
    <field group="5" table="address" id="city"/>
    <field group="5" table="address" id="postcode"/>
    <field group="5" table="address" id="state_code"/>
    <field group="5" table="address" id="country_code"/>
    <button id="saveit" label="Save" action="savegroups" success="redirect_entity" failure="default"/>
  </page>

  <page id="redirect_entity">
    <text>Customer saved.</text>
    <redirect id="redirect" act="edit" table="cust_entity" group="1" key="cust_no"/>
  </page>

</wizard>

<wizard> is the containing tag in this case, without any attributes. field and when work the same as for forms, but field have two new attributes, group and table to indicate where to store the information. Each group will result in one record. A wizard usually consist of several pages, the first must have the id attribute set to "default".

A wizard can also have buttons, when the button is pressed the action indicated in the action attribute will be run and if it's successful the page indicated in success will be opened, if it fails the page indicated in failure will be opened instead. In the sample above, if the builtin action "savegroups" succeeds the page "redirect_entity" is activated, the <text> tag allows text to be shown directly, but in this case the redirect will mean that the user never sees the text, instead they will be redirected to the newly created record. If the save fails it will show the entry page again.

The "savegroups" action will save all groups as separate records following the order of the groups and transfer primary keys from the first to the last so that they'll be connected.

It's possible to define custom actions by adding a <action> before the pages in the file. <action id="preview" file="../twospot/preview_email.php" function="previewEmail"/> for example will let you write <output id="preview_it" action="preview"/> inside a page. This will open the "file" attribute and call the "function" attribute returning the result.

function previewEmail($req,$action,$pagedata) {
   return "This is a sample output action response";
}

An action always takes three arguments, $req is the request parameters from the browser to show the page. $action is the name of the action (to allow certain kinds of reuse), and pagedata is a structure that holds the content of the wizard data as shown in the forms. The content is empty when the wizard is a first entered, so an <output> call on the first page will not have data to work with. Using a custom action for a button will have all fields included, regardless of what page they where on.

Here's another example of a wizard, this time to show a list of records that can be edited:

<wizard>

  <page id="default">
    <text>Company customers</text>
    <list id="company" rows="20">
      <table id="cust_entity" filter="cust_type='C'" link="edit,add,delete"/>
      <display table="cust_entity" field="cust_id" width="5"/>
      <display table="cust_entity" field="name" width="39"/>
      <display table="cust_entity" field="country_code" width="4"/>
      <display table="cust_entity" field="vat" width="15"/>
      <display table="cust_entity" field="updated" width="12"/>
    </list>
  </page>

</wizard>

In this case the <table> tag also has a filter attribute to further filter the query, and we're allowing whoever is using the list to edit, delete and add new records. The "width" attribute can be used to tweak the width of each column and the "rows" attribute in the <list> tag can be used to set how many rows will be displayed at once.