DOCVARIABLE

Aug 03, 2022
5 minutes to read

Mixed field

{ DOCVARIABLE “variable name” “argument1” “argument 2”… }

Inserts a string associated with a document variable.

The following members are used to obtain a DOCVARIABLE field value.

Member	Description
Document.Variables	RichEditControl first searches this collection for a specified variable.
Document.CalculateDocumentVariable	If the variable is not found in the collection, the control raises this event so you can specify the value in code.

Note

Set the event arguments’ CalculateDocumentVariableEventArgs.Value property to the DocVariableValue.Current value in the CalculateDocumentVariable event handler to save the initial DOCVARIABLE field value.

Use one of the following options to specify whether to update the DOCVARIABLE fields before printing or copying a range to the clipboard:

How to: Handle the CalculateDocumentVariable Event to Insert Formatted String

Tip

You can handle the CalculateDocumentVariable event to insert content from the RichEditDocumentServer, SubDocument or DocumentRange object. Refer to the following topic for more information:

Read Tutorial: How to: Insert Dynamic Content

This code snippet demonstrates how to handle the RichEditControl.CalculateDocumentVariable event to insert dynamic content into the document. In this example, it is used to get weather conditions. A variable name specified in the DOCVARIABLE field indicates a choice between location and weather, while the location itself is specified by the field argument.

View Example

Form1.cs
Form1.vb

csharp

void eventHandler_CalculateDocumentVariable(object sender, CalculateDocumentVariableEventArgs e) {
    if (e.Arguments.Count > 0) {
        string location = e.Arguments[0].Value.ToString();
        if ((location.Trim() == String.Empty) || (location.Contains("<"))) {
            e.Value = " ";
            e.Handled = true;
            return;
        }
        switch (e.VariableName) {
            case "Weather":
                Conditions conditions = new Conditions();
                conditions = Weather.GetCurrentConditions(location);
                e.Value = String.Format("Weather for {0}: \nConditions: {1}\nTemperature (C) :{2}\nHumidity: {3}\nWind: {4}\n",
                    location, conditions.Condition, conditions.TempC, conditions.Humidity, conditions.Wind);
                break;
            case "LOCATION":
                if (location == "DO NOT CHANGE!") e.Value = DocVariableValue.Current;
                break;
            default:
                e.Value = "LOCKED FIELD UPDATED";
                break;
        }
    }
    else {
        e.Value = "LOCKED FIELD UPDATED";
    }
    e.Handled = true;
}

Private Sub eventHandler_CalculateDocumentVariable(ByVal sender As Object, ByVal e As CalculateDocumentVariableEventArgs) Handles richEditControl1.CalculateDocumentVariable
    If e.Arguments.Count > 0 Then
        Dim location As String = e.Arguments(0).Value.ToString()
        If (location.Trim() = String.Empty) OrElse (location.Contains("<")) Then
            e.Value = " "
            e.Handled = True
            Return
        End If
        Select Case e.VariableName
            Case "Weather"
                Dim conditions As New Conditions()
                conditions = Weather.GetCurrentConditions(location)
                e.Value = String.Format("Weather for {0}: " & vbLf & "Conditions: {1}" & vbLf & "Temperature (C) :{2}" & vbLf & "Humidity: {3}" & vbLf & "Wind: {4}" & vbLf, location, conditions.Condition, conditions.TempC, conditions.Humidity, conditions.Wind)
            Case "LOCATION"
                If location = "DO NOT CHANGE!" Then
                    e.Value = DocVariableValue.Current
                End If
            Case Else
                e.Value = "LOCKED FIELD UPDATED"
        End Select
    Else
        e.Value = "LOCKED FIELD UPDATED"
    End If
    e.Handled = True
End Sub

How to: Handle the Event to Insert a Document Element

The code sample below shows how to handle the RichEditControl.CalculateDocumentVariable event to insert a barcode and a table:

C#
VB.NET

csharp

using DevExpress.BarCodes;
using DevExpress.XtraBars.Ribbon;
using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;
using System.Drawing;
using System.Text;
//...

richEditControl.CreateNewDocument();
Document document = richEditControl.Document;

// Create fields for a barcode and a table:
document.Fields.Create(document.Range.End, "DOCVARIABLE QRCODE");
document.Paragraphs.Append();
document.Fields.Create(document.Range.End, "DOCVARIABLE TABLE");

richEditControl.CalculateDocumentVariable += RichEditControl_CalculateDocumentVariable;
richEditControl.BeforeExport += RichEditControl_BeforeExport;

// Update all document fields:
document.UpdateAllFields();

// Save the result:
richEditControl.SaveDocument("result.docx", DocumentFormat.Docx);

private void RichEditControl_BeforeExport(object sender, BeforeExportEventArgs e)
{
    richEditControl.Document.UnlinkAllFields();
}

