7 Things Developers Should Know About the Publisher 2003 Object Model, Part 1

Article
07/11/2006

Andrew May
Microsoft Corporation

August 2005

Applies to:
Microsoft Office Publisher 2003

Summary: Learn what an experienced programmer needs to know before starting to use the Microsoft Office Publisher 2003 object model to automate the powerful print and Web publication functionality in Publisher. (15 printed pages)

Introduction
1: How the Publisher Object Model Is Structured
2: Using the ThisDocument Object
3: Commercial Printing Support in the Publisher Object Model
4: Performing Mail and Catalog Merges in Publisher
Conclusion
Additional Resources

Introduction

If you are an experienced developer new to the Microsoft Office Publisher 2003 object model, or Publisher in general, the wide range of publishing functionality supported in the object model can be confusing. Using the Publisher object model, you can automate:

Creating publications based on wizards and templates.
Generating mail and catalog merge publications.
Creating and publishing Web pages.
Formatting publications for commercial printing.
And much else.

Also, because Publisher is a desktop print and Web publishing application, its object model varies in several important ways from that of a typical word processing application such as Microsoft Office Word 2003.

This article, and its sequel, present information to orient you to seven areas that experienced programmers should know about before using the Publisher object model. Each of the seven areas are self-contained, so you can read the areas that apply to the programming solution you want to create.

Note If you are new to programming, and want to learn more about automating the Publisher object model, see Programming Publisher 2003 Made Easy: Lesson 1, the first in a five-part series that uses the Publisher object model to introduce Microsoft Visual Basic for Applications (VBA) and basic programming concepts, complete with hands-on exercises.

This article, Part 1, includes a discussion of how the Publisher object model is structured and the support it provides for formatting your publications for commercial printers and performing mail and catalog merges. The second article, 7 Things Developers Should Know About the Publisher 2003 Object Model, Part 2, covers creating publications from pre-defined wizards and templates, creating and publishing Web pages, and working with linked text boxes in your publication.

1: How the Publisher Object Model Is Structured

Structurally, the Publisher 2003 object model is relatively straightforward. As in other Microsoft Office applications, the Application object is the top-level object that contains the rest of the object model. The objects directly beneath the Application object either represent publications or content, such as Documents or Selection, or represent application settings, such as ColorSchemes, Options, and WebOptions.

The objects directly contained in the Application object include:

ColorSchemes: Represents the color schemes available in the Publisher application. For more information on how Publisher stores color schemes, see Transferring Publisher Custom Color Schemes Between Users and Computers.
Documents: Represents all open publications.
Options: Represents application and publication options in Publisher.
Selection: Represents the current selection in a window or task pane.
WebOptions: Represents the application settings for creating Web publications, including settings for saving and encoding the publication, and enabling Web-safe fonts.
Window: Represents the Publisher application window.

The Application object also contains several objects from the Office shared type library: Assistant, COMAddIns, CommandBars, FileDialog, FileSearch, and OfficeDataSourceObject.

Figure 1 shows the first three levels of the Publisher object model.

The Publisher object model

Figure 1. The Publisher object model

Using the Documents Collection

Publisher is a single document interface (SDI) application; a separate instance of Publisher is launched each time you open a publication. Each open document has its own unique Application object that you can access through code. However, the Publisher object model contains the Documents collection, which provides you with the advantages that come with a multiple document interface (MDI) in the developer environment. It gives you a simple, easy way of identifying and iterating through all the publications open on a system. This can be especially useful when you want to use code to:

Move content between publications.
Perform work on several publications at one time.

For example, suppose you want to create a function that iterates through all the publications you have open, and saves copies of any Web publications as HTML into a specific folder, as in the following function:

Function SaveOpenPubsAsHTML(FilePath As String)
Dim d As Document
  For Each d In Application.Documents
    If d.PublicationType = pbTypeWeb Then
      d.SaveAs Filename:=FilePath & d.Name, _
         Format:=pbFileHTMLFiltered, _
        AddToRecentFiles:=False
    End If
  Next d
End Function

Much of the code you write against the Publisher object model will likely involve the Document object. The Document object represents a publication; most of the objects it contains represent:

Publication content elements, such as the Page object.
Publication-level settings, such as the PageSetup and AdvancedPrintOptions objects.
User interface elements specific to each publication, such as the LayoutGuides and ScratchArea objects.

