RecipientData Class
Data About Single Data Source Record.When the object is serialized out as xml, its qualified name is w:recipientData.
Inheritance Hierarchy
System.Object
DocumentFormat.OpenXml.OpenXmlElement
DocumentFormat.OpenXml.OpenXmlCompositeElement
DocumentFormat.OpenXml.Wordprocessing.RecipientData
Namespace: DocumentFormat.OpenXml.Wordprocessing
Assembly: DocumentFormat.OpenXml (in DocumentFormat.OpenXml.dll)
Syntax
'Declaration
<ChildElementInfoAttribute(GetType(Active))> _
<ChildElementInfoAttribute(GetType(UniqueTag))> _
<ChildElementInfoAttribute(GetType(ColumnIndex))> _
Public Class RecipientData _
Inherits OpenXmlCompositeElement
'Usage
Dim instance As RecipientData
[ChildElementInfoAttribute(typeof(Active))]
[ChildElementInfoAttribute(typeof(UniqueTag))]
[ChildElementInfoAttribute(typeof(ColumnIndex))]
public class RecipientData : OpenXmlCompositeElement
Remarks
The following table lists the possible child types:
Active <w:active>
ColumnIndex <w:column>
UniqueTag <w:uniqueTag>
[ISO/IEC 29500-1 1st Edition]
17.14.27 recipientData (Data About Single Data Source Record)
This element specifies information about a single record within an external data source. If a record shall be merged into a merged document, then no information is needed about that record within this part. However, if a given record shall not be merged into a merged document, then the value of the unique key for that record shall be stored within the uniqueTag element as a child of this element (along with the active element) to indicate this exclusion.
[Note: This mapping is necessary in place of simply using the element order to correspond to the record indices in the external data source, as records can be added or deleted from external data sources, and a means must be provided to maintain WordprocessingML external record specific data like that specified in the active element (§17.14.1) and the corresponding external data record when the WordprocessingML document is reconnected to the external data source; irrespective of the ordering of the records within the external data source. In other words, this element, and its child elements enable merged WordprocessingML documents to maintain the relationship between the records within an external data and record specific WordprocessingML parameters. end note]
[Example: Consider a merged WordprocessingML document that:
Has been connected to a specified external data source containing three records; and
Has been configured by the hosting application to not populate a merged document with the record pertaining to John Smith in the external data source.
Consider also that the first time the given WordprocessingML document was connected to the external data source, John Smith's record was in the second record in the data source.
When this merged document is connected to the external data source the recipientData element can be used to store the number and value of the column containing the unique key for each data record within the external data source including John Smith's. This setting is represented using the following WordprocessingML to use the hash codes within the recipientData element to uniquely identify the three records within the external data source.
<w:recipientData> <w:column w:val="1" /> <w:uniqueTag>1408613399</w:uniqueTag> </w:recipientData> <w:recipientData> <w:active w:val="0" /> <w:column w:val="1" /> <w:uniqueTag>870254691</w:uniqueTag> </w:recipientData> <w:recipientData> <w:column w:val="1" /> <w:uniqueTag>1107777181</w:uniqueTag> </w:recipientData>
Here, the first, second (John Smith record), and third records within the specified data source whose unique key values are 1408613399, 870254691, and 1107777181 have been associated with with recipient data via the active element to specify that the record associated with the given record (John Smith's record) must not be used to populate a merged WordprocessingML document.
With these association in place, if a fourth record is added to the given external data source above John Smith's record, when the given merged WordprocessingML document is reconnected to the external data source, the hosting application still knows that John Smith's record must not be used to populate a merged WordprocessingML document as it is associated via its unique key value and is not dependent on the given record's ordinal position within the external data source. end example]
Parent Elements |
|---|
Root element of WordprocessingML Mail Merge Recipient Data part; recipients (§17.14.29) |
Child Elements |
Subclause |
|---|---|
active (Record Is Included in Mail Merge) |
§17.14.1 |
column (Index of Column Containing Unique Values for Record) |
§17.14.7 |
uniqueTag (Unique Value for Record) |
§17.14.35 |
[Note: The W3C XML Schema definition of this element’s content model (CT_RecipientData) is located in §A.1. end note]
© ISO/IEC29500: 2008.
Thread Safety
Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.