RichEdit Class

A client-side Rich Text Editor object.

Declaration

export class RichEdit

Properties

allowZoom Property

Specifies whether users can zoom the document.

Declaration

get allowZoom(): boolean
set allowZoom(value: boolean)

Property Value

true if users can zoom the document; otherwise, false.

|

Remarks

The Rich Text Editor allows you to zoom in and out of documents both in UI and code. Users can change the document’s zoom level in the corresponding drop-down menu in the View ribbon tab. Available levels range from 50% to 200%.

Run Demo: Overview

Set the allowZoom property to false to hide the drop-down Zoom Level menu and disable zoom functionality for users.

• JS

richEdit.allowZoom = false;

Regardless of the allowZoom property value, you can use the zoomLevel property to zoom the document at runtime.

authenticationOptions Property

Provides access to credentials used to identify editable ranges in a protected document.

Declaration

readonly authenticationOptions: AuthenticationOptions

Property Value

An object that contains the credentials.

|

Remarks

Run Demo: Document Protection

contextMenu Property

Provides access to the context menu settings.

Declaration

readonly contextMenu: IContextMenu

Property Value

An object that implements the IContextMenu interface and contains the context menu settings.

|

Remarks

• JS

richEdit.contextMenu.enabled = false;

Run Demo: Context Menu Customization

See Also

Context Menu Customization

document Property

Provides access to document structural elements.

Declaration

readonly document: RichEditDocument

Property Value

An object that lists a RichEdit document’s structural elements.

|

Remarks

The document property provides access to information about document structural elements (such as sections, sub-documents, and tables).

• JS

//reduces the document's font collection to the specified fonts
var myFonts = ['Arial', 'Calibri'];
richEdit.document.fonts.getAllFontNames().forEach(fontName => 
    myFonts.find(myFontName => 
        myFontName == fontName) ? null : richEdit.document.fonts.getByName(fontName).delete());

See Also

Document Model

documentExtension Property

Specifies the extension of the current document.

Declaration

get documentExtension(): string
set documentExtension(filePath: string)

Property Value

Returns the document extension, for instance, '.docx'.
Accepts the DOCX, RTF, and TXT file extensions in the following formats: '.docx', 'docx', 'pathPart/fileName.docx'.

|

Remarks

If the RichEdit control cannot match the specified value to a supported file extension, the control does not change the extension and gives warning.

documentFormat Property

Specifies the format in which the editor prepares the document for saving or export.

Declaration

get documentFormat(): DocumentFormat
set documentFormat(format: DocumentFormat)

Property Value

The document format.

|

Remarks

Use the documentFormat property to specify a default format in which the document will be prepared for saving (saveDocument) or export (downloadDocument) if the format is not specified in the corresponding method.

You can specify a document format as a string value.

• JS

richEdit.documentFormat = DevExpress.RichEdit.DocumentFormat.PlainText 
//or
richEdit.documentFormat = "txt";

RichEdit assigns a document format of an opened document to the documentFormat property.

See Also

Document Management

documentName Property

Specifies the name of the current document.

Declaration

get documentName(): string
set documentName(name: string)

Property Value

The document name.

|

Remarks

When you call the downloadDocument or downloadPdf method, the method’s documentName parameter allows you to specify the downloaded document name. If the parameter is not specified, this documentName property specifies the default document name.

• JS

richEdit.documentName = "MyDocument1";
//downloads the MyDocument1.txt file
richEdit.downloadDocument(DevExpress.RichEdit.DocumentFormat.PlainText);

RichEdit assigns the name of an opened document to the documentName property.

• JS

richEdit.openDocument(documentAsBase64, "DocumentName.docx", DevExpress.RichEdit.DocumentFormat.OpenXml)
// now the documentName property returns "DocumentName"

Important

The documentName property can address parent folders of the current directory, for example, richEdit.documentName = '../myDocument1'. Make sure that you configure access rights for application directories.

documentSaveFormat Property

Specifies the format in which the editor prepares the document for saving.

Declaration

get documentSaveFormat(): DocumentFormat
set documentSaveFormat(format: DocumentFormat)

Property Value

The document format.

|

Remarks

When a user clicks the Save button or the saveDocument method is called, the Rich Text Editor converts the document’s content to base64 and invokes the Saving event.

Use the documentSaveFormat property to specify a format in which the document will be converted to base64.

See Also

Document Management

events Property

Provides access to a list of client-side events specific to the RichEdit control.

Declaration

get events(): Events

Property Value

An object that allows you to assign handlers to the client-side events.

|

Remarks

The events property provides access to a list of properties whose names correspond to the events available to the RichEdit control. These properties allow you to dynamically add and remove events handlers.

