Skip to main content

Customize the Report/Data Source Wizard (ASP.NET MVC)

  • 15 minutes to read

This topic describes how to customize the Fullscreen Report Wizard and Fullscreen Data Source Wizard.

View Example: How to customize the Web Report Wizard

View Example: Reporting for Web (ASP.NET MVC, ASP.NET Core and Angular) - How to Use the Report Wizard Customization API and Hide Data Source Actions in Report Designer

Change the Predefined Wizard Settings

  1. Handle the client-side ASPxClientReportDesigner.CustomizeWizard event.
  2. Use the event argument’s Type property to identify the wizard type.
  3. Use the event argument’s Wizard property to access the wizard.
  4. Handle the wizard’s beforeInitialize event and use the argument’s state property to customize the predefined settings.

The following example demonstrates how to change the Report Wizard’s default page size and orientation:

<script type="text/javascript">
    function beforeInit(args) {
        // Customize the default page size and orientation.
        args.state.pageSetup.paperKind = "A4";
        args.state.pageSetup.landscape = true;
    }

    function CustomizeWizard(s, e) {
        if (e.Type === "ReportWizard") {
            e.Wizard.events.addHandler("beforeInitialize", beforeInit)
        }
    }
</script>

@Html.DevExpress().ReportDesigner(settings => {
    settings.Name = "ReportDesigner";
    settings.ClientSideEvents.CustomizeWizard = "CustomizeWizard";
    // ...
}).Bind(new DevExpress.XtraReports.UI.XtraReport()).GetHtml()

The resulting Specify Page Settings page:

Wizard Structural Elements

The FullscreenReportWizard and FullscreenDataSourceWizard classes implement the functionality for the Report Wizard and Data Source Wizard, respectively.

The wizard architecture includes the following main elements:

Wizard Customization Overview

To customize the Report/Data Source Wizard, handle the client-side ASPxClientReportDesigner.CustomizeWizard event. The event’s argument has the following properties:

  • Type - identifies the wizard type.
  • Wizard - provides access to the wizard. Use the Wizard‘s events collection to handle wizard events.

The following table lists wizard events and describes how to use them to customize the wizard:

Wizard Event

Description

beforeInitialize

Occurs before the FullscreenReportWizard.initialize/FullscreenDataSourceWizard.initialize method is called.

Handle this event to customize the predefined settings for the wizard’s global state. For instance, you can change the default page settings, the default report type, etc.

afterInitialize

Occurs after the FullscreenReportWizard.initialize/FullscreenDataSourceWizard.initialize method is called.

Handle this event to change the page count and / or sequence. For instance, you can remove a specific wizard page or register a new page.

beforePageInitialize

Occurs before the page’s initialize method is called.

Handle this event to customize the page’s content and state. For instance, you can remove a specific element from the start page or remove a specific section from other pages.

afterPageInitialize

Occurs after the page’s initialize method is called.

Handle this event to customize the page’s settings to display in the UI.

beforeFinish

Occurs before the wizard’s onFinish method is called.

Handle this event to customize the resulting wizard settings and generate a report/data source based on them. For instance, you can specify your custom report title if a user did not specify it.

afterFinish

Occurs after the wizard’s onFinish method is called.

Handle this event to customize the generated report. For instance, you can change the report name and display name.

Each fullscreen page except the start page has its own events listed below.

Page Event

Description

beforeSectionInitialize

Occurs before the section’s initialize method is called.

Handle this event to customize the section’s content and state. For instance, you can remove a specific element or customize the section’s options.

afterSectionInitialize

Occurs after the page’s initialize method is called.

Handle this event to customize the section’s settings to display in the UI. For instance, you can check a specific option (a data member, field or data connection).

<script type="text/javascript">
    function beforeSectionInit(args) {
        // ...
    }
    function beforePageInit(args) {
        args.page.events.addHandler("beforeSectionInitialize", beforeSectionInit);
    }

    function CustomizeWizard(s, e) {
        if(e.Type === "ReportWizard") {
            e.Wizard.events.addHandler("beforePageInitialize", beforePageInit)
        }
    }
