Accessing Parts using Convenience Functions

Return to the
Open XML SDK for JavaScript
Developer Center
The 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:

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.