fileName Property

Specifies the name of the downloaded file.

Declaration

get fileName(): string
set fileName(name: string)

Property Value

The file name.

|

Remarks

When you call the downloadDocument method, the method’s fileName parameter allows you to specify the downloaded file name.

If the parameter is not specified, this fileName property specifies the default file name.

• JS

richEdit.fileName = "myDocument1";

fullScreen Property

Enables you to switch the full-screen mode of the Rich Text Editor.

Declaration

get fullScreen(): boolean
set fullScreen(value: boolean)

Property Value

true if the Rich Text Editor is in full-screen mode; otherwise, false.

|

Remarks

In full-screen mode, the Rich Text Editor occupies the browser’s entire client region and can be resized with the browser window.

• JS

richEdit.fullScreen = true;

hasUnsavedChanges Property

Specifies the Save button availability.

Declaration

get hasUnsavedChanges(): boolean
set hasUnsavedChanges(value: boolean)

Property Value

true if the Save button is available; otherwise, false.

|

Remarks

The hasUnsavedChanges property is set to true on any document change.

The property is set to false and the Save button is disabled as a result in the following cases:

• The Saving event argument’s handled property is set to true.
• A request to save a document to the server (exportUrl/ExportUrl(String)) has succeeded and returns the 200 OK status response code.

You can set the property value manually to change the Save button availability.

Use the modified property to determine whether the document has unsaved changes.

history Property

Provides access to methods related to Rich Text Editor history.

Declaration

readonly history: History

Property Value

An object that contains history-related methods.

|

Remarks

• JS

richEdit.history.undo();

isDisposed Property

Indicates whether the RichEdit control is disposed.

Declaration

get isDisposed(): boolean

Property Value

true if the control is disposed; otherwise, false.

|

isDocumentImported Property

Indicates whether the document is imported to the control.

Declaration

get isDocumentImported(): boolean

Property Value

true if the document is imported to the control; false if the control is importing the document.

|

Remarks

When the isDocumentImported property returns false, the RichEdit control is importing a document and rejects an attempt to import another document.

layout Property

Provide access to the Rich Text Editor’s layout settings.

Declaration

readonly layout: RichEditLayout

Property Value

An object that contains layout settings.

|

Remarks

• JS

richEdit.layout.showHiddenSymbols = true;
richEdit.layout.showTableGridLines = false;

loadingPanel Property

Provides access to settings related to loading panel functionality.

Declaration

get loadingPanel(): LoadingPanel

Property Value

An object that contains settings related to a loading panel.

|

Remarks

The loadingPanel property allows you to perform the following actions:

• disable the loading panel;

• show and hide the loading panel manually;

• provide a custom loading panel.

• JS

richEdit.loadingPanel.show();

• JS

richEdit.loadingPanel.hide();

mailMergeOptions Property

Provides access to the options related to the mail merge functionality.

Declaration

readonly mailMergeOptions: MailMergeOptions

Property Value

An object that contains mail-merge options.

|

Remarks

• JS

var newDataSource = [
    { firstName: "Alex", birthYear: 1991 },
    { firstName: "Joe", birthYear: 1990 },
    { firstName: "Bob", birthYear: 1995 }
];
richEdit.mailMergeOptions.setDataSource(newDataSource);

• JS

richEdit.mailMergeOptions.activeRecordIndex = 15;

nusaSettings Property

Provides access to the Nuance-related settings.

Declaration

readonly nusaSettings: NusaSettings

Property Value

An object that contains Nuance-related settings.

|

printMode Property

Specifies the print mode.

Declaration

get printMode(): PrintMode
set printMode(val: PrintMode)

Property Value

The print mode.

|

Remarks

The printMode property specifies the mode used to print a document in the following cases:

• when a user clicks the Print ribbon button;

• when the printDocument method is called without a parameter.

• JS

richEdit.printMode = DevExpress.RichEdit.PrintMode.Pdf;
richEdit.printDocument();

Use the Mode(PrintMode) method to specify the print mode on the server side.

See Also

Print a Document

rangePermissionOptions Property

Provides access to visual settings for a permitted range.

Declaration

readonly rangePermissionOptions: RangePermissionOptions

Property Value

An object that contains visual settings.

|

Remarks

• JS

richEdit.rangePermissionOptions.highlightRanges=true;
richEdit.rangePermissionOptions.showBrackets=true;
richEdit.rangePermissionOptions.bracketsColor="blue";
richEdit.rangePermissionOptions.highlightColor="#8fbc8b";

Run Demo: Document Protection

readOnly Property

Specifies whether document modifications are prohibited.

Declaration

get readOnly(): boolean
set readOnly(value: boolean)