</script>

@Html.DevExpress().ReportDesigner(settings => {
    settings.Name = "ReportDesigner";
    settings.ClientSideEvents.CustomizeWizard = "CustomizeWizard";
    // ...
}).Bind(new DevExpress.XtraReports.UI.XtraReport()).GetHtml()

The following image illustrates the order in which events are raised:

Report Wizard Pages

The table below lists the Fullscreen Report Wizard’s pages, their IDs, and the corresponding classes.

Page Name

Page ID

Class

Select Report Type

FullscreenReportWizardPageId.SelectReportTypePage

SelectReportTypePage

Select Data Source

FullscreenReportWizardPageId.SelectDataSourcePage

SelectDataSourcePage

Specify Data Source Settings (Database)

FullscreenReportWizardPageId.SpecifySqlDataSourceSettingsPage

SpecifySqlDataSourceSettingsPage

Specify Data Source Settings (JSON)

FullscreenReportWizardPageId.SpecifyJsonDataSourceSettingsPage

SpecifyJsonDataSourceSettingsPage

Specify Data Source Settings (Object Data Source)

FullscreenReportWizardPageId.SpecifyObjectDataSourceSettingsPage

SpecifyObjectDataSourceSettingsPage

Define Report Layout

FullscreenReportWizardPageId.DefineReportLayoutPage

DefineReportLayoutPage

Specify Page Settings

FullscreenReportWizardPageId.SpecifyPageSettingsPage

SpecifyPageSettingsPage

Specify Page Settings (Label)

FullscreenReportWizardPageId.SpecifyLabelSettingsPage

SpecifyLabelSettingsPage

The following image shows the wizard’s navigation structure:

Page Sections

Each Report Wizard page except the Select Report Type page consists of sections. The tables below list the page sections.

Note

The ‘Specify Data Source Settings’ Page (Object Data Source) page is used only in full screen mode and has private section identifiers.

'Specify Page Settings' Page (Label)

Data Source Wizard Pages

The following table lists the Fullscreen Data Source Wizard’s pages, their IDs, and the corresponding classes:

Page Name

Page ID

Class

Select Data Source Type

FullscreenDataSourceWizardPageId.ChooseDataSourceTypePage

ChooseDataSourceTypePage

Specify Data Source Settings (Database)

FullscreenDataSourceWizardPageId.SpecifySqlDataSourceSettingsPage

SpecifySqlDataSourceSettingsPage

Specify Data Source Settings (JSON)

FullscreenDataSourceWizardPageId.SpecifyJsonDataSourceSettingsPage

SpecifyJsonDataSourceSettingsPage

Specify Data Source Settings (Object)

FullscreenDataSourceWizardPageId.SpecifyObjectDataSourceSettingsPage

SpecifyObjectDataSourceSettingsPage

Page Sections

The Specify Data Source Settings page contains the sections listed below depending on the selected data source type.

Remove a Page

  1. Handle the wizard’s afterInitialize event.
  2. Use the event argument’s wizard property to access the pageFactory object. Call this object’s unregisterMetadata method and pass the corresponding FullscreenReportWizardPageId/FullscreenDataSourceWizardPageId enumeration value as the parameter. This removes the page’s metadata from the factory and hides the page from the navigation panel.
  3. Use the event argument’s wizard property to access the iterator object and override its getNextPageId method to remove the page from the navigation logic.
  4. (Optional) Handle the wizard’s beforeInitialize event and use the argument’s state property to update the wizard’s global state. This step is required if you want to create a report/data source with settings that differ from the page’s default settings.

The following example demonstrates how to hide the Select Data Source page from the Report Wizard and enable users to create SQL data sources only:

<script type="text/javascript">
   function beforeInit(args) {
       args.state.dataSourceType = 1;
   }

   function afterInit(args) {
       // Remove the "Select Data Source" page's metadata from the factory.
       args.wizard.pageFactory.unregisterMetadata(DevExpress.Reporting.Designer.Wizard.FullscreenReportWizardPageId.SelectDataSourcePage);
       // Override the navigation logic to skip the "Select Data Source" page.
       var defaultGetNextPageId = args.wizard.iterator.getNextPageId;
       args.wizard.iterator.getNextPageId = function (pageId) {
           if (pageId === DevExpress.Reporting.Designer.Wizard.FullscreenReportWizardPageId.SelectReportTypePage) {
               return DevExpress.Reporting.Designer.Wizard.FullscreenReportWizardPageId.SpecifySqlDataSourceSettingsPage;
           } else {
               return defaultGetNextPageId.apply(this, [pageId]);
           }
       }
   }

   function CustomizeWizard(s, e) {
       if (e.Type === "ReportWizard") {
           e.Wizard.events.addHandler("beforeInitialize", beforeInit)
           e.Wizard.events.addHandler("afterInitialize", afterInit)
       }
   }
</script>

@Html.DevExpress().ReportDesigner(settings => {
    settings.Name = "ReportDesigner";
    settings.ClientSideEvents.CustomizeWizard = "CustomizeWizard";
    // ...
}).Bind(new DevExpress.XtraReports.UI.XtraReport()).GetHtml()

The resulting Report Wizard:

Remove a Page Section

  1. Handle the wizard’s beforePageInitialize event.
  2. Use the event argument’s pageId property to identify a wizard page. Compare this property value with the FullscreenReportWizardPageId/FullscreenDataSourceWizardPageId enumeration values.
  3. Use the event argument’s page property to access a page.
  4. Call the page’s unregisterSection method to hide a specic page section. Pass the corresponding FullscreenReportWizardSectionId/FullscreenDataSourceWizardSectionId value as the method parameter.
  5. Use the page’s setSectionPosition method to arrange the remaining sections within the page.
  6. Override the page’s getNextSectionId method to skip the removed section in the navigation logic.

The following example demonstrates how to hide the Select Data Source page’s section that displays available data sources:

<script type="text/javascript">
   function beforePageInit(args) {
       // Identify the "Select Data Source" page.
       if (args.pageId === DevExpress.Reporting.Designer.Wizard.FullscreenReportWizardPageId.SelectDataSourcePage) {
           // Remove the page's section that displays available data sources.
           args.page.unregisterSection(DevExpress.Reporting.Designer.Wizard.FullscreenReportWizardSectionId.ChooseAvailableDataSourcePage);
           // Make the "Select data source type" section occupy the entire page.
           args.page.setSectionPosition(DevExpress.Reporting.Designer.Wizard.FullscreenReportWizardSectionId.ChooseDataSourceTypePage);
           // Override the navigation logic to skip the removed section.
           args.page.getNextSectionId = function(sectionId) {
               if(!sectionId) return DevExpress.Reporting.Designer.Wizard.FullscreenReportWizardSectionId.ChooseDataSourceTypePage;
           }
       }
   }

   function CustomizeWizard(s, e) {
       if(e.Type === "ReportWizard") {
           e.Wizard.events.addHandler("beforePageInitialize", beforePageInit)
       }
   }
</script>

@Html.DevExpress().ReportDesigner(settings => {
    settings.Name = "ReportDesigner";
    settings.ClientSideEvents.CustomizeWizard = "CustomizeWizard";
    // ...
}).Bind(new DevExpress.XtraReports.UI.XtraReport()).GetHtml()

The resulting Select Data Source page:

Hide Report Types

  1. Handle the wizard’s beforePageInitialize event.
  2. Compare the event argument’s pageId property value with the FullscreenReportWizardPageId.SelectReportTypePage value to identify the Select Report Type page.
  3. Use the target page’s typeItems collection to hide unnecessary report types.

The following example demonstrates how to remove the Empty Report and Label Report types:

<script type="text/javascript">
    function beforePageInit(args) {
        if(args.pageId === DevExpress.Reporting.Designer.Wizard.FullscreenReportWizardPageId.SelectReportTypePage) {
            args.page.typeItems.splice(0, 1);
            args.page.typeItems.pop();
        }
    }

    function CustomizeWizard(s, e) {
        if(e.Type === "ReportWizard") {
            e.Wizard.events.addHandler("beforePageInitialize", beforePageInit)
        }
    }