void RichEditControl_CalculateDocumentVariable(object sender, CalculateDocumentVariableEventArgs e)
{
    switch (e.VariableName)
    {
        case "QRCODE":
            // Create new RichEditDocumentServer instance:
            var doc = new RichEditDocumentServer();

            // Insert a barcode as a shape
            Shape picture = doc.Document.Shapes.InsertPicture(doc.Document.Range.End, GenerateQrCode());
            picture.TextWrapping = TextWrappingType.InLineWithText;

            // Set the field value to the RichEditDocumentServer instance:
            e.Value = doc;
            e.Handled = true;
            break;
        case "TABLE":
            // Create new RichEditDocumentServer instance:
            var doc1 = new RichEditDocumentServer();

            // Insert a table:
            GenerateTable(doc1.Document);

            // Set the field value to the RichEditDocumentServer instance:
            e.Value = doc1;
            e.Handled = true;
            break;
    }
}

// This method generates a barcode:
Bitmap GenerateQrCode()
{
    BarCode barCode = new BarCode();
    barCode.Symbology = Symbology.QRCode;
    barCode.CodeText = "https://www.devexpress.com/";
    barCode.BackColor = Color.White;
    barCode.ForeColor = Color.Black;
    barCode.RotationAngle = 0;
    barCode.CodeBinaryData = Encoding.Default.GetBytes(barCode.CodeText);
    barCode.Options.QRCode.CompactionMode = QRCodeCompactionMode.Byte;
    barCode.Options.QRCode.ErrorLevel = QRCodeErrorLevel.Q;
    barCode.Options.QRCode.ShowCodeText = false;
    barCode.DpiX = 72;
    barCode.DpiY = 72;
    barCode.Module = 2f;

    return barCode.BarCodeImage;
}

// This method generates a table:
Table GenerateTable(Document document)
{
    Table table = document.Tables.Create(document.Range.Start, 3, 3);

    document.InsertSingleLineText(table.Rows[0].Cells[1].Range.Start, "Active Customers");
    document.InsertSingleLineText(table[1, 0].Range.Start, "Photo");
    document.InsertSingleLineText(table[1, 1].Range.Start, "Customer Info");
    document.InsertSingleLineText(table[1, 2].Range.Start, "Rentals");

    return table;
}

Imports DevExpress.BarCodes
Imports DevExpress.XtraBars.Ribbon
Imports DevExpress.XtraRichEdit
Imports DevExpress.XtraRichEdit.API.Native
Imports System.Drawing
Imports System.Text
'...

richEditControl.CreateNewDocument()
Dim document As Document = richEditControl.Document

' Create fields for a barcode and a table:
document.Fields.Create(document.Range.End, "DOCVARIABLE QRCODE")
document.Paragraphs.Append()
document.Fields.Create(document.Range.End, "DOCVARIABLE TABLE")

AddHandler richEditControl.CalculateDocumentVariable, AddressOf RichEditControl_CalculateDocumentVariable
AddHandler richEditControl.BeforeExport, AddressOf RichEditControl_BeforeExport

' Update all document fields:
document.UpdateAllFields()

' Save the result:
richEditControl.SaveDocument("result.docx", DocumentFormat.Docx)

Private Sub RichEditControl_BeforeExport(ByVal sender As Object, ByVal e As BeforeExportEventArgs)
    richEditControl.Document.UnlinkAllFields()
End Sub

Private Sub RichEditControl_CalculateDocumentVariable(ByVal sender As Object, ByVal e As CalculateDocumentVariableEventArgs)
    Select Case e.VariableName
        Case "QRCODE"
            ' Create new RichEditDocumentServer instance:
            Dim doc = New RichEditDocumentServer()

            ' Insert a barcode as a shape
            Dim picture As Shape = doc.Document.Shapes.InsertPicture(doc.Document.Range.End, GenerateQrCode())
            picture.TextWrapping = TextWrappingType.InLineWithText

            ' Set the field value to the RichEditDocumentServer instance:
            e.Value = doc
            e.Handled = True
        Case "TABLE"
            ' Create new RichEditDocumentServer instance:
            Dim doc1 = New RichEditDocumentServer()

            ' Insert a table:
            GenerateTable(doc1.Document)

            ' Set the field value to the RichEditDocumentServer instance:
            e.Value = doc1
            e.Handled = True
    End Select
End Sub

' This method generates a barcode:
Private Function GenerateQrCode() As Bitmap
    Dim barCode As New BarCode()
    barCode.Symbology = Symbology.QRCode
    barCode.CodeText = "https://www.devexpress.com/"
    barCode.BackColor = Color.White
    barCode.ForeColor = Color.Black
    barCode.RotationAngle = 0
    barCode.CodeBinaryData = Encoding.Default.GetBytes(barCode.CodeText)
    barCode.Options.QRCode.CompactionMode = QRCodeCompactionMode.Byte
    barCode.Options.QRCode.ErrorLevel = QRCodeErrorLevel.Q
    barCode.Options.QRCode.ShowCodeText = False
    barCode.DpiX = 72
    barCode.DpiY = 72
    barCode.Module = 2F

    Return barCode.BarCodeImage
End Function

' This method generates a table:
Private Function GenerateTable(ByVal document As Document) As Table
    Dim table As Table = document.Tables.Create(document.Range.Start, 3, 3)

    document.InsertSingleLineText(table.Rows(0).Cells(1).Range.Start, "Active Customers")
    document.InsertSingleLineText(table(1, 0).Range.Start, "Photo")
    document.InsertSingleLineText(table(1, 1).Range.Start, "Customer Info")
    document.InsertSingleLineText(table(1, 2).Range.Start, "Rentals")

    Return table
End Function