Document summary

xlsgen > overview > Document summary

Excel properties commonly known as "Document summary" provide a useful way to store, search and retrieve metadata from a collection of workbooks, which benefits both users and developers. Windows built-in indexing service as well as desktop search tools take advantage of this metadata to search and retrieve documents based on it.

You can access the Document summary of any Excel workbook either within Excel (File / Properties), or by simply hovering your mouse on a file in Windows Explorer, and also by right-clicking on it. Screen captures show an example of what you can see :

Accessing the Document summary tabs from within Excel

Hovering your mouse on an Excel file in Windows explorer produces a Document summary tool tip

Right-clicking on an Excel file in Windows explorer also provides access to the Document summary

The Document summary comprises built-in properties and custom properties.

Built-in properties

Here is the table of built-in properties. A number of which are accessible in read and write. Some of these are only accessible in read.

Name	Type	Read/Write
DocumentTitle	string	R / W
Subject	string	R / W
Author	string	R / W
Keywords	string	R / W
Comments	string	R / W
Template	string	R
LastSavedBy	string	R / W
RevisionNumber	string	R / W
TotalEditTime	string	R
DateLastPrinted	date	R / W
DateCreated	date	R / W
DateLastSaved	date	R / W
Thumbnail	clipboard picture	R
ApplicationName	string	R / W
DocumentSecurity	long	R
Category	string	R / W
Manager	string	R / W
Company	string	R / W
SharedDocument	boolean	R / W
DocumentVersion	string	R / W
DigitalSignature	blob	R

Notice some of those built-in properties are exposed by xlsgen as read/write although the Excel own object model only exposes them as read-only. Examples are : LastSavedBy and RevisionNumber.

Custom properties

Custom properties are arbitrary properties accessible in read or write. A custom property is either a string, a boolean, a date (OLE date) or a number. An Excel workbook does not store any custom property by default. Custom properties are particularly useful to identify a particular document's state.

Programming the Document summary

The Document summary is accessed from the Properties method of the current workbook. This provides access to both built-in and custom properties.

Java code

XlsWorkbook workbook = engine.New("myfile.xls");

XlsWorksheet wksht001 = workbook.AddWorksheet("Sheet1");

// access built-in property Author
workbook.getProperties().getSummaryProperties().putAuthor("some author");

// create a custom property of type string
workbook.getProperties().getCustomProperties().AddAsString("mystring", "myvalue");

// create a custom property of type date
workbook.getProperties().getCustomProperties().AddAsDate("mydate", 32560); // 21/02/1989

// create a custom property of type integer
workbook.getProperties().getCustomProperties().AddAsInteger("myinteger", 3);

// create a custom property of type bool
workbook.getProperties().getCustomProperties().AddAsBoolean("myboolean", true);

// read and update an existing custom property
XlsWorkbookCustomProperty custom = 
	workbook.getProperties().getCustomProperties().getCustomPropertyByName("mystring");

custom.putPropertyValueAsString("another value");

workbook.Close();

VB code

Dim workbook As IXlsWorkbook
Set workbook = engine.New("myfile.xls")

Dim wksht As IXlsWorksheet
Set wksht = workbook.AddWorksheet("Sheet1")

' access built-in property Author
workbook.Properties.SummaryProperties.Author = "some author"

' create a custom property of type string
Dim v As Variant
v = "myvalue"
workbook.Properties.CustomProperties.Add "mystring", v

' create a custom property of type date
Dim d As Variant
d = CDate("Jan 1 2006")
workbook.Properties.CustomProperties.Add "mydate", d

' create a custom property of type integer
Dim i As Variant
i = CLng(3)
workbook.Properties.CustomProperties.Add "myinteger", i

' create a custom property of type bool
Dim b As Variant
b = CBool(True)
workbook.Properties.CustomProperties.Add "myboolean", b

' read and update an existing custom property
Dim customproperty As IXlsWorkbookCustomProperty
Set customproperty = workbook.Properties.CustomProperties.CustomPropertyByName("mystring")

customproperty.Value = "another value"

workbook.Close

C# code

IXlsWorkbook workbook = excel.New("myfile.xls");
IXlsWorksheet wksht = workbook.AddWorksheet("Sheet1");

// access built-in property Author
workbook.Properties.SummaryProperties.Author = "some author";

// create a custom property of type string
object mystring = "myvalue";
workbook.Properties.CustomProperties.Add("mystring", ref mystring);

// create a custom property of type date
object mydate = (object) new System.DateTime(2006, 1, 1);
workbook.Properties.CustomProperties.Add("mydate", ref mydate);

// create a custom property of type integer
object myinteger = 3;
workbook.Properties.CustomProperties.Add("myinteger", ref myinteger);

// create a custom property of type bool
object myboolean = true;
workbook.Properties.CustomProperties.Add("myboolean", ref myboolean);

// read and update an existing custom property
IXlsWorkbookCustomProperty custom = 
	workbook.Properties.CustomProperties.get_CustomPropertyByName("mystring");

object anothervalue = "another value";
custom.set_PropertyValue(ref anothervalue);


workbook.Close();

C/C++ code

xlsgen::IXlsWorkbookPtr wbk;

wbk = engine->New(L"myfile.xls");

xlsgen::IXlsWorksheetPtr wksht1 = wbk->AddWorksheet(L"Sheet1");

xlsgen::IXlsWorkbookPropertiesPtr properties = wbk->Properties;

// access some built-in properties
properties->SummaryProperties->Author = L"some author";
properties->SummaryProperties->DocumentVersion = L"10.2";
properties->SummaryProperties->RevisionNumber = L"11";

// create a custom property of type string
VARIANT v;
v.vt = VT_BSTR;
v.bstrVal = SysAllocString(L"my value");
wbk->Properties->CustomProperties->Add(L"mystring", &v);

// create a custom property of type date
VARIANT date;
date.vt = VT_DATE;
DATE dt;
HRESULT hrDate = VarDateFromStr(L"Jan 1 2006", LANG_USER_DEFAULT/*lcid*/, 0/*dwFlags*/, &dt);
date.date = dt;
wbk->Properties->CustomProperties->Add(L"mydate", &date);

// create a custom property of type integer
VARIANT i;
i.vt = VT_I4;
i.lVal = 3;
wbk->Properties->CustomProperties->Add(L"myinteger", &i);

// create a custom property of type bool
VARIANT b;
b.vt = VT_BOOL;
b.boolVal = TRUE;
wbk->Properties->CustomProperties->Add(L"myboolean", &b);

// read and update an existing custom property
xlsgen::IXlsWorkbookCustomPropertyPtr custom = 
	wbk->Properties->CustomProperties->CustomPropertyByName[L"mystring"];

VARIANT v2;
v2.vt = VT_BSTR;
v2.bstrVal = SysAllocString(L"another value");
custom->PropertyValue = v2;

wbk->Close();