Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

Saving Ranges as Custom Building Blocks in Word 2007 Documents

Office 2007

Office Visual How To

Applies to: 2007 Microsoft Office System, Microsoft Office Word 2007

Joel Krist, Akona Systems

May 2007

Overview

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.

Code It

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

  1. Start Visual Studio.

  2. On the File menu, select New, and then select Project.

    The New Project dialog box appears.

  3. In the Project Types pane, select Visual C# or Visual Basic, and then select the Windows category.

  4. In the Templates pane, select Console Application.

  5. Specify a name for the project.

  6. Specify a location for the project and click OK.

    Visual Studio generates a Windows Console Application project with a single source file in it called Program.cs or Module1.vb, depending on the language selected in Step 3 above.

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

  1. On the Project menu, select the Add Reference… menu item.

    The Add Reference dialog box is displayed.

  2. Select the COM tab in the Add Reference dialog box, then locate and select the Microsoft Word 12.0 Object Library component.

  3. Click OK to add the reference.

Figure 1. Add a Reference

Adding 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.

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.

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

Now, add the following code to declare variables for the building block properties.

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(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();
}
Read It

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.

NoteNote
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.
See It

Saving Ranges as Custom Building Blocks

Watch the Video

Video Length: 00:06:32

File Size: 6.26 MB WMV

Explore It
Show:
© 2014 Microsoft