Working with Bibliographies
|Word Developer Reference|
The Microsoft Office Word 2007 object model includes several objects designed for automating the creation of bibliographies. The following table lists the main objects of the Word Bibliography feature. You can use these objects, and additional proerties and methods in the Word 2007 object model, to add sources to the source lists, cite sources in a document, and manage sources. The new objects added to the Word 2007 object model for managing bibliography sources are shown in the following table.
|Source||An individual source, such as a book, journal article, or interview.|
|Sources||A collection of Source objects.|
|Bibliography||The list of sources cited in the document (the current list) or the list of sources available in the application (in the master list).|
Understanding the source XML
Sources are added to the source lists programmatically by using XML strings. Depending on the type of source you want to add, the required XML structure changes. To determine the XML structure for a source type, you can add the same source type manually, and then view the XML returned. The following steps describe how to do this.
- On the References ribbon, click Manage Sources.
- In the Source Manager dialog box, click New.
- In the Create Source dialog box, select the type of source to create. For this example, select Book.
- Fill out the source fields, as shown in the following table:
Field Value Author Andrew Dixon Title Stylish Bibliographies Year 2006 City Chicago Publisher Adventure Works Press Tag name And01
- You can view and add information to additional fields by checking Show All Bibliography Fields.
- Click OK.
- Close the Source Manager dialog box.
- Start the Microsoft Visual Basic Editor (Alt+F11).
- Display the Immediate Window (Ctrl+G).
- Paste and run the following code.
Sub GetBibliographyXML() Dim strXml As String Dim objSource As Source Set objSource = Application.Bibliography.Sources( _ Application.Bibliography.Sources.Count) Debug.Print objSource.XML End Sub
After following the previous steps, the Immediate Window contains the following XML code.
The Guid and LCID elements are optional, but you can provide values for them if you want. The Guid element value should be a valid GUID, which you can generate programmatically outside the Word object model. (See the Microsoft Visual Studio documentation or the Microsoft Windows documentation on MSDN for information about programmatically generating ID.) Word generates GUIDs when users add or edit a source. If you do not add a GUID to the XML and a user then edits a source, Word generates a GUID. This enables Word to determine which source is most recent, based on the value of the GUID, and to prompt whether the user wants Word to update the outdated source to maintain continuity between the master list and the current list.
The LCID specifies the language for the source. (See MSDN for valid language identification values.) Word uses the LCID to know how to display a cited source in a document's bibliography. For example, one source may be written in French, one in English, and one in Japanese. From the LCID, Word determines how to display names (for example, Last, First for English), what punctuation to use (for example, using comma in one language and a semicolon in another), and what strings to use (for example, whether to use "et al" or another localized form).
After removing optional elements, you may have a structure similar to the following XML structure. (You can determine which elements are required because they do not have a corresponding editable field in the Create Source dialog box. Omitting one or more required element raises a run-time error.)
Now that you have the basic structure of the source XML for a book, you can add additional book sources to the master source list and the current source list. You can locate additional elements by checking the Show All Bibliography Fields check box.
|Alternatively, you can obtain the XML from the bibliography source file named "sources.xml" located at
Adding sources to the master source list and the current source list
Adding sources to the master source list is similar to adding sources to the current source list, with the exception that you access the Sources collection from different main objects. To add a source to the master source list, you access the Sources collection from the Bibliography property of the Application object. To add a source to the current source list, access the Sources collection from the Bibliography property of the Document object.
The following example uses the basic structure determined previously to add another book source to the master source list.
You can change the line
Application.Bibliography.Sources.Add strXml to
Inserting a source programmatically into the master source list does not automatically add it to the current source list. However, to add a citation to a document, the source must be listed in the current source list. You can manually copy one or more sources from the master list to the current list by using the Source Manager dialog box, or you can programmatically copy one or more sources from the master list to the current list. The following example copies all sources in the master source to the current source. After the sources are added to your current list, you can insert citations for those sources into a document.
|The value of the Tag property must be unique across sources in the current list. Thus the
Sharing your source list
There may be times when you want to share a source list with others in an organization. When you add sources to the master list, Word adds them to a file names "sources.xml" located at
c:\Documents and Settings\<user>\Application Data\Microsoft\Bibliography\sources.xml. You can share this file with others by giving them the file, which users can then load manually from the Source Manager dialog box or programmatically through code.
|When a user loads a source file, this is a one-time-only occurence and does not change either the existing master list or their current list. They can manually add the items in the shared source file to the current list by using the Source Manager dialog box.|
You can programmatically load a shared source. The following example shows how to load a shared source file that is located on a share on a local computer.
|Sharing the source.xml source file shares only sources in the master source list. Sources located in the current source are located in a document's data store. You can access this file by saving a document and opening the resulting DOCX file in a file compression application, such as WinZip. You can find the source file at the path "customXml" with a file name of (or similar to) "item1.xml". If you need to share the sources in a document with other users, you can share this file the same way that you would share the master list source file, as described previously.|
Sorting the master source list
You can set the sort order in the Source Manager dialog box by using the BibliographySort property. The BibliographySort property can be a String value of "Author", "Tag", "Title", or "Year". This object does not alter the sorting of sources in the document's bibliography. The following example sorts the sources by title.
You can insert a bibliography citation by using the Add method for the Fields collection. The following example inserts a citation at the cursor for the source that you added previously. The text for the field equals the tag value, or the value of the Tag element, which in this case is "Mor01". (See the XML code in the AddBibSource subroutine shown previously for the XML string "<b:Tag>Mor01</b:Tag>".) The value of the Tag element also corresponds to the Tag property for a Source object.
Applying a bibliography style
After you insert a bibliography into a document, you can set the bibliography style. Word formats several different styles of bibliographies. You can set the bibliography style by using the BibliographyStyle property. This property can be one of the following String values:
- GOST - Name Sort
- GOST - Title Sort
- ISO 690 - First Element Date
- ISO 690 - Numerical Refence
|These values are included in Word 2007, but new values may be added at any point in the future as new bibliography styles are defined.|
The following example sets the default bibliography style to the MLA style.
|You can also define your own documentation style in XML. The directory |
Inserting a bibliography
As with citations, bibliographies use fields. To insert a bibliography, you need to insert a field with a wdFieldBibliography constant specified for the field type. The following code inserts a bibliography into the active document at the cursor. This example assumes that the cursor is located at the end of the document or on a new page.