Saving Ranges as Custom Building Blocks in Word 2007 Documents
Applies to: 2007 Microsoft Office System, Microsoft Office Word 2007
Joel Krist, Akona Systems
Microsoft Office Word 2007 introduces building blocks to help with the process of adding frequently used content to documents. You can select building blocks from a predefined gallery of cover pages, pull quotes, headers, and footers to make documents look more professional. You can also create building blocks to simplify adding custom text, such as legal disclaimer text or other frequently used materials. The Word 2007 object model provides the Template.BuildingBlockEntries.Add method, which can be used to add new building blocks to a template. This How To illustrates how to use the Template.BuildingBlockEntries.Add method to save a range as a custom building block.
To illustrate how to programmatically save a range as a custom building block, this section walks through five key steps:
Create a Windows Console Application in Visual Studio 2005
This How To creates a Windows console application to illustrate how to save a range as a custom building block. The following code is not specific to a Windows console application and can be used in a variety of application types.
To create a Windows Console Application project in Visual Studio 2005
Add a Reference to the Word 12.0 Object Library
You must add a reference to the Microsoft Word 12.0 Object Library in the Visual Studio project so that you can program against the Word object model.
To add a reference to the Word 12.0 Object Library
Figure 1. Add a Reference
Import the Word Interop Namespace
By importing the Microsoft.Office.Interop.Word namespace, the objects defined in the namespace can be used without having to specify the fully qualified namespace path. To import the namespace, open the Program.cs or Module1.vb source file and add the following code to the top of the source file.
For a Visual Basic project, add the code to the top of the source file, above the Module statement. For a C# project, add the code before the namespace statement and right after the default using statements created by Visual Studio.
Declare Appropriate Variables
Add the following code to declare variables to hold references to the Word objects that are used in the custom building block save code.
For a Visual Basic project, place all of the following variable declarations within Sub Main(). For a C# project, place all of the following variable declarations within the Main() function.
Dim wordApplication As ApplicationClass = Nothing Dim wordDocument As Document = Nothing Dim objTemplate As Template = Nothing Dim objRange As Range
Now, add the following code to declare variables for the building block properties.
Dim paramBBName As String = "Header Test" Dim paramBBType As WdBuildingBlockTypes = _ WdBuildingBlockTypes.wdTypeCustomHeaders Dim paramBBCategory As String = "Building Block Tests" Dim paramBBDescription As String = "A sample header" Dim paramBBInsertOptions As WdDocPartInsertOptions = _ WdDocPartInsertOptions.wdInsertContent
Finally, declare the following C# variables to help with calling methods in the Word object model that accept optional parameters and by reference parameters.
object paramMissing = Type.Missing; object paramTemplateIndex = 1; object paramFalse = false;
Use the paramMissing variable when you call methods that accept optional parameters. Optional parameters are only optional in Microsoft Visual Basic. You must specify a value for optional parameters in C#. Using Type.Missing as the value for an optional parameter tells the method called that the parameter is not specified, and that the method should use the parameter's default value.
Use the paramTemplateIndex variable and paramFalse variable to make it easier to call the ApplicationClass.Templates.get_Item method and the Document.Close method that accept parameters of type object passed by reference. By declaring and initializing the variables as objects, it is possible to pass the parameters by reference.
Implement the Building Block Creation Code
The next step is to add code that saves a range as a custom building block. The code in the following code block does the following:
The shutdown related code closes the Word document, quits the Word application, releases references to the underlying Word COM objects, and makes calls to the .NET garbage collector. For more information about releasing COM objects when using managed code, see Chapter 2: Basics of Office Interoperability (Part 2 of 3), from the book, Microsoft .NET Development for Microsoft Office.
Try ' Start an instance of Word. wordApplication = New ApplicationClass() ' Create a new temporary document. wordDocument = wordApplication.Documents.Add() ' Load the Building Blocks.dotx template to store the building block in. ' After calling LoadBuildingBlocks Building Blocks.dotx will be ' Templates(1). wordApplication.Templates.LoadBuildingBlocks() objTemplate = wordApplication.Templates(1) ' Create a range and add some text to it. objRange = wordApplication.Selection.Range objRange.Text = "This is a custom header Building Block." ' Add a building block to the template based on the selected range. objTemplate.BuildingBlockEntries.Add( _ paramBBName, paramBBType, paramBBCategory, _ objRange, paramBBDescription, paramBBInsertOptions) ' Save the template. objTemplate.Save() Catch ex As Exception ' Respond to the error. Finally ' Release references to the Word objects. objRange = Nothing objTemplate = Nothing ' Close and release the Document object. If Not wordDocument Is Nothing Then wordDocument.Close(False) wordDocument = Nothing End If ' Quit Word and release the ApplicationClass object. If Not wordApplication Is Nothing Then wordApplication.Quit() wordApplication = Nothing End If GC.Collect() GC.WaitForPendingFinalizers() GC.Collect() GC.WaitForPendingFinalizers() End Try
This How To explores how to programmatically save a range as a custom building block in Word 2007. The key steps include:
The example C# code shown above uses the Type.Missing object to specify that an optional parameter was not provided and to use the default parameter value. To change the behavior to use values other than the default parameter values, specify the appropriate parameter types and values. For more information about the methods used in the sample code and the parameters they accept, see the Word Object Model Reference on MSDN.
Video Length: 00:06:32
File Size: 6.26 MB WMV