Saving Ranges as Custom Building Blocks in Word 2007 Documents

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.

Download the Code Sample

To illustrate how to programmatically save a range as a custom building block, this section walks through five key steps:

1. Creating a Windows Console Application project in Microsoft Visual Studio 2005.

2. Adding a reference to the Word 12.0 Object Library.

3. Importing the Word Interop assembly namespace.

4. Declaring the appropriate variables.

5. Implementing the building block creation code.

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.

Imports Microsoft.Office.Interop.Word

using Microsoft.Office.Interop.Word;

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

ApplicationClass wordApplication = null;
Document wordDocument = null;
Template objTemplate;
Range objRange;

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

string paramBBName = "Header Test";
WdBuildingBlockTypes paramBBType = WdBuildingBlockTypes.wdTypeCustomHeaders;
string paramBBCategory = "Building Block Tests";
object paramBBDescription = "A sample header";
WdDocPartInsertOptions paramBBInsertOptions = 
    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:

1. Starts Word and creates a new temporary document.

2. Gets the "Building Blocks.dotx" template to store the building block in.

3. Creates a range and adds some text to it.

4. Adds a building block to the "Building Blocks.dotx" template based on the range created above. The building block properties are listed in Table 1.

   Table 1. Building block properties
   PropertyDescription

   NameHeader test

   TypeCustom Headers

   CategoryBuilding Block Tests

   TemplateBuilding Blocks.dotx

   BehaviorInsert content only

   DescriptionA sample header

5. Saves the template and closes Word.

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

try
{
    // Start an instance of Word.
    wordApplication = new ApplicationClass();

    // Create a new temporary document.
    wordDocument = wordApplication.Documents.Add(ref paramMissing,
        ref paramMissing, ref paramMissing, ref paramMissing);

    // 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.get_Item(ref paramTemplateIndex);

    // 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, ref paramBBDescription,
        paramBBInsertOptions);

    // Save the template.
    objTemplate.Save();
}
catch (Exception ex)
{
    // Respond to the error
}
finally
{
    // Release references to the Word objects.
    objRange = null;
    objTemplate = null;

    // Close and release the Document object.
    if (wordDocument != null)
    {
        wordDocument.Close(ref paramFalse, ref paramMissing,
            ref paramMissing);
        wordDocument = null;
    }

    // Quit Word and release the ApplicationClass object.
    if (wordApplication != null)
    {
        wordApplication.Quit(ref paramMissing, ref paramMissing,
            ref paramMissing);
        wordApplication = null;
    }
    
    GC.Collect();
    GC.WaitForPendingFinalizers();
    GC.Collect();
    GC.WaitForPendingFinalizers();
}

This How To explores how to programmatically save a range as a custom building block in Word 2007. The key steps include:

1. Creating a Windows Console Application project in Visual Studio 2005.

2. Adding a reference to the Word 12.0 Object Library to the project. This identifies the project as using the Word 12.0 Object Library.

3. Importing the Microsoft.Office.Interop.Word namespace. This allows the project code to use the classes and types exposed as part of the Microsoft.Office.Interop.Word namespace without having to specify the fully qualified namespace path.

4. Declaring variables to help with method calls.

5. Implementing the building block creation code.

Note

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.

Watch the Video

Video Length: 00:06:32

File Size: 6.26 MB WMV

• Working With Building Blocks

• BuildingBlockEntries Collection

• Word Object Model Reference

• Word 2007 Developer Reference

• Understanding the Word Object Model from a .NET Developer's Perspective

• Office Developer Center on MSDN

• Understanding Optional Parameters in COM Interop