Adding Navigation Bars to Web Publications in Microsoft Office Publisher 2003

  • Article

 

Andrew May
Microsoft Corporation

January 2004

Applies to:
    Microsoft® Office Publisher 2003

Summary: Create pre-designed navigation bars in Web publications using the Publisher 2003 object model. Learn how to specify which links show up on a navigation bar, how to set the navigation bars to automatically update as pages are added to a publication, and customize the navigation bar's appearance. (15 printed pages)

Contents

Introduction
Web Navigation Bar Object Model
Creating a Web Navigation Bar
Adding Links to a Navigation Bar
Adding Navigation Bar Instances to Publication Pages
Deleting Links, Instances, and Navigation Bars
Navigation Web Bars Object Model
Conclusion

Introduction

Navigation bars are an important aspect of any Web site. An easy, clearly-marked way to move between the sections and pages of your Web site is vital for your site visitors to find the information they want. Microsoft® Office Publisher 2003 includes a wide range of pre-designed, customizable navigation bars so that you can organize your site however you need and add as many navigation bars as necessary, no matter how straight-forward or complex your site may be. For example, suppose your site is composed of several sections. You can add one navigation bar with links to the first page of each section, and then another, that appears on only the pages in a specified section, and contains links to only the pages in that section.

This article discusses how to use the Publisher 2003 object model to automate the creation and customization of navigation bars.

Web Navigation Bar Object Model

Each WebNavigationBarSet object represents a navigation bar available for adding to the pages of a publication. The WebNavigationBarSet object is best thought of as a virtual object. It does not appear on the pages of a publication; rather, instances (that is, shapes based on it) appear on the publication pages. For example, suppose you have a six-page Web publication, and you add the same navigation bar to each page. In this example, there are six instances of a navigation bar present in the publication, each based on the single WebNavigationBarSet object and sharing its characteristics.

Also, a specified WebNavigationBarSet object need not have any instances in a publication at all. A publication can have three WebNavigationBarSet objects in its collection, yet instances of only one of those navigation bars may actually appear on any pages of the publication.

Any changes you make to a WebNavigationBarSet object automatically propagate to all instances of that navigation bar. For example, if you add or delete a hyperlink, or change the WebNavigationBarSet object's orientation from horizontal to vertical, all instances of that navigation bar automatically update to reflect these changes.

For Web publications based on a wizard, Publisher includes two WebNavigationBarSet objects by default: a graphic bar that contains buttons, and another that is text only. Wizards are pre-defined templates containing text boxes and other design elements that you can customize and to which you can add your content. For more information on programmatically working with wizards in Publisher, see Creating and Customizing Wizard Publications in Microsoft Office Publisher 2003.

Each WebNavigationBarSet object contains a WebNavigationHyperlinks collection. Each Hyperlink object in the collection represents a link on the navigation bar. These links can be to other pages in the publication, or external locations.

There are three main steps in creating navigation bars for Web publications:

  • Create the WebNavigationBarSet object.
  • Add links to the WebNavigationBarSet object (or set its properties so that links can be added automatically).
  • Add instances of the WebNavigationBarSet object to pages in the publication.

Creating a Web Navigation Bar

You use the AddSet method of the WebNavigationBarSets collection to create a new WebNavigationBarSet object. This does not add any instances of the new WebNavigationBarSet object to publication pages.

The AddSet method enables you to name the navigation bar, as well as choose the desired design. This method also includes the optional AutoUpdate parameter, discussed in detail later in this article.

There are two ways to add links to a navigation bar:

  • Add specific links directly to the WebNavigationHyperlinks collection. This applies to links to pages in the publication, as well as external sources (such as URLs).
  • Set the AutoUpdate property of the WebNavigationBarSet object so that links are added automatically as pages are added to the publication. This applies only to links to pages in the same publication.

Use the Add method of the WebNavigationBarHyperlinks collection to add links to a WebNavigationBarSet object. When you add a link to the WebNavigationBarSet object, Publisher automatically adds the link to any instances of the navigation bar.