</script>

@Html.DevExpress().ReportDesigner(settings => {
    settings.Name = "ReportDesigner";
    settings.ClientSideEvents.CustomizeWizard = "CustomizeWizard";
    // ...
}).Bind(new DevExpress.XtraReports.UI.XtraReport()).GetHtml()

The resulting Select Report Type page:

Hide the “No Data” Item

  1. Handle the wizard’s beforePageInitialize event.
  2. Compare the event argument’s pageId property value with the FullscreenReportWizardPageId.SelectReportTypePage value to identify the Select Data Source page.
  3. Handle this page’s beforeSectionInitialize event.
  4. In the beforeSectionInitialize event handler, compare the event argument’s sectionId property value with the FullscreenReportWizardSectionId.ChooseDataSourceTypePage value to identify the section that allows users to select the data source type.
  5. Use the section’s typeItems collection to hide the No Data item.
<script type="text/javascript">
    function beforeSectionInit(args) {
        if(args.sectionId === DevExpress.Reporting.Designer.Wizard.FullscreenReportWizardSectionId.ChooseDataSourceTypePage) {
            args.section.typeItems.pop();
        }
    }
    function beforePageInit(args) {
        if(args.pageId === DevExpress.Reporting.Designer.Wizard.FullscreenReportWizardPageId.SelectDataSourcePage) {
            args.page.events.addHandler("beforeSectionInitialize", beforeSectionInit);
        }
    }

    function CustomizeWizard(s, e) {
        if(e.Type === "ReportWizard") {
            e.Wizard.events.addHandler("beforePageInitialize", beforePageInit)
        }
    }
</script>

@Html.DevExpress().ReportDesigner(settings => {
    settings.Name = "ReportDesigner";
    settings.ClientSideEvents.CustomizeWizard = "CustomizeWizard";
    // ...
}).Bind(new DevExpress.XtraReports.UI.XtraReport()).GetHtml()

The resulting Select Data Source page:

Prohibit New Data Source Creation

  1. Handle the wizard’s afterInitialize event.
  2. Use the event argument’s wizard property to access the pageFactory object. Call this object’s unregisterMetadata method to remove the Specify Data Source Settings (Database) and Specify Data Source Settings (JSON) pages.
  3. Use the event argument’s wizard property to access the iterator object and override its getNextPageId method to skip the removed page in the navigation logic.
  4. Handle the wizard’s beforePageInitialize event.
  5. Use the event argument’s pageId property to identify the Select Data Source page.
  6. Use the event argument’s page property to remove the section that allows users to select the data source type and make the remaining section occupy the entire page.
  7. Handle the beforeSectionInitialize event and disable the remaining section’s canCreateNew option.
