What's New For Developers in Publisher 2007

Saul Candib, Microsoft Corporation

October 2007

Applies to:   2007 Microsoft Office System, Microsoft Office Publisher 2007

Summary:   Explores new features for developers in Microsoft Office Publisher 2007, describes the new objects and members of the Publisher 2007 object model, and lists deprecated members. (13 printed pages)

Contents

  • Introduction to New Developer Features in Publisher 2007

  • Sending Personalized E-Mail Messages to Multiple Recipients

  • Managing Mail-Merge Recipient Lists

  • Creating Bulk-Mail Publications and Inserting Postal Bar Codes

  • Getting and Setting Printer Options

  • Recoloring Pictures

  • Saving Publications as Fixed Format Files (.pdf and .xps)

  • Changing Publication Templates and Reusing Extra Content

  • Applying a Business Information Set

  • New Automation Objects and Members

  • Deprecated Object Model Members

  • Conclusion

  • Additional Resources

Introduction to New Developer Features in Publisher 2007

The following list describes new developer-related features in Microsoft Office Publisher 2007. Each of these features has an associated API that makes it possible to control the feature programmatically. The new developer-related features provide the following functionality:

  • Creating e-mail merges (sending personalized e-mail messages to multiple recipients).

  • Managing mail-merge lists, including recipient lists for mail and catalog merges.

  • Creating bulk mail publications and inserting bar codes.

  • Getting and setting printer options.

  • Recoloring publications.

  • Saving publications as fixed format files: Portable Document Format (.pdf) and XML Paper Specification (.xps).

  • Changing templates and reusing extra content.

  • Setting business information.

This article introduces new objects and members that developers can use to take advantage of these features. It includes links to Office Publisher Help topics on MSDN that provide more details about each object and member, and code samples that show how to use some of the new objects and members.

Sending Personalized E-Mail Messages to Multiple Recipients

You can now programmatically create and send merged e-mail messages that contain your publication. The new EmailMergeEnvelope object exposes several properties that let you specify the recipients, subject, priority, and attachments to the merged e-mail message that contains your publication. The properties of the EmailMergeEnvelope object correspond to the required and optional settings in the Merge to E-mail dialog box in the Publisher 2007 user interface (UI).

In addition, the new Attachment object and Attachments collection expose members that let you add, name, and delete attachments to a merged e-mail message programmatically.

Managing Mail-Merge Recipient Lists

Publisher 2007 introduces the ability to combine information from multiple data sources into a common master data source for creating mail-merge documents. You can use this feature in the UI and through the object model.

You can use several new methods of the MailMergeDataField object to create and manage mail-merge recipient lists. The AddToRecipientFields method adds a new field (column) from a particular data source to the master data source (combined collection of data fields) for a mail-merge publication. The MapToRecipientField method maps a column in a particular data source to a recipient column in the master data source, while the UnmapRecipientField method undoes the mapping.

Additionally, the new IsMapped and MappedTo properties of the MailMergeDataField object provide information about the mapping status of data fields, while the IsMaster property of the MailMergeDataSource object indicates whether the parent object is a master data source (a combination of all data sources connected to the current publication). The EditRecord method of the MailMergeDataSource object changes one of the data fields in one of the records in the master data source.

The new ExportRecipientList method of the MailMerge object exports the list of mail-merge recipients to a Microsoft Office Access (.mdb) file or to a comma-delimited text (.csv) file. The new CreateShortcut method of the MailMerge object creates a shortcut to the file that contains the list of recipients or products for a mail-merge publication to make it easier to access the list later.

Creating Bulk-Mail Publications and Inserting Postal Bar Codes

Office Publisher 2007 makes it easier for businesses to take advantage of bulk mailing rates by programmatically creating and inserting postal bar codes and validating mail-recipient addresses in mail-merged publications. Several new members of existing objects extend the Publisher object model for support of bulk mailing, bar codes, and address validation. You can write code that uses these members in the Publisher Visual Basic Editor window, or you can create an add-in for Office Publisher 2007 that validates recipient addresses and maintains its own data sources.

The new MailMergeInsertBarcode event of the Application object occurs when a user issues the command to insert bar codes into a mail-merge publication, either in the UI or programmatically.

