Client Commands

• Jun 17, 2021
• 4 minutes to read

The ASPxRichEdit commands allow you to create, open, modify, and save a document on the client.

Run Demo: Client commands

Most client commands replicate the ribbon UI commands. You can use these commands to create items for a custom toolbar.

Run Demo: Custom toolbar View Example: Insert text to the document end

When you use a command to change a document’s content, client-side events occur. Set the RaiseClientEventsOnModificationsViaAPI property to false to trigger the client events only in response to user actions.

ASPX

<dx:ASPxRichEdit ID="richEdit" runat="server" ClientInstanceName="richEdit" Width="100%">
    <Settings>
        <Behavior RaiseClientEventsOnModificationsViaAPI="false" />
        <!-- ... -->
    </Settings>
</dx:ASPxRichEdit>

The ASPxRichEdit commands property returns a RichEditCommands object that contains client commands. Each command is an object with its own execute and getState methods.

How to Execute a Command

Call the execute method to invoke a command. A command can be applied to the selected content, entire document, or control. Some commands require additional data as a parameter. See the signature of the command’s execute method for more information.

JS

richEdit.selection.selectAll();
richEdit.commands.changeFontFormatting.execute({bold: true, size: 25, foreColor: "#789"});
richEdit.commands.copy.execute();

The ASPxRichEdit allows you to restrict certain operations and format features to protect a document. To check whether the command is enabled, the ASPxRichEdit calls the getState method when you execute a command. If the command is disabled, its execute method takes no action and returns false.

How to Get a Command State

Call the getState method to get the information about the command state on the client.

JS

if (richEdit.commands.changeViewType.getState().value)
    console.log("The current type of the view is the Print Layout View");
else
    console.log("The current type of the view is the Simple View");

The getState method returns an object of the CommandState<T> or SimpleCommandState class with the following settings:

• enabled - indicates whether the command is enabled;

• visible - indicates whether the command’s UI element is visible;

• value - gets the command state value.

A command can have different states in different parts of a document. Refer to the following section for more information: Document Protection.

How to Define a Shortcut

Use the assignShortcut command to define a shortcut. The command’s execute method accepts the following parameters:

• keyCode - a number that identifies the key combination of the shortcut. Use the GetShortcutCode method to get the number for a key combination.

• callback - a callback function to execute when the shortcut is activated.

The example below shows how to define the Alt + U shortcut to update the selected field.

JS

var myKeyCode = ASPxClientUtils.GetShortcutCode(ASPx.KeyCode.Key_u, false, false, true);
richEdit.commands.assignShortcut.execute(myKeyCode, function(){ richEdit.commands.updateField.execute(); } );

How to Process a Batch of Commands without Intermediate Updates

Enclose your code in the beginUpdate - endUpdate method calls to suppress the document’s visual updates and improve performance when you make multiple changes to a document.

Each call to beginUpdate should be paired with the endUpdate call. The beginUpdate method locks an open document, so that its content is not visually updated after each modification. The endUpdate method unlocks the document to enable all the changes to take effect.

JS

richEdit.commands.beginUpdate();  
richEdit.document.activeSubDocument.paragraphsInfo.forEach(function (paragraph) {
    // Selects the current paragraph
    richEdit.selection.setSelection(paragraph.interval);
    // Justifies the selected text to the entire paragraph width
    richEdit.commands.changeParagraphFormatting.execute({alignment: ASPx.ParagraphAlignment.Justify}); 
});
richEdit.commands.endUpdate();

Examples

Refer to the following section for more examples on how to use the client-side API: Common Use Cases.

Change the Page Size of the Current Section

Document elements are measured in different units. For instance, the font size is measured in points, but the page and margin sizes are measured in twips. Use the methods of the RichEditUnitConverter class to convert measurement units.

JS

var width = richEdit.unitConverter.centimetersToTwips(21);
var height = richEdit.unitConverter.centimetersToTwips(29.7);
richEdit.commands.changePageSize.execute(width, height);

Resize an Inserted Picture

Some commands allow you to pass a callback function to its execute method. In the example below, the callback function of the execute(imageUrl,callback) command changes the size of the inserted image.

JS

var URL = 'https://demos.devexpress.com/ASPxImageAndDataNavigationDemos/Content/Images/landscapes/07.jpg';
richEdit.commands.insertPicture.execute(URL, function (interval) {
   richEdit.selection.intervals = [interval];
   richEdit.commands.changePictureScale.execute(10, 10);
});

Force the Synchronization

The forceSyncWithServer command allows you to force sending the latest changes made in a document to the server. Use the command to avoid losing these changes when a server-side operation (for instance, save) is performed.

JS

richEdit.commands.forceSyncWithServer.execute(function ()=> console.log("Models are equivalent"));

Refer to the following section for more information: Client-Server Document Synchronization.