Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Expand]Forms and User Controls
  [Expand]Messages, Notifications and Dialogs
  [Expand]Editors and Simple Controls
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Expand]Data Grid
  [Expand]Vertical Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Diagrams
  [Expand]Gauges
  [Expand]Map Control
  [Expand]Scheduler
  [Expand]Spreadsheet
  [Collapse]Rich Text Editor
    Overview
   [Expand]Getting Started
   [Collapse]Fundamentals
    [Expand]RichEditControl
    [Expand]Document
     Supported Document Formats
    [Collapse]Fields
     [Collapse]Field Codes
       AUTHOR
       COMMENTS
       CREATEDATE
       DATE
       DOCPROPERTY
       DOCVARIABLE
       HYPERLINK
       IF
       INCLUDEPICTURE
       KEYWORDS
       LASTSAVEDBY
       MERGEFIELD
       NUMPAGES
       PAGE
       PRINTDATE
       REVNUM
       SAVEDATE
       SEQ
       SUBJECT
       SYMBOL
       TC
       TIME
       TITLE
       TOC
     [Expand]Format Switches
      Field Structure
      Inserting a Field
      Field Display Modes
      Updating a Field
      Field Types
     Commands
     Services
     Layout API
     Product Class Structure
     Default Keyboard Shortcuts
     Measure Units
     HTML Tag Interpretation
   [Expand]Concepts
   [Expand]Visual Elements
   [Expand]Examples
   [Expand]Member Tables
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]Printing-Exporting
  [Expand]PDF Viewer
   Reporting
  [Expand]Snap
  [Expand]TreeMap Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

DOCVARIABLE

DOCVARIABLE

Mixed field

{ DOCVARIABLE "variable name" "argument1" "argument 2"... }

Expanded Overview

Inserts the value of a document variable specified by a text in the field argument. Document variables are contained in the DocumentVariableCollection collection object, accessible using the Document.Variables property.

You can handle the Document.CalculateDocumentVariable event which is fired before a field is updated. The CalculateDocumentVariableEventArgs.Arguments property provides access to a collection of arguments contained within the field, so that you can analyze them and calculate a proper value for the CalculateDocumentVariableEventArgs.Value property. That value substitutes the previous value of the field.

If the Document.CalculateDocumentVariable event is not handled, it does not occur. In this situation, the field update replaces its former value with the value of the corresponding document variable. If a variable with that name is not found, a field result is set to an empty string.

Note

When the DOCVARIABLE field is updated, its previous value is lost. To prevent this, handle the Document.CalculateDocumentVariable event and set the CalculateDocumentVariableEventArgs.Value property of event arguments to the DocVariableValue.Current value.

You can specify whether the DOCVARIABLE fields are updated before printing or copying a range to the Clipboard. Use the FieldOptions.UpdateDocVariablesBeforeCopy, Document.UpdateDocVariablesBeforePrint or the FieldOptions.UpdateDocVariablesBeforePrint option.

Expanded Locking the Field

If a field is locked (the Field.Locked property is true), the field cannot be updated by the Field.Update or FieldCollection.Update methods and by executing UI commands. The Document.CalculateDocumentVariable event is not raised for a locked field and it retains its previous value. However, you can set the FieldOptions.UpdateLockedFields option to change default actions for locked fields.

Expanded Simple Example of Use

You can return a text or the entire document as a document variable. Thus, updating a DOCVARIABLE field and handling the Document.CalculateDocumentVariable event is a useful method of constructing complex documents.

Consider mail merge activity. When the RichEditControl.MailMerge method is called, all fields are updated. A common task is to evaluate DOCVARIABLE fields in a document depending on the variable name and argument and then substitute fields with their values.

Show Me

A complete sample project is available in the DevExpress Code Examples database at http://www.devexpress.com/example=E3099.

This code snippet demonstrates how to handle the RichEditControl.CalculateDocumentVariable event to insert custom 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.

Expanded Master-Detail Report

A combination of the Mail Merge feature with the DOCVARIABLE field and RichEditDocumentServer instances enables you to create a master-detail report. Although the Snap Reporting performs this task with less effort, master-detail reporting is a good illustration of DOCVARIABLE versatility. For more information, review the following example.

Show Me

A complete sample project is available in the DevExpress Code Examples database at http://www.devexpress.com/example=E3662.

Expanded See Also

How would you rate this topic?​​​​​​​