Andrew May's WebLog : Publisher

Publisher Object Model Overview Article Now Live on MSDN

Andrew May — Fri, 02 Sep 2005 00:29:00 GMT

Yesterday saw the publication of my penultimate article on Publisher 2003, 7 Things Developers Should Know About the Publisher 2003 Object Model, Part 1. If you're an Office developer new to the Publisher object model (or new to Publisher in general), this article and its sequel aim to give you a quick overview of the unique aspects of the Publisher developer story.

These articles grew out of the fact that I was handing off the responsibility for Publisher developer documentation to another programmer-writer for the Office "12" release. As part of the transition, I had thought of a handful of areas where Publisher functionality or the object model was unique enough to require some explanation, even to the experienced programmer-writer taking my place. I wrote up a few of these areas on this blog (here, here, and here), then decided to turn the whole thing into an MSDN article. Which naturally became two.

Part 1 covers the following areas:

· General object model structure

· The ThisDocument object

· Commercial Printing Support in the object model

· Catalog and mail merge

While Part 2, most likely to be published next week, tackles these topics:

· Wizards and templates

· Web pages

· Stories and linked text boxes

I actually wrote these articles a few months back, but for various publishing reasons they're only now seeing the light of day. (My editor told me they were holding off publishing them in order to not overshadow the release of Harry Potter VI. I can see that.)

Publisher 2003: Creating and Managing Linked Text Boxes

Andrew May — Sat, 14 May 2005 01:21:00 GMT

(Note: This is the third in a series of entries that aim to introduce experienced programmers to the Publisher object model.

The first entry covered creating Web pages programmatically. You can read it here.

The second entry covered working with wizards and templates. You can read it here.)

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, in does differ in one very important aspect: because Publisher is a desktop design and publishing application, it provides you to 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.

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 textboxes, 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 textbox 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's 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 textboxes, format the text, etc.

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

Activedocument.Stories(2).TextRange.Font.Size=12

The following example, on the other hand, set the font size for only the story text contained in the specific textbox:

Activedocument.Pages(1).Shapes("Story2TextBox1") _

.TextFrame.TextRange.Font.Size=12

You can not create or delete stories through the Stories collection. Rather, when you add a textbox to the publication, you are also adding a new story to the publication. For example, the following code adds a textbox, and therefore a story, to the active publication, even though no text has been 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, as well as 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 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 have been 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)

ShowStoryCount

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

ShowStoryCount

tb2.TextFrame.BreakForwardLink

ShowStoryCount

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 retrieves 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 also 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 the 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 automatically reduce text size.

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.

Figure 2. The Story Object Model Structure

Working with Publisher Wizards and Templates

Andrew May — Mon, 09 May 2005 23:35:00 GMT

Note: This is the second in a series of entries that aim to introduce experienced programmers to the Publisher object model. The first entry covered creating Web pages programmatically. You can read it here.

Publisher has a different concept of templates and wizards than other Office programs, such as Word. 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 bundled 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 quickly change the lay out and design of your publication.

· 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 in Publisher 2003