Property Value

true if the document is in a read-only state; otherwise, false.

|

Remarks

• JS

richEdit.readOnly = true;

selection Property

Provides access to the selection in Rich Text Editor.

Declaration

readonly selection: RichEditSelection

Property Value

An object that contains members to work with the selection.

|

Remarks

• JS

richEdit.selection.goToSubDocumentEnd();

See Also

Client API

Selection

showHorizontalRuler Property

Specifies whether the horizontal ruler is shown.

Declaration

get showHorizontalRuler(): boolean
set showHorizontalRuler(value: boolean)

Property Value

true if the ruler is visible; otherwise, false.

|

Remarks

• JS

richEdit.showHorizontalRuler = true;

The Rich Text Editor hides the horizontal ruler when Simple View mode is enabled.

simpleViewSettings Property

Provides access to the Simple view mode’s settings.

Declaration

readonly simpleViewSettings: SimpleViewSettings

Property Value

An object that contains the Simple view mode’s settings.

|

Remarks

Set the viewType property to Simple to enable the Simple view mode.

• JS

richEdit.viewType = DevExpress.RichEdit.ViewType.Simple;
richEdit.simpleViewSettings.fixedWidth = 300;
richEdit.simpleViewSettings.paddings = {top: 40, right: 40, bottom: 40, left: 40};

Alternatively, you can specify the Simple view mode’s settings on the server side (SimpleView(Action<SimpleViewSettingsBuilder>)) or using the Options object (simpleViewSettings).

Run Demo: Simple View

spellCheckerOptions Property

Provides access to spell check settings.

Declaration

readonly spellCheckerOptions: SpellCheckerOptions

Property Value

An object that contains spell check settings.

|

Remarks

Use the client-side spellCheck option or the server-side SpellCheck(Action<SpellCheckBuilder>) method to configure spell check settings. The spellCheckerOptions property allows you to access the isEnabled setting that enables and disables spell check at runtime.

Refer to the following section for more information: Spell Check.

unitConverter Property

Allows you to convert units.

Declaration

readonly unitConverter: UnitConverter

Property Value

A unit converter object.

|

Remarks

• JS

var marginSize = richEdit.unitConverter.centimetersToTwips(1);
var margins = new DevExpress.RichEdit.Margins(
    marginSize, marginSize, marginSize, marginSize);
richEdit.document.sections.getByIndex(0).margins = margins;

viewType Property

Specifies a document view layout type.

Declaration

get viewType(): ViewType
set viewType(type: ViewType)

Property Value

The document view type. 0 (zero) corresponds to the Simple view type; 1 corresponds to the PrintLayout view type.

|

Remarks

• JS

richEdit.viewType = DevExpress.RichEdit.ViewType.PrintLayout;

If the viewType property is set to Simple, use the simpleViewSettings property to customize the Simple View mode’s settings.

See Also

Simple View - Online Demo

zoomLevel Property

Specifies the document’s zoom level.

Declaration

get zoomLevel(): number
set zoomLevel(value: number)

Property Value

The zoom level as a percentage in the range from 0.5 to 2.0.

|

Remarks

The Rich Text Editor allows you to zoom in and out of documents both in UI and code. Users can change the document’s zoom level in the corresponding drop-down menu in the View ribbon tab.

In code, you can use the zoomLevel property to zoom the document. This property accepts values in the range from 0.5 to 2.0 that corresponds to 50% and 200% respectively.

• JS

richEdit.zoomLevel = 0.7;

Methods

adjust Method

Modifies the RichEdit’s size against the control’s container.

Declaration

adjust(): void

Remarks

The adjust method recalculates the size of the control’s client object to correctly display it, when the control’s parent container is dynamically changed on the client side.

assignShortcut(shortcut, callback) Method

Assign a shortcut to a function.

Declaration

assignShortcut(
    shortcut: ShortcutOptions,
    callback: () => void
): void

Parameters

The shortcut options.

| | callback | () => void |

A function to assign a shortcut.

|

Remarks

• JS

// adds the Ctrl+1 shortcut
var ctrlKey = true;
var shortcutOpts = new DevExpress.RichEdit.ShortcutOptions( 
    DevExpress.RichEdit.KeyCode.Key_1, ctrlKey);    
richEdit.assignShortcut(shortcutOpts, function () { alert('your actions here'); });

beginUpdate Method

Locks the RichEdit to prevent its visual updates until the endUpdate method is called.

Declaration

beginUpdate(): void

Remarks

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

Each call to beginUpdate must be paired with the endUpdate call. The beginUpdate method locks the RichEdit, so that it is not rendered after each modification. The endUpdate method unlocks the control to enable all the changes to take effect.

