Document properties allow some useful information to be stored along with the document. There are system (built-in) and user defined (custom) properties. Built-in properties contain such things as document title, author's name, document statistics, and so on. Custom properties are just name-value pairs where user defines both the name and value.
You can use document properties in your document automation project to store some useful info along with the document such as when the document was received/processed/time stamped and so on.
You can access document properties in Microsoft Word by using the File | Properties menu.
To access document properties in Aspose.Words do the following:
· To obtain built-in document properties, use Document.BuiltInDocumentProperties.
· To obtain custom document properties, use Document.CustomDocumentProperties.
Document.BuiltInDocumentProperties returns a Properties.BuiltInDocumentProperties object and Document.CustomDocumentProperties returns a Properties.CustomDocumentProperties object. Both objects are collections of the Properties.DocumentProperty objects. These objects can be obtained through the indexer property either by name or by index. Properties.BuiltInDocumentProperties additionally provides access to the document properties via a set of typed properties that return values of the appropriate type. Properties.CustomDocumentProperties allows adding or removing document properties from the document.
Example
Enumerates through all built-in and custom properties in a document.
[Java]
String fileName = getMyDir() + "Properties.doc";
Document doc = new Document(fileName);
System.out.println(MessageFormat.format("1. Document name: {0}", fileName));
System.out.println("2. Built-in Properties");
for (DocumentProperty prop : doc.getBuiltInDocumentProperties())
System.out.println(MessageFormat.format("{0} : {1}", prop.getName(), prop.getValue()));
System.out.println("3. Custom Properties");
for (DocumentProperty prop : doc.getCustomDocumentProperties())
System.out.println(MessageFormat.format("{0} : {1}", prop.getName(), prop.getValue()));
The Properties.DocumentProperty class allows you to get the name, value, and type of the document property:
· To get the name of a property, use Properties.DocumentProperty.Name.
· To get the value of a property, use Properties.DocumentProperty.Value. Properties.DocumentProperty.Value returns an Object, but there is a set of methods allowing you to get the value of the property converted to a particular type.
· To get the type of a property, use DocumentProperty.Type. This returns one of the PropertyType enumeration values. After you get to know what type the property is, you can use one of the DocumentProperty.ToXXX methods such as DocumentProperty.ToString and DocumentProperty.ToInt to obtain the value of the appropriate type instead of getting DocumentProperty.Value.
While Microsoft Word automatically updates some document properties when needed, Aspose.Words never automatically changes any properties. For example, Microsoft Word updates the time the document was last printed, last saved, updates statistical properties (word, paragraph, character etc counts).
Aspose.Words does not update any properties automatically, but provides a method for updating some statistical built-in document properties. Call the Document.UpdateWordCount method to recalculate and update the BuiltInDocumentProperties.Characters, BuiltInDocumentProperties.CharactersWithSpaces, BuiltInDocumentProperties.Words and BuiltInDocumentProperties.Paragraphs properties in the BuiltInDocumentProperties collection. This will ensure they are synchronized with changes made after the document was opened or created.
Note that Aspose.Words never updates the BuiltInDocumentProperties.Lines and BuiltInDocumentProperties.Pages properties.
You cannot add or remove built-in document properties in Aspose.Words, you can only change their values.
To add custom document properties in Aspose.Words, use CustomDocumentProperties.Add passing the name of the new property and the value of the appropriate type. The method returns the newly created DocumentProperty object.
Example
Checks if a custom property with a given name exists in a document and adds few more custom document properties.
[Java]
Document doc = new Document(getMyDir() + "Properties.doc");
CustomDocumentProperties props = doc.getCustomDocumentProperties();
if (props.get("Authorized") == null)
{
props.add("Authorized", true);
props.add("Authorized By", "John Smith");
props.add("Authorized Date", new Date());
props.add("Authorized Revision", doc.getBuiltInDocumentProperties().getRevisionNumber());
props.add("Authorized Amount", 123.45);
}
To remove custom properties, use DocumentPropertyCollection.Remove passing it the name of the property to remove.
Example
Removes a custom document property.
[Java]
Document doc = new Document(getMyDir() + "Properties.doc");
doc.getCustomDocumentProperties().remove("Authorized Date");