Publication wizards are one of the most powerful and versatile features in Microsoft® Office Publisher 2003. As mentioned above, wizards are pre-defined publication templates included as part of Publisher. Wizards enable you to quickly generate professional-looking publications in a wide range of formats, from invitations to flyers to catalogs to websites.

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, as well as 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 an object’s ability (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 “Working with Templates.”

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.

But not only do publications and pages have wizard properties, but shapes do as well. 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’s 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 new 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 template 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 above 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 to for the new template 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 above 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, _

AddToRecentFiles:=False

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 programmatically set a publication's properties, 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 new publication based on the template.

Making Macros Available in Publisher Templates

As mentioned above, 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’s not practical to make your macro code available through creating templates. If you had particular macro functionality you wanted to make available for all publication types, you would have to create a separate template with that code for each publication wizard. In such cases, it’s best to just create an add-in for Publisher and deploy your code that way.

Publisher 2003: Using the NewDocument and DocumentOpen Events

Andrew May — Thu, 05 May 2005 03:26:00 GMT

I got an email the other day from a user who asked if the NewDocument event in Publisher actually worked. It does, but it is a little more complicated than you'd think. Read on.

To enable event handling within a typical application, you create a new class module, and declare an Application object with events:

Public WithEvents App As Publisher.Application

Then, write your event handlers:

Private Sub App_NewDocument(ByVal Doc As Document)

MsgBox "You've created a new publication", , "New Pub Created"

End Sub

Finally, initialize the your object with the Application object:

Dim pub As New Class1

Sub Register_Event_Handler()

Set pub.App = Publisher.Application

End Sub

Which is exactly what the user was doing. But whenever he created a new document, either through the user interface or programmatically, his NewDocument event handler was never invoked. The NewDocument event didn't seem to be firing.

Actually, it was; he just hadn't hooked up his event handler to the right Publisher.Application object.

Publisher is a single document interface (SDI) application; each document you have open resides in a separate instance of Publisher. Which means if you have an instance of Publisher that already contains an open document, and you open another document, you're actually launching another instance of Publisher first. That second instance of Publisher then opens the document, even though it looks like you're launching the document directly from the first instance.

That's why his NewDocument event handler never fired. His code was watching the first instance of Publisher; but with a document already open in the first instance, any commands to create a new document actually launched another instance of Publisher, which is where the NewDocument event was raised.

The same is true of the DocumentOpen event; if the instance of Publisher already contains an open document, then an additional instance launches, and the DocumentOpen event is raised in that second instance.

The only time either event would occur in an existing instance of Publisher is if Publisher was open, but didn't have a document open. Which means you can't write VBA code in a document to have it watch it's own application instance for those events. By simple fact that the document containing the VBA code was open, additional instances of Publisher would be launched for any open or new document commands.

You can, of course, use the DocumentOpen and NewDocument events from:

· Another instance of Publisher

· A Publisher add-in

· Another application

So let's create an example for the first bullet point, another instance of Publisher. The example below creates a new instance of Publisher, and initializes code to respond to events raised within that instance.

First, create a new class module, and declare an Application object with events, as you would normally:

Public WithEvents App As Publisher.Application

Then, write handler procedures for all the application events to which you want to respond:

Private Sub App_DocumentBeforeClose(ByVal Doc As Document, Cancel As Boolean)

MsgBox "You are about to close: " & Doc.Name

End Sub

Private Sub App_DocumentOpen(ByVal Doc As Document)

MsgBox "You have opened: " & Doc.Name, , "Document Open"

End Sub

Private Sub App_NewDocument(ByVal Doc As Document)

MsgBox "You've created a new publication", , "New Pub Created"

End Sub

Private Sub App_WindowPageChange(ByVal Vw As View)

MsgBox "Hey", , "Window Page Change Event"

End Sub

However, in the procedure that initializes your application object, set your variable to the application instance launched when Publisher opens a new document, not the application instance that contains the document with the VBA project.

For example, the following code creates a new document, and initializes the pub.App variable with the resulting new instance of Publisher. The event handlers now fire when events are raised in that application instance. Calling the NewDocument method, as the next line of code does, actually results in two events: the DocumentBeforeClose event for the new document open in the previous line, and then the NewDocument event for the new document that replaces it.

Dim pub As New Class1

Sub InitializeNewPubInstance()

Set pub.App = NewDocument.Application

pub.App.NewDocument

End Sub

You could also create a new instance of Publisher using the New VB keyword. However, instances of Publisher launched this way are not visible by default; this enables you to launch Publisher and automate it without displaying it to the user. So you have to explicitly specify the application be visible, like so:

Sub NewDocTest()

Set pub.App = New Publisher.Application

pub.App.ActiveWindow.Visible = True

pub.App.NewDocument

End Sub

Now you event handler can respond to events the user raises in that Publisher instance, including DocumentOpen and NewDocument events. The event handlers I wrote simply pop up message boxes, but you get the idea. Just remember, those message boxes will appear in the Publisher instance running the code, not the Publisher instance actually raising the events.

One last piece of house-keeping. We want to release the pub.App variable if and when the user closes that instance of Publisher. So let's create a procedure that does that, and place it in the ThisDocument project:

Public Sub FreeApp()

Set pub.App = Nothing

End Sub

And then call that procedure from the Quit event handler:

Private Sub App_Quit()

ThisDocument.FreeApp

End Sub

On a related note, did you know it's impossible to programmatically arrive at a Publisher instance that doesn't have a document open? The New keyword launches a new instance of Publisher, with a new blank publication open. The Document.Close method closes the current publication, but then opens a new blank publication in it's place. There is no way to launch Publisher without also opening a publication. Likewise, there is no way to programmatically close the current publication without either also closing Publisher, or getting a new publication in its place. To get an instance of Publisher without an open publication, you have to go through the user interface.

Creating Web Pages with the Publisher Object Model

Andrew May — Mon, 25 Apr 2005 22:26:00 GMT

You know, sometimes it's the obvious things you miss. I was meeting a few days ago with the programmer-writer who is taking over writing Publisher developer help for the next release. I was giving him a guided tour of the Publisher object model, and I thought "you know, this should really be written down somewhere."

Oops.

I had written an entire series for beginning developers on how to get started with the Publisher object model. But somehow I had never gotten around to writing an article that contained the things an experienced programmer would want to know if they were coming to the Publisher object model—and perhaps Publisher as a whole—for the first time.

So I've decided to see if I can't write a series of entries here that address the issues an experienced programmer would encounter as they ramp up on the Publisher object model. With any luck, I'll be able to roll them into an actual article somewhere down the road.

Here's the first of those topics. It's a snappy little number I like to call:

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, as well as 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 automatically added 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 represent an HTML file format available in Publisher 2002 that enabled re-importation of the HTML 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 an .mht file. An .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)

