Use Embedded Fields (Mail Merge)
- 4 minutes to read
This topic describes how to use Mail Merge to bind report controls to data. This feature allows you to create templates where data source values populate specific placeholders while other text remains constant.
You can apply mail merge to the Text of the following controls:
Embed Fields in the Text Value
XRLabel Control
Double-click a control on the design surface to invoke the in-place editor. Insert data field names enclosed in square brackets to create embedded fields.
When a user previews or exports the report, the data is retrieved from the source specified by the XtraReport.DataSource and XtraReport.DataMember (if applicable) properties. If the field name in the data source matches the name in square brackets, the name and the square brackets are replaced by the current field data.
The report is bound to a flat data table, so you cannot reference another table or query. However, you can use dot-separated complex names for the Federated Data Source, or refer to complex objects - collection items or nested properties.
Use the [?ParameterName] syntax to embed the value of the report parameter into the text displayed in the control:
A database barrel icon is displayed above the control if embedded fields are valid for report data source and data member. The same icon appears if you specify an expression for the control.
XRRichText Control
Double-click the Rich Text control to invoke the in-place rich text editor. You can select any text part and use the formatting toolbar to adjust its color and font.
Embedded fields are replaced with values obtained from the report’s data source when users preview or export the report:
The Rich Text control handles the text the mail merge fields return as plain text. You cannot use embedded fields in reports to insert text with complex formatting (RTF). This means that paragraphs are translated into line breaks.
However, you can use the DevExpress Office File API library to perform advanced mail merge operations, and load the resulting file into the Rich Text Control with the LoadFile method. For more information, review the following help topic: Mail Merge in Word Processing Document API.
Format Embedded Fields
You can apply formats to embedded field values. Select a data field and expand the control’s smart tag. Click the Format String property’s ellipsis button and choose a built-in format pattern in the invoked Format String Editor.
This adds the selected format to the data field. The format specifier is separated from the field name with the ! character and applies this format to field values when users preview or export a document.
Mail Merge and Expression Bindings
You can use mail merge fields in either the Text property or an expression bound to the Text property, but not both. An expression binding takes precedence over the Text property value, so when you bind an expression to the Text property, the property value is ignored and no mail merge is performed.
Mail Merge
Report Design Surface:
Code snippet:
Preview:
Expression Binding
Report Design Surface:
Code snippet:
xrLabel1.ExpressionBindings.AddRange(new DevExpress.XtraReports.UI.ExpressionBinding[] {
new DevExpress.XtraReports.UI.ExpressionBinding("BeforePrint", "Text", "\'Expression:\' + NewLine() + [CategoryName] + NewLine()+ [Description]")});
Preview:
Limitations
- Embedded fields cannot be exported to XLS and XLSX as values; they are always exported as plain text. We recommend that you use text formats instead to combine dynamic data and static text.
- Empty or missing value in the embedded field leaves a gap in the content. If it is important for your application, you can use the RichEditDocumentServer component to perform mail merge before the XRRichText control loads its content.
- Do not change embedded fields in the Text property value within the BeforePrint event handler. This event occurs after the embedded fields are processed, so your changes will have no effect.