You can use the Add method to create links to other pages in the publication, as well as external sources (such as URLs). For external links, set the RelativePage parameter to pbHlinkTargetTypeURL or pbHlinkTargetTypeEmail, and then use the Address parameter to specify the address of the new hyperlink.

For links to pages in the publication, set the RelativePage parameter to the enumeration representing the location of the target page in relation to the page on which the navigation bar appears (for example, first page, last page, next page, or previous page). Note that, while each instance of a navigation bar contains the same hyperlinks, links with relative targets may link to different pages based on the page on which the instances appear. For example, suppose a navigation bar contains a relative link to the next page. For an instance of that navigation bar on page two, the link's target page is page three; for an instance on page three, the target page is page four, and so on. Also note that the link target is based on page order; re-ordering the pages of a publication may change the target page for a relative link.

To keep a link's target page the same, even if you re-order the pages in a publication, set the RelativePage parameter to pbHlinkTargetTypePageID and then use the PageID parameter to specify the target page based on its PageID property.

The following example adds three horizontal navigation bars to a publication but does not add instances of those navigation bars to any publication pages. The first has one link to the next page in the publication; the second, links to the previous and next pages in the publication; the third, a link to the previous page in the publication.

Sub AddNavBars()
Dim newWNB As WebNavigationBarSet

With ActiveDocument.WebNavigationBarSets
    Set newWNB = .AddSet("Next", pbnbDesignEnclosedArrow, False)
        With newWNB
            .Links.Add , pbHlinkTargetTypeNextPage, , "Next"
            .ChangeOrientation pbNavBarOrientHorizontal
        End With
    Set newWNB = .AddSet("NextPrevious", pbnbDesignEnclosedArrow, False)
    With newWNB
        With .Links
            .Add , pbHlinkTargetTypePreviousPage, , "Previous"
            .Add , pbHlinkTargetTypeNextPage, , "Next"
        End With
        .ChangeOrientation pbNavBarOrientHorizontal
    End With
    Set newWNB = .AddSet("Previous", pbnbDesignEnclosedArrow, False)
        With newWNB
            .Links.Add , pbHlinkTargetTypePreviousPage, , "Previous"
            .ChangeOrientation pbNavBarOrientHorizontal
        End With
End With
End Sub

The optional AutoUpdate parameter of the WebNavigationBarSets.AddSet method lets you specify which publication pages are automatically linked to on the new navigation bar. If you specify the AutoUpdate parameter as True when calling the AddSet method, Publisher automatically adds links for any page that has the IncludePageOnNewWebNavigationBars property of its WebPageOptions object set to True. The default for the AutoUpdate parameter is False.

Setting AutoUpdate to False results in a navigation bar with no links.

The following table summarizes how the AutoUpdate parameter of the AddSet method interacts with the Page.IncludePageOnNewWebNavigationBars property to determine whether the navigation bar is updated with a link for that page. As you can see, both must be specified as True in order for a link to be added to the navigation bar.

Table 1. Interaction of the AutoUpdate parameter with the IncludePageOnNewWebNavigationBars property

WebNavigationBarSet.AddSet
AutoUpdate: =		 Page.
IncludePageOnNewWebNavigationBars =		 Result
True True Link added
  False No link added
False True  
  False  

In addition, the AutoUpdate property of a WebNavigationBarSet object takes its initial value from the AutoUpdate parameter of the WebNavigationBarSets.AddSet method. If the AutoUpdate parameter is specified as True, the AutoUpdate property of the resulting WebNavigationBarSet object is True as well (the default is False). As we see in the next section, this property helps determine whether links for new pages added to the publication are automatically included on the navigation bar.

Whenever you add a page to a Web publication, you can specify whether you want a link to that page automatically included on Web navigation bars whose AutoUpdate property is True. This applies to existing bars, as well as navigation bars created for the publication later.