createDocumentProcessor Method

Creates a new document processor.

Declaration

createDocumentProcessor(
    options?: IInitDocumentProcessorOptions
): DocumentProcessorBase

Parameters

An object that contains the document processor’s options.

|

Returns

The newly created document processor.

|

Remarks

The document processor is a non-visual object that allows you to access and customize a document via code.

Use the createDocumentProcessor method to create an instance of a document processor. Set the IInitDocumentProcessorOptions.cloneCurrentModel option to true to clone the current document model to the newly created document processor. If the property is set to false, the processor is created with a new document.

Note

Dispose the document processor after use. If you create a document processor in the onCalculateDocumentVariable event handler, the processor is disposed automatically.

• JS

var proc = richEdit.createDocumentProcessor();
proc.document.fields.create(proc.document.length, 'docvariable complexContent');
proc.document.fields.create(proc.document.length, 'docvariable text');
proc.document.fields.create(proc.document.length, 'docvariable complexContent');
proc.document.fields.create(proc.document.length, 'docvariable text');
proc.onCalculateDocumentVariable = function (s, e) {
    if (e.variableName == 'complexContent') {
        var docvarProc = richEdit.createDocumentProcessor();
        var picUrl = 'your-image-URL';
        var picSize = new DevExpress.RichEdit.Size(docvarProc.unitConverter.pixelsToTwips(200), docvarProc.unitConverter.pixelsToTwips(200));
        docvarProc.document.insertPicture(0, picUrl, picSize);
        docvarProc.document.insertText(docvarProc.document.length, 'Content1');
        docvarProc.document.setCharacterProperties(new DevExpress.RichEdit.Interval(1, 3), { bold: true });
        docvarProc.document.insertText(docvarProc.document.length, 'Content2');
        e.value = docvarProc;
    }
    if (e.variableName == 'text') {
        e.value = '!SimpelText!';
    }
}
proc.document.fields.updateAllFields(function () {
    proc.exportDocumentToBase64(function (base64) {
        proc.dispose();
        richEdit.openDocument(base64, 'someFile', DevExpress.RichEdit.DocumentFormat.OpenXml, (succ) => console.log(succ));
        }, DevExpress.RichEdit.DocumentFormat.OpenXml);
});

dispose Method

Releases resources used by the RichEdit.

Declaration

dispose(): void

downloadDocument Method

Downloads the current document.

Declaration

downloadDocument(
    documentFormat?: DocumentFormat,
    documentName?: string
): void

Parameters

The document format.

| | documentName | string |

The name of the downloaded document.

|

Remarks

Call the downloadDocument method to download the current document.

• If the documentFormat parameter is not specified, the RichEdit uses the documentFormat property value instead. If the property is not specified, the document is downloaded in the OpenXml format (.docx).

• If the documentName parameter is not specified, the RichEdit uses the documentName property value instead. If the property is not specified, the document name is set to ‘document1’.

• JS

richEdit.newDocument();
// downloads the myDocument.rtf file
richEdit.downloadDocument(DevExpress.RichEdit.DocumentFormat.Rtf, 'myDocument');

downloadPdf Method

Downloads the current document as a PDF file.

Declaration

downloadPdf(documentName?: string, options?: ((pdfDocument: any) => void) | {
    modifyPdfDocument?: (pdfDocument: any) => void;
    modifyPdfPage?: (pdfDocument: any) => void;
}): void

Parameters

The name of the downloaded document.

| | options | (pdfDocument: any) => void | {modifyPdfDocument: (pdfDocument: any) => void, modifyPdfPage: (pdfDocument: any) => void} |

A function that allows you to modify the PDF document before it is downloaded; or an object that contains modifyPdfDocument and modifyPdfPage functions.

|

Remarks

The downloadPdf method exports the document to the Portable Document Format (PDF) and downloads it to a local machine.

You can write a function to modify each page after it is exported ( modifyPdfPage ), or modify the document after the export is completed ( modifyPdfDocument ). The pdfDocument parameter is an object of the PDFKit library. If an export fails, the parameter returns null.

If the documentName parameter is not specified, the file is downloaded with a name specified by the documentName property. If the property is not specified, the downloaded file name is ‘document1’.

Note

If you use the downloadPdf method, you should provide a list of available fonts and their sources to be uploaded to the client, and register the pdfkit library on your page.

endUpdate Method

Unlocks the RichEdit object after a call to the beginUpdate method and causes an immediate visual update.

Declaration

endUpdate(): void

Remarks

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

Each call to beginUpdate must be paired with the endUpdate call. The beginUpdate method locks the RichEdit, so that it is not rendered after each modification. The endUpdate method unlocks the control to enable all the changes to take effect.

