Adding Custom Properties to New Documents in Office.js
Have you ever wanted to add custom information to your Word documents, Excel spreadsheets, or PowerPoint presentations? Office.js allows you to do exactly that! This article will guide you through the process of adding custom properties, known as "document properties" in Office, to newly created documents using Office.js.
The Problem: Adding Information Beyond the Basics
When creating documents in Microsoft Office applications, you can typically add basic information like the author, title, and subject. However, what if you need to store additional details, such as project codes, client names, or even custom metadata? This is where custom properties come in handy.
Code Example: A Simple Illustration
Let's start with a basic example of adding a custom property called "ProjectName" to a new Word document.
Office.onReady(function (info) {
if (info.host === Office.HostType.Word) {
// Get the current document
Word.run(function (context) {
// Add a custom property named "ProjectName"
context.document.properties.add("ProjectName", "My Awesome Project");
// Save the changes to the document
context.sync();
console.log("Custom property added!");
})
.catch(function (error) {
console.error("Error: " + error);
});
}
});
This code utilizes Office.js, the JavaScript API that allows you to interact with Office applications. The Office.onReady function ensures that the code runs only after Office is ready, and the Word.run function executes the code within the Word environment.
Understanding the Code:
Office.onReady: This ensures that the Office.js script runs only after Office has initialized.info.host === Office.HostType.Word: This condition checks if the script is running within Word. Adjust this condition for other Office applications like Excel or PowerPoint.Word.run: This function creates a context for working within the Word document.context.document.properties.add("ProjectName", "My Awesome Project"): This line adds a custom property with the name "ProjectName" and assigns the value "My Awesome Project" to it.context.sync(): This line saves the changes made to the document.
Beyond the Basics: Handling Different Data Types
Custom properties in Office.js support various data types, allowing you to store diverse information.
- Text: Simple text values, like in the example above.
- Number: Integer and decimal numbers.
- Date: Dates represented as ISO 8601 strings (e.g., "2023-09-26").
- Boolean: True or false values.
You can use the appropriate methods provided by Office.js to handle these data types during property creation.
Custom Properties in Action: A Real-World Use Case
Imagine you are creating a template for reports in Word. You can use custom properties to store information like:
- ReportType: "Monthly Sales Report" or "Quarterly Performance Report"
- ClientName: The name of the client for whom the report is generated.
- ReportDate: The date when the report was created.
These custom properties can then be used within the report document, perhaps displayed in a header or footer, to provide relevant context and information.
Conclusion: Expanding the Capabilities of Office
Custom properties in Office.js offer a powerful way to enrich documents with additional data, making them more informative and useful. This technique can be used to enhance templates, manage project information, and even create custom workflows within Office applications.
For further exploration and advanced use cases, consult the official Office.js documentation https://docs.microsoft.com/en-us/javascript/api/office/ and the Microsoft Developer Network (MSDN) https://msdn.microsoft.com/en-us/library/office/ff837081(v=office.15).aspx.
