RichEdit Class

A client-side Rich Text Editor object.

Declaration

export class RichEdit

Properties

authenticationOptions Property

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

Declaration

readonly authenticationOptions: AuthenticationOptions

Property Value

Type	Description
AuthenticationOptions	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

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

Remarks

JS

richEdit.contextMenu.enabled = false;

Run Demo: Context Menu Customization

document Property

Provides access to document structural elements.

Declaration

readonly document: RichEditDocument

Property Value

Type	Description
RichEditDocument	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());

documentExtension Property

Specifies the extension of the current document.

Declaration

documentExtension: string

Property Value

Type	Description
string	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

documentFormat: DocumentFormat

Property Value

Type	Description
DocumentFormat	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.

documentName Property

Specifies the name of the current document.

Declaration

documentName: string

Property Value

Type	Description
string	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

documentSaveFormat: DocumentFormat

Property Value

Type	Description
DocumentFormat	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.

events Property

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

Declaration

readonly events: Events

Property Value

Type	Description
Events	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

fileName: string

Property Value

Type	Description
string	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

fullScreen: boolean

Property Value

Type	Description
boolean	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

hasUnsavedChanges: boolean

Property Value

Type	Description
boolean	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

Type	Description
History	An object that contains history-related methods.

Remarks

JS

richEdit.history.undo();

isDisposed Property

Indicates whether the RichEdit control is disposed.

Declaration

readonly isDisposed: boolean

Property Value

Type	Description
boolean	true, if the control is disposed; otherwise, false.

isDocumentImported Property

Indicates whether the document is imported to the control.

Declaration

readonly isDocumentImported: boolean

Property Value

Type	Description
boolean	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

Type	Description
RichEditLayout	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

readonly loadingPanel: LoadingPanel

Property Value

Type	Description
LoadingPanel	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

Type	Description
MailMergeOptions	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

Type	Description
NusaSettings	An object that contains Nuance-related settings.

printMode Property

Specifies the print mode.

Declaration

printMode: PrintMode

Property Value

Type	Description
PrintMode	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.

rangePermissionOptions Property

Provides access to visual settings for a permitted range.

Declaration

readonly rangePermissionOptions: RangePermissionOptions

Property Value

Type	Description
RangePermissionOptions	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

readOnly: boolean

Property Value

Type	Description
boolean	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

Type	Description
RichEditSelection	An object that contains members to work with the selection.

Remarks

JS

richEdit.selection.goToSubDocumentEnd();

showHorizontalRuler Property

Specifies whether the horizontal ruler is shown.

Declaration

showHorizontalRuler: boolean

Property Value

Type	Description
boolean	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

Type	Description
SimpleViewSettings	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

Type	Description
SpellCheckerOptions	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

Type	Description
UnitConverter	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

viewType: ViewType

Property Value

Type	Description
ViewType	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.

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

Name	Type	Description
shortcut	ShortcutOptions	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

Name	Type	Description
options	IInitDocumentProcessorOptions	An object that contains the document processor’s options.

Returns

Type	Description
DocumentProcessorBase	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

Name	Type	Description
documentFormat	DocumentFormat	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

Name	Type	Description
documentName	string	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

Name	Type	Description
commandId	CommandId	The command’s identifier.
parameter	any	The command’s parameter.

Returns

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

Remarks

The ribbon commands that require a parameter are listed below.