executeCommand(commandId) Method

Executes the specified command.

Declaration

executeCommand(
    commandId: CommandId,
    parameter?: any
): boolean

Parameters

The command’s identifier.

| | parameter | any |

The command’s parameter.

|

Returns

true if the command is successfully executed; otherwise, false.

|

Remarks

The ribbon commands that require a parameter are listed below.

The following color formats are available:

• 'Auto' and 'NoColor' values.
• Hexadecimal notation (for example, '#31bb32').
• RGB format (for example, 'rgb(51,187,51)').
• Named colors (for example, 'darkturquoise').

Show allowed color names

• JS

richEdit.executeCommand(DevExpress.RichEdit.HomeTabItemId.ChangeFontName, 'Arial');
richEdit.executeCommand(DevExpress.RichEdit.HomeTabCommandId.ChangeStyle, 'PS-heading 1');
richEdit.executeCommand(DevExpress.RichEdit.TableDesignTabCommandId.ChangeTableStyle, 'Plain Table 1');
richEdit.executeCommand(DevExpress.RichEdit.TableDesignTabCommandId.ChangeTableRepositoryItemBorderStyle, 'Dotted');
richEdit.executeCommand(DevExpress.RichEdit.TableDesignTabCommandId.ChangeTableRepositoryItemBorderWidth, richEdit.unitConverter.pointsToTwips(0.75));
richEdit.executeCommand(DevExpress.RichEdit.FloatingObjectsFormatTabCommandId.ChangeFloatingObjectOutlineWidth, 15);
richEdit.executeCommand(DevExpress.RichEdit.PageLayoutTabCommandId.ChangePageColor, '#ff7f50');

exportToArrayBuffer(callback) Method

Exports the current document to an ArrayBuffer object.

Declaration

exportToArrayBuffer(
    callback: (buffer: ArrayBuffer) => void,
    documentFormat?: DocumentFormat
): void

Parameters

A function that gets the ArrayBuffer object as a parameter.

| | documentFormat | DocumentFormat |

The document format.

|

Remarks

The exportToArrayBuffer method exports the current document to an ArrayBuffer object. Use the documentFormat parameter to specify the document’s format. After export, the control calls the callback function and sends the ArrayBuffer object there as a parameter.

exportToBase64(callback) Method

Exports the current document to base64.

Declaration

exportToBase64(
    callback: (base64: string) => void,
    documentFormat?: DocumentFormat
): void

Parameters

A function that gets the base64 string as a parameter.

| | documentFormat | DocumentFormat |

The document format.

|

Remarks

The exportToBase64 method exports the current document to a base64 string. Use the documentFormat parameter to specify the document’s format. After export, the control calls the callback function and sends the base64 string there as a parameter.

exportToBlob(callback) Method

Exports the current document to a blob.

Declaration

exportToBlob(
    callback: (blob: Blob) => void,
    documentFormat?: DocumentFormat
): void

Parameters

A function that gets the blob as a parameter.

| | documentFormat | DocumentFormat |

The document format.

|

Remarks

The exportToBlob method exports the current document to a binary large object (blob). Use the documentFormat parameter to specify the document’s format. After export, the control calls the callback function and sends the blob there as a parameter.

exportToFile(callback) Method

Exports the current document to a file object.

Declaration

exportToFile(
    callback: (file: File) => void,
    documentFormat?: DocumentFormat
): void

Parameters

A function that gets the exported file as a parameter.

| | documentFormat | DocumentFormat |

The document format.

|

Remarks

The exportToFile method exports the current document to a file object. Use the documentFormat parameter to specify the document’s format. After export, the control calls the callback function and sends the file there as a parameter.

The code sample below exports the document content to a file and inserts it in the current position.

• JS

richEdit.exportToFile(function(file){
  richEdit.selection.activeSubDocument.insertContent(richEdit.selection.active, 
    file, DevExpress.RichEdit.DocumentFormat.OpenXml, function (interval, success){
      if (success)  
        console.log('Inserted interval [' + interval.start + ', ' + interval.end + ']');
  });
}, DevExpress.RichEdit.DocumentFormat.OpenXml);

exportToPdf Method

Exports the current document to a PDF and invokes the PdfExporting event.

Declaration

exportToPdf(documentName?: string, options?: ((pdfDocument: any) => void) | {
    modifyPdfDocument?: (pdfDocument: any) => void;
    modifyPdfPage?: (pdfDocument: any) => void;
}): void

Parameters

The name of the exported document.

| | options | (pdfDocument: any) => void | {modifyPdfDocument: (pdfDocument: any) => void, modifyPdfPage: (pdfDocument: any) => void} |

A function that allows you to modify the PDF document before it is downloaded; or an object that contains modifyPdfDocument and modifyPdfPage functions.

|

Remarks

The exportToPdf method exports the current document to the Portable Document Format (PDF). You can write a function to modify each page after it is exported ( modifyPdfPage ), or modify the document after the export is completed ( modifyPdfDocument ).

The pdfDocument parameter is an object of the PDFKit library. If an export fails, the parameter returns null.

The control invokes the PdfExporting event. Handle it to process (for instance, to save) the exported document. To access the PDF file, use the base64, blob, or blobStream parameter.

If the PdfExporting event is not handled (the handled property is not set to true), you can use the ExportUrl(String) property to process a document on the server side.

Note

If you use the exportToPdf method, you should provide a list of available fonts and their sources to be uploaded to the client, and register the pdfkit library on your page.

Tip

Use the downloadPdf method to download the current document as a PDF file.

See Also

Export a Document to PDF

focus Method

Sets input focus to the RichEdit.

Declaration

focus(): void

Remarks

• JS

var subDocument = richEdit.selection.activeSubDocument;
var position = richEdit.selection.active;
var templateText = '[Type your text here]';

richEdit.beginUpdate();
richEdit.history.beginTransaction();

position = subDocument.insertParagraph(position).interval.end;
position = subDocument.insertParagraph(position).interval.end;
position = subDocument.insertText(position, 'Dear Mr Stanley,').end;
position = subDocument.insertParagraph(position).interval.end;
var tmpTextInterval = subDocument.insertText(position, templateText);
position = tmpTextInterval.end;
position = subDocument.insertParagraph(position).interval.end;

richEdit.endUpdate();
richEdit.history.endTransaction();

richEdit.selection.setSelection(tmpTextInterval);
richEdit.focus();

Run Demo: Ribbon Customization

getCommandState(commandId) Method

Returns the state of the command.

Declaration

getCommandState(
    commandId: CommandId
): CommandState

Parameters

The command identifier.

|

Returns

An object that contains the command’s state.

|

Remarks

• JS

var currentFontColor = richEdit.getCommandState(DevExpress.RichEdit.HomeTabCommandId.ChangeFontForeColor).value;

mailMerge(callback) Method

Merges the bound data to a document template and executes a callback function.

Declaration

mailMerge(
    callback: (blob: Blob) => void,
    mergeMode?: MergeMode,
    documentFormat?: DocumentFormat,
    exportFrom?: number,
    exportRecordsCount?: number
): void

Parameters

A function that is called when the merged document is ready.

| | mergeMode | MergeMode |

The delimiter that starts the new merged range.

| | documentFormat | DocumentFormat |

The exported document format.

| | exportFrom | number |

The number of the first exported record in a data source.

| | exportRecordsCount | number |

The number of records to export.

|

Remarks

The code sample below demonstrates how to executes the mail merge and load the resulting document to the Rich Text Editor.

• JS

var format = DevExpress.RichEdit.DocumentFormat.OpenXml;
var newDataSource = [
    { firstName: "Alex", birthYear: 1991 },
    { firstName: "Joe", birthYear: 1990 },
    { firstName: "Bob", birthYear: 1995 }
];
richEdit.newDocument();
richEdit.document.insertText(richEdit.document.length, 'FirstName: ');
richEdit.document.fields.createMergeField(richEdit.document.length, "firstName");

richEdit.mailMergeOptions.setDataSource(newDataSource);
richEdit.mailMerge(function (mergedDocument) {
  richEdit.openDocument(mergedDocument, "MergedDocument", format);
}, DevExpress.RichEdit.MergeMode.NewParagraph, format);

newDocument Method

Creates and opens a new document.

Declaration

newDocument(): void

Remarks

• JS

richEdit.newDocument();

openDocument Method

Opens the specified document or the Open dialog.

Declaration

openDocument(
    fileContent?: File | Blob | ArrayBuffer | string,
    documentName?: string,
    documentFormat?: DocumentFormat,
    callback?: (importSuccess: boolean) => void
): void

Parameters

A file content.

| | documentName | string |

A file name, that is assigned to the documentName property.

| | documentFormat | DocumentFormat |

A document format. This property is used when the base64 parameter does not contain information about a MIME type. If both values are specified, an exception is thrown.

| | callback | (importSuccess: boolean) => void |

A function that is called after a document is opened and allows you to react to an attempt to open an invalid document. If this parameter is not specified and the opened file is not valid, the RichEdit displays an error message.

|

Remarks

• Call the method with parameters to open a particular document.

• JS

javascriptCopy

