Custom Parameter Editor in the Document Viewer (ASP.NET MVC)

• Jun 18, 2024
• 5 minutes to read

This topic describes how to customize a standard parameter editor and implement a custom editor for a standard parameter type.

Customize the Standard Editor

This example removes the unnecessary time part from the DateTime editor and prevents the user from entering a date earlier then the specified date.

Change the Editor Options

Handle the WebDocumentViewerClientSideEvents.CustomizeParameterEditors event and use the info.editor.extendedOptions property to customize the DateBox editor options.

function customizeParameterEditors(s, e) {
    if (e.parameter.type === 'System.DateTime') {
        e.info.editor = $.extend({}, e.info.editor);
        e.info.editor.extendedOptions =
            $.extend(e.info.editor.extendedOptions || {},
                { type: 'date' }, { displayFormat: 'dd-MMM-yyyy' });
        var validationRule = {
            type: "range",
            min: new Date(2000, 0, 1),
            message: "We do not retain data prior to the year 2000."
        };
        e.info.validationRules = [validationRule];
    };
    if (e.parameter.name == "p_employeeID") {
        e.info.editor = { header: 'employeeID-custom-editor' };
    };

Add a Validation Rule

Handle the WebDocumentViewerClientSideEvents.CustomizeParameterEditors event and add a validation rule to the editor’s validationRules array.

function customizeParameterEditors(s, e) {
    if (e.parameter.type === 'System.DateTime') {
        e.info.editor = $.extend({}, e.info.editor);
        e.info.editor.extendedOptions =
            $.extend(e.info.editor.extendedOptions || {},
                { type: 'date' }, { displayFormat: 'dd-MMM-yyyy' });
        var validationRule = {
            type: "range",
            min: new Date(2000, 0, 1),
            message: "We do not retain data prior to the year 2000."
        };
        e.info.validationRules = [validationRule];
    };
    if (e.parameter.name == "p_employeeID") {
        e.info.editor = { header: 'employeeID-custom-editor' };
    };

The customized parameter editor appears as follows:

Create a Custom Editor

In this example, a report contains the p_employeeID integer parameter that identifies an employee. To help the user select the correct employee, create a custom editor that displays the expandable employee hierarchy and information about each employee.

Instead of the TextBox editor that the Document Viewer automatically creates for the integer report parameter, the application uses the Tree List editor populated with custom data.

The data source for the Tree List editor is a list of Employee objects created on the server and serialized to JSON.

The custom parameter editor is shown in the following image:

Do the following to implement a custom value editor:

1. Create the Employee class.

   Employee.cs

   public class Employee
   {
       public Employee() { }
   
       public int id { get; set; }
       public int parentId { get; set; }
       public string name { get; set; }
       public string title { get; set; }
   }
   

   Employee.vb

   Public Class Employee
        Public Sub New()
        End Sub
   
        Public Property id() As Integer
        Public Property parentId() As Integer
        Public Property name() As String
        Public Property title() As String
    End Class
   

2. Add a controller action that creates JSON data for the parameter editor.

   HomeController.cs

   public class HomeController : Controller {
   // ...
       // Create an Employee list and serialize it to JSON.
       public ActionResult ListEmployees()
       {
           var employees = new System.Collections.Generic.List<Employee>();
           employees.Add(new Employee()
           {
               id = 2,
               parentId = 0,
               name = "Andrew Fuller",
               title = "Vice President"
           });
           employees.Add(new Employee()
           {
               id = 1,
               parentId = 5,
               name = "Nancy Davolio",
               title = "Sales Representative"
           });
           employees.Add(new Employee()
           {
               id = 3,
               parentId = 5,
               name = "Janet Leverling",
               title = "Sales Representative"
           });
           employees.Add(new Employee()
           {
               id = 4,
               parentId = 5,
               name = "Margaret Peacock",
               title = "Sales Representative"
           });
           employees.Add(new Employee()
           {
               id = 5,
               parentId = 2,
               name = "Steven Buchanan",
               title = "Sales Manager"
           });
           return Json(employees, JsonRequestBehavior.AllowGet);
       }
       // ...
   }
   

   HomeController.vb

   Public Class HomeController
       Inherits System.Web.Mvc.Controller
       ' ...
       ' Create an Employee list and serialize it to JSON.
       Public Function ListEmployees() As ActionResult
           Dim employees = New System.Collections.Generic.List(Of Employee)()
           employees.Add(New Employee() With {.id = 2, .parentId = 0,
                         .name = "Andrew Fuller", .title = "Vice President"})
           employees.Add(New Employee() With {.id = 1, .parentId = 5,
                         .name = "Nancy Davolio", .title = "Sales Representative"})
           employees.Add(New Employee() With {.id = 3, .parentId = 5,
                         .name = "Janet Leverling", .title = "Sales Representative"})
           employees.Add(New Employee() With {.id = 4, .parentId = 5,
                         .name = "Margaret Peacock", .title = "Sales Representative"})
           employees.Add(New Employee() With {.id = 5, .parentId = 2,
                         .name = "Steven Buchanan", .title = "Sales Manager"})
           Return Json(employees, JsonRequestBehavior.AllowGet)
       End Function
       ' ...
   End Class
   

3. Define a custom editor template that contains the Tree List editor.

   Viewer.cshtml

   <script type = "text/html" id = "employeeID-custom-editor" >
   <div data-bind="dxTreeList: { dataSource: data, columns: columns, showBorders: true,
            selection:{mode: 'single'}, onSelectionChanged: onTreeListSelectionChanged, 
            onInitialized: onTreeListInitialized}"> 
       </div>
   </script>
   

4. Configure the data source and column bindings for the Tree List.

   Viewer.cshtml

   // Specifies the endpoint for the tree list data.
   var data = window.location.protocol + "//" + window.location.host + "/Home/ListEmployees";
   // Specifies the columns to display in the tree list.
   var columns = [{ dataField: "name", caption: "Name" }, { dataField: "title", caption: "Title" }];
   

5. Instruct the Document Viewer to use a custom template as an editor for the p_employeeID parameter. For this, in the CustomizeParameterEditors event handler, identify the target parameter type and assign the name of the custom editor template to the header variable that specifies the editor in the info.editor object.

   Viewer.cshtml

   function customizeParameterEditors(s, e) {
       if (e.parameter.type === 'System.DateTime') {
           e.info.editor = $.extend({}, e.info.editor);
           e.info.editor.extendedOptions =
               $.extend(e.info.editor.extendedOptions || {},
                   { type: 'date' }, { displayFormat: 'dd-MMM-yyyy' });
           var validationRule = {
               type: "range",
               min: new Date(2000, 0, 1),
               message: "We do not retain data prior to the year 2000."
           };
           e.info.validationRules = [validationRule];
       };
       if (e.parameter.name == "p_employeeID") {
           e.info.editor = { header: 'employeeID-custom-editor' };
       };
   

6. Subscribe to the CustomizeParameterEditors event.

   Viewer.cshtml

   @Html.DevExpress().WebDocumentViewer(settings =>
   {
       settings.ClientSideEvents.BeforeRender = "onBeforeRender";
       settings.ClientSideEvents.ParametersReset = "onParametersReset";
   

   Viewer.vbhtml

   @Html.DevExpress().WebDocumentViewer(
                   Sub(settings)
                       settings.ClientSideEvents.BeforeRender = "onBeforeRender"
                       settings.ClientSideEvents.ParametersReset = "onParametersReset"
   

Example

The complete sample project is available in the DevExpress Examples repository on GitHub.

View Example: Customized Parameter Editor in Web Reporting Controls (ASP.NET MVC)