Customize Parameter Editor in the Document Viewer in React Applications

• Jun 05, 2024
• 3 minutes to read

This topic describes two ways to customize a standard parameter editor in the Web Document Viewer:

View Example: Customize Parameter Editor in the Web Document Viewer

Customize a Standard Editor

Use the CustomizeParameterEditors event to change the display format and set validation rules for parameters.

The code snippets in the sections below remove the unnecessary time part from the DateTime editor and prevent users from entering a date earlier than the specified date.

Change the Editor Options

Use the extendedOptions property to customize the DateBox editor options.

const onCustomizeParameterEditors = React.useCallback(({ args }: { args: any }): void => {
    if (args.parameter.type === 'System.DateTime') {
        args.info.editor = {...args.info.editor};
        args.info.editor.extendedOptions = {
          ...args.info.editor.extendedOptions,
          type: 'date',
          displayFormat: 'dd-MMM-yyyy'
        };
        ...
}, []);

Add a Validation Rule

Use the validationRules property to add rules to validate the value entered in the editor.

const onCustomizeParameterEditors = React.useCallback(({ args }: { args: any }): void => {
    if (args.parameter.type === 'System.DateTime') {
    ...
        args.info.validationRules = [{
          type: "range",
          min: new Date(1990, 0, 1),
          message: "No data available prior to the year 1990."
      }];
      ...
}, []);

The customized parameter editor appears as follows:

Create a Custom Editor Template

This section contains an example of a custom editor for the p_employeeID parameter that identifies an employee. The custom editor displays the expandable employee hierarchy and information about each employee.

Use the DevExtreme TreeList component as a template for the Employee ID parameter’s value editor.

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:

Follow the steps below to implement a custom value editor:

1. Create the Employee class.

   Employee.cs

   public class Employee {
       public int Id { get; set; }
       public int ParentId { get; set; }
       public string Name { get; set; }
       public string Title { get; set; }
   }
   

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

   HomeController.cs

   public IActionResult ListEmployees() {
       var employees = new 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);
   }
   

3. Define a custom editor template with the Tree List editor.

   const CustomParameterEditor = ({data}: {data: IEditorViewModel}) => {
       const dataSource = `${BACKEND_URL}/Home/ListEmployees`;
       const columns = [{ dataField: "name", caption: "Name" }, { dataField: "title", caption: "Title" }];
   
       const onSelectionChanged = (e: any) => {
         if (e.selectedRowsData.length > 0) {
           var selectedEmployeeID = e.selectedRowsData[0].id;
           parametersModel.p_employeeID = selectedEmployeeID;
         }
       }
   
     return (
         <TreeList
             dataSource={dataSource}
             columns={columns}
             showBorders={true}
             selection={{ mode: 'single' }}
             selectedRowKeys={data.value}
             onSelectionChanged={onSelectionChanged}
         />
     );
   };
   

4. To register the template, pass the template name and the template itself to the templateEngine.setTemplate method:

   templateEngine.setTemplate('employeeID-custom-editor', CustomParameterEditor);
   

5. In the CustomizeParameterEditors event handler, set the header property to the template name for the p_employeeID parameter:

   page.tsx

   const onCustomizeParameterEditors = React.useCallback(({ args }: { args: any }): void => {
   ...
       if (args.parameter.name == "p_employeeID") {
           args.info.editor = { header: 'employeeID-custom-editor' };
       };
   }, []);
   

6. Handle the CustomizeParameterEditors event.

   page.tsx

   <ReportViewer reportUrl="CustomParameterReport" templateEngine={templateEngine}>
     <RequestOptions invokeAction="/DXXRDV" host="http://localhost:5000/" />
     <Callbacks
         CustomizeParameterEditors={onCustomizeParameterEditors}
         BeforeRender={onBeforeRender} />
   </ReportViewer>