The MailMergeGenerateBarcode event of the Application object occurs when Publisher requires data to generate bar codes in a mail-merge publication, in particular, when the mail-merge recipient list changes.

The EverValidated property of the MailMergeDataSource object indicates whether the list of recipient addresses in the parent object has ever been validated.

The ValidatedClean property of the MailMergeDataSource object indicates whether all recipient addresses in the parent object were successfully validated, and whether any changes were made to the list since the last validation that require the list to be validated again.

The new InsertBarcode method of the TextRange object inserts a bar code field at the end of the text range that is represented by the parent object.

The new InsertBarcodeVisible property of the Application object enables insertion of bar codes into the publication from the UI.

The ValidateAddressVisible property of the Application object enables validation of the recipient address list from the UI.

Getting and Setting Printer Options

You can get and set many new printer options programmatically. These options correspond to the options that you can set in the Print Setup and Advanced Printer Setup dialog boxes in the Office Publisher 2007 UI.

The new Printer object exposes 15 properties, many of which correspond to settings in the Print Setup dialog box for a specific printer. For example, the PaperOrientation property gets or sets the paper orientation (landscape or portrait) of the printer. The IsActivePrinter property gets or sets a specific printer as the active printer.

The new InstalledPrinters object represents the collection of all the printers installed on your computer.

The AdvancedPrintOptions object exposes four new properties that specify how envelopes are fed to the printer and whether the printed page should be rotated.

Recoloring Pictures

You can use the new Recolor method of the PictureFormat object to apply a color cast to a picture in a publication. To subsequently change the colors of the picture back to the original colors, use the RestoreOriginalColors method of the same object.

In addition, you can use three new properties of the PictureFormat object to get information about recolored pictures and to set recoloring options:

  • The IsRecolored property value indicates whether the image represented by the parent PictureFormat object was recolored, either in the user interface or by using the Recolor method.

  • The LeaveBlackAsBlack property value indicates whether the black parts of the original image should remain black when you recolor the image represented by the parent PictureFormat object.

  • The RecoloredPictureColor property returns the color that is applied to the image represented by the parent PictureFormat object.

Saving Publications as Fixed Format Files (.pdf and .xps)

You can save your publications as .pdf and .xps files, and then share them with other users who have PDF or XPS readers. This makes it easier to share your publications with customers, colleagues, or family members who do not have Office Publisher 2007 installed on their computers. It also readies the document to be sent to commercial presses, to copy shops, for desktop printing, or for electronic distribution.

To save a publication in a fixed format programmatically, use the ExportAsFixedFormat method of the Document object.

Changing Publication Templates and Reusing Extra Content

If you want to change the current publication template, for example, from one style of brochure to another, you can use the new ChangeDocument method of the Document object to change the current publication to one that uses the publication wizard, and optionally, the design that you specify.

When you change publication templates in an existing publication, some shapes in the old publication template may not fit neatly into the new template. Office Publisher 2007 classifies these shapes as surplus shapes, and notifies you of the classification so that you will not lose work. Two new properties provide information about surplus shapes:

  • The SurplusShapes property of the Document object returns a ShapeRange object that represents the collection of surplus shapes that result from changing the publication type.

  • The IsExcess property of the Shape object indicates whether the specified shape is a surplus shape.

Applying a Business Information Set

The new SetBusinessInformation method of the Document object applies an existing business information set, which consists of a logo image and business contact information (such as a company name and address), to the current publication.

New Automation Objects and Members

The following tables list new objects, methods, properties, events, enumerations, and constants in the Office Publisher 2007 object model.

Table 1 lists the new objects in the Office Publisher 2007 object model.

Table 1. New objects in Publisher 2007

Object

Description

Attachment

Represents a single file attachment for e-mail merge contained in a publication.

Attachments

A collection that contains Attachment objects that represent the attachments in a publication.

EmailMergeEnvelope

Represents the e-mail container (envelope) that holds the Publisher 2007 document that is merged into an e-mail merge.

InstalledPrinters

Gets the names of all printers installed on the computer.

MailMergeDataSources

