Manage Document Properties with Node.js via C++

Introduction

Microsoft Excel provides the ability to add properties to spreadsheet files. These document properties provide useful information and are divided into 2 categories as detailed below.

System-defined (built-in) properties: Built-in properties contain general information about the document like document title, author name, document statistics and so on.
User-defined (custom) properties: Custom properties defined by the end user in the form of a name‑value pair.

The most important point to know about built-in and custom properties is that built-in properties can be accessed and modified, but not created or removed. However, custom properties can be created and managed.

How to Manage Document Properties Using Microsoft Excel

Microsoft Excel allows you to manage the document properties of the Excel files in a WYSIWYG manner. Please follow the steps below to open the Properties dialog in Excel 2016.

From the File menu, select Info.

Selecting Info Menu

2. Click on the Properties heading and select Advanced Properties.

Clicking Advanced Properties Selection

3. Manage the file’s document properties.

Properties Dialog

In the Properties dialog, there are different tabs, such as General, Summary, Statistics, Contents, and Custom. Each tab helps configure different kinds of information related to the file. The Custom tab is used to manage custom properties.

How to Work with Document Properties Using Aspose.Cells

Developers can dynamically manage the document properties using the Aspose.Cells APIs. This feature helps developers store useful information along with the file, such as when the file was received, processed, time‑stamped, and so on.

Aspose.Cells for Node.js via C++ directly writes the information about API and version number in output documents. For example, upon rendering a document to PDF, Aspose.Cells for Node.js via C++ populates the Application field with the value 'Aspose.Cells' and the PDF Producer field with the value, e.g., 'Aspose.Cells v17.9'.

Please note that you cannot instruct Aspose.Cells for Node.js via C++ to change or remove this information from output documents.

How to Access Document Properties

Aspose.Cells APIs support both types of document properties, built‑in and custom. Aspose.Cells' Workbook class represents an Excel file and, like an Excel file, can contain multiple worksheets, each represented by the Worksheet class, whereas the collection of worksheets is represented by the WorksheetCollection class.

Use the WorksheetCollection to access the file’s document properties as described below.

To access built‑in document properties, use WorksheetCollection.getBuiltInDocumentProperties().
To access custom document properties, use WorksheetCollection.getCustomDocumentProperties().

Both the WorksheetCollection.getBuiltInDocumentProperties() and WorksheetCollection.getCustomDocumentProperties() return an instance of Aspose.Cells.Properties.DocumentPropertyCollection. This collection contains Aspose.Cells.Properties.DocumentProperty objects, each of which represents a single built‑in or custom document property.

It is up to the application requirements how to access a property; that is, by using the index or the name of the property from the DocumentPropertyCollection as demonstrated in the example below.

const path = require("path");
const AsposeCells = require("aspose.cells.node");

// The path to the documents directory.
const dataDir = path.join(__dirname, "data");
const filePath = path.join(dataDir, "sample-document-properties.xlsx");

// Instantiate a Workbook object and open an Excel file
const workbook = new AsposeCells.Workbook(filePath);

// Retrieve a list of all custom document properties of the Excel file
const customProperties = workbook.getCustomDocumentProperties();

// Accessing a custom document property by using the property name
const customProperty1 = customProperties.get("ContentTypeId");
console.log(`${customProperty1.getName()} ${customProperty1.getValue()}`);

// Accessing the same custom document property by using the property index
const customProperty2 = customProperties.get(0);
console.log(`${customProperty2.getName()} ${customProperty2.getValue()}`);

The Aspose.Cells.Properties.DocumentProperty class allows you to retrieve the name, value, and type of the document property:

To get the property name, use DocumentProperty.getName().
To get the property value, use DocumentProperty.getValue(). This returns the value as an object.
To get the property type, use DocumentProperty.getType(). This returns one of the PropertyType enumeration values. After you obtain the property type, use one of the DocumentProperty.ToXXX methods to obtain the value of the appropriate type instead of using DocumentProperty.getValue(). The DocumentProperty.ToXXX methods are described in the table below.

The DocumentProperty class also provides a set of methods that return the values of other data types.

Member Name	Description	ToXXX Method
Boolean	The property data type is Boolean	ToBool
Date	The property data type is DateTime. Note that Microsoft Excel stores only the date portion; no time can be stored in a custom property of this type	ToDateTime
Float	The property data type is Double	ToDouble
Number	The property data type is Int32	ToInt
String	The property data type is string	ToString

