Creating and Customizing Wizard Publications in Publisher 2003

  • Article

 

Andrew May
Microsoft Corporation

January 2004

Applies to:
    Microsoft® Office Publisher 2003

Summary: Generate and customize professional-quality publications programmatically using the Microsoft Office Publisher 2003 object model and pre-defined design templates included with the Publisher wizards. (9 printed pages)

Contents

Introduction
Exploring the Publisher Wizard Object Model
Publication-Wide Wizard Properties
Page-Specific Wizard Properties
Where to Find It in the Publisher 2003 User Interface
Conclusion

Introduction

One of the most powerful and versatile features in Microsoft® Office Publisher 2003 is the publication wizards. In Publisher, wizards are pre-defined templates containing text boxes and other design elements that you can customize and to which you can add your content. 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 based on 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.

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.

Exploring the Publisher Wizard Object Model

The Publisher object model lets you extend that design flexibility even farther by automating the generation and customization of professional-quality publications based on wizards.

Any publication created based on a Publisher wizard template has a Wizard object as the child of its Document object. The ID property of the Wizard object determines the publication type generated by that wizard (for example, catalog, invitations, or newsletter).

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 these examples, each Page object in the publication contains its own Wizard object as well.

For example, in the code examples included in this article, we create a newsletter with the following publication-wide wizard properties specified:

  • Do not include a customer address on the newsletter.
  • Print the newsletter as a two-sided document.

In addition, specify the following page-level wizard properties:

  • For page two, set text boxes to display text in two columns.
  • For page three, set text boxes to display text in two columns as well, and add a calendar to the page.

Each Wizard object has one or more properties in its WizardProperties collection. Each WizardProperty object determines an aspect of the publication (if the Wizard object is a child of the Document object) or page (if the Wizard object is a child of a specific Page object).

Each WizardProperty object includes the property's current value; you can get or set this value using the CurrentValueId property. In addition, each WizardProperty object contains a WizardValues collection of all the values possible for that property. This collection contains a WizardValue object for each possible value of the wizard property.

Publication-Wide Wizard Properties

Some other examples of publication-wide wizard properties include:

  • How many panels to include for a brochure
  • Whether to include special content, such as order or response forms, in a publication
  • Publication print orientation

For the Wizard object belonging to the Document object, the first property in a WizardProperties collection is always Design. The Design property determines the layout of the publication created by the wizard, and may also determine whether other wizard properties are enabled. A publication based on a wizard always has all the properties specified for that wizard. However, some properties may not be applicable for certain designs. In these cases, that wizard property is disabled based on the design chosen. Use the Enabled property of the WizardProperty object to determine whether the property is enabled. For example, the Graphic and Tear-offs properties are not enabled for flyers based on the Car Wash Fundraiser or Charity Bazaar Fundraiser designs.

Determining Whether a Publication is Based on a Wizard

If you try and access the Wizard object for a publication that was not created from a wizard, you receive an error. To prevent this, use the IsWizard property of the Document object to determine if a publication was based on a wizard.

The following example determines if a publication was based on a wizard; if it was, the code lists all the publication-wide wizard properties, and, if they are enabled, their current values. The commented-out section of the code sample lists all of the possible values for each wizard property as well.

Sub ListPublicationWizardProperties()
Dim wpLoop As WizardProperty
Dim wvLoop As WizardValue
'determine if publication was based on a wizard
If ThisDocument.IsWizard = True Then
    'list wizard id and name
    With ThisDocument.Wizard
        Debug.Print "Wizard: " & .ID & " (" & .Name & ")"
    End With
    'loop through each property and return current value
    For Each wpLoop In ThisDocument.Wizard.Properties
        If wpLoop.Enabled = True Then
            With wpLoop
                Debug.Print "Property: " & .ID & " (" & .Name & ")" & _
                    "   Current Value: " & .CurrentValueId
                'Debug.Print "Possible Values: (" & .Values.Count & ")"
                    'loop through each value list them
                    'For Each wvLoop In .Values
                    '    With wvLoop
                    '        Debug.Print .ID & " (" & .Name & ")"
                    '    End With
                    'Next
            End With
        Else
            Debug.Print "Property " & wpLoop.ID & " is disabled"
        End If
    Next
Else
    Debug.Print "This document was not created from a Publisher wizard."
End If
End Sub

Creating Publications Based on Wizards

