This documentation is archived and is not being maintained.

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

Office 2003

Andrew May
Microsoft Corporation

September 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. (14 printed pages)


5: Working with Publisher Wizards and Templates
6: Creating Web Pages with the Publisher Object Model
7: Creating and Managing Linked Text Boxes in Publisher 2003
Additional Resources


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.

This article picks up where we left off in part one: 7 Things Developers Should Know About the Publisher 2003 Object Model, Part 1. Previously, 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, such as:

  • Creating publications from pre-defined wizards and templates.
  • Creating and publishing Web pages.
  • Working with linked text boxes in your publication.
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. This article is the first in a five-part series that uses the Publisher object model to introduce Visual Basic for Applications (VBA) and basic programming concepts, complete with hands-on exercises.

5: Working with Publisher Wizards and Templates

Publisher has a different concept of templates and wizards than other Office programs, such as Microsoft Office Word 2003. In Publisher, both terms refer to publication types on which you can base your publications, with important differences:

  • Publication wizards are pre-defined publications that come included with Publisher. These publication wizards contain text boxes and other design elements that you can customize, and to which you can add your content in the publications you create using them. Publication wizards also contain design automation options that enable you to change the layout and design of your publication quickly.
  • Templates are user-created publications that you can save to use as the basis for creating other publications. If you save the template to a specific location, Publisher then makes it available as a template on the New Publication task pane in the application interface.

Let's examine each of these in detail.

Using Wizards to Create Publications in Publisher 2003

Publication wizards are a powerful and versatile feature in Microsoft Office Publisher 2003. As mentioned previously, wizards are pre-defined publication templates included as part of Publisher. Wizards enable you to generate professional-looking publications quickly in a wide range of formats, from invitations to flyers to catalogs to Web sites.

When you create a publication using a wizard, Publisher populates the new publication with design elements based on the wizard type and design you choose. You can add your content to these elements, and customize the elements as you desire. You can change the appearance of the publication later by simply specifying a different design available for that wizard. The wizard then morphs the publication to adhere to that design scheme.

In Publisher, morphing refers to the ability of an object (be it a shape, page, or entire publication) to change its appearance based on the user's choice of design. Choose a different design, and Publisher automatically updates the object according to the design chosen.

Some wizards generate multi-page publications, with different content and design options depending on the page. For example, a newsletter may include different design elements present on the front cover than on the interior pages.

Unlike templates in applications such as Word, you cannot access or alter publication wizards themselves. However, you can create a user-defined template based on a publication wizard. In such a case, you can alter the template in any way you like, such as adding VBA code to the publication, and the template retains the morphing and other functionality of the wizard on which it is based. For more information, see Creating and Using Templates in Publisher 2003.

The Publisher object model lets you extend the design flexibility in publication wizards even farther by automating the generation and customization of publications based on wizards. Any publication created based on a publication wizard template has a Wizard object as the child of its Document object. If you create a publication based on a multi-page wizard template, the individual pages in the publication may have wizard properties that apply to only that page. In such a case, each Page object in the publication contains its own Wizard object as well. For more information on programmatically working with publication wizards, see Creating and Customizing Wizard Publications in Publisher 2003.

Shapes in Publisher also have wizard properties. Any shape that Publisher adds to the default appearance of a publication based on a wizard design has properties that uniquely identify it. Publisher uses these properties to keep track of shapes that "belong" to the wizard design, as opposed to any custom shapes the user might add to the publication later. For more information, see Identifying Wizard Shapes in a Publication

Note   Publisher also includes group wizard shapes, which are related to, but independent from, the publication and page-level wizards. Group wizard shapes are pre-defined group shapes, such as calendars, coupons, or Web navigation bars, that contain design automation options. Unlike wizard publications, you can add group wizard shapes to any publication, whether or not it is based on a publication wizard. Also, you set the design of each group wizard shape individually. For more information, see Working with Group Wizard Shapes

Creating and Using Templates in Publisher 2003

