Wizard Customization Overview
- 3 minutes to read
This document describes the structural elements of a Report Wizard that is used to create new reports and bind existing reports to data in the End-User Report Designer for WinForms.
Note
To learn how to customize the Report Wizard of the End-User Report Designer for WPF, see Wizard Customization Overview.
Wizard Structural Elements
The Data Source Wizard is used to bind an existing report to a data source. The Report wizard re-uses all Data Source wizard pages and adds extra pages to configure the report layout, as well as pages to create a label and inherited reports.
You can specify a custom list of labels available in the Label Report wizard. To do this, assign a path to an XML file containing custom label definitions to the static LabelWizardCustomization.ExternalLabelProductRepository property.
The Report wizard architecture is based on the MVP (Model-View-Presenter) design pattern. Every wizard page is defined by a presenter and view.
Model
Settings defined on the Report Wizard pages are stored by the ReportModel class.
These settings are translated to the XtraReportModel class that also stores data-related settings defined on the Data Source Wizard pages.
To save any additional data to a model object from custom wizard pages, use the XtraReportModel.Tag property.
When adding custom fields to this model, make sure that they implement the Equals method.
- Views define the Graphical User Interface of wizard pages. Each page view is an XtraUserControl descendant populated with data editors allowing an end-user to specify particular settings. Each page view should descend from the WizardViewBase class that implements the IWizardPageView interface.
Presenters define the logic behind a specific wizard page. Each presenter defines how a page is initialized, how the user-specified data is processed in the context of the current page as well as how settings specified by an end-user are submitted to the report model.
Each page presenter should descend from the abstract WizardPageBase<TView, TModel> class that implements the IWizardPage<TWizardModel> interface. The TView type parameter of this class allows you to associate a page presenter with an appropriate view.
The following documents list the default page views and presenters used in the Data Source and Report wizards.
Wizard Customization API
To define wizard customization logic for the Report and Data Source wizards of a WinForms End-User Report Designer, implement the IWizardCustomizationService interface. This interface contains the following four methods, which you need to implement.
- 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 execution of a wizard
- IWizardCustomizationService.TryCreateReport - implements custom logic to create a report based on settings accumulated in a report model during the execution of a wizard
Both the CustomizeDataSourceWizard and CustomizeReportWizard methods receive an object implementing the IWizardCustomization<TModel> interface. This interface exposes methods covering different aspects of wizard customization. For example, it allows you to register custom wizard pages and obtain various wizard resources from an internal container.
To apply your wizard customization logic to the End-User Report Designer for WinForms, pass an instance of your IWizardCustomizationService implementation to the report designer’s XRDesignMdiController.AddService method.
Code Examples
The following code examples illustrate the wizard customization API.