Skip to main content

DevExpress v24.2 Update — Your Feedback Matters

Our What's New in v24.2 webpage includes product-specific surveys. Your response to our survey questions will help us measure product satisfaction for features released in this major update and help us refine our plans for our next major release.

Take the survey Not interested

DocumentProcessorBase Class

Implements the base functionality of a document processor.

#Declaration

TypeScript
export abstract class DocumentProcessorBase

#Inheritance

DocumentProcessorBase

#Properties

#document Property

Provides access to document structural elements.

#Declaration

TypeScript

#Property Value

Type Description
RichEditDocumentBase

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

#Remarks

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

#onCalculateDocumentVariable Property

Specifies an event handler to a client event that occurs when a DOCVARIABLE field is updated.

#Declaration

TypeScript
set onCalculateDocumentVariable(val: null | ((s: DocumentProcessorBase, e: CalculateDocumentVariableEventArgs) => void))

#Property Value

Type Description
void

A function that handles the event. null to remove the event.

#Remarks

The CalculateDocumentVariable event fires when a DOCVARIABLE value is calculated (when a field is updated, or during the mail merge process). Handle this event to analyze the DOCVARIABLE field name and arguments, and provide custom content to insert into this field.

The DOCVARIABLE field has the following structure: { DOCVARIABLE “variable name” “argument1” “argument 2”… }

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!';
    }
}

#unitConverter Property

Allows you to convert units.

#Declaration

TypeScript
readonly unitConverter: UnitConverter

#Property Value

Type Description
UnitConverter

A unit converter object.

#Remarks

var size = new DevExpress.RichEdit.Size(
    richEdit.unitConverter.centimetersToTwips(24),
    richEdit.unitConverter.centimetersToTwips(18));
richEdit.document.sections.getByIndex(0).pageSize = size;

#Methods

#dispose Method

Releases resources used by the document processor.

#Declaration

TypeScript
dispose(): void

#Remarks

Note

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

var proc = richEdit.createDocumentProcessor();
...
proc.dispose();

#downloadDocument(fileName, documentFormat) Method

Downloads the current document.

#Declaration

TypeScript
downloadDocument(
    fileName: string,
    documentFormat: DocumentFormat
): void

#Parameters

Name Type Description
fileName string

The name of the downloaded document.

documentFormat DocumentFormat

The document format.

#downloadPdf(fileName) Method

Downloads the current document as a pdf file.

#Declaration

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

#Parameters

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

#exportDocumentToBase64(callback) Method

Exports the current document in the specified format to base64.

#Declaration

TypeScript
exportDocumentToBase64(
    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 exportDocumentToBase64 method exports the current document to a base64 string. Use the documentFormat parameter to specify the document’s format. After export, the document processor calls the callback function and returns the base64 string as a parameter. You can use this function to save the exported document.

var proc = richEdit.createDocumentProcessor();
...
proc.document.fields.updateAllFields(function () {
    proc.exportDocumentToBase64(function (base64) {
        proc.dispose();
        richEdit.openDocument(base64, 'someFile', DevExpress.RichEdit.DocumentFormat.OpenXml, function (succ) { console.log(succ); });
    }, DevExpress.RichEdit.DocumentFormat.OpenXml);
});

#exportDocumentToBlob(callback) Method

Exports the current document in the specified format to a blob.

#Declaration

TypeScript
exportDocumentToBlob(
    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 exportDocumentToBlob method exports the current document to a binary large object (blob). Use the documentFormat parameter to specify the document’s format. After export, the document processor calls the callback function and returns the blob as a parameter. You can use this function to save the exported document.

#exportToPdf(callback) Method

Exports the current document to PDF.

#Declaration

TypeScript
exportToPdf(callback: (base64: string, blob: Blob, stream: any) => void, options?: ((pdfDocument: any) => void) | {
    modifyPdfDocument?: (pdfDocument: any) => void;
    modifyPdfPage?: (pdfDocument: any) => void;
}): void

#Parameters

Name Type Description
callback (base64: string, blob: Blob, stream: any) => void

A function that gets the PDF document as a parameter.

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 document processor sends the resulting PDF file in the base64, blob, and stream formats to the callback function. You can use the function to save the exported document.

Tip

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

#importDocument(source, documentFormat, callback) Method

Imports a document from a base64 data or from a file.

#Declaration

TypeScript
importDocument(
    source: string | File,
    documentFormat: DocumentFormat,
    callback: (importSuccess: boolean) => void
): void

#Parameters

Name Type Description
source string | File

A document in a base64 format or a file object.

documentFormat DocumentFormat

The document format.

callback (importSuccess: boolean) => void

Allows you to perform custom actions after a file is imported.