Represents the collection of all MailMergeDataSource objects in the active Publisher document, each of which represents one of the data sources in a mail-merge operation.

PageSize

Gets the page size of the current publication.

PageSizes

Represents the collection of all PageSize objects in the parent Document object, where each PageSize object represents one of the page sizes available in the current Publisher document.

Printer

Corresponds to a printer available on your system.

Table 2 lists the new methods in the Office Publisher 2007 object model.

Table 2. New methods in Publisher 2007

Methods

Objects

Description

AddToRecipientFields

MailMergeDataField

Adds the parent MailMergeDataField object from a particular data source to the master data source (collection of data fields) for a mail-merge publication.

ChangeDocument

Document

Changes the current publication to one that uses the wizard, and optionally, the design that you specify.

CreateShortcut

MailMerge

Creates a shortcut to the file that contains the list of recipients or products for a mail-merge publication.

EditRecord

MailMergeDataSource

Changes one of the data fields in one of the records in the master data source (the combined mail-merge recipient list).

ExportAsFixedFormat

Document

Converts a Publisher 2007 publication into .pdf or .xps format. The conversion readies the document to be sent to commercial presses, to copy shops, for desktop printing, or for electronic distribution.

ExportRecipientList

MailMerge

Exports the list of mail-merge recipients to an Access (.mdb) file or to a comma-delimited text (.csv) file.

GetExpression

GraphicItem

Returns the current expression for the primary key column that corresponds to the specified field.

MapToRecipientField

MailMergeDataField

Maps a field (column) in a particular data source represented by the parent MailMergeDataField object to a recipient field (column) in the master data source (combined mail-merge recipient list).

MoveToPage

Shape

Moves a shape to the specified page.

Recolor

PictureFormat

Changes the color of a picture in a publication.

RestoreOriginalColors

PictureFormat

Restores the original colors of a picture that was recolored.

SaveAsPicture

Shape, ShapeRange

Saves one or more shapes to a picture file.

SetBusinessInformation

Document

Helps store business information. Business information consists of a logo image and business contact information, such as the company name and address.

SetId

Wizard

Specifies the type of the wizard (template) to convert the current publication type to.

ShowWizardCatalog

Application

Displays the Publication Types catalog for the wizard of the specified type.

UnmapRecipientField

MailMergeDataField

Undoes the mapping between the parent MailMergeDataField object in a particular data source and the recipient field in the master data source (combined mail-merge recipient list) to which it is currently mapped.

Table 3 lists the new properties in the Office Publisher 2007 object model.

Table 3. New properties in Publisher 2007

Property

Objects

Description

Assistance

Application

Gets a reference to the 2007 Microsoft Office system IAssistance object, which enables developers to create a customized Help experience for users within the 2007 Office system. Read-only.

AutomationSecurity

Application

Specifies the security mode to use when you open files programmatically.

AvailablePageSizes

PageSetup

Returns the PageSizes collection that contains all the PageSize objects available in the current publication. Read-only.

BackSideInsertFaceUp

AdvancedPrintOptions

Gets or sets whether the second side of the paper for two-sided printing should be inserted face up or face down.

BaseCMYK

ColorFormat

Returns the base cyan-magenta-yellow-black (CMYK) color value of the parent ColorFormat object before any tinting or shading is applied to the color. Read-only.

DataSources

MailMergeDataSource

Returns the MailMergeDataSources collection that includes the parent MailMergeDataSource object. Read-only.

EmailMergeEnvelope

MailMerge

Returns the EmailMergeEnvelope object associated with the parent MailMerge object. Read-only.

IncludeContinuedFromPage

TextFrame

Determines whether the text "Continued from page pagenumber" appears in a text box when Publisher 2007 uses text-box linking.

IncludeContinuedOnPage

TextFormat

Determines whether the text "Continued on page pagenumber" appears in a text box when Publisher 2007 uses text-box linking.

InsertBarcodeVisible

Application

Determines whether Add a postal bar code is available under More Items on the Mail Merge and Catalog Merge task panes in the Publisher 2007 UI; and whether Add postal bar codes is available under Prepare for Mailing on the Publisher Tasks task pane in the Publisher 2007 UI.

InstalledPrinters

Application