There are two methods for adding pages to a publication: Add, and AddWizardPage. Each has an optional parameter, AddHyperlinkToWebNavBar, that helps determines whether links are added to each navigation bar for the pages added. Specify AddHyperlinkToWebNavBar as True and Publisher adds a link for each page to any WebNavigationBarSet objects with their AutoUpdate property set to True. The default for the AddHyperlinkToWebNavBar parameter is False.

The following table summarizes how the AddHyperlinkToWebNavBar parameter of the Add and AddWizardPage methods interacts with the AutoUpdate parameter to determine whether a navigation bar is updated with a link for added pages. As you can see, both must be specified as True in order for a link to be added to the navigation bar.

Table 2. Interaction of the AutoUpdate parameter with the AddHyperlinkToWebNavBar parameter

Page.Add or Page.AddWizardAddHyperlinkToWebNavBar: = WebNavigationBarSet.AutoUpdate = Result
True True Link added
  False No link added
False True  
  False  

To get the results you expect when setting your navigation bars to automatically update, it is important to understand exactly how these features interact:

The AutoUpdate property of a WebNavigationBarSet object takes its initial value from the AutoUpdate parameter of the WebNavigationBarSets.AddSet method. If the AutoUpdate parameter is specified as True, the AutoUpdate property of the resulting WebNavigationBarSet object is True as well (the default is False).

Similarly, the IncludePageOnNewWebNavigationBars property of each added Page takes its initial value from the AddHyperlinkToWebNavBar parameter. If the AddHyperlinkToWebNavBar parameter is set to True, the IncludePageOnNewWebNavigationBars property of the WebPageOptions object of the added Page objects is True as well (the default is False).

It's important to understand that Publisher only assesses whether to automatically add a link to a navigation bar when the Addset, Add, or AddWizardPage methods are executed. Changing the AutoUpdate property of a navigation bar only applies to pages that are added after the value is changed. It has no effect on links to existing pages in the WebNavigationBarSet object. Similarly, changing the IncludePageOnNewWebNavigationBars property of a page's WebPageOptions object only applies to any WebNavigationBarSet objects that are created after the value was changed. It has no effect on the links on existing WebNavigationBarSet objects. This is all true whether or not instances of the navigation bar are added to the publication.

The next example illustrates how the auto-update functionality of navigation bars works.

It creates a publication and adds two pages, with the AddHyperlinkToWebNavBar parameter of the Add method specified as True, which in turn sets the IncludePageOnNewWebNavigationBars property of those pages to True. A navigation bar is then created with the AutoUpdate parameter of the AddSet method specified as True as well. An instance of the navigation bar is added to every page. Since both parameters were set to True, the resulting instances of the navigation bar include links to all three pages.

The AutoUpdate property of the navigation bar is then set to False. Two more pages are added, again with the AddHyperlinkToWebNavBar parameter set to True. Because of the AutoUpdate property, however, links to these pages are not added to the navigation bar instances.

The AutoUpdate property of the navigation bar is then set back to True. Notice that the first navigation bar does not update to include links to pages four or five.

A second navigation bar is created, again with the AutoUpdate parameter of the AddSet method set to True. Instances of the second navigation bar contain links to all five pages in the publication.

Sub AddNavBarsAndChangeAutoUpdate()
Dim newDoc As Document

'create a new web publication
Set newDoc = NewDocument(pbWizardWebSiteBlank)
'add two new pages, set IncludeOnNewNavBars to True
'title all three pages
With newDoc.Pages
    .Add 2, 1, , True
    .Item(1).Name = "Page 1"
    .Item(2).Name = "Page 2"
    .Item(3).Name = "Page 3"
End With

'add new navbar, set AutoUpdate to True
'add new navbar to each page
'set AutoUpdate to False
With newDoc.WebNavigationBarSets
    .AddSet "NavBar1", pbnbDesignDottedArrow, True
    .Item(.Count).AddToEveryPage 50, 50
    .Item(.Count).AutoUpdate = False
End With

'add two more pages with IncludeOnNewNavBars set to True
With newDoc.Pages
    .Add 2, 3, , True
    .Item(4).Name = "Page 4"
    .Item(5).Name = "Page 5"
