Create Editors for Custom Parameter Types in an ASP.NET MVC Application

• Dec 18, 2023
• 8 minutes to read

This topic explains how to implement a custom parameter type, add custom type parameters to a report, and create a custom editor for the Document Viewer’s Parameters Panel. The custom parameter type defines an email address.

Create a Custom Parameter Type and a Converter

Define a CustomParameterType class with the Value property. Implement a CustomParameterTypeConverter converter to display a parameter value in a document.

CustomParameterType.cs

using System;
using System.ComponentModel;
using System.Globalization;

namespace CustomParameterEditorAspNetMvcExample
{
    [TypeConverter(typeof(CustomParameterTypeConverter))]
    public class CustomParameterType
    {
        public string Value { get; set; }
        public override string ToString()
        {
            return Value;
        }
    }

    public class CustomParameterTypeConverter : TypeConverter
    {
        public override object ConvertTo(ITypeDescriptorContext context,
            CultureInfo culture, object value, Type destinationType)
        {
            if (destinationType == typeof(string))
            {
                return ((CustomParameterType)value).Value;
            }
            return base.ConvertTo(context, culture, value, destinationType);
        }
        public override bool CanConvertTo(ITypeDescriptorContext context,
            Type destinationType)
        {
            return destinationType == typeof(string) ||
                base.CanConvertTo(context, destinationType);
        }

        public override bool CanConvertFrom(ITypeDescriptorContext context, Type sourceType)
        {
            return sourceType == typeof(string) || base.CanConvertFrom(context, sourceType);
        }
        public override object ConvertFrom(ITypeDescriptorContext context,
            CultureInfo culture, object value)
        {
            var valueString = value as string;
            if (valueString != null)
            {
                return new CustomParameterType { Value = valueString };
            }
            return base.ConvertFrom(context, culture, value);
        }
    }
}

CustomParameterType.vb

Imports System
Imports System.ComponentModel
Imports System.Globalization

<TypeConverter(GetType(CustomParameterTypeConverter))>
Public Class CustomParameterType
    Public Property Value() As String
    Public Overrides Function ToString() As String
        Return Value
    End Function
End Class

Public Class CustomParameterTypeConverter
        Inherits TypeConverter

        Public Overrides Function ConvertTo(
                                           ByVal context As ITypeDescriptorContext,
                                           ByVal culture As CultureInfo,
                                           ByVal value As Object,
                                           ByVal destinationType As Type) As Object
            If destinationType Is GetType(String) Then
                Return DirectCast(value, CustomParameterType).Value
            End If
            Return MyBase.ConvertTo(context, culture, value, destinationType)
        End Function
        Public Overrides Function CanConvertTo(
                                              ByVal context As ITypeDescriptorContext,
                                              ByVal destinationType As Type
                                              ) As Boolean
            Return destinationType Is GetType(String) OrElse
                MyBase.CanConvertTo(context, destinationType)
        End Function

        Public Overrides Function CanConvertFrom(
                                                ByVal context As ITypeDescriptorContext,
                                                ByVal sourceType As Type
                                                ) As Boolean
            Return sourceType Is GetType(String) OrElse
                MyBase.CanConvertFrom(context, sourceType)
        End Function
        Public Overrides Function ConvertFrom(
                                             ByVal context As ITypeDescriptorContext,
                                             ByVal culture As CultureInfo,
                                             ByVal value As Object
                                             ) As Object
            Dim valueString = TryCast(value, String)
            If valueString IsNot Nothing Then
                Return New CustomParameterType With {.Value = valueString}
            End If
            Return MyBase.ConvertFrom(context, culture, value)
        End Function
End Class

Implement a Custom Parameter Serializer

A serializer is necessary to pass data from the client to the controller on the server and store the parameter value in report definition files.

CustomDataSerializer.cs

using DevExpress.XtraReports.Native;

namespace CustomParameterEditorAspNetMvcExample
{
    public class CustomDataSerializer : IDataSerializer
    {
        public const string Name = "myCustomDataSerializer";

        public bool CanDeserialize(string value, string typeName, object extensionProvider)
        {
            return typeName == typeof(CustomParameterType).FullName;
        }

        public bool CanSerialize(object data, object extensionProvider)
        {
            return data is CustomParameterType;
        }

        public object Deserialize(string value, string typeName, object extensionProvider)
        {
            if (typeName == typeof(CustomParameterType).FullName)
            {
                return new CustomParameterType { Value = value };
            }
            return null;
        }

        public string Serialize(object data, object extensionProvider)
        {
            var parameter = data as CustomParameterType;
            return parameter != null ? parameter.Value : null;
        }
    }
}

CustomDataSerializer.vb

Imports DevExpress.XtraReports.Native