Gets the names of all printers installed on the computer and to which the application can print the publication. Read-only.

IsExcess

Shape

Indicates whether the parent Shape object is an excess shape after the document template (wizard) is changed by using the Document.ChangeDocument method or by using the Change Template command in the Publisher 2007 UI. Publisher 2007 places any excess shape under Extra Content in the Format Publication task pane. Read-only.

IsMapped

MailMergeDataField

Indicates if the parent MailMergeDataField object is mapped to a recipient field in the master data source (combined mail-merge recipient list). Read-only.

IsMaster

MailMergeDataSource

Indicates whether the parent MailMergeDataSource object is a master data source (a combination of all data sources connected to the current publication). Read-only.

IsRecolored

PictureFormat

Returns True if the image represented by the parent PictureFormat object was recolored, either in the UI or by using the PictureFormat.Recolor method. Read-only.

LeaveBlackAsBlack

PictureFormat

Returns True if, while you are recoloring, the black portion of the original image should be left as black. Read-only.

LinesCount

TextRange

Returns the number of lines of text in the text range represented by the parent TextRange object. Read-only.

ManualFeedAlign

AdvancedPrintOptions

Gets or sets the alignment (left, right, or center) of where envelopes are fed to the printer's manual feed.

ManualFeedDirection

AdvancedPrintOptions

Gets or sets the orientation (landscape or portrait) of how envelopes are fed to the printer's manual feed.

MappedTo

MailMergeDataField

Returns the name of the recipient field (column) in the master data source (combined mail-merge recipient list) that the parent MailMergeDataField object is mapped to. Read-only.

PageRotated

AdvancedPrintOptions

Gets or sets whether the second page must be rotated 180 degrees from the first-page direction before it is reinserted for two-sided printing.

PageSize

PageSetup

Returns or sets the page size for the specified custom mailing label.

ParagraphsCount

TextRange

Returns the number of paragraphs of text in the text range represented by the parent TextRange object. Read-only.

RecoloredPictureColor

PictureFormat

Returns the color that is applied to the image represented by the parent PictureFormat object. Read-only.

ShowFollowUpCustom

Application

Gets or sets the string (if any) that appears as the fourth item under Prepare to follow-up on this mailing on the third Mail Merge task pane in the Publisher 2007 UI.

SurplusShapes

Document

Returns a ShapeRange object that represents the collection of surplus shapes that Publisher 2007 places under Extra Content in the Format Publication task pane after the document template (wizard) is changed by using the Document.ChangeDocument method or by using the Change Template command in the Publisher 2007 UI. Read-only.

Transparency

ColorFormat

Returns or sets a Single indicating the degree of transparency of the specified fill, shadow, or line as a value between 0.0 (opaque) and 1.0 (clear).

Type

MailMerge

Gets or sets the type of mail merge represented by the parent MailMerge object.

UseWizardForBlankPublication

Options

Gets or sets whether to use a wizard for blank publications.

ValidateAddressVisible

Application

Determines whether Validate addresses is available under Refine recipients in the Mail Merge task pane and whether Validate addresses is available under Prepare for Mailing on the Publisher Tasks task pane in the Publisher 2007 UI.

ValidatedClean

MailMergeDataSource

Indicates whether all recipient addresses in the parent MailMergeDataSource object were successfully validated, and whether any changes were made to the list since the last validation that require the list to be validated again.

WordsCount

TextRange

Returns the number of words in the text range represented by the parent TextRange object. Read-only.

Table 4 lists the new events in the Office Publisher 2007 object model.

Table 4. New events in Publisher 2007

Event

Object

Description

AfterPrint

Application

Occurs after all variables and fields are printed. UI control does not return to the user until the event handler executes. The event is called after all the drawing operations are complete to notify the user that the document has printed.

BeforePrint

Application

Occurs before the publication is printed or previewed. This event occurs only after the document fully loads and the On Load events are returned. Printing does not occur until the event handler executes.

HideCatalogUI

Application

Occurs when the catalog of publication wizards is hidden in the Publisher 2007 UI.

MailMergeGenerateBarcode

Application

Occurs when Publisher 2007 requires data to generate bar codes in a mail-merge publication, in particular, when the mail-merge recipient list changes.