You can also create templates in Publisher. Templates are especially useful if you create certain publications, such as newsletters, flyers, or postcards, over and over again. Templates enable you to design master publications that reflect your company's brand and identity; you can then use that template to create additional publications, adding only the information that is unique to each publication.

Publisher templates are simply publications saved to a specific user directory. Each time you launch a new instance of Publisher, the application makes the publications in that directory available as templates on the New Publication task pane.

To create a template, save your publication to the following user directory:

Drive:\Documents and Settings\userName\Application Data\Microsoft\Templates

Where Drive represents the computer drive letter, and userName represents the name of the user to whom you want to make this publication available as a template. If you want to make the template available to multiple users on the same computer, you must save the template to the specified location in each user's directory.

Publisher displays available templates under Templates in the New Publications task pane. Because Publisher loads the available templates on launch, you need to open a new instance of Publisher for the new templates to be available. Even then, the new template is not displayed in any instances of Publisher launched before the template was saved.

If you do not have any templates saved, the Templates folder does not appear on the New Publication task pane.

To save a publication as a template programmatically, use the Document.SaveAs method, specifying the file location specified in the Filename parameter. This is directly equivalent to selecting Save as type: Publisher Template in the Save As dialog box.

The following function saves the specified document as a template:

Function SaveAsTemplate(pub As Document, fileName As String)
  With pub
   .SaveAs fileName:= _
   "C:\Documents and Settings\user\Application Data\Microsoft\Templates\" _
      & fileName, _
      Format:=pbFilePublication, _
  End With
End Function

You can specify custom categories to group your templates. The custom categories are listed under Templates in the New Publications task pane. To do this, specify a category for the publication before you save it as a template. From the File menu, select Properties. On the Summary tab, enter a value for Category. If you do not specify a category for your template, Publisher displays it in a category named My Templates by default.

Note   There is no way to set a publication's properties programmatically, such as Category, using the Publisher object model.

Any Visual Basic for Applications (VBA) code contained in the template gets copied into any publications you later create based on the template.

If you create a template based on a publication wizard, any publications you create based on the template retain the design automation functionality of the wizard.

Publications based on a template retain no link to that template. Any changes you later make in the template are not propagated to any publications previously created from that template.

Programmatically, work with templates as you would with any other Publisher files. There are no object model objects or properties specific to templates. For example, you cannot create a publication based on a template using the NewDocument method. In such a case, use the Document.Open method to open the template file directly, and then use the Document.SaveAs method to create a publication based on the template.

Making Automation Available in Publisher Templates

As mentioned previously, you cannot edit any of the publication wizards included in Publisher. You can, however, create a template based on a publication wizard. This template could include any code you wanted to make available for publications based on that publication wizard.

However, because users employ a number of publication wizards to create a wide range of publication types, in many cases it is not practical to make your macro code available through creating templates. If you want to make particular macro functionality available for all publication types, create a separate template with that code for each publication wizard. In such cases, it is best to create an add-in for Publisher and deploy your code that way.

6: Creating Web Pages with the Publisher Object Model

You can create Web pages with Publisher 2003. In Publisher 2003, there are two types of publications: print publications and Web publications. A Web publication represents a group of Web pages. Each publication page corresponds to a single Web page. You create and design the pages within Publisher as you would a print publication. When you have finished designing your Web publication, you publish the file to the Web.

You can also publish a print publication to the Web; however, the appearance of the Web pages may differ from the printed publication.

When Publisher publishes a publication to the Web, it creates an HTML representation of each page in the publication, and then saves those HTML files, along with any necessary supporting files, to the specified URL location.

The HTML files that Publisher publishes have no link to the original Publisher file used to generate them. If you later need to make changes to the Web pages, do not edit them directly. Rather, make your changes to the original Publisher Web publication, and then re-publish the file to the same URL location. Changes made to the HTML directly are not propagated back to the original Web publication; indeed, if you do edit the HTML, and later re-publish the Publisher file, your changes are overwritten.