Public Class CustomDataSerializer
    Implements IDataSerializer

    Public Const Name As String = "myCustomDataSerializer"

    Public Function CanDeserialize(
                                  ByVal value As String, ByVal typeName As String,
                                  ByVal extensionProvider As Object
                                  ) As Boolean Implements IDataSerializer.CanDeserialize
        Return typeName = GetType(CustomParameterType).FullName
    End Function

    Public Function CanSerialize(
                                ByVal data As Object,
                                ByVal extensionProvider As Object
                                ) As Boolean Implements IDataSerializer.CanSerialize
        Return TypeOf data Is CustomParameterType
    End Function

    Public Function Deserialize(
                               ByVal value As String,
                               ByVal typeName As String,
                               ByVal extensionProvider As Object
                               ) As Object Implements IDataSerializer.Deserialize
        If typeName = GetType(CustomParameterType).FullName Then
            Return New CustomParameterType With {.value = value}
        End If
        Return Nothing
    End Function

    Public Function Serialize(
                             ByVal data As Object,
                             ByVal extensionProvider As Object
                             ) As String Implements IDataSerializer.Serialize
        Dim parameter = TryCast(data, CustomParameterType)
        Return If(parameter IsNot Nothing, parameter.Value, Nothing)
    End Function
End Class

Register the Custom Parameter Serializer at Startup

Add the following code to the Global.asax file to register the CustomDataSerializer service in the application:

Global.asax.cs

public class MvcApplication : System.Web.HttpApplication {
    protected void Application_Start() {
    // ...
        DevExpress.XtraReports.Native.SerializationService.RegisterSerializer(
            CustomDataSerializer.Name, new CustomDataSerializer());
            // ...
    }
    // ...
}

Global.asax.vb

Public Class MvcApplication
    Inherits System.Web.HttpApplication
    ' ...
    Protected Sub Application_Start()
    ' ...
        DevExpress.XtraReports.Native.SerializationService.RegisterSerializer(
                CustomParameterEditorAspNetMvcExample.CustomDataSerializer.Name,
                New CustomParameterEditorAspNetMvcExample.CustomDataSerializer())
                ' ...
    End Sub
    ' ...
End Class

Add the Custom Parameter Type to the Report Designer

Handle the Report Designer’s Init event to add a custom parameter type (Custom Type) and specify the custom-parameter-editor HTML template as the parameter’s editor. The editor template is based on the dxTextBox editor.

Designer.cshtml

@model DevExpress.XtraReports.UI.XtraReport

<script type="text/html" id="custom-parameter-editor">
    <div data-bind="dxTextBox: { value: value }, 
         dxValidator: { validationRules: [{ type: 'email', message: 'Email is not valid.' }]}">
    </div>
</script>
<script type="text/javascript">
    function reportDesignerInit(sender, e) {
        var editor = { header: "custom-parameter-editor" };
        sender.AddParameterType({
            displayValue: "Custom Type",
            specifics: "custom",
            value: "@typeof(CustomParameterEditorAspNetMvcExample.CustomParameterType).FullName",
            valueConverter: function(valueObj) { return valueObj; }
        }, editor);
    }
    <!-- ... -->
    }
</script>

@Html.DevExpress().ReportDesigner(settings =>
{
    settings.Name = "ReportDesigner1";
    settings.ClientSideEvents.Init = "reportDesignerInit";
    <!-- ... -->
}).Bind(Model).GetHtml()

Designer.vbhtml

@ModelType DevExpress.XtraReports.UI.XtraReport

<script type="text/html" id="custom-parameter-editor">
    <div data-bind="dxTextBox: { value: value },
         dxValidator: { validationRules: [{ type: 'email', message: 'Email is not valid.' }]}">
    </div>
</script>
<script type="text/javascript">
    function reportDesignerInit(sender, e) {
        var editor = { header: "custom-parameter-editor" };
        sender.AddParameterType({
            displayValue: "Custom Type",
            specifics: "custom",
            value: "@GetType(CustomParameterEditorAspNetMvcExample.CustomParameterType).FullName",
            valueConverter: function(valueObj) { return valueObj; }
        }, editor);
    }
    <!-- ... -->
    }
</script>

@Html.DevExpress().ReportDesigner(
    Sub(settings)
        settings.Name = "ReportDesigner1"
        settings.ClientSideEvents.Init = "reportDesignerInit"
        <!-- ... -->
    End Sub).Bind("Model").GetHtml()

Run the project and open the Report Designer. Save the empty report to a file (Template.repx). This file contains a serialized extension that references the custom type serializer. You can use the Template.repx file as a new report template.

Use Template for New Reports