When you call the NewDocument method to create a publication, you can use the optional Wizard parameter to specify the wizard you want the new publication based on. Use the optional Design parameter to specify the wizard design for the publication.

You cannot later assign a wizard to a publication that was not created from a wizard.

The following example creates a new publication based on the newsletter publication, and applies the "Bars Newsletter" design (52) to the publication.

Dim newDoc As Document
'set wizard publication type and design
Set newDoc = NewDocument(pbWizardNewsletters, 52)
'set the color scheme
newDoc.ColorScheme = newDoc.Application.ColorSchemes("Cavern")

**Note   **This example also applies a color scheme to the publication. This is an option offered in the Wizard task pane in the Publisher user interface. It does not, however, apply a font scheme. Font schemes are not supported in the Publisher 2003 object model.

Setting Publication-Wide Wizard Properties

Once you create a publication based on a wizard, you can set the wizard properties for that publication. Use the FindPropertyByID method to return a specific WizardProperty object from the WizardProperties collection. Then use the CurrentValueID property of that wizard property to set the property value.

If you try and access a wizard property that is not enabled for the design applied to your publication, you receive an error. To prevent this, use the Enabled property of the WizardProperty object to determine if a property is in use for a publication. The Enabled property is read-only; you cannot enable or disable a wizard property.

The following code builds on the previous example. It uses the FindPropertyById method to return two publication-wide wizard properties for the newsletter publication: "Customer address" (901), which is set to None (0), and "One- or two- sided printing", which is set to One (1).

With newDoc.Wizard.Properties
    'specifies no customer address for publication
    .FindPropertyById(901).CurrentValueId = 0
    'specifies two-sided printing for publication
    .FindPropertyById(907).CurrentValueId = 1
End With

Page-Specific Wizard Properties

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 these examples, each Page object that has page-specific wizard properties also contains a Wizard object. The ID property for the page wizard objects is always the same as the ID property of the publication wizard.

In Publisher 2003, the following wizards have page-specific wizard properties: Catalogs, Newsletters, and Web Sites.

Page wizard properties affect only the page for which they are set. For example, each page in a publication created from the Newsletter Wizard has two page wizard properties: Column, and Content. The Column property enables you to set the number of columns in the text boxes for each page. The Content property enables you to include specific types of content on each page, such as calendars or order forms.

Each page in a publication has the same list of wizard properties; however, some of the properties may not be enabled. For example, for the first and last pages of publications based on the Newsletter Wizard, wizard page property 44 (Content) is disabled, so you cannot add content to those pages that is inappropriate (like adding an order form to the front page).

Determining Whether a Page has Wizard Properties

If a wizard has page-specific properties, then when a publication is created from that wizard, all pages in the publication have those properties. You can later add more pages with wizard properties to the publication (this is discussed later in this article). However, you can also add pages to a publication that do not have wizard properties. For example, pages added by using the Add method, or through appending catalog merge results to a publication, do not have wizard properties. Use the IsWizardPage property of the Page object to determine whether a page has specific wizard properties.

For a specified publication, each page that has wizard properties has the same set of wizard properties; however, those properties may not all be enabled for each page.

The following example loops through the pages in the active publication and tests for pages with wizard properties. If the page has wizard properties, they are listed along with whether or not they are enabled, and if enabled, their current value. This example assumes the active publication is based on a wizard.

Sub ListWizardPages()
Dim pgLoop As Page
Dim wpLoop As WizardProperty
ActiveDocument.ViewTwoPageSpread = False
For Each pgLoop In ActiveDocument.Pages
    With pgLoop
        ActiveDocument.ActiveView.ActivePage = pgLoop
        'determine if page has wizard properties
        If .IsWizardPage = True Then
            Debug.Print "Page " & .PageNumber & " has wizard properties."
            With .Wizard
                For Each wpLoop In .Properties
                    With wpLoop
                    'determine if property is enabled
                    If wpLoop.Enabled = True Then
                        'list properties that are enabled
                        Debug.Print "Property: " & .ID & " (" & .Name & ")"
                        Debug.Print "Current Value: " & .CurrentValueId
                    Else
                        'list properties that are not enabled
                        Debug.Print "Property " & .ID & _
                            " (" & .Name & ") is not enabled."
                    End If
                    End With
                Next
            End With
        Else
          'list pages without wizard properties
          Debug.Print "Page " & .PageNumber & _
            " does not have wizard properties."
        End If
    End With
Next
End Sub

Setting Page-Specific Wizard Properties