var documentAsBase64 = "e1xydGYxXGRlZmYwe1xmb250dGJse1xmMCBDYWxpYnJpO319e1xjb2xvcnRibCA7XHJlZDB"
+ "cZ3JlZW4wXGJsdWUyNTUgO1xyZWQyNTVcZ3JlZW4yNTVcYmx1ZTI1NSA7fXtcKlxkZWZjaHAgXGZzMjJ9e1xzdHl"    
+ "sZXNoZWV0IHtccWxcZnMyMiBOb3JtYWw7fXtcKlxjczFcZnMyMiBEZWZhdWx0IFBhcmFncmFwaCBGb250O317XCp"
+ "cY3MyXGZzMjJcY2YxIEh5cGVybGluazt9e1wqXHRzM1x0c3Jvd2RcZnMyMlxxbFx0c3ZlcnRhbHRcdHNjZWxsY2J"
+ "wYXQyXHRzY2VsbHBjdDBcY2x0eGxydGIgTm9ybWFsIFRhYmxlO319e1wqXGxpc3RvdmVycmlkZXRhYmxlfXtcaW5"
+ "mb31cbm91aWNvbXBhdFxzcGx5dHduaW5lXGh0bWF1dHNwXGV4cHNocnRuXHNwbHRwZ3BhclxkZWZ0YWI3MjBcc2V"
+ "jdGRcbWFyZ2xzeG4xNDQwXG1hcmdyc3huMTQ0MFxtYXJndHN4bjE0NDBcbWFyZ2JzeG4xNDQwXGhlYWRlcnk3MjB"
+ "cZm9vdGVyeTcyMFxwZ3dzeG4xMjI0MFxwZ2hzeG4xNTg0MFxjb2xzMVxjb2xzeDcyMFxwYXJkXHBsYWluXHFse1x"
+ "mczIyXGNmMFxjczEgRG9jdW1lbnQgdGV4dH1cZnMyMlxjZjBccGFyfQ==";
richEdit.openDocument(documentAsBase64, "DocumentName", DevExpress.RichEdit.DocumentFormat.Rtf);

• Call the method without parameters to invoke the Open dialog.

• JS

javascriptCopy

richEdit.openDocument();

If the opened file is not valid, the RichEdit opens a new document.

printDocument Method

Invokes a browser-specific Print dialog that can be used to print the current document.

Declaration

printDocument(
    mode?: PrintMode | IPrintingSettings
): void

Parameters

A print mode or an interface that declares print settings.

|

Remarks

• JS

richEdit.printDocument(DevExpress.RichEdit.PrintMode.Pdf);

If the mode parameter is not specified, the RichEdit prints a document in a mode set by the printMode property.

Note

If you print a document in PDF printing mode, you should provide a list of available fonts and their sources to be uploaded to the client, and register the pdfkit library on your page.

See Also

Print a Document

saveDocument Method

Invokes the Saving event.

Declaration

saveDocument(
    documentFormat?: DocumentFormat,
    reason?: string,
    documentName?: string
): void

Parameters

The document format.

| | reason | string |

A value that identifies the reason why the document saving process starts.

| | documentName | string |

The name of the saved document.

|

Remarks

When the saveDocument method is called, the Rich Text Editor converts the document’s content to base64 and invokes the Saving event. Write the event handler to save the document on the client. Set the handled property to true to prevent further processing.

• JS

richEdit.events.saving.addHandler(function(s, e) {
    console.log(e.base64);
    e.handled = true;
});
// ...
richEdit.saveDocument(DevExpress.RichEdit.DocumentFormat.OpenXml);

If the handled property is not set to true (the event is not handled), specify the ExportUrl(String) property to save the document on the server.

If a document has no unsaved changes, the saveDocument method does not invoke the Saving event. To invoke the event for an unchanged document, set the hasUnsavedChanges property to true.

• JS

richEdit.hasUnsavedChanges = true;
richEdit.saveDocument();

See Also

Save a Document

scrollToPage(index) Method

Scrolls the document to the specified page.

Declaration

scrollToPage(
    index: number
): void

Parameters

The page index.

|

Remarks

Call the scrollToPage method to scroll the document to the top of the specified page. If you need to scroll to a specific position in the document, call the scrollToPosition method.

The following code snippet scrolls the document to the first page:

• JS

richEdit.scrollToPage(0);

scrollToPosition(position) Method

Scrolls the document to the specified position.

Declaration

scrollToPosition(
    position: number,
    subDocument?: SubDocument,
    pageIndex?: number
): void

Parameters

The target position in the document.

| | subDocument | SubDocument |

The target sub-document.

| | pageIndex | number |

The page index.

|

Remarks