.WebPagePreview

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 publication 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 will be uploaded to the Web server when published, rather than the entire publication. The EnableIncrementalUpload property applies only to Web publications that have already been published to a Web server. If a Web publication has not already been published to a Web server, the entire publication will be 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.

Publisher: 'Using Tags in Publisher' Article Now Live

Andrew May — Mon, 24 Jan 2005 21:47:00 GMT

My latest article on programming Publisher, Using Tags to Store Custom Information in Publisher 2003 and Publisher 2002, has just been published on MSDN. As the name states, the article talks about using the Tags collection of the Document, Page, and Shape objects in Publisher to store information, such as custom variables or state information not normally persisted in a Publisher file. You can use the Tags collection to persist a wide range of custom information within your publication, at the publication, page, or shape level. An interesting aspect of the Tags collection is one of the rare pieces of the Publisher object model that doesn't have a counterpart in the application's user interface.

If you've been reading my Publisher blog entries, you got a preview of the information in the article here, here, and here. But this article builds on that material and is worth a look even if you've read those entries.

I'm pretty happy with how this one turned out, especially the in-depth examples using catalog merge. I knew that when you perform a catalog merge, all the shapes in the catalog merge area are copied for each record. What I found out was, this includes any tags you've assigned to those shapes. Which lets you do some very interesting things, like embedding merge data source information within the shapes of the finished merge publication.

Go take a look.

Publisher: Formatting Text Across Multiple Text Boxes, or in the Overflow Buffer

Andrew May — Mon, 22 Nov 2004 19:08:00 GMT

Here's an interesting quirk in Publisher's object model. It's by design, and it makes sense if you think about it. But it may lead to some unexpected results if you don't take it into account. I didn't, and it did, so I thought I'd point it out.

First, start out with a text box that's small enough that not all the text displays:

Then, programmatically decrease the text font size:

ThisDocument.Pages(1).Shapes("Example"). _

TextFrame.TextRange.Font.Size = 14

You'd expect that all the text in the text box would be set to the new font size, right? Instead, you get this:

All the text that was showing at the time the code ran is set to the new, smaller font size, thereby leaving space in the text box for more text to display. The additional text displayed, however, is still formatted at the previous, larger, font size.

This is actually by design. Here's why it happens:

Publisher lets you link multiple text boxes together, and automatically manages how text flows from one text box to the next. If there isn't room to display all the text in the first text box, the text flows into the second, and so on. If there's too much text to display in the final text box, Publisher stores the text in an overflow buffer. That's the case here; there's only one textbox, so any text there isn't room to display is stored in the overflow buffer.

Now, let's look at that line of code again:

ThisDocument.Pages(1).Shapes("Example"). _

TextFrame.TextRange.Font.Size = 14

In this code, TextFrame.TextRange returns a TextRange object that represents the text currently displaying in the text box. Which does not include any of the text stored in the overflow buffer. So only the text showing in the text box at the time the code runs is resized.

To change the font size on all the text in the example above, you'd want to use the Story object. The Story object represents:

· All the text in an unlinked text frame, including the overflow buffer.

· All the text flowing between linked text frames, including the overflow buffer.

· The text in a table cell.

So, whereas TextFrame.TextRange represents the text currently displayed in a specific text box, Story.TextRange represents the entire text of that story, no matter how many text boxes (and the overflow buffer) it currently resides in. Each TextFrame and TextRange object has a Story property, which lets you access the Story object the text in it belongs to.

Here's the code again, rewritten to change the font size of all the text, both in the text box and overflow buffer:

ThisDocument.Pages(1).Shapes("Example"). _

TextFrame.TextRange.Story.TextRange.Font.Size = 14

Note Just be aware when you set story properties, you set them for the entire story, no matter which text box it appears in. If the Story object in the above example flowed through several text boxes, the font size in each would be set to 14.

There is no object in the Publisher object model that represents the overflow buffer. Each TextFrame does have an Overflowing property, however, that indicates whether text is overflowing from that text box into the overflow buffer. (For linked text frames, of course, only the final text frame could be overflowing.)

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

· Allow the text to overflow

· Adjust the text frame size to fit the text

· Reduce the text size so that the it fits in the text frame

Publisher: Creating a Linked Picture from an Embedded Picture (Part 2 of 2)

Andrew May — Mon, 08 Nov 2004 23:50:00 GMT

Read Part 1 here.

In the last entry, I showed you how to write a function that creates a separate .jpg file from a picture embedded in a publication. Now, let's finish the job by replacing the embedded picture with a picture linked to the new .jpg file.

Below is an example of a procedure that may call this function. It specifies the shape from which to create a linked picture, and the location to which to save the resulting picture file. It takes the file path returned from the function and uses it to replace the embedded picture with the newly-created linked picture.

Sub ReplaceEmbeddedPictureWithLinked()

Dim pubShape As Shape

Dim PubFileName As String

Dim PicFileName As String

'Select the embedded picture to create a linked picture from

Set pubShape = ActiveDocument.Pages(3).Shapes("Picture 5")

'Specify the file path to save picture

PubFileName = ActiveDocument.FullName

'Call function

PicFileName = CreatePictureAsFile(pubShape, PubFileName)

'Replace embedded picture with linked picture

pubShape.PictureFormat.Replace pathname:=PicFileName, _

insertas:=pbPictureInsertAsLinked

End Sub

Publisher: Creating a Linked Picture from an Embedded Picture (Part 1 of 2)

Andrew May — Mon, 08 Nov 2004 23:41:00 GMT

A lot of the time, entries that I post here end up inspiring me so that I expand them into articles that end up on MSDN. This time, I'm doing things the other way around: the next two posts are going to be excerpts from an article I actually published about 8 months ago.

Here's why:

The other day a user emailed me, asking how he could 'pull out' an embedded picture from a publication; i.e., he wanted to save the embedded picture as a separate file. This is something that comes up, in email to me and the Publisher newsgroups, fairly regularly. And I've written about how to do it; it's not that tough. Problem is, I wrote about it as a (very minor) part of a 34-page article, which was itself the second in a series of three articles—aimed at commercial printers, no less. Given all that, the chances of him finding the relevant code sample by doing a Web search was pretty small.

So I'm posting the relevant portions here, in the hopes they'll be a little more 'visible'. These are excerpted from the thrillingly-titled Automating Commercial Printing Prepress Tasks in Publisher 2003, Part 2. This article really contains a lot of useful information about how to write code that manages the graphics you include in your publications, including code sample on how to:

· Identify embedded and linked pictures in the publication.

· Generate a list of all pictures that were modified or whose links are broken.

· Update linked pictures whose originals were modified.

· Convert linked pictures to embedded pictures.

· Save embedded pictures as linked pictures.

· Replace one picture with another picture.

· Replace an empty picture frame with a picture.

· Gather detailed information about a specific picture.

So if any of those tasks fit with what you need to do, check it out.

End of commercial. Back to the task: how do you turn an embedded picture back into its original, separate file?

The short answer is, unfortunately, that you can't. However, what you can do is create a new, linked picture file from the embedded picture. There's a number of reasons why you'd want to do this: Using linked pictures instead of embedded pictures not only decreases the file size of a publication but also provides a separate image file that can be edited if necessary, and then updated quickly in Publisher.

Just realize that the resulting linked picture may not be the same format or resolution as the original picture embedded in the publication. This is because Publisher converted the picture twice: once when it embedded the picture, and again when it saved the picture as a separate file. Also, you cannot save an embedded EPS picture as an EPS file.

The following example creates a linked picture from an embedded one. Currently in the Publisher object model, the SaveAsPicture method applies only to the Page object, not individual shapes on a page. The function below creates a publication of the exact same dimensions as the shape passed it. It then pastes the shape onto the publication's single page, and saves the page as a .jpg file. It passes the full file path of the saved JPG file back to the calling procedure.

Function CreatePictureAsFile(shpEmbeddedPicture As Shape, _

strFileName As String) As String

Dim pubDocument As Document

'Create the new publication

Set pubDocument = NewDocument

'Set the page dimensions to equal

'the picture dimensions

With pubDocument.PageSetup

.PageHeight = shpEmbeddedPicture.Height

.PageWidth = shpEmbeddedPicture.Width

End With

'Paste the picture into the new publication

shpEmbeddedPicture.Copy

pubDocument.Pages(1).Shapes.Paste

'Position the picture correctly

With pubDocument.Pages(1)

With .Shapes(1)

.Top = 0

.Left = 0

End With

'Passes file path of picture back to calling procedure

CreatePictureAsFile = strFileName & "_" & _

shpEmbeddedPicture.Name & ".jpg"

'Saves a picture at the specified file path

.SaveAsPicture Filename:=CreatePictureAsFile

End With

'Closes Publisher instance without

'saving publication created

pubDocument.Application.Quit

End Function

Read Part 2 here.

Publisher: Using Tags to Store Custom Properties (Part 3)

Andrew May — Mon, 01 Nov 2004 01:03:00 GMT

First, I discussed the tags collection, which you can use as generic holding bins for whatever data you want to persists within your publications, pages, or shapes.

Next, I showed you a few examples using document and page-level tags.

So now, to round things out, let’s look at a short example using tags stored in shapes.

Let go back to the book example I mentioned in the first entry: you’ve created a book, and each chapter is a separate publication. Now, let’s further suppose that within each chapter you’re using textbox shapes for a number of different functions: the main chapter text, but also side-bar stories, pull quotes, figure captions, that kind of thing. Programmatically, there’s no way to tell the function of each textbox shape. Except you used tags to do exactly that. When you created each publication, you added a Tag object to each text box that denoted what you’re using it for. Like so:

Activedocument.Selection.ShapeRange(1).Tags.Add "StoryType", "PullQuote"

(The above code assigns the tag to the first shape in the ShapeRange you currently have selected in the active document. Obviously, if you’ve only got one shape selected, then that’s shape one.)

Now, suppose you decide later that you want to change the font you used for all the pull quotes, and bump up the point size while you’re at it. You can quickly create a procedure that identifies all the text boxes containing pull quotes, based on the value of their ‘StoryType’ tag, and makes the appropriate changes.

Sub FormatPullQuotes()

Dim d As Document

Dim p As Page

Dim s As Shape

Dim t As Tag

For Each d In Documents

For Each p In d.Pages

For Each s In p.Shapes

If s.Type = pbTextFrame Then

For Each t In s.Tags

If (t.Name = "StoryType" And t.Value = "PullQuote") Then

s.TextFrame.TextRange.Font.Name = "Arial"

s.TextFrame.TextRange.Font.Size = 20

End If

Next t

End If

Next p

Next d

End Sub

These examples are fairly basic, but I hope you get the idea of just how useful and flexible Tag objects can be. I’m sure, once you start looking at your own business processes, you’ll see situations where using tags will come in handy.

Publisher: Using Tags to Store Custom Information (Part 2)

Andrew May — Fri, 29 Oct 2004 20:52:00 GMT

In my last entry, I talked about the Tags collection, which you can use as generic holding bins for whatever data you want to persists within your publications, pages, or shapes. Now let's look at some actual examples.

So far, the examples I've been able to think up use tags for storing two general types of information:

· Publication, page, or shape attribute information that isn't already stored in any of the available object model properties.

· Variable data that is needed for running some procedure or add-in functionality.

Example Using a Document-Level Tag

Suppose you've created a catalog of your products, including prices that are subject to change over time. You want to be sure none of your employees prints the catalog for a customer once it's more than three months old. So when you've finished creating the catalog, you add a document tag, called Expiration Date, and set its value to a date 90 days in the future.

ActiveDocument.Tags.Add "ExpirationDate", CStr(Now + 90)

And then you write an event handler for opening the document. The event handler compares the value of the Expiration Date tag with the current date. If the publication is opened after the expiration date, a dialog box displays advising the user not to print the catalog because the prices may not be accurate anymore.

