SubDocumentReference Class

  • Article

Anchor for Subdocument Location.When the object is serialized out as xml, its qualified name is w:subDoc.

Inheritance Hierarchy

System.Object
  DocumentFormat.OpenXml.OpenXmlElement
    DocumentFormat.OpenXml.OpenXmlLeafElement
      DocumentFormat.OpenXml.Wordprocessing.RelationshipType
        DocumentFormat.OpenXml.Wordprocessing.SubDocumentReference

Namespace:  DocumentFormat.OpenXml.Wordprocessing
Assembly:  DocumentFormat.OpenXml (in DocumentFormat.OpenXml.dll)

Syntax

'Declaration
Public Class SubDocumentReference _
    Inherits RelationshipType
'Usage
Dim instance As SubDocumentReference

public class SubDocumentReference : RelationshipType

Remarks

[ISO/IEC 29500-1 1st Edition]

17.17.1.1 subDoc (Anchor for Subdocument Location)

This element specifies a location within a master document for the insertion of the contents of a specified subdocument. The specified subdocument's contents should appear at the specified location within the master document as needed, but shall remain part of the separate file specified by the subdocument location. The location of the subdocument shall be specified by the relationship whose Id attribute matches the id attribute on this element.

If the relationship type of the relationship specified by this element is not https://schemas.openxmlformats.org/officeDocument/2006/subDocument, is not present, or does not have a TargetMode attribute value of External, then the document shall be considered non-conformant.

When a subdocument is displayed at the specified location within the master document, the following logic determines how the styles and formatting of the subdocument and associated master document shall be handled:

  • All direct formatting in the subdocument is retained.

  • For each style in each subdocument:

If a style with the same styleId attribute value exists in the master document, display the contents of the subdocument using the style in the master document.

Otherwise, import the style into the master document and display the content using the original style.

If a subsequent subdocument also contains a style with the same styleId attribute value, the latter’s style is ignored and the content is displayed using the version of the style imported into the master document.

[Example: Consider a book consisting of three chapters, two of which have been divided into subdocuments as follows (the red rectangle indicates the bounds of each subdocument's contents):

DocumentFormat.OpenXml.Wordprocessing.SubDocumentR

The resulting master document would consist of its own WordprocessingML content as well as subdocument anchors in the appropriate locations:

<w:body>
<w:p>
…
<w:r>
<w:t>My Book</w:t>
</w:r>
</w:p>
<w:p>
<w:r>
<w:t>Once upon a time…</w:t>
</w:r>
</w:p>
<w:p>
<w:subDoc r:id="subDocRel1" />
</w:p>
<w:p>
<w:subDoc r:id="subDocRel2" />
</w:p>
<w:sectPr>
…
</w:sectPr>
</w:body>

The two subDoc elements specify that the subdocuments targeted by the relationships with an ID of subDocRel1 and subDocRel2 must be imported in that order after the content of the first two paragraphs of content. Examining the contents of the corresponding relationship part item, we can see the targets for those relationships:

<Relationships … >
…
<Relationship Id="subDocRel1" TargetMode="External" Type="https://schemas.openxmlformats.org/officeDocument/2006/relationships/subDocument" Target="Chapter1.docx" />
<Relationship Id="subDocRel2" TargetMode="External" Type="https://schemas.openxmlformats.org/officeDocument/2006/relationships/subDocument" Target="Chapter2.docx" />
…
</Relationships>

The corresponding relationship part item shows that the two files to be imported are located in the same location as the current file and name Chapter1.docx and Chapter2.docx respectively. end example]

Parent Elements

bdo (§17.3.2.3); customXml (§17.5.1.3); dir (§17.3.2.8); fldSimple (§17.16.19); hyperlink (§17.16.22); p (§17.3.1.22); sdtContent (§17.5.2.36); smartTag (§17.5.1.9)

Attributes

Description

id (Relationship to Part)

Namespace: .../officeDocument/2006/relationships

Specifies the relationship ID to a specified part.

The specified relationship shall match the relationship type required by the parent element:

  • https://schemas.openxmlformats.org/officeDocument/2006/customXml for the contentPart element

  • https://schemas.openxmlformats.org/officeDocument/2006/relationships/footer for the footerReference element

  • https://schemas.openxmlformats.org/officeDocument/2006/relationships/header for the headerReference element

  • https://schemas.openxmlformats.org/officeDocument/2006/relationships/font for the embedBold, embedBoldItalic, embedItalic, or embedRegular elements

  • https://schemas.openxmlformats.org/officeDocument/2006/relationships/printerSettings for the printerSettings element

  • https://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink for the longDesc or hyperlink element

[Example: Consider an XML element which has the following id attribute:

<… r:id="rId10" />

The markup specifies the associated relationship part with relationship ID rId1 contains the corresponding relationship information for the parent XML element. end example]

The possible values for this attribute are defined by the ST_RelationshipId simple type (§22.8.2.1).

[Note: The W3C XML Schema definition of this element’s content model (CT_Rel) 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.

See Also

Reference

SubDocumentReference Members

DocumentFormat.OpenXml.Wordprocessing Namespace