Once you determine that a page has wizard properties, you can access them using the WizardProperties object of that specific page. As with publication-wide wizard properties, use the FindPropertyByID method to return a specific WizardProperty object from the WizardProperties collection. Then use the CurrentValueID property of that wizard property to set the property value.

If you try and access a wizard property that is not enabled for the specified page, you receive an error. Use the Enabled property to determine if a wizard property is enabled for a specified page.

**Note   **To access page wizard properties, you must specify the page as the active page in the publication.

Also, when you access wizard page properties, make sure that the document is viewed as a one-page spread. Publisher always returns the wizard properties of the left-hand page of a two-page spread, even if you attempt to access the wizard properties of the right-hand page. Use the ViewTwoPageSpread property of the Document object to specify viewing the publication as a one-page spread, as shown in the example below.

Building on previous examples, the following code sets one property for page 2 of the newsletter, and two properties for page 3.

With newDoc.Pages
     ActiveDocument.ViewTwoPageSpread = False
    'sets page 2 as active page
    newDoc.ActiveView.ActivePage = .Item(2)
    'specifies two-column layout for page 2
    .Item(2).Wizard.Properties.FindPropertyById(43).CurrentValueId = 1
    'sets page 3 as active page
    newDoc.ActiveView.ActivePage = .Item(3)
    'specifies two-column layout for page 3
    .Item(3).Wizard.Properties.FindPropertyById(43).CurrentValueId = 1
    'adds a calendar to page 3
    .Item(3).Wizard.Properties.FindPropertyById(44).CurrentValueId = 2
    'sets page 1 as active page again
    newDoc.ActiveView.ActivePage = .Item(1)
End With

Adding Pages with Wizard Properties to a Publication

Use the AddWizardPage method to insert additional pages that have page-specific wizard properties. This method allows you to add one wizard page at a time, and to select the type of wizard page you want.

If you select a wizard page type not available for the wizard your publication is based on, you receive an error. For example, attempting to add a catalog type wizard page into a newsletter wizard publication results in an error.

The following example adds two pages to a publication based on the Newsletter Wizard. The first new page is inserted after page two, and has a content type of calendar. The second new page is inserted after page three, and has a content type of sign-up form.

For newsletters, the page type specified sets the value of the page wizard property 44 (Content). So for the first page inserted, the CurrentValueId property of the WizardProperty object representing wizard property 44 (Content) is set to 2 (Calendar), while for the second page inserted that value is set to 17 (Sign-up form).

With ActiveDocument.Pages
    .AddWizardPage 2, pbWizardPageTypeNewsletterCalendar
    .AddWizardPage 3, pbWizardPageTypeNewsletterSignupForm
End With

Where to Find It in the Publisher 2003 User Interface

All of the object model elements discussed in this article are also represented by controls in the Publisher 2003 user interface. To view the wizard properties available for a publication based on a wizard, open the document and make sure the task pane is displayed. To display the task pane, on the View menu, click Task Pane. Select a page in the publication, and do the following:

  • To view the publication-level wizard properties, click Wizard Options on the Task Pane (where Wizard is the name of the wizard your publication is based on.) This lists all the publication-level wizard properties, and their possible values, except Design.
  • To view the Design Wizard property and its possible values, on the task pane, click Publication Designs.
  • To view page-specific wizard properties, on the task pane, click Page Content. This option is only displayed if the wizard type has page-specific wizard properties. Only wizard page properties that are enabled for the selected page are displayed.

Publisher Wizard Object Model Hierarchy

The following diagrams illustrate the section of the Publisher 2003 object model that is related to wizards.

Note   Wizard objects contained in Shape and ShapeRange objects are not addressed in this article because they pertain to the design and properties of Design Gallery objects, and are independent of any wizard upon which a publication may be based.

Click here to see larger image

Figure 1. Part one of object model for Publisher wizards (click picture to see larger image)

Click here to see larger image

Figure 2. Part two of object model for Publisher wizards (click picture to see larger image)

Conclusion

Programmatically creating publications using wizards is a great way to quickly create professional-quality publications that present a consistent corporate or organization identity. By using wizards, along with choosing a set color scheme and group of fonts, you can create a "look and feel" for your publications that is unique to your business or organization. Programming against the Publisher 2003 object model can jumpstart this process. For example, if you send out a newsletter each month, you could write code that automatically creates a publication template, based on the same wizard with the same publication and page level properties each time.