Call the scrollToPosition method to scroll the view to the specified position in the main sub-document or in headers/footers (using optional parameters). If you need to scroll the document to a specific page, use the scrollToPage method.

The following sections demonstrate how to use the scrollToPosition method in different scenarios.

Navigate to the Beginning of the Document

• JS

richEdit.scrollToPosition(0);

Find a Bookmark by Its Name

• JS

var bookmarkName = 'Bookmark';
var bookmark = richEdit.document.bookmarks.find(bookmarkName)[0];
var subDocument = richEdit.selection.activeSubDocument;
richEdit.scrollToPosition(bookmark.interval.start, subDocument);

Scroll to the Third Page Header

• JS

var section = richEdit.document.sections.getByIndex(0);
var header = section.getHeader();
richEdit.scrollToPosition(0, header, 2);

Scroll to the First Page Footer

• JS

var section = richEdit.document.sections.getByIndex(0);
var footer = section.getFooter();
richEdit.scrollToPosition(0, footer);

setCommandEnabled(command, enabled) Method

Sets the command’s availability.

Declaration

setCommandEnabled(
    command: RibbonItemId | CommandId,
    enabled: boolean
): void

Parameters

The command identifier.

| | enabled | boolean |

true to enable the command; false to disable the command.

|

Remarks

• JS

var ribbonButton = new DevExpress.RichEdit.RibbonButtonItem("sendEmail", "Send Email",
  { icon: "email", showText: true, beginGroup: true });
ribbon.getTab(DevExpress.RichEdit.RibbonTabType.Home).insertItem(ribbonButton);
...
richEdit.setCommandEnabled("sendEmail", false);
richEdit.setCommandEnabled(DevExpress.RichEdit.InsertTabCommandId.ShowInsertTableDialog, false);
richEdit.setCommandEnabled(DevExpress.RichEdit.InsertTabItemId.ShowBookmarkDialog, false);

updateRibbon(callback) Method

Updates the RichEdit ribbon on the client side.

Declaration

updateRibbon(
    callback: (ribbon: Ribbon) => void
): void

Parameters

A function that updates the ribbon.

|

Remarks

The ribbon consist of tabs. The RibbonTabType enum has identifiers of all build-in tabs. Pass a tab’s identifier to the getTab(id) method to get the tab.

A tab contains various items. Call a tab’s getItem(id) method to get the tab’s item by its identifier. Use the RibbonItemId type to access item identifiers.

• JS

var commandId = "MailMergeSwitch";
var showMailMergeResult = false;
var templateDocument = null;
var format = DevExpress.RichEdit.DocumentFormat.OpenXml;

var newDataSource = [
    { firstName: "Alex", birthYear: 1991 },
    { firstName: "Joe", birthYear: 1990 },
    { firstName: "Bob", birthYear: 1995 }
];
var showTemplateDocument = function() {
    showMailMergeResult = !showMailMergeResult;
    richEdit.openDocument(templateDocument, "TemplateDocument", format);
};
var showResultDocument = function() {
    richEdit.loadingPanel.show();
    richEdit.exportToBase64(function(documentAsBase64) {
        templateDocument = documentAsBase64;
        richEdit.mailMerge(function (mergedDocument) {
          var reader = new FileReader();
          reader.onloadend = function () {
            showMailMergeResult = !showMailMergeResult;
            richEdit.openDocument(reader.result, "MergedDocument", format);
          };
          reader.readAsDataURL(mergedDocument);
        }, DevExpress.RichEdit.MergeMode.NewParagraph, format);
    });
};

richEdit.events.customCommandExecuted.addHandler(function(s, e) {
    if (e.commandName == commandId)
        if (showMailMergeResult)
            showTemplateDocument();
        else 
            showResultDocument();
});

richEdit.newDocument();
richEdit.document.insertText(richEdit.document.length, 'You can change template as you want.');
richEdit.document.insertParagraph(richEdit.document.length);
richEdit.document.insertText(richEdit.document.length, 'FirstName: ');
richEdit.document.fields.createMergeField(richEdit.document.length, "firstName").update();
richEdit.mailMergeOptions.setDataSource(newDataSource);

richEdit.documentName = "TemplateDocument";

richEdit.updateRibbon(function(ribbon) {
    if (!ribbon.getTab(DevExpress.RichEdit.RibbonTabType.MailMerge).getItem(commandId))
        ribbon.getTab(DevExpress.RichEdit.RibbonTabType.MailMerge)
            .insertItem(new DevExpress.RichEdit.RibbonButtonItem(commandId, "Switch document"), 0);
    ribbon.activeTabIndex = DevExpress.RichEdit.RibbonTabType.MailMerge;
});

See Also

Ribbon Customization