Wizards. Getting Started

To add Wizard "from the box", first, add required modules:

  • platform independend XafariModule;
  • platform specific XafariWinModule and XafariWebModule.

Then, create WizardAction in controller. The following code demonstrates how to do this:

  • c#
  • VB

private Xafari.Actions.WizardAction wizardAction1;
//...
this.wizardAction1.AcceptButtonCaption = null;
this.wizardAction1.CancelButtonCaption = null;
this.wizardAction1.Caption = "Template \'Wizard\'";
this.wizardAction1.Category = "WizardTemplates";
this.wizardAction1.ConfirmationMessage = null;
this.wizardAction1.Id = "Wizard1";
this.wizardAction1.ImageName = "XafariLogo";
this.wizardAction1.IsSizeable = false;
this.wizardAction1.ObjectType = typeof(Xafari.FeatureCenter.Wizards.WizardObject);
this.wizardAction1.Shortcut = null;
this.wizardAction1.StepsCount = 3;
this.wizardAction1.Tag = null;
this.wizardAction1.TargetObjectsCriteria = null;
this.wizardAction1.TargetViewId = null;
this.wizardAction1.TemplateContext = "Wizard";
this.wizardAction1.ToolTip = null;
this.wizardAction1.TypeOfView = null;
this.wizardAction1.Execute += new DevExpress.ExpressApp.Actions.PopupWindowShowActionExecuteEventHandler(this.wizardAction3_Execute);
//...
private void wizardAction3_Execute(object sender, PopupWindowShowActionExecuteEventArgs e)
{
  e.PopupWindow.View.ObjectSpace.CommitChanges();
  this.ObjectSpace.Refresh();
}

Private wizardAction1 As Xafari.Actions.WizardAction
'...
Me.wizardAction1.AcceptButtonCaption = Nothing
Me.wizardAction1.CancelButtonCaption = Nothing
Me.wizardAction1.Caption = "Template \'Wizard\'"
Me.wizardAction1.Category = "WizardTemplates"
Me.wizardAction1.ConfirmationMessage = Nothing
Me.wizardAction1.Id = "Wizard1"
Me.wizardAction1.ImageName = "XafariLogo"
Me.wizardAction1.IsSizeable = False
Me.wizardAction1.ObjectType = GetType(Xafari.FeatureCenter.Wizards.WizardObject)
Me.wizardAction1.Shortcut = Nothing
Me.wizardAction1.StepsCount = 3
Me.wizardAction1.Tag = Nothing
Me.wizardAction1.TargetObjectsCriteria = Nothing
Me.wizardAction1.TargetViewId = Nothing
Me.wizardAction1.TemplateContext = "Wizard"
Me.wizardAction1.ToolTip = Nothing
Me.wizardAction1.TypeOfView = Nothing
Me.wizardAction1.Execute += New DevExpress.ExpressApp.Actions.PopupWindowShowActionExecuteEventHandler(Me.wizardAction3_Execute)
'...
Private Sub wizardAction3_Execute(ByVal sender As Object, ByVal e As PopupWindowShowActionExecuteEventArgs)
  e.PopupWindow.View.ObjectSpace.CommitChanges()
  Me.ObjectSpace.Refresh()
End Sub

WizardAction properties:

  • ObjectType refers to the class that is used in the Wizard.
  • ShowDefaultWelcomeView flag specifies whether or not to add first step with the welcome message.
  • ShowDefaultGoodbyeView flag specifies whether or not to add first step with the final message.
  • TemplateContext specifies the template name for the Wizard's Views. Xafari supplies 4 Wizard templates for the TemplateContext values, it names are listed in Xafari.XafariTemplateContext class, see static fields "Wizard*".
  • StepsCount specifies the expected number of the Wizard steps without a welcome and final.

WizardAction events:

  • CreateWizardObject occurs when master initialized, it intended to create object for the execution of the Wizard.

Note:

To use Wizard in Web application, you need override CreateShowViewStrategy method, the following code demonstrates this:

  • c#
  • VB

public partial class FeatureCenterAspNetApplication : WebApplication
{
  //...
  protected override ShowViewStrategyBase CreateShowViewStrategy()
  {
    return new XafariShowViewStrategy(this);
  }
}

Public Partial Class FeatureCenterAspNetApplication
  Inherits WebApplication
  '...
  Protected Overrides Function CreateShowViewStrategy() As ShowViewStrategyBase
    Return New XafariShowViewStrategy(Me)
  End Function
End Class

For each detected WizardAction framework will automatically add the node to the Application Model. In addition, for each of the Wizard's stage the individual View will be created.

The image below shows the Wizard node in the Application Model:

wizards_3

Application Model provides the following operations with Wizard:

  • to customize captions and descriptions
  • to add and edit conditions for the jump between stages
  • to customize generates View for the each of the stages
  • to configure visibility and accessibility for the Wizard service buttons for the each of the stages
  • to add new stages or delete existing
  • to create new Wizard
  • to change logo

Each step node contains the criteria collection, the criterion defines a next step to jump.

The Wizard searches the criteria at the moment of transition from the current step. If the criteria are present, the Wizard sequentially checks each of them and searches the first criterion, which is true. After the true criterion is detected, the Wizard jumps to the step specified in the NextStep property. If any one criterion fails, the Wizard continues to the next step in the step list.

To add a criterion, focus step node and select Add|WizardNextStepCriteria from the context menu.

wizards_4

Image below shows Criterion 1 criterion. Criteria property specifies a criteria string supported by the Criteria Language Syntax. If it is True, then Wizard go to the Step 2 step, specified in the NextStep property.

wizards_5

If the Criterion 1 is not met, then the Wizard checks for the Criterion 2. If the Criteria string returns True, then Wizard go to the Step 3 step.

wizards_6

Else, the Wizard checks for the Criterion 3 and interprets its Criteria string.

wizards_7

If all criteria are proved to be False, the Wizard just proceeds to the next step in order, in our case it is Step 2.

Thus, the mechanism of criteria (conditions) of the transitions allows to design intricate scenarios for the Wizard.

To start Wizard you can also use SimpleAction (it requires to implement Execute event handler) and PopupWindowShowAction (it requires to implement CustomizePopupWindowParams and Execute events handlers). Examine WizardsViewController.cs file of the Feature Center installed with Xafari to learn on how to use SimpleAction or PopupWindowShowAction.

controller_CustomNextStep method demonstrates on how to implement a conditional jump logic.