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

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

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).

//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

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

get documentFormat(): DocumentFormat
set documentFormat(format: 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.

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

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.

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.

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

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.

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

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

get fileName(): string
set fileName(name: 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.

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

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.

richEdit.fullScreen = true;

hasUnsavedChanges Property

Specifies the Save button availability.

Declaration

get hasUnsavedChanges(): boolean
set hasUnsavedChanges(value: 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

richEdit.history.undo();

isDisposed Property

Indicates whether the RichEdit control is disposed.

Declaration

get 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

get 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

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

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.

richEdit.loadingPanel.show();

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

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

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

get printMode(): PrintMode
set printMode(val: 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.

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

Type	Description
RangePermissionOptions	An object that contains visual settings.

Remarks

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

RichEdit with a permitted range

Run Demo: Document Protection

readOnly Property

Specifies whether document modifications are prohibited.

Declaration

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

Property Value

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

Remarks

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

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

Type	Description
boolean	`true` if the ruler is visible; otherwise, `false`.

Remarks

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.

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

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

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

Remarks

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

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

// 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.

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’.

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`

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.

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.

See Also

Export a Document to PDF

focus Method

Sets input focus to the RichEdit.

Declaration

focus(): void

Remarks

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

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.

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

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	string \| File \| Blob \| ArrayBuffer	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.

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.

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	IPrintingSettings \| PrintMode	A print mode or an interface that declares print settings.

Remarks

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

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.

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.

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

See Also

Save a Document

setCommandEnabled(command, enabled) Method

Sets the command’s availability.

Declaration

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

Parameters

Name	Type	Description
command	CommandId \| RibbonItemId	The command identifier.
enabled	boolean	true to enable the command; false to disable the command.

Remarks

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

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.

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