Command	Parameter
ChangeFontName	The new font name.
ChangeStyle	The new character or paragraph style name. Use the CS- prefix for character styles and PS- prefix for paragraph styles.
ChangeTableStyle	The new table style name.
ChangeTableRepositoryItemBorderStyle	Available values: 'None', 'Dashed', 'Double', 'Dotted', and 'Single'. If the parameter is specified incorrectly, the 'Single' value is applied.
ChangeTableRepositoryItemBorderWidth	A border width in twips. The ribbon item displays the width in points. Use UnitConverter to convert units in RichEdit.
ChangeFloatingObjectOutlineWidth	The new outline width in twips. The ribbon item displays the width in points. Use UnitConverter to convert units in RichEdit.
ChangeFloatingObjectFillColor ChangeFloatingObjectOutlineColor ChangeFontForeColor ChangeFontHighlightColor ChangePageColor ChangeTableRepositoryItemBorderColor	The new color (see the available color formats 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

Name	HEX	Name	HEX	Name	HEX	Name	HEX
aliceblue	#f0f8ff	darkturquoise	#00ced1	lightskyblue	#87cefa	peachpuff	#ffdab9
antiquewhite	#faebd7	darkviolet	#9400d3	lightslateblue	#8470ff	peru	#cd853f
aqua	#00ffff	deeppink	#ff1493	lightslategray	#778899	pink	#ffc0cb
aquamarine	#7fffd4	deepskyblue	#00bfff	lightsteelblue	#b0c4de	plum	#dda0dd
azure	#f0ffff	dimgray	#696969	lightyellow	#ffffe0	powderblue	#b0e0e6
beige	#f5f5dc	dodgerblue	#1e90ff	lime	#00ff00	purple	#800080
bisque	#ffe4c4	feldspar	#d19275	limegreen	#32cd32	red	#ff0000
black	#000000	firebrick	#b22222	linen	#faf0e6	rosybrown	#bc8f8f
blanchedalmond	#ffebcd	floralwhite	#fffaf0	magenta	#ff00ff	royalblue	#4169e1
blue	#0000ff	forestgreen	#228b22	maroon	#800000	saddlebrown	#8b4513
blueviolet	#8a2be2	fuchsia	#ff00ff	mediumaquamarine	#66cdaa	salmon	#fa8072
brown	#a52a2a	gainsboro	#dcdcdc	mediumblue	#0000cd	sandybrown	#f4a460
burlywood	#deb887	ghostwhite	#f8f8ff	mediumorchid	#ba55d3	seagreen	#2e8b57
cadetblue	#5f9ea0	gold	#ffd700	mediumpurple	#9370d8	seashell	#fff5ee
chartreuse	#7fff00	goldenrod	#daa520	mediumseagreen	#3cb371	sienna	#a0522d
chocolate	#d2691e	gray	#808080	mediumslateblue	#7b68ee	silver	#c0c0c0
coral	#ff7f50	green	#00ff00	mediumspringgreen	#00fa9a	skyblue	#87ceeb
cornflowerblue	#6495ed	honeydew	#f0fff0	mediumturquoise	#48d1cc	slateblue	#6a5acd
cornsilk	#fff8dc	hotpink	#ff69b4	mediumvioletred	#c71585	slategray	#708090
crimson	#dc143c	indianred	#cd5c5c	midnightblue	#191970	snow	#fffafa
cyan	#00ffff	indigo	#4b0082	mintcream	#f5fffa	springgreen	#00ff7f
darkblue	#00008b	ivory	#fffff0	mistyrose	#ffe4e1	steelblue	#4682b4
darkcyan	#008b8b	khaki	#f0e68c	moccasin	#ffe4b5	tan	#d2b48c
darkgoldenrod	#b8860b	lavender	#e6e6fa	navajowhite	#ffdead	teal	#008080
darkgray	#a9a9a9	lavenderblush	#fff0f5	navy	#000080	thistle	#d8bfd8
darkgreen	#006400	lawngreen	#7cfc00	oldlace	#fdf5e6	tomato	#ff6347
darkkhaki	#bdb76b	lemonchiffon	#fffacd	olive	#808000	turquoise	#40e0d0
darkmagenta	#8b008b	lightblue	#add8e6	olivedrab	#6b8e23	violet	#ee82ee
darkolivegreen	#556b2f	lightcoral	#f08080	orange	#ffa500	violetred	#d02090
darkorange	#ff8c00	lightcyan	#e0ffff	orangered	#ff4500	wheat	#f5deb3
darkorchid	#9932cc	lightgoldenrodyellow	#fafad2	orchid	#da70d6	white	#ffffff
darkred	#8b0000	lightgray	#d3d3d3	palegoldenrod	#eee8aa	whitesmoke	#f5f5f5
darksalmon	#e9967a	lightgreen	#90ee90	palegreen	#98fb98	yellow	#ffff00
darkseagreen	#8fbc8f	lightpink	#ffb6c1	paleturquoise	#afeeee	yellowgreen	#9acd32
darkslateblue	#483d8b	lightsalmon	#ffa07a	palevioletred	#d87093	windowtext	#000000
darkslategray	#2f4f4f	lightseagreen	#20b2aa	papayawhip	#ffefd5

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

Name	Type	Description
callback	(buffer: ArrayBuffer) => void	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

Name	Type	Description
callback	(base64: string) => void	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

Name	Type	Description
callback	(blob: Blob) => void	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

Name	Type	Description
callback	(file: File) => void	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

Name	Type	Description
documentName	string	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.

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

Name	Type	Description
commandId	CommandId	The command identifier.

Returns

Type	Description
CommandState	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

Name	Type	Description
callback	(blob: Blob) => void	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

Name	Type	Description
fileContent	File | Blob | ArrayBuffer | string	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

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

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

Name	Type	Description
mode	PrintMode | IPrintingSettings	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.

saveDocument Method

Invokes the Saving event.

Declaration

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

Parameters

Name	Type	Description
documentFormat	DocumentFormat	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();

setCommandEnabled(command, enabled) Method

Sets the command’s availability.

Declaration

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

Parameters

Name	Type	Description
command	RibbonItemId | CommandId	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

Name	Type	Description
callback	(ribbon: Ribbon) => void	A function that updates the ribbon.

Remarks

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;
});