<script type="text/javascript">
    function beforeSectionInit(args) {
        // Indetify the section that allows users to select available data sources.
        if (args.sectionId === DevExpress.Reporting.Designer.Wizard.FullscreenReportWizardSectionId.ChooseAvailableDataSourcePage) {   
            // Disable the capability to create new data sources (hide the radio group with a choice).             
            args.section.canCreateNew(false);
        }
    }

    function beforePageInit(args) {
        // Identify the "Select Data Source" page.
        if(args.pageId === DevExpress.Reporting.Designer.Wizard.FullscreenReportWizardPageId.SelectDataSourcePage) {
            // Remove the "Select the data source type" section.
            args.page.unregisterSection(DevExpress.Reporting.Designer.Wizard.FullscreenReportWizardSectionId.ChooseDataSourceTypePage);
            // Make the remaining section occupy the entire page.
            args.page.setSectionPosition(DevExpress.Reporting.Designer.Wizard.FullscreenReportWizardSectionId.ChooseAvailableDataSourcePage);
            // Handle the page's beforeSectionInitialize event.
            args.page.events.addHandler("beforeSectionInitialize", beforeSectionInit)
            // // Override the navigation logic to skip the removed section.
            args.page.getNextPageId = function(pageId) {
                if(!pageId) return DevExpress.Reporting.Designer.Wizard.FullscreenReportWizardSectionId.ChooseAvailableDataSourcePage;
            }
        }
    }

    function afterInit(args) {
        // Remove the "Specify Data Source Settings (Database)" page's metadata from the factory.
        args.wizard.pageFactory.unregisterMetadata(DevExpress.Reporting.Designer.Wizard.FullscreenReportWizardPageId.SpecifySqlDataSourceSettingsPage);
        // Remove the "Specify Data Source Settings (JSON)" page's metadata from the factory.
        args.wizard.pageFactory.unregisterMetadata(DevExpress.Reporting.Designer.Wizard.FullscreenReportWizardPageId.SpecifyJsonDataSourceSettingsPage);
        // Override the navigation logic to skip the removed pages.
        var defaultGetNextPageId = args.wizard.iterator.getNextPageId;
        args.wizard.iterator.getNextPageId = function (pageId) {
            if (pageId === DevExpress.Reporting.Designer.Wizard.FullscreenReportWizardPageId.SelectDataSourcePage) {
                return DevExpress.Reporting.Designer.Wizard.FullscreenReportWizardPageId.DefineReportLayoutPage;
            } else {
                return defaultGetNextPageId.apply(this, [pageId]);
            }
        }
    }

    function CustomizeWizard(s, e) {
        if(e.Type === "ReportWizard") {
            e.Wizard.events.addHandler("afterInitialize", afterInit)
            e.Wizard.events.addHandler("beforePageInitialize", beforePageInit)
        }
    }
</script>

@Html.DevExpress().ReportDesigner(settings => {
    settings.Name = "ReportDesigner";
    settings.ClientSideEvents.CustomizeWizard = "CustomizeWizard";
    // ...
}).Bind(new DevExpress.XtraReports.UI.XtraReport()).GetHtml()

The resulting Report Wizard:

Customize Color Schemes

  1. Handle the wizard’s beforePageInitialize event.
  2. Compare the event argument’s pageId property value with the FullscreenReportWizardPageId.SpecifyPageSettingsPage value to identify the Specify Page Settings page.
  3. Handle this page’s beforeSectionInitialize event.
  4. In the beforeSectionInitialize event handler, compare the event argument’s sectionId property value with the FullscreenReportWizardSectionId.ConfigurePageSettingsPage value to identify the section that allows users to define page settings and a report color scheme.
  5. Use the section’s removeColorScheme or removeAllColorSchemes method to remove a specific scheme or all schemes. Use the addColorScheme method to register a custom color scheme.
<script type="text/javascript">
    function beforeSectionInit(args) {
        if (args.sectionId === DevExpress.Reporting.Designer.Wizard.FullscreenReportWizardSectionId.ConfigurePageSettingsPage) {
            // Remove specific color schemes and the capability to specify a custom scheme.
            args.section.removeColorScheme("Grey", "Jeans Blue", "Light Green", "Custom");
            // Uncomment this line to remove all color schemes.
            // args.section.removeAllColorSchemes();
            args.section.addColorScheme("My Color", "255, 96, 110, 246");
        }
    }
    function beforePageInit(args) {
        if(args.pageId === DevExpress.Reporting.Designer.Wizard.FullscreenReportWizardPageId.SpecifyPageSettingsPage) {
            args.page.events.addHandler("beforeSectionInitialize", beforeSectionInit);
        }
    }

    function CustomizeWizard(s, e) {
        if(e.Type === "ReportWizard") {
            e.Wizard.events.addHandler("beforePageInitialize", beforePageInit)
        }
    }
</script>

@Html.DevExpress().ReportDesigner(settings => {
    settings.Name = "ReportDesigner";
    settings.ClientSideEvents.CustomizeWizard = "CustomizeWizard";
    // ...
}).Bind(new DevExpress.XtraReports.UI.XtraReport()).GetHtml()

The resulting color scheme set:

Change the Predefined Page Settings

  1. Handle the wizard’s afterPageInitialize event.
  2. Use the event argument’s pageId property to identify a wizard page. Compare this property value with the FullscreenReportWizardPageId/FullscreenDataSourceWizardPageId enumeration values.
  3. Handle the page’s afterSectionInitialize event.
  4. In the afterSectionInitialize event handler, compare the event argument’s sectionId property value with the FullscreenReportWizardSectionId/FullscreenDataSourceWizardSectionId value.
  5. Use the section’s documented API to customize the page’s predefined settings.

The following example demonstrates how to select all data members and fields on the Define Report Layout page:

<script type="text/javascript">
    function afterSectionInit(args) {
        if (args.sectionId === DevExpress.Reporting.Designer.Wizard.FullscreenReportWizardSectionId.SelectDataMembersPage_Members) {
            args.section.selectAllDataFields();

            // Uncomment these lines to select specific data fields.
            //args.section.selectDataField("Categories.CategoryID")
            //args.section.selectDataField("Categories.CategoryName")

            // Uncomment this line to select the 'Products' table's fields.
            //args.section.selectDataFields("Products")
        }
    }
    function afterPageInit(args) {
        if(args.pageId === DevExpress.Reporting.Designer.Wizard.FullscreenReportWizardPageId.DefineReportLayoutPage) {
            args.page.events.addHandler("afterSectionInitialize", afterSectionInit);
        }
    }

    function CustomizeWizard(s, e) {
        if(e.Type === "ReportWizard") {
            e.Wizard.events.addHandler("afterPageInitialize", afterPageInit)
        }
    }
</script>

@Html.DevExpress().ReportDesigner(settings => {
    settings.Name = "ReportDesigner";
    settings.ClientSideEvents.CustomizeWizard = "CustomizeWizard";
    // ...
}).Bind(new DevExpress.XtraReports.UI.XtraReport()).GetHtml()

The Define Report Layout page’s initial state:

Customize the Wizard Result

  1. Handle the wizard’s beforeFinish event.
  2. Use the event argument’s wizardModel property to customize the resulting wizard settings. These settings are sent to the server side to generate a report/data source.
  3. Use the event argument’s state property to read specific values that a user entered on wizard pages or to pass the updated wizard settings to the afterFinish event.
  4. Handle the wizard’s afterFinish event.
  5. Use the event argument’s wizardResult to access the generated report and customize its properties.
  6. Use the event argument’s state property to read values from the global state.

The following example demonstrates how to:

  • specify a custom report title if a user did not specify it;
  • update the resulting report’s name and display name based on the report title.
<script type="text/javascript">
    function beforeFinish(s) {          
        if(!s.wizardModel.ReportTitle) {
            s.wizardModel.ReportTitle = "My Report"
            s.state.reportTitle = "My Report "
        }
    }
    function afterFinish(s) {
        s.wizardResult.name(s.state.reportTitle.replace(/ /g, ""))
        s.wizardResult.displayName(s.state.reportTitle)
    }
    function CustomizeWizard(s, e) {
        if(e.Type === "ReportWizard") {
            e.Wizard.events.addHandler("beforeFinish", beforeFinish)
            e.Wizard.events.addHandler("afterFinish", afterFinish)
        }
    }
</script>

@Html.DevExpress().ReportDesigner(settings => {
    settings.Name = "ReportDesigner";
    settings.ClientSideEvents.CustomizeWizard = "CustomizeWizard";
    // ...
}).Bind(new DevExpress.XtraReports.UI.XtraReport()).GetHtml()

The resulting report:

Report Wizard Customization API

The Report Wizard Customization API allows you to specify a custom template to generate a report, and make adjustments to the generated report (such as report branding, header/footer formatting, font settings) in the Report Wizard.

For this, you should register your own implementation of the ReportWizardCustomizationService class.

The CustomizeReportTypeList and CustomizeReportTypeListAsync methods allow you to add custom report types and remove existing report types from the Select Report Type wizard page, as the following image illustrates:

CustomizeReportTypeList Sample Result

View Example: Reporting for Web (ASP.NET MVC, ASP.NET Core and Angular) - How to Use the Report Wizard Customization API and Hide Data Source Actions in Report Designer