Customizing the Document Viewer Toolbar in ASP.NET

• Dec 27, 2021
• 3 minutes to read

This document describes how to customize menu commands available in the Web Document Viewer‘s toolbar. In particular, it shows how to add a new toolbar command at design time and at runtime.

This document consists of the following sections.

• Create a Web Application
• Prepare a Custom Command Icon
• Add a Custom Command at Design Time
• Modify Commands at Runtime

Create a Web Application

To get started with this tutorial, open an existing ASP.NET Web application or create a new one from scratch. To learn how to create a simple Web application containing a report, see the Adding a New Report to an ASP.NET WebForms Application topic. For information on how to add a print preview to a Web application, refer to the Adding a Document Viewer to an ASP.NET Application document.

Prepare a Custom Command Icon

To provide a custom command icon that will be displayed in the Web Document Viewer’s toolbar, perform the following steps.

1. Create the required image file (24x24 pixels) and add it to the project (e.g., the CustomButton.png in this example).

2. Declare a CSS class specifying the custom command icon as shown below.

   CSS

   .customButton {
     background-image: url(../CustomButton.png);
     background-repeat: no-repeat;
   }
   

Add a Custom Command at Design Time

To add a new menu command to the Document Viewer’s toolbar at design time, do the following.

1. Switch to the Design view and click the Document Viewer’s smart tag. In the invoked actions list, select Designer...

   

2. In the invoked AspxWebDocumentViewer Designer, activate the Menu Items tab.

3. Click the Add button to add a new menu command. This automatically creates a new WebDocumentViewerMenuItem object and adds it to the ASPxWebDocumentViewer.MenuItems collection. Specify the settings for the added command in the Item Properties list.

   

   The following properties are available.

   • Disabled - specifies whether or not the command is disabled by default.
   • HasSeparator - specifies whether or not the command has a visual separator.
   • HotKey - specifies the keyboard shortcut used to invoke the command.
   • ImageClassName - specifies the CSS class of the command’s glyph.
   • JSClickAction - specifies the client-side action to be performed when the command is invoked.
   • Text - specifies the text for the command.
   • Visible - specifies whether or not the command is visible in the designer user interface.
4. Click OK to apply changes and close the dialog.

Modify Commands at Runtime

To customize menu commands at runtime, handle the ASPxClientWebDocumentViewer.CustomizeMenuActions event on the client side.

The event argument provides access to the Actions collection containing all commands available in the Document Viewer. You can add new commands to the collection as well as modify the existing commands. Refer to Document Viewer’s Client-Side API for a complete list of available commands

The code sample below demonstrates the client-side CustomizeMenuActions event handler that hides an existing command and registers a custom one in the toolbar.

JS

function CustomizeMenuActions(s, e) {
    var actions = e.Actions;

    // Get the "Print Page" action and hide it. 
    var printPageAction = e.GetById(DevExpress.Report.Preview.ActionId.PrintPage);
    if (printPageAction)
        printPageAction.visible = false;

    // Add a new action. 
    actions.push({
        text: "Custom Command",
        imageClassName: "customButton",
        hasSeparator: false,
        disabled: ko.observable(false),
        visible: true,
        hotKey: { ctrlKey: true, keyCode: "Z".charCodeAt(0) },
        clickAction: function () {
            alert('Clicked.');
        }
    })
};

To assign the handler to the client-side CustomizeMenuActions event, assign the handler name to the WebDocumentViewerClientSideEvents.CustomizeMenuActions property as shown below.

HTML

<div>   
    <dx:ASPxWebDocumentViewer ID="ASPxWebDocumentViewer1" runat="server" ClientInstanceName="DocumentViewer" 
       ClientSideEvents-CustomizeMenuActions="CustomizeMenuActions">
    </dx:ASPxWebDocumentViewer>   
</div>