This demo shows how to extend the ASPxHtmlEditor with custom dialogs.
In addition to built-in dialogs available within the ASPxHtmlEditor, you can use any number of custom dialogs, which can be easily added at both design and runtime. To add custom dialogs to the editor, use its CustomDialogs collection. A custom dialog is represented by an HtmlEditorCustomDialog object, which provides the following settings:
- Caption and Name. Use these properties to specify a dialog's caption and name. The dialog's name is used for reference, as described below.
- FormPath. Use this property to provide a path to a user control representing a dialog's form. In the demo, a form contains the ASPxGridView bound to the InsertTemplateData.xml file, which provides predefined content templates.
- OkButtonText, OkButtonVisible, CancelButtonText, and CancelButtonVisible. These options allow you to specify the visibility and caption of two standard dialog buttons. By default, these buttons are labeled "OK" and "Cancel". You can customize default button captions as necessary. In this demo, the Ok button's caption is changed to reflect the dialog's functionality.
You can associate a custom dialog with a toolbar item, that when clicked, invokes the dialog. To accomplish this, add a ToolbarCustomDialogButton toolbar item to the ASPxHtmlEditor, and assign the dialog's name to the toolbar item's Name property.
In this demo, you can click the Insert Template button to invoke the corresponding custom dialog. In the dialog, select an appropriate template and click the Insert button (or simply double click a template) to insert it into the editor. You may switch off the dialog's "Overwrite content" option, to preserve the current content when inserting templates.
The ASPxHtmlEditor provides you with events that allow you to respond to end-user interactions with custom dialogs and dialog button clicks on the client side. Events include:
- CustomDialogOpened. You can handle this event to initialize a custom dialog. In the demo, the OnCustomDialogOpened JavaScript function represents the CustomDialogOpened event handler. This function calls the RestoreInsertTemplateFormDialogState function, to focus the recently selected template in the dialog and restore the checked state of the "Overwrite content" option.
- CustomDialogClosing. You can handle this event to respond to closing a custom dialog (initiated via a click on a dialog button or the header's close button). To identify a dialog and an element being clicked, use the event parameter's Name and Status properties. To prevent default processing on closing a dialog, assign true to the event parameter's handled property. In the demo, the OnCustomDialogClosing JavaScript function represents the CustomDialogClosing event handler. This function retrieves the selected template's text when the Insert dialog button is clicked (it's the Ok dialog button labeled "Insert"), and closes the dialog via the ASPxClientHtmlEditor.CustomDialogComplete method call. Since the dialog is closed programmatically, the function prevents the default closing of the dialog. Note that you can also double click a template to select it and close the dialog. This is accomplished by handling the RowDblClick client event of the ASPxGridView, located in the dialog (see the OnGridRowDblClick function).
- CustomDialogClosed. You can handle this event to perform specific actions, based upon the dialog button that has been clicked or any other suitable condition. In this demo, the OnCustomDialogClosed JavaScript function represents the CustomDialogClosed event handler. This function inserts the selected template's text to the editor, in response to clicking the dialog's Insert button or double-clicking the template. Also, this function calls the SaveInsertTemplateFormDialogState function, to store the dialog's selected template and the checked state of the "Overwrite content" option for future use.
This demo also demonstrates how to define the keyboard shortcut (Ctrl+Shift+I) to open a custom dialog by creating the corresponding item within the editor's Shortcuts collection.