Figure 2 shows the structure of the Document object and the objects it contains. For clarity, the numerous objects contained in the ShapeRange object are not included.

Figure 2. The Document object model section (click picture to see larger image)

Within the Document object, the Pages collection represents the pages in a publication, with each Page object representing a specific page. Similar to the Document object, the objects the Page object contains represent:

Page content elements, such as the HeaderFooter and Shape objects.
Page-level settings, such as the WebPageOptions and Wizard objects.
User interface elements specific to each page, such as the LayoutGuides and RulerGuides objects.

Figure 3 shows the structure of the Page object and the objects it contains.

The Page object model section

Figure 3. The Page object model section

Using the Shapes Collection

The Shapes collection contains a Shape object for each object on the publication page. This includes:

General Publisher shapes such as tables, text boxes, and Web controls.
Office AutoShapes, such as rectangles, stars, and arrows.
Publisher wizard group shapes, such as calendars and Web navigation bars.
OLE objects.
Microsoft ActiveX controls.
Pictures and empty picture frames.

However, be aware there are cases where shapes that appear on a given publication page don't actually reside in that page's Shapes collection. For example:

Master pages contain the design and layout elements that the user wants to repeat on multiple pages in a publication. Users put these common elements on master pages to give their publication a more consistent appearance. A master page can contain anything that you can put on a publication page, as well as some elements (such as headers, footers, and layout guides) that you can only set up on a master page. These elements, while they appear to be on the publication page, actually belong to the Shapes collection of the master page applied to that publication page.
Shapes that you insert on one page, and that belong to the page's Shapes collection, may extend beyond the borders of that page. If you have two pages side-by-side as a reader spread, shapes on one page may extend onto the other page.

2: Using the ThisDocument Object

Similar to Word and Microsoft Office Excel 2003, each Publisher code project contains a special class module that enables you to write event handlers for that specific publication. This class module, ThisDocument, is located in the Publisher Objects folder in the Project Explorer window.

The ThisDocument class module represents the publication that contains the module. Any event handlers you write in the ThisDocument module automatically fire in response to the appropriate event in the publication; you do not have to declare or initialize ThisDocument as an object variable.

You can write ThisDocument event handlers for any of the Publisher Document events:

BeforeClose
Open
Redo
ShapesAdded
ShapesRemoved
Undo
WizardAfterChange

Note Publisher is a single document interface (SDI). Some events, such as the NewDocument and DocumentOpen events, though initiated in one instance of Publisher, actually take place in a separate application instance. For more information, see Using the NewDocument and DocumentOpen Events.

Use the following steps to create an event procedure.

Under your publication project in the Project Explorer window, double-click ThisDocument.
In the Object list box, select Document.
In the Procedure list box, select an event form. An empty subroutine is added to the class module.
Add the Visual Basic instructions you want to run when the event occurs.

The following example responds to the ShapesAdded event. If the user adds shapes to the publication, this event handler saves the publication as a new publication, with an appended file name, in the same directory. If the user already added shapes, the code does not save the publication as a new publication. Note that the Left function trims the ".pub" file extension off the original file name before appending the file name.

Private Sub Document_ShapesAdded()
  If Not Right(ThisDocument.FullName, 14) = "_newShapes.pub" Then
    ThisDocument.SaveAs _
      Filename:=Left(ThisDocument.FullName, Len(ThisDocument.FullName) - 4) & _
      "_newShapes"
    MsgBox Prompt:="You added shapes to the publication.", _
      Title:="Publication saved as new publication."
  End If
End Sub

You can also use the ThisDocument object in your code, as shown in the previous example. Because Publisher is a single document interface, the ThisDocument object is always equivalent to the ActiveDocument global property.

You cannot delete the ThisDocument class module from your project.

You can even use the ThisDocument object to initialize an application object, and thereby activate its event handlers. To do so, place the code that initializes the Application object within the Open event handler of the ThisDocument object.

First, create a class module, for example Class1, in which you declare the application object with events:

Public WithEvents App As Publisher.Application

Next, write your application event handlers in that class module:

Private Sub App_WindowPageChange(ByVal Vw As View)
  MsgBox Prompt:="You are now viewing page " & _
    ThisDocument.ActiveView.ActivePage.PageNumber, _
    Title:="Window Page Change Event"
End Sub

Finally, include code that initializes the Application object in the ThisDocument.Open event handler:

Dim pub As New Class1
Private Sub Document_Open()
  Set pub.App = Publisher.Application
End Sub

Now, as soon as the publication opens, the application object is initialized and able to respond to events.

3: Commercial Printing Support in the Publisher Object Model

The Publisher object model provides support for commercial printers who want to use automation to identify and fix potential problems with files, thereby avoiding costly mistakes during the printing process. Commercial printers perform these checks, often called prepress operations or preflight, to make sure the file is formatted and configured exactly as necessary for the commercial printing process.

For example, the preflight checks you automate using the Publisher object model could include:

Setting the color model of the publication
Setting which printer's marks to print, if any
Setting whether the publication is printed as a negative or flipped image
And many others

In addition, you can also select which inks you want to print, and set attributes of the plates for those inks.

If you are working with a commercial printer, or planning on sending your publications out for printing, you can use the Publisher object model to set the appropriate print settings before handing off your files, thereby helping ensure your publications are printed as you want them.

These print settings are contained in the Document.AdvancedPrintOptions object. In addition to many properties that let you control exactly how the publication is printed, the AdvancedPrintOptions object also contains the PrintablePlates collection. Each PrintablePlate object in this collection represents one ink for the publication. Use the PrintablePlate object to set attributes for that ink, such as the angle and frequency, or even whether to print that ink at all.

For more information on defining the color mode and inks used in a publications, and controlling print output using the Publisher 2003 object model, see Automating Commercial Printing Prepress Tasks in Publisher 2003, Part 1.

For a brief explanation of color models, see Choosing Colors and Inks for a Publication.

Figure 4 displays the AdvancedPrintOptions object and the child objects it contains.

Figure 4. The AdvancedPrintOptions object model section (click picture to see larger image)

Another area of interest to commercial printers is graphics management. Preflight checks often include determining such things as whether:

Linked image files are missing.
Images are the necessary format and resolution.
Images are sized proportionally.

In the Publisher user interface, you can use the Graphics Manager to identify potential issues with pictures in a file. The Publisher object model does not include a programmatic equivalent of the Graphics Manager; however, you can write your own custom procedures that check the image properties of importance to you or your printer and flag potential issues.

Each picture in a publication is represented by a Shape object whose Type property is either pbPicture or pbLinkedPicture. Each Shape object of these types contains a PictureFormat object whose properties represent the picture's characteristics.

Figure 5 shows the PictureFormat object and the properties it contains.

Figure 5. The PictureFormat object model section (click picture to see larger image)

For more information on managing graphics and performing design checks using the Publisher 2003 object model, see Automating Commercial Printing Prepress Tasks in Publisher 2003, Part 2.

Note If you are a commercial printer, Publisher offers support through the Publisher Service Provide Program. PSPP members get priority support and access to the resources they need to print Publisher files quickly and easily. To join the PSPP or learn more, visit Publisher Prepress on Office Online.

4: Performing Mail and Catalog Merges in Publisher

Like Word, Publisher enables you to perform mail merge operations. In addition, Publisher takes the mail merge concept one step further, enabling you to perform catalog merges.

Like mail merge, with catalog merge you combine information from a data source with a publication, used as a merge template, to create additional publication pages. Unlike mail merge, however, with catalog merge the pages you create display multiple data source records per page. Use catalog merge to create catalogs, directories, photo albums, or any other type of publication that displays one or more items per page. You can merge both text and pictures into your publication.

When you use catalog merge, you combine information from a data source with a catalog merge template to generate merged pages, which you can save as a new publication or add to the end of an existing publication. You can also save your catalog merge template and use it again, whenever you update the information in your data source, to create additional sets of merged pages.

You can programmatically perform mail and catalog merges using the Publisher object model. For more information, see Creating Catalogs with Microsoft Office Publisher 2003.

For more information on sorting and filtering data source records prior to performing the mail or catalog merge, see Sorting and Filtering Your Data for Mail or Catalog Merges in Microsoft Office Publisher 2003.

Conclusion

Now that we discussed how the Publisher object model is structured, we can examine areas where it offers unique functionality you will not find in a typical word processing application. Part two of this article covers creating publications from pre-defined wizards and templates, creating and publishing Web pages, and working with linked text boxes in your publication.

Additional Resources

This section lists a number of resources you can use to learn more about the products and technologies mentioned or used in this article.

Sites:

Articles:

Blogs:

Andrew May's Weblog