All reports created with the New command in the Report Designer should be based on the custom template with the custom type serializer. Otherwise, a custom report parameter causes an error when the report is opened.

Modify the New command so that it opens a Template report:

Designer.cshtml

@model DevExpress.XtraReports.UI.XtraReport

<script type="text/html" id="custom-parameter-editor">
    <div data-bind="dxTextBox: { value: value }, 
         dxValidator: { validationRules: [{ type: 'email', message: 'Email is not valid.' }]}">
    </div>
</script>
<script type="text/javascript">
    function reportDesignerInit(sender, e) {
        var editor = { header: "custom-parameter-editor" };
        sender.AddParameterType({
            displayValue: "Custom Type",
            specifics: "custom",
            value: "@typeof(CustomParameterEditorAspNetMvcExample.CustomParameterType).FullName",
            valueConverter: function(valueObj) { return valueObj; }
        }, editor);
    }
    function onCustomizeMenuActions(s, e) {
        var newReportAction = e.GetById(DevExpress.Reporting.Designer.Actions.ActionId.NewReport);
        if (newReportAction) {
            newReportAction.clickAction = function () {
                s.OpenReport("TemplateReport");
            }
        }
    }
</script>

@Html.DevExpress().ReportDesigner(settings =>
{
    settings.Name = "ReportDesigner1";
    settings.ClientSideEvents.Init = "reportDesignerInit";
    settings.ClientSideEvents.CustomizeMenuActions = "onCustomizeMenuActions";
}).Bind(Model).GetHtml()

Designer.vbhtml

@ModelType DevExpress.XtraReports.UI.XtraReport

<script type="text/html" id="custom-parameter-editor">
    <div data-bind="dxTextBox: { value: value },
         dxValidator: { validationRules: [{ type: 'email', message: 'Email is not valid.' }]}">
    </div>
</script>
<script type="text/javascript">
    function reportDesignerInit(sender, e) {
        var editor = { header: "custom-parameter-editor" };
        sender.AddParameterType({
            displayValue: "Custom Type",
            specifics: "custom",
            value: "@GetType(CustomParameterEditorAspNetMvcExample.CustomParameterType).FullName",
            valueConverter: function(valueObj) { return valueObj; }
        }, editor);
    }
    function onCustomizeMenuActions(s, e) {
        var newReportAction = e.GetById(DevExpress.Reporting.Designer.Actions.ActionId.NewReport);
        if (newReportAction) {
            newReportAction.clickAction = function () {
                s.OpenReport("TemplateReport");
            }
        }
    }
</script>

@Html.DevExpress().ReportDesigner(
    Sub(settings)
        settings.Name = "ReportDesigner1"
        settings.ClientSideEvents.Init = "reportDesignerInit"
        settings.ClientSideEvents.CustomizeMenuActions = "onCustomizeMenuActions"
    End Sub).Bind("Model").GetHtml()

Register a Custom Serializer When Reports are Saved

The application should register a custom serializer for all reports when they are saved to avoid an error if the user adds a custom parameter to that report.

The application uses a custom report storage to save a report and open it from a file. Modify the storage’s SaveData method to register the custom serializer for all saved reports:

CustomReportStorageWebExtension.cs

public override void SetData(XtraReport report, string url) {
    // Stores the specified report to a Report Storage using the specified URL. 
    // This method is called only after the IsValidUrl and CanSetData methods are called.
    var resolvedUrl = Path.GetFullPath(Path.Combine(reportDirectory, url + FileExtension));
    if (!resolvedUrl.StartsWith(reportDirectory + Path.DirectorySeparatorChar)) {
        throw new FaultException("Invalid report name.");
    }

    report.SaveLayoutToXml(resolvedUrl);
}

CustomReportStorageWebExtension.vb

Public Overrides Sub SetData(ByVal report As XtraReport, ByVal url As String)
    ' Stores the specified report to a Report Storage using the specified URL. 
    ' This method is called only after the IsValidUrl and CanSetData methods are called.
    Dim resolvedUrl = Path.GetFullPath(Path.Combine(reportDirectory, url + FileExtension))
    If Not resolvedUrl.StartsWith(reportDirectory + Path.DirectorySeparatorChar) Then
        Throw New FaultException("Invalid report name.")
    End If

    report.SaveLayoutToXml(resolvedUrl)
End Sub

Run the Application

The Document Viewer opens the CustomParameterReport, which contains custom parameters. The Parameters panel displays custom editors for custom parameter types:

This example is based on the project created from the ASP.NET MVC Reporting template in our Web App Template Gallery. For more information on the Template Gallery, review the following topic: Create an ASP.NET MVC Application with a Report Designer.

View Example: Custom Report Parameter Types in Web Reporting Controls (ASP.NET MVC)