const path = require("path");
const AsposeCells = require("aspose.cells.node");

// The path to the documents directory.
const dataDir = path.join(__dirname, "data");
const filePath = path.join(dataDir, "sample-document-properties.xlsx");

// Instantiate a Workbook object and open an Excel file
const workbook = new AsposeCells.Workbook(filePath);

// Retrieve a list of all custom document properties of the Excel file
const customProperties = workbook.getCustomDocumentProperties();

// Accessing a custom document property
const customProperty1 = customProperties.get(0);

// Storing the value of the document property as an object
const objectValue = customProperty1.getValue();

// Accessing another custom document property
const customProperty2 = customProperties.get(1);

// Checking the type of the document property and then storing the value according to that type
if (customProperty2.getType() === AsposeCells.PropertyType.String) {
    const value = customProperty2.getValue().toString();
    console.log(`${customProperty2.getName()} : ${value}`);
}

How to Add or Remove Custom Document Properties

As described earlier, developers cannot add or remove built‑in properties because these properties are system‑defined, but it is possible to add or remove custom properties because they are user‑defined.

How to Add Custom Properties

Aspose.Cells APIs expose the add(string, string) method for the CustomDocumentPropertyCollection class in order to add custom properties to the collection. The add(string, string) method adds the property to the Excel file and returns a reference for the new document property as an Aspose.Cells.Properties.DocumentProperty object.

const path = require("path");
const AsposeCells = require("aspose.cells.node");

// The path to the documents directory.
const dataDir = path.join(__dirname, "data");

// Instantiate a Workbook object and open an Excel file
const workbook = new AsposeCells.Workbook(path.join(dataDir, "sample-document-properties.xlsx"));

// Retrieve a list of all custom document properties of the Excel file
const customProperties = workbook.getCustomDocumentProperties();

// Adding a custom document property to the Excel file
customProperties.add("Publisher", "Aspose");

// Save the resultant spreadsheet
workbook.save(path.join(dataDir, "out_sample-document-properties.xlsx"));

How to Configure “Link to Content” Custom Property

To create a custom property linked to the content of a given range, call the CustomDocumentPropertyCollection.addLinkToContent(string, string) method and pass the property name and source. You can check whether a property is configured as linked to content using the DocumentProperty.isLinkedToContent() method. Moreover, it is also possible to get the source range using the DocumentProperty.getSource() method.

We use a simple template Microsoft Excel file in the example. The workbook has a defined named range labeled MyRange, which refers to a cell value.

const path = require("path");
const AsposeCells = require("aspose.cells.node");

// The path to the documents directory.
const dataDir = path.join(__dirname, "data");

// Instantiate a Workbook object and open an Excel file
const workbook = new AsposeCells.Workbook(path.join(dataDir, "sample-document-properties.xlsx"));

// Retrieve a list of all custom document properties of the Excel file
const customProperties = workbook.getWorksheets().getCustomDocumentProperties();

// Add link to content.
customProperties.addLinkToContent("Owner", "MyRange");

// Accessing the custom document property by using the property name
const customProperty1 = customProperties.get("Owner");

// Check whether the property is linked to content
const isLinkedToContent = customProperty1.isLinkedToContent();

// Get the source for the property
const source = customProperty1.getSource();

// Save the file
workbook.save(path.join(dataDir, "out_sample-document-properties.xlsx"));

How to Remove Custom Properties

To remove custom properties using Aspose.Cells, call the DocumentPropertyCollection.remove(string) method and pass the name of the document property to be removed.

const path = require("path");
const AsposeCells = require("aspose.cells.node");

// The path to the documents directory.
const dataDir = path.join(__dirname, "data");

// Instantiate a Workbook object and open an Excel file
const workbook = new AsposeCells.Workbook(path.join(dataDir, "sample-document-properties.xlsx"));

// Retrieve a list of all custom document properties of the Excel file
const customProperties = workbook.getCustomDocumentProperties();

// Removing a custom document property
customProperties.remove("Publisher");

// Save the file
workbook.save(path.join(dataDir, "out_sample-document-properties.xlsx"));

Advanced Topics

Preview workbook with Node.js via C++ Manage Worksheets of Microsoft Excel files with Node.js via C++