End With
    
'set NavBar1 AutoUpdate property to True
'add new navbar, set AutoUpdate to True
'add new navbar to each page
With newDoc.WebNavigationBarSets
    .Item(.Count).AutoUpdate = True
    .AddSet "NavBar2", pbnbDesignDottedArrow, True
    .Item(.Count).AddToEveryPage 200, 50
End With

End Sub

This example focuses on how the page properties function to determine inclusion on navigation bars.

Again, the example creates a publication and adds two pages, with the AddHyperlinkToWebNavBar parameter of the Add method set to True. A navigation bar is then created with the AutoUpdate parameter of the AddSet method set to True as well. An instance of the navigation bar is added to every page. Because both parameters are set to True, the resulting instances of the navigation bar include links to all three pages.

Two more pages are then added, this time with the AddHyperlinkToWebNavBar parameter set to False. Because of this setting, links to these pages are not added to the navigation bar.

The IncludePageOnNewNavigationWebBars property of page four is then set to True. Notice that the navigation bar does not update to include page four.

A second navigation bar is created, again with the AutoUpdate parameter of the AddSet method set to True. Instances of the new navigation bar contain links to the first four pages of the publication, but not page five.

Sub AddPagesAndChangeIncludeOnNavBars()
Dim newDoc As Document

'create a new web publication
Set newDoc = NewDocument(pbWizardWebSiteBlank)
'add two new pages, set IncludeOnNewNavBars to True
'title all three pages
With newDoc.Pages
    .Add 2, 1, , True
    .Item(1).Name = "Page 1"
    .Item(2).Name = "Page 2"
    .Item(3).Name = "Page 3"
End With

'add new navbar, set AutoUpdate to True
'add new navbar to each page
With newDoc.WebNavigationBarSets
    .AddSet "NavBar1", pbnbDesignDottedArrow, True
    .Item(.Count).AddToEveryPage 50, 50
End With

'add two more pages with IncludeOnNewNavBars set to False
With newDoc.Pages
    .Add 2, 3, , False
    .Item(4).Name = "Page 4"
    .Item(5).Name = "Page 5"
End With
    
'change page four to be included on new navbars
With newDoc.Pages
    .Item(4).WebPageOptions.IncludePageOnNewWebNavigationBars = True
End With

'add new navbar, set AutoUpdate to True
'add new navbar to each page
With newDoc.WebNavigationBarSets
    .AddSet "NavBar2", pbnbDesignDottedArrow, True
    .Item(.Count).AddToEveryPage 200, 50
End With
End Sub

Adding Navigation Bar Instances to Publication Pages

Once you create a WebNavigationBarSet object and add links to it (or set its AutoUpdate property to True, so that links can be added automatically), you still have to add instances of it to specific pages for the navigation bar to actually appear in your publication. There are two methods of adding navigation bar instances to publication pages.

If you want the same navigation bar to appear on every page in a publication, use the AddToEveryPage method of the WebNavigationBarSet object. This method inserts an instance of the specified navigation bar into every page in the publication that has the IncludePageOnNewNavigationWebBars of the WebPageOptions object set to True. However, if you add pages after running the method, they do not automatically contain an instance of the navigation bar.

To add an instance of a navigation bar to a specific page, use the AddWebNavigationBar method of that page's Shapes collection.

Regardless of the method you use, the navigation bar instance is inserted onto the page as a Shape object with a Type property of pbWebNavigationBar.

The following example inserts instances of the three navigation bars created earlier onto four pages of a Web publication. This example assumes the active publication is at least four pages long.

Sub AddNavBarsToPages()
With ActiveDocument.Pages
    .Item(1).Shapes.AddWebNavigationBar "Next", 200, 800
    .Item(2).Shapes.AddWebNavigationBar "NextPrevious", 150, 800
    .Item(3).Shapes.AddWebNavigationBar "NextPrevious", 150, 800
    .Item(4).Shapes.AddWebNavigationBar "Previous", 200, 800
End With
End Sub