By default, Publisher treats the first page in the publication as the initial page in your Web site. By default, Publisher saves the HTML file representing the first publication page as "index.htm". Publisher saves the HTML pages for any other publication pages, and any support files (such as image files), in a folder called "index_file", located in the same directory as the index file. If you do not specify the file name for an HTML file, Publisher generates a name for it automatically.

To determine if a publication is a print or Web publication, use the Document.PublicationType property. To convert a print publication to a Web publication, or vice versa, use the Document.ConvertPublicationType method. Note that this overwrites the previous version of the file.

To publish a file to the Web, use the Document.SaveAs method. For the Format parameter, specify pbFileHTMLFiltered. For the Filename parameter, specify the URL location to which you want to publish the file. This corresponds to choosing the Publish to the Web command from the File menu. Note that the .htm file extension is added automatically to the value of the Filename parameter if the value of the Format parameter is pbFileHTMLFiltered.

This example saves the active Web publication as a set of filtered HTML pages and supporting files. In this example, Publisher names the HTML file representing the first publication page after the original Web publication name. (Note that URLPath must be replaced with a valid file path for this example to work.)

With ActiveDocument
    .SaveAs Filename:="URLPath" & .Name, Format:=pbFileHTMLFiltered
End With

Note   The pbFilePublicationHTML value of the Format parameter represents an HTML file format available in Publisher 2002 that enabled re-importation of the HTML that Publisher generated. Because of the resulting large file size, however, this file format has been deprecated and should not be used.

If you specify pbFileWebArchive for the Format parameter, Publisher generates a .mht file. A .mht file is an HTML file that has all of its support files, such as images and other files, embedded in it.

If you later make changes to the Web publication and need to re-publish it, simply use the SaveAs method with the same file path specified. This overwrites the existing HTML files; no warning is given.

To generate a preview of a Web publication, use the Document.WebPreview method. This method generates a local HTML copy of the publication, and displays it in the users default browser. The Web preview opens with the active page displayed. Preview Web pages are generated for each page in the publication. However, if the publication is a print publication or otherwise lacks a navigation bar, there may be no way to navigate to those pages.

The following example sets the active page of the publication and generates a Web preview of the publication.

With ActiveDocument
    .ActiveView.ActivePage = .Pages(2)
End With

Publisher 2003 includes pre-defined Web navigation bars that you can include in your Web publication. For more information on how to use Web navigation bars programmatically, see Adding Navigation Bars to Web Publications in Microsoft Office Publisher 2003.

To specify settings for the Web publications you create, use the WebOptions object. This object contains properties that represent settings that newly created Web publications inherit, such as encoding and font options. When you modify any of these settings, any Web publications you create inherit the modified properties.

For example, if you need to re-publish a large Web publication, you might want to set the EnableIncrementalUpload to True. This specifies that only changes made to a publication are uploaded to the Web server when published, rather than the entire publication. The EnableIncrementalUpload property applies only to Web publications that are already published to a Web server. If a Web publication has not already been published to a Web server, the entire publication is published to the server during the initial publishing process, regardless of whether the EnableIncrementalUpload property is set to True.

The WebOptions object settings are application-level settings specific to each user.

To specify Web properties for a specific page, use the WebPageOptions object. This object contains properties that represent Web characteristics of the specified publication page, such as background sound, page description, and whether to include the page on new Web navigation bars. To specify a file name for the HTML file generated from a publication page, use the WebPageOptions.PublishFileName property. As mentioned earlier, specifying a file name for a Web page is optional. When a publication is saved as filtered HTML, Publisher automatically generates file names for any Web page that does not have a file name specified. User defined file names are only used when a publication is saved as filtered HTML. File names must be specified without a file extension.

7: Creating and Managing Linked Text Boxes in Publisher 2003

While the way you work with text in the Publisher object model is very similar to how you work with text in other word processing applications, such as Word, it does differ in one very important aspect: Because Publisher is a desktop design and publishing application, it provides you with the ability to include multiple text flows in a single publication, and programmatically control how those flows are laid out and formatted.

For example, suppose you needed to create a newsletter. You would probably want to include several different articles, each with their own distinct content and formatting. In addition, a given article might continue from one page to another; those pages might not be contiguous. The final result might look something like the three-page newsletter in Figure 1.

Layout of a sample newsletter

Figure 1. Lay out of a sample newsletter

In Publisher, each distinct flow of text is referred to as a story. A given story may span one or more text boxes, on one or more pages. Those pages need not be contiguous. Consider the sample newsletter in Figure 1. The first story is contained in a single text box on the first page. The second story starts in a text box on page one, then concludes in another text box on page three. Story three is contained in three text boxes: two on page two, and a single text box on page three.

Publisher lets you link multiple text boxes together to contain a story, and automatically manages how text flows from one text box to the next. If there isn't room to display all the story text in the first text box, the text flows into the second, and so on. If there is too much text to display in the final text box, Publisher stores the remaining text in an overflow buffer. Publisher automatically adjusts the amount of text contained in each text box as you resize the text boxes, format the text, or make other changes.

Using the Story Object to Manage Text

When working with story text through the Publisher object model, it is important to distinguish between the story itself, and the individual text boxes that contain it. Each story in a given publication is represented by a Story object contained in the Document.Stories collection. Operations performed on a Story object affect the entire story, regardless of the text boxes in which it is contained. For example, the following code sets the font size for a story to 12 points, for all the text boxes that contain that story.


But the following example sets the font size for only the story text contained in the specific text box:

Activedocument.Pages(1).Shapes("Story2Text box1") _

You cannot create or delete stories through the Stories collection. Rather, when you add a text box to the publication, you are also adding a new story to the publication. For example, the following code adds a text box, and therefore a story, to the active publication, even though no text was specified for the text box.

ActiveDocument.Pages(1).Shapes.AddTextbox _
  Orientation:=pbTextOrientationHorizontal, _
  Left:=72, Top:=72, Width:=200, Height:=200

If you then deleted the text box, or linked it to an existing text box, the number of stories in the publication would decrease by one. Use the Stories.Count property to return the number of stories in a publication at a given time.

To delete a story, you must delete each text box that contains the story text.

Use the TextFrame property to access the text frame of the first text box of a story. Use the TextRange property to return the full text of the story.

A story may also be placed within a table, in which case the story would be contained in one or more Cell objects rather than TextFrame objects. In such a case, use the Cell.TextRange property to access the text in a specific table cell. Use the HasTextFrame property to determine if a story is contained in one or more TextFrame objects.

The only objects to which you can link a text box are:

  • An empty text box that is not already part of a chain of connected text boxes.
  • A drawing shape that has a text frame. To determine if a shape has a text frame, use the Shape.HasTextFrame property.

Using the TextFrame Object to Manage Story Content

Each text box contains a TextFrame object, which contains the text in shape, and the properties that control the margins and orientation of the text frame. The TextFrame object includes several members that enable you to determine if a text box is part of a linked story, and to set or sever the connections between text boxes.

To determine if a text box is connected to a preceding or following text box, use the HasPreviousLink and HasNextLink properties, respectively. To access the text frames of those connected shapes, use the PreviousLinkedTextFrame and NextLinkedTextFrame properties. To connect one text box to the text box that you want to follow it, use the NextLinkedTextFrame property as well.

To break the forward link for a specified text frame, use the BreakForwardLink method. Applying this method to a shape in the middle of a chain of shapes with linked text frames will break the chain, leaving two sets of linked shapes. All of the text, however, will remain in the first series of linked shapes.

The following example illustrates the relationship between a story and the connected text boxes that contain it. The example adds three text boxes to the active publication, and adds text to the first text box. At this point, with the text boxes not connected, three stories are added to the publication's Stories collection. Next, the example links the three text boxes together by setting the NextLinkedTextFrame property of the first two text boxes. By doing this, two stories have been removed from the Stories collection. Note that the code calls the ValidLinkTarget method to determine if each text frame is a legitimate target to which to link.

Finally, the third text box is disconnected by calling the BreakForwardLink method for the second text box. The story text is now stored only in the first two text boxes, and the overflow buffer if necessary. In addition, text box three now represents a new, empty story.

Sub BreakTextLink()
  Dim tb1 As Shape
  Dim tb2 As Shape
  Dim tb3 As Shape

  Set tb1 = ActiveDocument.Pages(1).Shapes.AddTextbox _
      (Orientation:=msoTextOrientationHorizontal, _
      Left:=72, Top:=36, Width:=72, Height:=36)
  tb1.TextFrame.TextRange = "This is some text. " _
      & "This is some more text. This is even more text. " _
      & "And this is some more text and even more text."

  Set tb2 = ActiveDocument.Pages(1).Shapes.AddTextbox _
      (Orientation:=msoTextOrientationHorizontal, _
      Left:=72, Top:=108, Width:=72, Height:=36)

  Set tb3 = ActiveDocument.Pages(1).Shapes.AddTextbox _
      (Orientation:=msoTextOrientationHorizontal, _
      Left:=72, Top:=180, Width:=72, Height:=36)

  If tb1.TextFrame.ValidLinkTarget(tb2) Then
    tb1.TextFrame.NextLinkedTextFrame = tb2.TextFrame
  End If
  If tb2.TextFrame.ValidLinkTarget(tb3) Then
    tb2.TextFrame.NextLinkedTextFrame = tb3.TextFrame
  End If
End Sub

Function ShowStoryCount()
  MsgBox "There are currently " & _
    ActiveDocument.Stories.Count & _
    " stories in this publication.", , "Story Count"
End Function

There is no object in the Publisher object model that represents the overflow buffer for a specific story. Each TextFrame has an Overflowing property, however, that indicates whether text is overflowing from that text box into the overflow buffer. For linked text frames, only the final text frame can be overflowing.

For a given story, the text in the overflow buffer is the difference between the End property of the final linked TextFrame in the story, and the End property of the Story object itself.

For example, the following procedures retrieve the text in the overflow buffer. First, the code determines if the selected text box has overflow text. If it does, the procedure retrieves the text contained in the overflow buffer by using the Characters method. This method returns a TextRange object that contains the characters from the end of the text box TextRange object to the end of the Story object. The code then uses the Text property of the resulting TextRange object to return a string representing the overflow text, which it then displays in a message box.

Sub GetOverflowText()
  Dim ot As String
  With Selection.ShapeRange(1).TextFrame
    If .Overflowing Then
      With .TextRange
        ot = .Characters(.End, .Story.TextRange.End).Text
        MsgBox prompt:=ot, Title:="Overflow Text"
      End With
    End If
  End With
End Sub

Also, each TextFrame object has an AutoFitText property, which lets you set how you want Publisher to deal with overflowing text:

  • Allow the text to overflow.
  • Reduce the text size so that it fits in the text frame.
  • Reduce or enlarge the text size so it fills the text frame.

The following text boxes cannot be part of a chain of connected text boxes: headers or footers, navigation bars, inline objects, personal information text boxes, text boxes already containing text, or text boxes set to reduce text size automatically.

Finally, each TextFrame and TextRange object has a Story property, which enables you to access the Story object associated with a specific text frame or text range.

The Publisher Story Object Model

Figure 2 illustrates the structure of the Publisher object model surrounding the Story object. It also includes the TextFrame properties concerned with manipulating the text frames of a specific story.

The Story object model structure

Figure 2. The Story object model structure


Now that you have seen how to use some of the functionality unique to the Publisher object model, you can explore more on your own. For member definitions and code samples, refer to the Microsoft Office Publisher 2003 VBA Language Reference.

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.