[Expand]General Information
[Expand]WinForms Controls
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Collapse]Reporting
 [Expand]Product Information
 [Expand]Get Started with DevExpress Reporting
 [Expand]Create Popular Reports
 [Collapse]Detailed Guide to DevExpress Reporting
   Introduction to Banded Reports
  [Collapse]Provide Data to Reports
   [Expand]Bind a Report to a Data Source
   [Collapse]Bind Report Controls to Data
     Data Binding Modes Comparison
     Bind Report Controls to Data (Expression Bindings)
     Bind Report Controls to Data (Legacy Data Bindings)
     Use Embedded Fields (Mail Merge)
     Update Report Data Bindings
  [Expand]Use Report Controls
  [Expand]Shape Report Data
   Arrange Dynamic Report Contents
  [Expand]Customize Appearance
  [Expand]Add Navigation
  [Expand]Provide Interactivity
  [Expand]Add Extra Information
  [Expand]Merge Reports
  [Expand]Use Expressions
  [Expand]Store and Distribute Reports
  [Expand]Reporting API
 [Expand]Visual Studio Report Designer
 [Expand]Create End-User Reporting Applications
 [Expand]API Reference
[Expand]Report and Dashboard Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]eXpress Persistent Objects
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
View this topic on docs.devexpress.com (Learn more)

Use Embedded Fields (Mail Merge)

This topic describes how to provide data to report controls using the advanced Mail Merge binding method. This feature allows you to create templates in which data source values populate specific fields while other text remains constant.

Expanded Mail Merge Overview

You can use the mail merge feature for different purposes depending on the report's data binding mode.

This feature has the following advantages when a report uses expression bindings (the UserDesignerOptions.DataBindingMode is set to DataBindingMode.Expressions or DataBindingMode.ExpressionsAdvanced):

  • You can use mail merge to merge multiple data fields and static content in a control's text instead of running the Expression Editor and specifying a complex expression with formatting functions.
  • For the XRRichText control, mail merge allows you to change specific text parts' appearance using the formatting toolbar.

In the legacy binding mode (the UserDesignerOptions.DataBindingMode is set to DataBindingMode.Bindings), you can specify only one data field for a control's bindable properties. In this case, mail merge is one way to embed multiple data fields in a control's text along with static content.

Expanded Embed Fields in a Control Text

Initially, you can apply mail merge to the XRControl.Text property only. Double-click the required control on the design surface to invoke the in-place editor. Insert data field names with square brackets to create embedded fields and use any prefixes or postfixes.

You can embed a parameter's value into a control's content using the [?ParameterName] syntax.

A database barrel icon is displayed above the control if embedded fields are valid in the current data context (specified by the XtraReportBase.DataSource and XtraReportBase.DataMember properties). The same icon appears if you bind the control to data using expression bindings or legacy data bindings.

For the XRRichText control, you can select any text part and adjust its color and font options using the formatting toolbar.

Embedded fields are replaced with values obtained from an assigned data source when previewing or exporting a report:

Consider the following specifics and limitations when using embedded fields:

  • Field names should not use dots and spaces to be interpreted correctly.
  • Mail Merge is not available for a table's nested fields in a master-detail hierarchy.
  • You can insert embedded fields in the XRControl.Text property either at design time or runtime before the XtraReport.CreateDocument method is called. Therefore, the mail merge feature does not work if you supply the control text after report generation starts, for example, in the XRControl.BeforePrint event handler.
  • Embedded fields cannot be exported to XLS and XLSX as values; they are always exported as plain text. We recommend using text formats instead if you need to accompany dynamic data with static text.

Expanded Format Embedded Fields

The mail merge feature enables you to apply formats to embedded field values. Select a required data field and click the control's smart tag. Click the XRControl.TextFormatString property's ellipsis button, and in the invoked Format String Editor, choose a built-in format pattern.

This adds the selected format to the target data field by separating it from the field name with the ! symbol and applies this format to field values when previewing a document.

Expanded Supported Controls

You can apply the mail merge feature to the Text of the following report controls inherited from the XRFieldEmbeddableControl class:

Is this topic helpful?​​​​​​​