Accessing a Navigation Bar through One of Its Instances

If you have a navigation bar instance in a publication, and you need to identify the navigation bar that it represents, use the Shape.WebNavigationBarSetName property to return the name of the navigation bar.

For example, the following code identifies any navigation bar instances present on the first page of the publication, and uses the WebNavigationBarSetName property to identify the navigation bar each instance represents. This information is then used to insert an instance of each navigation bar in use on page one onto page two.

Sub AddUsedNavBarsToPageTwo()
Dim nbLoop As Shape

With ActiveDocument.Pages(1)
    For Each nbLoop In .Shapes
        If nbLoop.Type = pbWebNavigationBar Then
            With nbLoop
                ActiveDocument.Pages(2).Shapes _
                .AddWebNavigationBar Name:=.WebNavigationBarSetName, _
                    Left:=.Left, Top:=.Top
            End With
        End If
    Next
End With
End Sub

Customizing Navigation Bar Instances

Each navigation bar instance is added to the publication page as a grouped Shape object. That is, the Shape object contains a GroupShapes collection that is accessed through its GroupItems property. The GroupShapes collection represents the text boxes, borders, lines, and other design elements that make up the navigation bar's appearance on the page.

You can add to, delete, reformat, and otherwise manipulate these shapes just as you do shapes in any other grouped shape. The only difference is that changes made to a navigation bar instance are propagated to all the instances of that navigation bar (with certain exceptions, which are discussed below). For example, if you change the color of a hyperlink's font, or add a border to a navigation bar instance, those changes appear on all the instances of that navigation bar in your publication.

The most important thing to remember about editing the shapes in a navigation bar instance is that the changes you make are only propagated to the other instances when the changed shape is deselected. Also, if you make multiple changes to a shape, only the final change is propagated when the shape is deselected. So, to edit a shape and have your changes propagate programmatically, you must:

  • Select the shape (using the Shape.Select method)
  • Make a single change
  • Deselect the shape (using the Selection.Unselect method)

Otherwise, your changes only execute on the instance you edited; they do not propagate to the other instances.

The following example demonstrates this methodology. It identifies the instance of the navigation bar "Test1" on the first page of the publication, and makes several changes to the formatting in each text box in the instance. These changes are made in such a way that they propagate to all the other instances of the navigation bar in this publication.

Notice that the first page is made the active page in the publication; the Select method only operates on shapes on the active page of the publication. Also, before each font change is made, the shape is selected, and after each change, it is deselect by using the Selection.Unselect method.

Sub FormatTextInNavBar()
Dim gshLoop As Shape
Dim shLoop As Shape

'set page 1 as active page,
'so selection method below will work
ActiveDocument.ActiveView.ActivePage = ActiveDocument.Pages(1)
With ActiveDocument.Pages(1)
    For Each gshLoop In .Shapes
        
        'Find all navigation bar instances on page 1
        If gshLoop.Type = pbWebNavigationBar Then
            
            'Identify navigation bar that shape is instance of
            If gshLoop.WebNavigationBarSetName = "Test1" Then
                
                'Disable showing selected link in navigation bar
                ActiveDocument.WebNavigationBarSets("Test1") _
                    .ShowSelected = False
                For Each shLoop In gshLoop.GroupItems
                    'Identify text boxes in the navigation bar instance
                    If shLoop.Type = pbTextFrame Then
                        'Format text
                        With shLoop.TextFrame.TextRange.Font
                            shLoop.Select
                            .Bold = msoTrue
                            ActiveDocument.Selection.Unselect
                            shLoop.Select
                            .Size = 24
                            ActiveDocument.Selection.Unselect
                            shLoop.Select
                            .Name = "Arial"
                            ActiveDocument.Selection.Unselect
                        End With
                        
                    End If
                 Next
             End If
        End If
    Next
End With
End Sub

Navigation Bar Customization Is Not Propagated to Selected Page Links

There is one property of the WebNavigationBarSet object that interferes with the propagation of changes made in navigation bar instances: the ShowSelected property.

