Accessing Parts using Convenience Functions
Return to the
Open XML SDK for JavaScript
Developer CenterThe normal way to navigate from the package to the main document part, or to navigate from one part to another part is through relationships. From one point of view, there are two varieties of relationships– implicit relationships and explicit relationships:
- Implicit relationships – these relationships are used in
Open XML when there is only one target part of a given relationship type.
While the relationship has a relationship ID, you will not find a reference to
this relationship ID in the markup for the source part. Instead, if you want
to get that related part, you look for a relationship with a given relationship
type. If it exists, then you can open the related part. An example of this
type of relationship is the relationship in WordprocessingML from the main
document part to the comments part. A document may or may not have comments,
so it may or may not have a comments part. To navigate to the comments part,
you look for a relationship with the relationship type of “http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments”. - Explicit relationships – these relationships are used in
Open XML when there may be more than one target part of a given relationship
type. You will always find markup in the source part that contains the
relationship ID. If you want to retrieve the related parts, you typically find
the markup in the source part that contains the reference to the related part.
You get the relationship ID from the markup, and then look up the relationship
by its relationship ID. An example of this type of relationship is the
relationship in WordprocessingML from the main document part to a header part.
There may be multiple header parts, so to navigate to the header part, you
first find the markup for the section properties in the main document part.
You then find the markup for the relationship to the header part and retrieve
the relationship ID. You then retrieve the relationship with the given ID, and
can retrieve the related part from the relationship that you found.
Note that most of the commonly used relationship types and
content types are pre-defined in openxml.js. The code that defines
these relationship and content types looks like this (sorry for the small font, but it looks better when it does not wrap):
// *********** relationship types *********** openXml.relationshipTypes = { alternativeFormatImport: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/aFChunk", calculationChain: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/calcChain", cellMetadata: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/sheetMetadata", chart: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/chart", chartColorStyle: "http://schemas.microsoft.com/office/2011/relationships/chartColorStyle", ... worksheet: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet", worksheetComments: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments", worksheetSortMap: "http://schemas.microsoft.com/office/2006/relationships/wsSortMap", xmlSignature: "http://schemas.openxmlformats.org/package/2006/relationships/digital-signature/signature", }; // ********************* content types *********************** openXml.contentTypes = { calculationChain: "application/vnd.openxmlformats-officedocument.spreadsheetml.calcChain+xml", cellMetadata: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheetMetadata+xml", chart: "application/vnd.openxmlformats-officedocument.drawingml.chart+xml", chartColorStyle: "application/vnd.ms-office.chartcolorstyle+xml", chartDrawing: "application/vnd.openxmlformats-officedocument.drawingml.chartshapes+xml", ... worksheetComments: "application/vnd.openxmlformats-officedocument.spreadsheetml.comments+xml", worksheetSortMap: "application/vnd.ms-excel.wsSortMap+xml", xmlSignature: "application/vnd.openxmlformats-package.digital-signature-xmlsignature+xml", };
For many of the explicit relationships, there are
convenience functions that make it easier to retrieve the related part. To
demonstrate the use of the convenience functions, first let us take a look at
how to retrieve a part when not using the convenience functions.
You can find the main document part like this:
// Open a blank document that is stored as a base64 string. var doc = new openXml.OpenXmlPackage(blankDocument_base64); // Get the main document part. var mainPart = doc.getPartByRelationshipType(openXml.relationshipTypes.mainDocument);
When using the convenience function, the code looks like
this:
// Open a document that is stored as a base64 string. var doc = new openXml.OpenXmlPackage(document_base64); // Get the main document part. var mainPart = doc.mainDocumentPart();
This pattern should look familiar – it is the same pattern
as followed by the Open XML SDK for the .NET Framework.
The difference in coding is more pronounced when finding the
comments part:
// Open a document that is stored as a base64 string. var doc = new openXml.OpenXmlPackage(document_base64); // Get the main document part. var mainPart = doc.mainDocumentPart().wordprocessingCommentsPart();
If we examine the wordprocessingCommentsPart
function, we see that it is defined like this:
openXml.OpenXmlPart.prototype.wordprocessingCommentsPart = function () { return this.getPartByRelationshipType( openXml.relationshipTypes.wordprocessingComments); };
You can see that these convenience methods are pretty
simple. However, these navigation operations are pretty comment. We often
need to write code to navigate from the package to the main document part, or
navigate from the main document part to the comments part or styles part, so these
convenience methods make it quite a bit easier.
You may find that you need to perform some navigation where
the convenience functions have not yet been written. When you encounter this
situation, you can either write a convenience function locally that follows the
same pattern, or you can simply use the getPartByRelationshipType or getPartsByRelationshipType
methods.