(You'd place this event handler in the ThisDocument object module.)

Private Sub Document_Open()

If CDate(ActiveDocument.Tags("ExpirationDate").Value) < Now Then

MsgBox Prompt:="Prices in this catalog may be out of date." & _

vbLf & "Do not release this catalog to a customer" & vbLf & _

"without checking that prices are accurate.", _

Buttons:=vbExclamation, _

Title:="Expiration Date Passed"

End If

End Sub

Example Using a Page-Level Tag

By design, when you perform a catalog merge, the publication you create or append with the merge results contains no information about the merge publication or data source used to create it. It has no 'memory' of having been created by a catalog merge.

But what if you wanted to retain that information in the target publication? Suppose you're building a single publication as a catalog, and you're using catalog merges from several different publication and/or data sources. (Maybe each section of your catalog uses a different data source, or each section has a different layout and so uses a different catalog merge area.) It'd be reasonable to want to know which pages in the publication where created with which data sources and publications, and when.

The following example uses page-level tags to store this information.

First, it opens the target publication and records how many pages are in the publication prior to the merge being executed. Then it executes the merge, appending the resulting pages to the target publication. Next, the code adds three tags to each new page created by the merge. These tags contain the following information:

· The data source used in the merge

· The publication that contains the catalog merge area used in the merge

· Date and time of the merge

The code even creates or increments a document-level tag called "No of Merges", which contains the number of merge results that have been appended to the target publication.

Function ExecuteMergeAndTagPages(filePath As String)

Dim d As Document

Dim p As Page

Dim intPages As Integer

Dim i As Integer

Dim t As Tag

Dim TagExists As Boolean

TagExists = False

Set d = Application.Open(filePath)

intPages = d.Pages.Count

d.Close

Set d = ActiveDocument.MailMerge.Execute(Pause:=False, _

Destination:=pbMergeToExistingPublication, _

Filename:=filePath)

For i = (intPages + 1) To d.Pages.Count

Set p = d.Pages(i)

With p.Tags

.Add "Data Source", ActiveDocument.MailMerge.DataSource.Name

.Add "Merge Pub", ActiveDocument.FullName

.Add "Page Creation Date", CStr(Now)

End With

Next i

For Each t In d.Tags

If t.Name = "No of Merges" Then

t.Value = t.Value + 1

TagExists = True

End If

Next t

If TagExists = False Then

d.Tags.Add Name:="No of Merges", Value:=1

End If

End Function

Once you've stored this information, of course, you can write code that programmatically queries the tags and takes action based on the results. For example, you could write a procedure that deletes all the pages created using a certain data source.

Next time, I'll see if I can't come up with some code samples that use tags at the individual shape level.

Publisher: Using Tags to Store Custom Information (Part 1)

Andrew May — Fri, 29 Oct 2004 17:55:00 GMT

Today I'm going to talk about the Tags collection, a feature in the Publisher object model that hasn't gotten a lot of notice, but is extremely useful when you examine it. (And I'm as guilty as anyone of ignoring it; one of the Publisher testers pointed out tags to me months ago, and it's taken this long for me to start playing around with them.)

Tags are, in essence, generic holding bins where you can store whatever information you want to persist with the publication. The Tags collection is a child of the Document, Page, and Shape objects, so you can save data at the publication, page, or individual shape level.

Each Tag object consists of two properties: a name, and a value. The Name property is simply a string that identifies the tag. The Name property of a Tag must be unique within a given Tags collection. For example, you can't have two Tag objects named "Creation Date" in a single Shape object, but multiple Shape objects could each have a single Tag object named that.

The Value property of a Tag object is where things get interesting. It's data type is Variant, which means it can store any data type except fixed-length strings. (For more information about the Variant data type, see this reference topic.) So you can store pretty much any kind of information you want, including user-defined types.

Here's another interesting aspect of tags: The Tags collection is one of the rare pieces of the Publisher object model that doesn't have a counterpart in the application's user interface. (The only other instance of this I can think of is WizardTags.) Tags are a totally programmatic feature: you can't get or set Tag objects except through code. So unless you explicitly expose them in the user interface (by displaying them in a dialog box, for example) or the user writes code to find them, the average user isn't going to be aware of them at all. Which makes them an ideal place to store information you don't want the average (that is, non-programming) user to have easy access to.

To add a Tag object, use the Tags.Add method, which takes the Tag object name and value as parameters:

ActiveDocument.Tags.Add "CreationDate", CStr(Now)

So what kind of information can you store in tags? Pretty much anything you want. Seriously, the more I play around with tags, the more ideas I get for how to use them. I'm in the process of implementing some of these ideas in code. I'll post code samples as I complete them. For now, consider the following example to get your mind thinking about how you could use Tags in your business processes:

Suppose you're creating publications for a number of projects. You might want to add a Tag object to each publication to identify which project it's for. So you add a Tag object, named for the project, that has an initial value of "Pending":

ActiveDocument.Tags.Add "Farble Project", "InProcess"

When the project is done, you change the value to "Complete". Then, you write a procedure that goes through your various work folders once a week and moves any publications where Tag.Value="Complete" to a 'Completed Projects' folder.

Here's the hierarchy of the Tags object model section:

In my next few entries, we'll look at examples using Tags at the publication, page, and shape levels. See you then.

Publisher: Working with Multiple Open Documents

Andrew May — Wed, 27 Oct 2004 17:23:00 GMT

Here's something I didn't notice until I'd been programming with Publisher for awhile:

You might have noticed that in Publisher 2003, we added a Documents collection to the Application object. But, you might ask, isn't Publisher a single document interface (SDI) application? If so, shouldn't each open document have its own separate Application object?

And you'd be right on all counts. Publisher is indeed an SDI application, so each open document has its own unique Application object that you can use in code. However, the Documents collection is our way of providing you 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 especially comes in handy when you're doing the following:

· Moving content between publications

· Performing work on several publications at a time

Here's an example of how using the Documents collection simplifies moving content between publications. The code below cuts a shape from the first page of one publication, and then pastes it onto the second page of another publication.

Sub MoveFred()

Documents("Publication1").Pages(1).Shapes("Fred").Cut

Documents("Publication2").Pages(2).Shapes.Paste

End Sub

Handling two separate Publisher application is fairly straight-forward. But things can get tricky when you have multiple instances of Publisher open, and you want to coordinate action between them. That's where the Documents collection comes in handy. For instance, suppose you've created a book, and that each chapter is a separate publication. Using the Documents collection, you can easily selected the publications you want to print, in the order you want to print them to produce a complete copy of your book.

Sub PrintMyBook()

With Documents

.Item("TitlePage").PrintOut

.Item("Chapter1").PrintOut

.Item("Chapter2").PrintOut

'etc etc

End With

End Sub

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

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

(By the way, Publisher automatically adds the .htm file extension to the filename when you set the Format parameter to pbFileHTMLFiltered.)

A lot easier than having to keep track of all the individual application instances of Publisher, isn't it?

Publisher: Writing Macros to Save Time and Effort

Andrew May — Tue, 26 Oct 2004 18:14:00 GMT

Just a quick, shameless plug:

Do you have things that you do repeatedly in Publisher? Do you find yourself doing a certain set of tasks over and over again? Wouldn't it be great if you could tell Publisher to perform complicated tasks automatically? Guess what? You can. There's a way to give Publisher detailed instructions on what you want it to do to, when you want it to do it, and even under what conditions, and have Publisher carry out all your instructions automatically.

You can do all that, and more, by writing macros. And the best part is, writing macros is easy. Give me a few minutes of your time and I'll show you how.

I've written a series of lessons that teach you what you need to know to start writing macros today. Each self-contained lesson introduces core programming concepts, with plenty of examples and hands-on exercises to show you what we're talking about. You don't need any special experience, just a computer with Publisher installed. After each lesson you'll have learned skills you can start using in your macros right away.

So why wouldn't you give it a try?

Here's links to the first four lessons:

Lesson One

Lesson Two

Lesson Three

Lesson Four

Publisher: Programming Made Easy Article Now Live

Andrew May — Wed, 06 Oct 2004 22:28:00 GMT

The first of my five part series, ‘Programming Microsoft Office Publisher Made Easy’ went live yesterday. The series consists of five lessons aimed at users who have never coded before, and want some from-the-ground-up assistance in writing powerful, flexible macros using the Publisher object model.

Here’s a list of the content and tentative publish dates for the five articles:

Lesson One (now live)

· Writing your first macro

· Macro security settings

· Sub procedures

Lesson Two (now live)

· Object-oriented programming

· Object variables

· Method parameters

· Creating event handlers

Lesson Three (now live)

· Creating dialog boxes

· If…Then statements

· Data variables

Lesson Four (now live)

· Object collections

· For Each…Next loops

· Nesting code statements

· Indenting code

Lesson Five (November 2^nd)

· Return types

· Using the Object Browser

· Using the online help

And remember, if you read an article, please take a minute and rate it to let us know what you thought.

Afterwards, if you want some more background on Visual Basic and object-oriented programming, check out these two previous blog entries:

Publisher Programming Made Easy: Why Program with Objects, Anyway?

Publisher Programming Made Easy: Types of Visual Basic Statements