The ShowSelected property is a way of visually indicating to users which Web page they are currently viewing. When this property is specified as True, the navigation bar link for the current page appears graphically different in some way than the rest of the links. The difference in appearance depends on the design chosen. For example, the line under or border around the link could be a different color, or the link text could be formatted bold. When the user is viewing page two, the link to page two on the navigation bar is different; on page three, the link to page three is different, and so on. This should not be confused with the Shape.Select and Selection.Unselect methods discussed above.

The shape for the link that appears "selected" is actually a different shape than the "unselected" shape that appears on all the other pages. For example, on page three of a publication, the shape that represents the "selected" page three link is a different shape than the shape for the "unselected" page three that appears on navigation bars placed on any other page. Because of this, changes made to the WebNavigationBarSet object do not propagate to shapes that represent "selected" links.

If you run the above example with the line that sets ShowSelected to False commented out, the font formatting does not propagate to any of the "selected" shape: on page two, the page two link's font does not change; on page three, the page three link's font does not change, as so on.

There are two ways of dealing with this behavior:

  • Set the ShowSelected property to False, as shown above. Shapes for "selected" links are not displayed; navigation bar changes are propagated to all shapes displayed.

  • Do not rely on changes made to a navigation bar to propagate to all shapes in the navigation bar instances. Make the changes directly to every shape in every instance.

    **Note   **If you do not rely on changes to propagate to other instances, you do not need to select and deselect the shape each time a change is made to it. However, if you later add another instance of the navigation bar, its appearance may not match the other instances.

Below is the code from the earlier example, rewritten to reformat shape text in each instance of the navigation bar, rather than rely on changes propagating from one instance to the other instances.

Sub FormatTextOnNavBarShapes()
Dim pgLoop As Page
Dim gshLoop As Shape
Dim shLoop As Shape

For Each pgLoop In ActiveDocument.Pages
    For Each gshLoop In pgLoop.Shapes
        
        'Find all navigation bar instances on page
        If gshLoop.Type = pbWebNavigationBar Then
            
            'Identify navigation bar that shape is instance of
            If gshLoop.WebNavigationBarSetName = "Test1" Then
                
                'Enable showing selected link in navigation bar
                ActiveDocument.WebNavigationBarSets("Test1") _
                    .ShowSelected = True
                For Each shLoop In gshLoop.GroupItems
                    'Identify text boxes in the navigation bar instance
                    If shLoop.Type = pbTextFrame Then
                        'Format text
                        With shLoop.TextFrame.TextRange.Font
                            .Bold = msoTrue
                            .Size = 24
                            .Name = "Georgia"
                        End With
                        
                    End If
                 Next
             End If
        End If
    Next
Next
End Sub

To delete a WebNavigationBarSet object, and remove any instances of it that appear in a publication, use its DeleteSetAndInstances method.

To remove a specific link from a navigation bar, use the Delete method of the Hyperlink object that represents that link in the WebNavigationBarHyperlinks collection. When you run this method, Publisher automatically deletes the hyperlink from any instances of the navigation bar as well.

To remove an instance of a navigation bar from a publication page, use the Delete method of the Shape object that represents the navigation bar instance. As mentioned earlier, each shape representing a navigation bar instance has a Type property of pbWebNavigationBar.

The following example identifies any navigation bar instances on the first page of a publication, and deletes them.

Dim shpLoop As Shape
For Each shpLoop In ActiveDocument.Pages(1).Shapes
    With shpLoop
        If .Type = pbWebNavigationBar Then
            .Delete
        End If
    End With
Next

The following figures show the object model for navigation Web bars in Publisher.

Click here to see larger image

Figure 1. Part one of navigation Web bars object model (click picture to see larger image)

Click here to see larger image

Figure 2. Part two of navigation Web bars object model (click picture to see larger image)

Conclusion

It doesn't matter how informative or entertaining the content on your Web site is if your users can't get to it. Automating the addition and customization of navigation bars for your Publisher Web publication is a great way to provide your visitors with a clear, comprehensive way to move within your site.