Wizard Customization Overview

• Aug 18, 2023
• 4 minutes to read

The Report Wizard allows you to create new reports and customize existing ones in the End-User Report Designer. The Report Wizard includes Data Source Wizard pages for binding a report to data and adds extra pages for configuring the report layout.

Wizard Structural Elements

The Wizard architecture conforms to the MVP (Model-View-Presenter) design pattern and includes the following structural elements:

• Presenter

  A page Presenter defines the logic to initialize a page, process data on this page and pass the data between a View and Model.

  Each page Presenter should descend from the abstract WizardPageBase<TView, TModel> class (from the DevExpress.Data.WizardFramework namespace). The TView and TModel type parameters allow you to associate the page Presenter with an appropriate View and Model.

  C#

  class MyCustomPage<TModel> : WizardPageBase<IMyPageView, TModel> {
      // ...
  }
  

  VB.NET

  Friend Class MyCustomPage(Of TModel)
      Inherits WizardPageBase(Of Views.IMyCustomPageView, TModel)
      ' ...
  End Class
  

• View

  A page View relies on the MVVM design pattern. Each View consists of a ViewModel that processes data that is displayed in the user interface and a XAML template that defines the page’s visual appearance and layout.

  A ViewModel should inherit the WizardPageBase class (from the DevExpress.Xpf.DataAccess.DataSourceWizard namespace) and implement the corresponding View interface.

  C#

  public class MyPageViewModel : DevExpress.Xpf.DataAccess.DataSourceWizard.WizardPageBase, IMyPageView {
     // ...
  }
  

  VB.NET

  Public Class MyPageViewModel
      Inherits DevExpress.Xpf.DataAccess.DataSourceWizard.WizardPageBase
      Implements IMyPageView
     ' ...
  End Class
  

  The XAML template should reference the corresponding ViewModel type by a Key.

  XAML

  <DataTemplate x:Key="{x:Type dxrew:MyPageViewModel }"> 
    <Label Content="Page Content" /> 
  </DataTemplate>
  

• Model

  The ReportModel class stores settings defined on the Report Wizard pages. The XtraReportModel class accumulates these settings and data-related settings specified on the Data Source Wizard pages.

  Override the Equals method to take all the model settings into account when you create a model descendant and add custom fields to it.

You can create a custom wizard page using the following approaches:

• Provide your custom appearance for a specific wizard page by creating a XAML template with the required ViewModel type referenced by a Key. The specified Key is used to locate the corresponding template automatically.

• Customize an existing wizard page by inheriting from its Presenter and View objects.

  The following documents list the default page Presenters and Views used in the Data Source and Report wizards:

  • Data Source Wizard Pages
  • Report Wizard Pages
• Create a custom wizard page from scratch by implementing a page Presenter, View, and Model (optional). Inherit the page Presenter from the abstract WizardPageBase<TView, TModel> class (the DevExpress.Data.WizardFramework namespace). To implement the View, inherit a ViewModel from the WizardPageBase class (the DevExpress.Xpf.DataAccess.DataSourceWizard namespace) and write a XAML template. To add custom fields to the Model, create the XtraReportModel class descendant.

Wizard Customization API

You can customize the Report and/or Data Source Wizard by implementing the IWizardCustomizationService interface, which provides the following four methods:

• IWizardCustomizationService.CustomizeDataSourceWizard - Provides the customization logic to the Data Source Wizard.
• IWizardCustomizationService.CustomizeReportWizard - Provides the customization logic to the Report Wizard.
• IWizardCustomizationService.TryCreateDataSource - Implements custom logic to create a data source based on settings accumulated in a data source model during the Wizard execution.
• IWizardCustomizationService.TryCreateReport - Implements custom logic to create a report based on settings accumulated in a report model during the Wizard execution.

Both the CustomizeDataSourceWizard and CustomizeReportWizard methods receive two arguments:

• The first argument (that has the DataSourceWizardCustomizationModel or ReportWizardCustomizationModel type, respectively) allows you to specify the first wizard page and the corresponding report and data source models.
• The second argument is a IntegrityContainer class descendant that allows you to register custom page Presenter and View objects. For instance, use the ViewModelSourceIntegrityContainer class which provides additional methods to register ViewModels.

To apply the wizard customization, assign your custom IWizardCustomizationService instance to the ReportDesignerBase.ServicesRegistry property.

Code Examples

The following code examples demonstrate how to customize the Report Wizard:

• Remove Data Providers from the Report Wizard
• Register a Custom Page in the Report Wizard