MailMergeInsertBarcode

Application

Occurs when the user issues the command to insert postal bar codes into a mail-merge publication, either in the Publisher 2007 UI, or programmatically.

MailMergeRecipientListClose

Application

Occurs when the user closes the Mail Merge Recipients dialog box. (On the Mail Merge or E-mail Merge task pane, click Edit Recipient List.) Also occurs when the user closes the Catalog Merge Product List dialog box, which opens when the user clicks Edit Product List in the Catalog Merge task pane.

MailMergeWizardFollowUpCustom

Application

Occurs when a user clicks the string that appears as the fourth item under Prepare to follow-up on this mailing on the third Mail Merge task pane in the Publisher 2007 UI.

ShowCatalogUI

Application

Occurs when the catalog of publication wizards is displayed in the Publisher 2007 UI.

Table 5 lists the new enumerations in the Office Publisher 2007 object model.

Table 5. New enumerations in Publisher 2007

Enumeration

Description

PbDriverType

Driver-type constants returned by the Printer.DriverType property.

pbEmailMergePriority

Constants for merged e-mail message priority passed to and returned by the EmailMergeEnvelope.Priority property.

PbFixedFormatIntent

Constants passed to the ExportAsFixedFormat method that specify how the user intends to share the resulting file: by sending it to a commercial printer or desktop printer, or by distributing it online or through e-mail merge.

PbFixedFormatType

Constants passed to the ExportAsFixedFormat method that specify the different file formats in which you can save fixed-format publications, .pdf or .xps.

PbMergeType

Constants that specify the type of mail merge, passed to and returned by the MailMerge.Type property.

PbPrintStyle

Constants that specify the print style, passed to the Document.PrintOutEx and ExportAsFixedFormat methods.

PbRecipientListFileType

Constants that specify the type of file in which to save an exported mail-merge recipient list, passed to the MailMerge.ExportRecipientList method.

Table 6 lists new constants that are available in existing enumerations in the Office Publisher 2007 object model.

Table 6. New constants in Publisher 2007

Enumeration

Constants

PbFieldType

pbFieldPersonalizedHyperlinkURL

PbFileFormat

pbFilePlainText

pbFileUnicodeText

PbHlinkTargetType

pbHlinkTargetTypePersonalized

PbMailMergeDataSource

pbMergeInfoSubODSO

PbMailMergeDestination

pbSendEmail

PbWizard

pbWizardEmailAutomatic

Deprecated Object Model Members

Table 7 lists object-model items that are deprecated in the Office Publisher 2007 object model.

Table 7. Deprecated items in Publisher 2007

Object or Enumeration

Member or Constant

AdvancedPrintOptions object

PrintableRect property

AdvancedPrintOptions object

PrintMode property

AdvancedPrintOptions object

UseCustomHalftone property

Application object

FileSearch property

Document object

ActivePrinter property

Document object

PersonalInformationSet property

FillFormat object

Transparency property

Label object

Object only

Labels collection

Collection only

LinkFormat object

Transparency property

Options object

DisplayPrintTroubleshooter property

Options object

EnvelopePrintOrientation property

Options object

EnvelopePrintPlacement property

Options object

PrintLineByLine property

Options object

UpdatePersonalInfoOnSave property

Options object

UseEnvelopePaperSizes property

Options object

UseEnvelopePrintOptions property

Options object

UseHelpfulMousePointers property

PageSetup object

AvailableLabels property

PageSetup object

Label property

PageSetup object

MultiplePagesPerSheet property

PageSetup object

Orientation property

PbFileFormat enumeration

pbFilePublicationHTML constant

PbPublicationLayout enumeration

All constants

ShadowFormat object

Transparency property

Conclusion

This article introduces the new features of interest to developers in Office Publisher 2007, including the APIs associated with the new features. It lists all the new objects and members added to the Office Publisher 2007 object model and provides links to Office Publisher Help topics on MSDN that show how to use the new objects and members. In addition, it lists the items that are deprecated in the Office Publisher 2007 object model.

Additional Resources

For more information about existing members of the Office Publisher 2007 object model, see the following resources: