Online Print Wizard Service Provider

Online Print Wizard Service Provider

 

Microsoft Corporation

August 2006

 

Applies to:

   Microsoft Windows Vista

Summary: This article describes the Online Print Wizard (OPW) and how service providers can build online ordering services for photo printing that integrate with it.

 

Contents

Introduction

Access Points

User Interface

    User Interface: Service Provider List Page

    User Interface: Privacy Notice

    User Interface: Connection Progress Page

    User Interface: Service Provider Web Pages

    User Interface: Web Service Error Pages

    User Interface: Upload Progress Page

    User Interface: Finish Page

Building Online Print Wizard Web Pages

    Overview

    Requirements and Guidelines

    Registering a Service Provider for the Online Print Wizard

    Client-Server Interaction: Using window.external.*() Functions

        FinalBack() Function

        FinalNext() Function

        Cancel() Function

        Caption() Property

        SetWizardButtons() Function

        SetHeaderText() Function

        PassportAuthenticate() Function

        Property Property

    Client-Server Interaction: Accessing window.external Properties

    Client-Server Interaction: Navigation Script Functions

        OnBack() Function

        OnNext() Function

        OnCancel() Function

        HTML Sample – Returning to the Service Provider List Page

        HTML Sample – Navigating to the Next Page

        Enabling AutoComplete

    The Transfer Manifest: Overview

    Retrieving Information from the Transfer Manifest

    Transferring Files

        Populating the post Element

        Populating the uploadinfo Element

        Using the htmlui Element to Display a Link

        Defining a Success Page Using the successpage Element

Security Considerations

Transfer Manifest XML Schema

    cancelledpage

    failurepage

    file

    filelist

    formdata

    htmlui

    imageproperty

    metadata

    post

    resize

    successpage

    transfermanifest (root element)

    uploadinfo

Introduction

The Online Print Wizard (OPW) enables users to send photos stored on their computers, attached hardware devices, and network devices to digital photo developing services (referred to as "service providers" in this specification) on the Internet.

The OPW solution consists of three main components:

• The OPW user interface that is part of Windows Vista.
• A Microsoft Service Provider Server, maintained by Microsoft, which lists service providers for each country or region. The OPW connects to the Microsoft Service Provider Server and downloads the list.
• A Web server, developed and run by a service provider, that provides a custom workflow for ordering prints of digital images. The user interface for this Web server is displayed in the OPW. In addition to the workflow displayed in the OPW, the Web server receives digital images from the client for processing.

An example of the OPW and integration performed by Service Providers can be found in Microsoft Windows XP. Go to the My Pictures folder and, in the Picture Tasks pane on the left side of the window, click Order prints.

This document describes the OPW implementation for Windows Vista, the integration points that may be leveraged by service providers, and the program model and protocols for integrating an online digital image processing service with the OPW platform.

Access Points

The OPW may be accessed from the Print menu on the taskbar in either the Windows Photo Gallery or the Windows Photo Gallery Viewer. The Windows Photo Gallery can be accessed from the Start menu. The Windows Photo Gallery Viewer can be accessed by right-clicking on a photo, clicking Open With, and then choosing Windows Photo Gallery Viewer, or by double-clicking on a photo from within the Windows Photo Gallery or Windows Explorer. Both the Windows Photo Gallery and the Windows Photo Gallery Viewer have similar taskbars. In each, the Print menu is invoked by clicking the drop-down menu beneath the printer icon.

The following two menu options that are related to the OPW functionality appear when the Print menu is invoked:

1. Order prints menu item

   When this menu item is selected, the OPW is instantiated and the service provider list page is displayed.

2. Most Recently Used (MRU) menu item

   The MRU menu item displays the service provider, which may be preconfigured by an OEM (see the OEM Pre-Installation Kit [OPK] documentation) or populated by the user as the result of previously selecting a service provider on the service provider list page. When the MRU menu item is selected, the OPW is instantiated, and the first page of that provider's order workflow is displayed.

The following screen shots show how these menu items appear in the Windows Photo Gallery and the Windows Photo Gallery Viewer:

Figure 1. Menu items in the Windows Photo Gallery

Figure 2. Menu items in Windows Photo Gallery Viewer

User Interface

The OPW provides user interface (UI) for various steps in the ordering process, including the following:

• Service provider list page
• Privacy notice
• Connection progress page
• Service provider Web pages
• Error page
• Upload progress page
• Default finish page

User Interface: Service Provider List Page

When instantiated from the Order prints menu item, the Online Print Wizard presents the user with a list of service providers to select from. The list of service providers that is displayed on the service provider list page depends on the country/region setting on the user's computer. You can view or change this setting in Regional and Language Options in Control Panel. The order of the provider list is alphabetical based on the system locale.

The following screen shot shows the service provider list page.

Figure 3. Service provider list page

When you select a service provider from the service provider list and then click Send Pictures, the OPW implementation creates a transfer manifest — which describes each of the images that have been selected by the user for processing — and exposes it to the service provider's Web site. The transfer manifest may be accessed by the service provider using script. The service provider can read the transfer manifest, modify it, or transmit it back to its Web server if it chooses to.

User Interface: Privacy Notice

To notify the user that personal information that is associated with their pictures is being made available to the service provider through the transfer manifest, the OPW displays a privacy notice after the service provider is selected. The privacy notice dialog box provides a check box that gives the user the option to decline to show the dialog box in subsequent invocations of the OPW. If the Send button in the dialog box is clicked, the OPW progresses to the service provider's Web pages. If Cancel is clicked, the dialog box closes and the user may select another service provider or quit. The privacy dialog box is pictured below.

Figure 4. Privacy notice dialog box

User Interface: Connection Progress Page

The OPW may display a connection progress page as a service provider's Web pages are being retrieved. If the OPW is able to make a connection to the selected provider immediately, this page might not appear. The connection progress page is pictured below.

Figure 5. Connection progress page

User Interface: Service Provider Web Pages

After the transfer manifest is made available to the service provider, the OPW displays HTML pages from the service provider's Web server that compose a workflow for ordering digital photo prints. The image that follows this paragraph shows an example of a quantity selection page generated by a service provider's Web server and displayed within the OPW. The header section contains the words "Customize Your Order: Step 1 of 5" and is part of the OPW client. The Next, Back, and Cancel buttons are also part of the OPW client. The service provider does not provide these elements, but can interact with them using script (Described in Client-Server Interaction: Using window.external.*() Functions). Note that the Back button is the arrow in the upper left corner. The service provider's HTML page is displayed below the header.

Figure 6. Page from a service provider's Web site

User Interface: Web Service Error Page

If an error, such as an attempt to navigate to a nonexistent page, occurs when the OPW attempts to load a service provider's Web page, the Web service error page, pictured below, will be displayed.

Figure 7. Web service error page

User Interface: Upload Progress Page

As each selected photo is being uploaded to the service provider, the OPW displays a page indicating progress to the user. The file name, a thumbnail of the image currently being transferred, and an upload progress indicator are shown in the upload progress page. The upload progress page is shown below.

Figure 8. Upload progress page

User Interface: Finish Page

After the ordering process is complete, the OPW provides a client-side finish page, which may optionally display additional text and a URL provided by the service provider. The text in the finish page will indicate whether the transfer of photos was successful, canceled by the user, or aborted due to an error. The following screen shot shows a finish page.

Figure 9. Finish page

Building Online Print Wizard Web Pages

This section contains the necessary information for building Web pages for print ordering that integrate with the Online Print Wizard (OPW). It also details how to create registry settings to enable additional services to appear in the wizards.

Requirements for Third-Party Service Partners

• Wizards cannot contain advertisements unrelated to the photo printing order.
• Wizards cannot contain objectionable or adult content.
• Each wizard must be visually consistent within its screens, but does not need to be consistent with standard wizards in the Microsoft® Windows® operating system.
• Technical requirements are defined in Requirements and Guidelines.

Overview

When a service provider is selected from the service provider list page that is displayed within the OPW, the OPW browses to a special Web page hosted on the service provider's Web server. Script on the page may then interact with the wizard through the window.external object provided by Windows Internet Explorer®, and the upload process can be controlled by using script on the Web page to read and modify the transfer manifest.

The navigation functions and the transfer manifest are described in Client-Server Interaction and Transfer Manifest. Instructions for registering a service provider to appear in the OPW are in Registering a Service Provider for the Online Print Wizard. Using these pieces, you can build your own pages for ordering prints online.

Requirements and Guidelines

Before you begin developing your Web print ordering pages, there are a number of requirements and guidelines that you should consider incorporating into your design. Adhering to these requirements and guidelines provides for both a good user experience and a good customer experience using your integrated OPW solution.

• General advertisements, objectionable, or adult content may not be displayed on pages displayed in the OPW. Cross-sales links and advertisements are permitted if they are related to the order being submitted through the OPW (for example, "Get 50% off on your next order"). These links and advertisements must be contained within the service provider's Web page displayed within the OPW.
• A service provider's server must not download software (such as Microsoft® ActiveX® controls) to a client machine or have a dependency on software that does not ship in Windows Vista to complete an OPW transaction.
• The OPW uses an instance of the WebBrowser control via the IWebBrowser2 interface, documented on MSDN, for displaying a service provider's Web pages. As a result, the Internet Options settings configurable through Internet Explorer are applicable to the OPW implementation. A service provider's Web pages must be functional without errors when the default Internet Explorer settings are applied.
• A service provider's OPW implementation may instantiate a new browser window for advanced features such as showing to a user what a cropped image might look like and for cases in which large amounts of text that is ancillary to the ordering process (for example, privacy statements, online help, terms of service) must be displayed to the user. When a new browser window is displayed, the HTML page's contents must include a Close button. The menu bar and any toolbars of the instantiated browser window must be suppressed. Pages displayed within the OPW must not contain active links that instantiate a Web browser, except as described previously.
• A service provider must display a link to its privacy statement on the first Web page displayed in the OPW.
• Pop-up message boxes may be created through a service provider's Web page only to convey informational or error messages to the user.
• Web pages displayed in the OPW must conform to the size of the display window. Vertical scrolling is permitted, but horizontal scrolling is not allowed. The physical dimensions of the display window are 536 pixels (width) by 306 pixels (height).
• A user may select an image file format that is not capable of being processed by a service provider. As a result, when the user-selected file list is transmitted to the service provider's server for processing, the server must be prepared to handle any of the following conditions accordingly:

  • The image file selection contains both supported file formats and formats that are not supported by the service provider. The service provider must filter out the user-selected files whose formats are not supported, and for each unsupported image, display a message informing the user of the file types not supported by the service provider. For example, a message might contain the following text:

    An error occurred processing the following file: MyImage.bmp. This error usually occurs when the image's file type is not supported by the service. Please be sure that you have selected image files with the following extensions: .jpeg, .jpg, .tiff.

    The subset of selected image file formats that are supported by the service provider should then be processed normally.

  • The image file selection contains only file formats that are not supported by a service provider. For each unsupported image, the service provider should display message text on the page informing the user of the file types not supported by the service provider. When no image files remain to be processed, the service provider must inform the user and exit gracefully.

• A service provider must apply good privacy and security practices. The service provider must also conform to the privacy and security practices that are legally required by the region that the service provider operates in.
• A service provider must apply good accessibility practices to their Web page designs. Graphic buttons should not be used to navigate to other pages or through the wizard. Web pages displayed within the OPW should not have Back, Forward, or Cancel buttons or links. Instead, the solution must integrate with the wizard's built-in Back, Forward, and Cancel buttons through event handling.
• Service providers should offer online help, a support e-mail address (with at least a 48-hour response time), and a toll-free customer service number.

Registering a Service Provider for the Online Print Wizard

There are several ways service providers can have their services displayed in the OPW service provider list page.

1. When the OPW is instantiated, the OPW communicates with the Microsoft Service Provider Server. Metadata that is associated with service providers is maintained by Microsoft on this server. This data is downloaded to the computer running Windows Vista, persisted in the computer's registry, and displayed in the OPW service provider list page. If your company is interested in being managed on the Microsoft Service Provider Server, please send a request to opwreq@microsoft.com.
2. A service provider may provide a setup application to customers that saves information about the service provider — including a URL for connecting to the service provider's Web server — to the registry.
3. A service provider may partner with an OEM, who can preinstall the service provider's registry information on the computer running Windows Vista. For details, see the OEM Pre-installation Kit (OPK).

If a service provider plans on writing a setup application, the setup application must write information about its service to a specific location in the registry. Data must be added to the registry using the following subkey:

HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\PublishingWizard\InternetPhotoPrinting\Providers\ServiceProviderName

The value for ServiceProviderName must be a text string and a single word. Many service providers use their company name without spaces — for example, FabrikamPrinting.

There are four required fields, each of which is a REG_SZ data type. The four fields are described in the following table.

Name	Meaning
IconPath	The URL to your icon. For example, https://www.fabrikam.com/site.ico.
DisplayName	The name displayed for your service, in the first line of the service provider's entry in the service provider list page (displayed in the screen shot in User Interface: Service Provider List Page.).
Description	The description for your service, which is shown in the second line below the display name in the service provider list page (displayed in the screen shot in User Interface: Service Provider List Page). The description would ideally be less than 70 characters. Service providers should test to make sure the description fits into one line.
HREF	The URL for the first page of your service. For example, https://www.fabrikam.com/printphotos.html.

When the URL is used, the wizards append two parameter/value tags to the end of the URL to help the service receive proper language and location information. For example, if your URL was https://www.fabrikam.com/webwizard/page1.htm, the actual formed URL would be https://www.fabrikam.com/webwizard/page1.htm?lcid=1033\&langid=1033. The meanings of the two variables are given in the following table.

Name	Meaning
LCID	LCID tells the service provider's server the country/region and language that is set in the user's browser. LCID should not be used to determine the language of the UI, but should be used to determine formats for currency, date and time, numbers, and so on.
LangId	LangId tells the server what the user's default UI language is so that the server can display the UI in the correct language.

Client-Server Interaction: Using window.external.*() Functions

The OPW framework exposes functions that a service provider's Web pages may call to interact with the OPW client. The functions are methods of the window.external object, and are accessible from JavaScript on each HTML page. The code examples are in JavaScript.

FinalBack() Function

void FinalBack();

Called when the server wants to tell the client to navigate to the service provider list page of the OPW. For example, suppose the wizard currently shows the first page in the server-side Web pages, and you want the wizard to return to the service provider list page when the user clicks Back. You would implement the OnBack() function (see Client-Server Interaction: Navigation Script Functions, later in this paper) to include a call to FinalBack(), telling the client to navigate to the starting page of the OPW.

FinalNext() Function

void FinalNext();

Called to send the photos to the provider, or to end the OPW on the last server-side HTML page (for instance, on the cancellation page if the upload was canceled). This is typically done from the OnNext() handler, which is invoked when the user clicks the Next button.

Calling FinalNext() will implicitly begin an upload if the transfer manifest has been populated with upload information. The upload process is explained in Transferring Files.

Cancel() Function

void Cancel();

Called to simulate clicking a Cancel button. A call to Cancel() will invoke the script navigation function OnCancel(), if OnCancel() is implemented. The wizard will exit and a cancellation page will be shown.

Caption() Property

read-only property Caption;

Called to retrieve the caption.

SetWizardButtons() Function

void SetWizardButtons( bool EnableBackButton,
                       bool EnableNextButton,
                       bool LastServerSidePage);

Called to update the Back, Next, and Finish buttons in the client's wizard frame when a new server-side page is displayed or when the user has manipulated a UI element on the page.

Name	Meaning
Bool EnableBack	Enable the Back button
Bool EnableNext	Enable the Next button
Bool LastServerSidePage	Display a Finish button instead of a Next button. This tells the wizard that the ordering process is complete, and that this is the last server-side page. This flag is not normally set if the images have not yet been transferred. The wizard will immediately exit to a client-side completion page when the user clicks Finish. The OnNext() handler is not invoked when Finish is clicked, so there is no mechanism for navigating to any other server-side pages.

When the user clicks a wizard button (Back, Next, or Cancel), the client calls the JavaScript functions OnBack(), OnNext(), and OnCancel(), which must be implemented on each server-side UI page. Clicking Finish, however, will simply exit from the wizard pages, without calling OnNext(). Finish is normally enabled if the page is a success page, a cancellation page, or a failure page, defined in the uploadinfo element of the transfer manifest.

    // Enable Back and Next buttons when this page loads. 
    function window.onload()
    {
        // Enable Back and Next.
        window.external.SetWizardButtons(1, 1, 0);
    }

SetHeaderText() Function

void SetHeaderText(string HeaderTitle, string HeaderSubtitle);

Sets the title that should appear in the wizard header, above the HTML region. Call window.external.SetHeaderText() to set the text in the header when your page loads. Note that the second parameter is not used in Windows Vista.

        function window.onload()
        {
        // Enable Back and Next buttons when this page loads.
            window.external.SetWizardButtons(1, 1, 0);
            // Set the wizard header.
            window.external.SetHeaderText("Online Print Provider", ""); 
        }

PassportAuthenticate() Function

bool PassportAuthenticate(string bstrSignInUrl);

Redirects the client to be authenticated with the Microsoft Passport Network.

Name	Meaning
String SignInUrl	A URL to a Web page that results in a redirection to the Passport Network for log on. This causes the Passport Network sign-in UI to appear.
Bool Return Value	The function returns True if authentication succeeds, or False otherwise.

It is safe to call this function even if a user is already signed in to the Passport Network.

Property Property

write property Property(string PropertyName, var PropertyValue);
read property Property(string PropertyName);

Allows arbitrary properties to be stored on the client. These properties are accessible from each wizard page and can be used to pass information between pages. These properties are also used to pass information back to the client-side wizard as necessary. A set of properties with well-known names and meanings is defined for this purpose. If the Web page tries to retrieve a property that is not defined, null is returned.

Name	Meaning
String PropertyName	Name of the property to set or retrieve.

The script to set a property value looks like this:

window.external.Property("PropertyName")=Value;

The script to get a property value looks like this:

var Value = window.external.Property("PropertyName");

Client-Server Interaction: Accessing window.external Properties

Windows passes these predefined properties to expose client settings and file information to the server. Script on the page can access the properties at any time through window.external.Property("Propertyname").

Name	Meaning
TransferManifest	An XML document used to control the file upload. Described in more detail in The Transfer Manifest.
High Contrast	A Boolean value that is true if the client computer's display has high contrast enabled and false otherwise. In Windows Vista, high contrast is considered enabled if the Turn on High Contrast check box is selected in the Ease of Access Center within the Appearance and Personalization control panel. The server can use this setting to determine whether to display high-contrast HTML pages or simplified UI elements.

Client-Server Interaction: Navigation Script Functions

As described earlier, each page must implement OnBack() and OnNext() in a script on each page. OnCancel() may be implemented to provide custom behavior when Cancel is clicked. These functions may call the client's window.external functions to perform navigation between wizard pages as appropriate. These functions take no parameters. Clients ignore return values.

OnBack() Function

This function indicates that the user has clicked Back in the wizard. If the intent is to tell the client to navigate back to the service provider list page, call window.external.FinalBack(). Otherwise, this function should contain code to load the previous server-side page. Some ways to load the previous page are by setting window.location or by submitting a form to a script that generates the next page.

OnNext() Function

This function indicates that the user has clicked Next in the wizard. If the current server-side page is at the stage where photos should be uploaded, call window.external.FinalNext() to tell the client to transfer files and complete the wizard, as appropriate. If the current page is a cancellation, failure, or success page that indicates the result of the print ordering process, and the Next button is enabled, OnNext() should also call FinalNext() to end the wizard. Otherwise, this function should contain code to load the next server-side page. Some ways to load the next page are by setting window.location or by submitting a form to a script that generates the next page.

Note If the Finish button is enabled, OnNext() is not called when the Finish button is clicked. Make sure that Next is displayed if OnNext() contains script to be executed. For more information, see the SetWizardButtons() function.

OnCancel() Function

This function indicates that the user has clicked Cancel from within the wizard, or that window.external.Cancel() has been called. The server-side UI should be designed so that the user may cancel at any time.

HTML Sample – Returning to the Service Provider List Page

The server-side code for a wizard page is very simple. The following is a short sample from the source markup for an error page that enables the Back button and navigates to the first page of the OPW when the Back button is clicked:

<html>
    <head>
    <script language="JavaScript">

    function window.onload()
    {
        window.external.SetWizardButtons(1, 0, 0);
    }

    function window.onback()
    {
        window.external.FinalBack();
    }

    </script>
    </head>
    <body>
        <p>Windows was unable to connect to the Internet,
        or the Web service returned an invalid wizard page. </p>
        <p>To return to the list of online printing services
        and try again, click Back.</p>
        <p>To close this wizard, click Cancel.</p>
    </body>
</html>

HTML Sample – Navigating to the Next Page

The OnNext() function is implemented similarly to OnBack(); it can navigate the browser to the next server-side page as required. The following HTML example shows an implementation of OnNext() that submits form data to navigate to the next page.

<html><head>
<script>
    function window.onload()
    {
        // Enable the Back and Next buttons.
        window.external.SetWizardButtons(1, 1, 0);
        window.external.SetHeaderText("Test Online Print Provider.", ""); 
    }

    function window.onback()
    {
        window.external.FinalBack();
    }

    function window.onNext(){
        // The next line submits the form.
        document.frm.submit();
    }
</script>
</head>
<body>
<form name="frm" id="frm" action="Step2.aspx" method="post">
<p>Please enter your email address.</p>
<input type="text" id="email" name="email" value="enter_email_here" /> 
</form>

The OnNext() function can also call window.external.FinalNext to navigate to the next Microsoft® Win32®-based client-side page at the end of the HTML pages. This implicitly begins an upload of the files to be transferred. The contents of the transfer manifest must be updated with the data required for an upload before FinalNext() is called. The Transferring Files section describes this in more detail.

Enabling AutoComplete

AutoComplete, a feature which stores previous entries and suggests matches for you, is particularly useful on pages such as billing or address pages that require the customer to enter data. In any server page that has a form for the user to fill out, you can optionally enable AutoComplete by adding a call to document.*FormName.*fireEvent("onSubmit") right before the call to submit the form, as indicated in the following code:

    function window.onNext(){
        // Enable AutoComplete for the form Form1. 
        document.Form1.fireEvent("onSubmit");
        // Submit the form.
        document.Form1.submit();
    }

If AutoComplete is enabled in code by including the call to fireEvent() as above, it will behave exactly as the Internet Explorer AutoComplete settings specify:

• If AutoComplete is enabled in code and enabled in Internet Explorer, it will be enabled in the page.
• If AutoComplete is enabled in code, and the Internet Explorer settings enable AutoComplete for all forms except user names and passwords, then AutoComplete will be enabled in the page for all forms except user names and passwords.
• If AutoComplete is disabled in Internet Explorer, it will be disabled in the page, regardless of whether it was enabled in code.
• If AutoComplete is not enabled in code, then it will be disabled in the page regardless of Internet Explorer settings.

The Transfer Manifest: Overview

The Online Print Wizard (OPW) uses the transfer manifest as a communication channel between the site's HTML pages and the Win32 wizard framework.

The manifest describes the files that are going to be transferred, identifying such details as the source file names, destination file names, image size, and metadata. In return, the HTML from the site can modify the manifest, adding files or removing files from the list and then adding information about where and how the files should be transferred.

The manifest is exposed as the property (window.external.Property("TransferManifest"). The manifest is an XML DOM (IXMLDOMDocument). You can view its fields in the Transfer Manifest XML Schema section of this document.

When the OPW is first displayed, the wizard framework populates the transfer manifest with some initial values, based on the files the user initially selected.

Here is an example of a transfer manifest, initially populated when the user launches the OPW after selecting two files to order prints of.

<transfermanifest>
<filelist>
<file id="0" 
      source="C:\Users\Me\Pictures\Vacation\Vacation020.jpg" 
      extension=".jpg" 
      contenttype="image/jpeg" 
      destination="Vacation020.jpg" 
      size="730540">
      <metadata>
            <imageproperty id="cx">1536</imageproperty>
            <imageproperty id="cy">2048</imageproperty>
      </metadata>
</file>
<file id="1" 
      source="C:\Users\Me\Pictures\Vacation\Vacation021.jpg" 
      extension=".jpg" 
      contenttype="image/jpeg" 
      destination="Vacation021.jpg" 
      size="618652">
      <metadata>
            <imageproperty id="cx">1536</imageproperty>
            <imageproperty id="cy">2048</imageproperty>
      </metadata>
</file>
</filelist>
</transfermanifest>

Retrieving Information from the Transfer Manifest

The wizard builds the manifest to contain the basic elements as children of the root node transfermanifest, as shown in the following table.

Name	Meaning
filelist	Root element for the file list being copied. Has an attribute that indicates whether folders will be used.
file	Element describing a file to be transferred. Provides the attributes source, destination, and size, as well as the children describing the metadata for the file and the target to post the file to.
uploadinfo	Describes information for the upload, including navigation targets, and so on. (See the next section, Transferring Files.)

The HTML for the Web page can then use the DOM (Document Object Model) object to select these nodes and modify their UI accordingly. For example, a photo printing site might use the source information to display thumbnails of all the images for which prints will be ordered, or use the dimensions indicated in the metadata nodes to determine whether the image has a high enough resolution for quality prints.

Note The manifest is recreated each time the site is navigated to. For example, if the user selects Fabrikam Printing, a copy of the manifest is created for Fabrikam to see. If the user then returns to the provider list and selects another site, a new instance of the manifest is created for the new site.

Example

The following script retrieves the number of files selected for printing from the transfer manifest and displays that number.

<script>
        var xml = window.external.Property("TransferManifest");
        var files = xml.selectNodes("transfermanifest/filelist/file");
            alert('You are about to upload ' + files.length + ' files.');
</script>

Transferring Files

Files are transferred to the provider when window.external.FinalNext() is called. For instance, the call to FinalNext() may be done when the user clicks Next and window.onNext() is invoked:

        function window.onNext(){
            window.external.finalNext();
        }

When the HTML UI is ready to call window.external.FinalNext(), it must add information to the manifest about how the files will be transferred and how the transfer results should be displayed. The post element and the uploadinfo element of the transfer manifest are used to add this information.

Populating the post Element

The wizard framework will handle the call to FinalNext() by using the information in the transfer manifest to initiate an HTTP POST request once per file. Therefore, each file element to be transferred needs to have a child post element that is properly populated. The required href attribute of each post element should specify the URL to which the file should be posted. The required name attribute specifies the form data name of the post. Each post element may also have formdata children encoded as separate parts within post.

The following example JavaScript code shows how one might add a post element to each file element in the transfer manifest, and set its attributes and formdata child elements:

    var xml = window.external.Property("TransferManifest");
    var files = xml.selectNodes("transfermanifest/filelist/file");
    for (i = 0; i < files.length; i++) {           
        var postTag = xml.createNode(1, "post", "");
        postTag.setAttribute("href", 
        "https://www.fabrikam.com/sampleUpload.aspx");
        postTag.setAttribute("name", "FileToUpload");
        var formdataTag = xml.createNode(1, "formdata", "");
        dataTag.setAttribute("name","email");  
        dataTag.text = "username@fabrikam.com";
        postTag.appendChild(formdataTag);
        files.item(i).appendChild(postTag);
    }

Populating the uploadinfo Element

Prior to calling window.external.FinalNext(), the site should always add an uploadinfo element as a child of the root transfermanifest node. The uploadinfo element can be used to specify pages to navigate to upon successful upload, cancellation, or failure, as well as define additional text or hyperlinks in the final page of the Online Print Wizard. The uploadinfo element can have the children shown in the following table.

Name	Meaning
htmlui	Defines the URL that the wizard should link to in its final page, following the last HTML page defined in successpage.
successpage	Defines the URL that the wizard should navigate to on a successful upload of the user's files.
cancelledpage	Defines the URL that the wizard should navigate to if the user clicks Cancel in the OPW.
failurepage	Defines the URL that the wizard should navigate to if the upload fails.

The uploadinfo element has the following attribute.

Name	Meaning
friendlyname	Optional. Defines the text that may be shown in the final page of the wizard that follows the last HTML page defined in successpage. This text may display a hyperlink to the URL specified in the href attribute of the htmlui element.

Using the htmlui Element to Display a Link

The htmlui element may be used in conjunction with the friendlyname attribute of the uploadinfo element to provide additional text and a link for users to navigate to from the client-side page that appears after navigating from the last HTML page in the ordering process, as shown in the screen shot below.

The following example JavaScript script shows how to add a link in the last page of the wizard, so that it will appear as in the screen shot below.

<script>
    var xml = window.external.Property("TransferManifest");
    var uploadTag = xml.createNode(1, "uploadinfo", "");
    uploadTag.setAttribute("friendlyname", 
        "</a>Click here to see the photos you just uploaded: " +
        "<a href=\"https://myserver.com/library/\">Photo Library</a>.<a>");
    var htmluiTag = xml.createNode(1, "htmlui", "");
    uploadTag.appendChild(htmluiTag);
    htmluiTag.setAttribute("href","https://myserver.com/library/");
    uploadTag.appendChild(htmluiTag);
    xml.documentElement.appendChild(uploadTag); 
</script>

The following screen shot shows how the finish page would appear.

Figure 10. Finish page

Defining a Success Page Using the successpage Element

The following code shows how to add a node to the transfer manifest that defines a page to display after a successful transfer.

<script>
var xmlDoc = window.external.Property("TransferManifest");
// The next line assumes the <uploadinfo/> element 
// has already been created in a previous page.
var uploadInfo = xmlDoc.selectSingleNode("transfermanifest/uploadinfo")
var successpageTag= xml.createNode(1, "successpage", "");
successpageTag.setAttribute("href", "https://myserver.com/successpage.html");
uploadInfo.appendChild(successpageTag);
</script>

Note The success page should implement the OnCancel, OnNext, and OnBack functions. Otherwise the OPW may show a script error.

Security Considerations

Encrypt Sensitive Information

All online printing providers should use HTTPS to transfer sensitive information such as passwords, personal identification numbers (PINs), credit card numbers, and Social Security numbers.

Prevent Fraudulent Transactions

When developing an online printing Web service, be aware that hackers may attempt to submit fraudulent transactions — for example, attempting to upload more photos than were actually paid for. Be careful to design your service in such a way that authentication and validation cannot be bypassed or easily simulated from outside the Online Print Wizard.

Transfer Manifest XML Schema

This schema describes the following elements and their attributes:

Elements

• cancelledpage
• failurepage
• file
• filelist
• formdata
• htmlui
• imageproperty
• metadata
• post
• resize
• successpage
• transfermanifest (document element)
• uploadinfo

Document conventions

• [] - optional
• []* - zero or more times
• +[] - one or more times

cancelledpage

Specifies the HTML page to display in the OPW if the order is canceled. The canceled page has the same access to the transfer manifest as other wizard pages.

Syntax

<cancelledpage
     href = "string"
>
          <!-- Text content is ignored by the OPW. --/>
</cancelledpage>

Attributes

Attribute	Description
href	The URL of the HTML page to display upon cancellation.

Element Information

Parent Element	Child Elements
uploadinfo	None

failurepage

Defines the HTML page to display in the OPW if the transfer of photos to the provider fails. The failure page has the same access to the transfer manifest as other wizard pages.

Syntax

<failurepage
     href = "string"
>
          <!-- Text content is ignored by the OPW. --/>
</failurepage>

Attributes

Attribute	Description
href	The URL of the page to display if the upload of images to the service provider fails.

Element Information

Parent Element	Child Elements
uploadinfo	None

file

Describes a file that will be transferred.

Syntax

<file
     [ contenttype = "string" ]
       destination = "string"  
     [ extension = "string" ]
       id = "string"
     [ size = "string" ]
       source = "string" 
>
     <!-- Child elements -->
          [    <metadata> ]*
          [    <resize> ]
          [    <post> ]
          <!-- Text content is ignored by the OPW. --/>
</file>

Attributes

Attribute	Description
contenttype	Optional. The Multipurpose Internet Mail Extensions (MIME) type of the file. If the OPW is able to determine the MIME type of the file, this attribute will be added to the transfer manifest when the OPW is instantiated.
destination	Required. Relative file name to use when saving the image. For example, myimage.jpg. Defaults to the original name of the file.
extension	Optional. The file extension, such as .PNG, of the file.
id	Required. An integer greater than or equal to zero, representing the unique identifier (ID) of this image in the selection of images. This attribute is added to the transfer manifest by the OPW when it is first instantiated.
size	Optional. Size of the image in bytes. If the OPW is able to determine the file size, this attribute will be added to the transfer manifest when the OPW is instantiated.
source	Required. Full path to the file on the client computer. For example, C:\Users\Administrator\Pictures\myimage.jpg. The OPW populates this attribute with the path when the OPW is first instantiated

Element Information

Parent Element	Child Elements
filelist	metadata, post, resize

filelist

Contains a list of all the files that will to be transferred to the service provider.

Syntax

<filelist>
     <!-- Child elements -->
    +[   <file> ]
          <!-- Text content is ignored by the OPW. --/>
</filelist>

Attributes

No supported attributes.

Element Info

Parent Element	Child Elements
transfermanifest	file

formdata

Defines optional form data that can be transferred with the file. This element is added by the service. The form data, together with information from the post element, is used to create the post header for a multi-part post. Multiple formdata elements can be contained under a single post node.

Syntax

<formdata
    name = "string"
>
     <!-- Content is the value of the form data named by the name attribute. --/>
</formdata>

Attributes

Attribute	Description
name	The name of the form data.

Content Information

The content of this element is the value of the form data named by its name attribute.

Element Information

Parent Element	Child Elements
post	None

htmlui

Defines the URL of the Web page to link to when the transfer of photos to print has been completed successfully. The link is displayed on the first client-side Win32® page after the last server-side HTML page. May be used in combination with the friendlyname attribute of the uploadinfo element to display the link.

Syntax

<htmlui
    href = "string"
>   
          <!-- Text content is ignored by the OPW. --/>
</htmlui>

Attributes

Attribute	Description
href	URL to link to on the client-side completion page when a transfer is successful.

Element Information

Parent Element	Child Elements
uploadinfo	None

imageproperty

Specifies an image property that relates to this file. Multiple imageproperty elements may be contained under a metadata node.

Syntax

<imageproperty
     id = "string"
>
    <!-- Text content should be the value of the property named by id attribute.-- />
</imageproperty> 

Attributes

Attribute	Description
id	The name of the image property

Content Information

The text content of this element is the value of the image property named by the id attribute.

Element Information

Parent Element	Child Elements
metadata	None

metadata

Contains a series of imageproperty elements that defines the metadata for the particular file.

Syntax

<metadata>
     <!-- Child element -- />
     [<imageproperty>]*
          <!-- Text content is ignored by the OPW. --/>
</metadata>

Attributes

This element has no supported attributes.

Element Information

Parent Element	Child Elements
file	imageproperty

post

Specifies the URL to which the file should be posted. This element is added by the service provider, along with formdata, to build a post header.

Syntax

<post
     [ filename = "string" ]
       href = "string"
       name = "string"
>
      <!-- Child elements --/>
      [ <formdata/> ]*
          <!-- Text content is ignored by the OPW. --/>
</post>

Attributes

Attribute	Description
filename	Optional. The file name for the posted file.
href	Required. The URL of the script to post to.
name	Required. The form name associated with this part of the post.

Element Information

Parent Element	Child Element
file	formdata

resize

Defines how the OPW should scale and resize an image before it is uploaded to the service provider. Aspect ratio will always be preserved, and images will not be resized if they are less than or equal to the width or height specified. The significance of the cx and cy attributes depends on the proportions of the original image.

If the original image is wider than it is tall (landscape orientation), the width of the resized image is determined by the cx attribute, and the height is calculated to preserve aspect ratio, ignoring cy. If cx is less than or equal to 0, or if cx is greater than the original width, then the original width is used and the image is not resized.

If the original image is taller than it is wide (portrait orientation), the height of the resized image is determined by the cy attribute, and the width is calculated to preserve aspect ratio, ignoring cx. If cy is less than or equal to 0, or if cy is greater than the original height, then the original height is used and the image is not resized.

Syntax

<resize
     cx = "string"
     cy = "string"
>
          <!-- Text content is ignored by the OPW. --/>
</resize>

Attributes

Attribute	Description
cx	Required. Width of the resized image. See the description of resize for details.
cy	Required. Height of the resized image. See the description of resize for details.
quality	Optional. A value from 1 to 100 that indicates the quality of JPEG compression to use. Ignored in the case of an image that is not JPEG encoded.

Element Information

Parent Element	Child Elements
file	None

successpage

Defines the HTML page to display in the OPW after photos are successfully uploaded.

Syntax

<successpage
     href = "string"
>
          <!-- Text content is ignored by the OPW. --/>
</successpage>

Attributes

Attribute	Description
href	Required. URL of the success page.

Element Information

Parent Element	Child Elements
uploadinfo	None

transfermanifest

This is the root node of the transfer manifest.

Syntax

<transfermanifest
     <!-- Child elements --/>
     <filelist>
     <uploadinfo>
>
          <!-- Text content is ignored by the OPW. --/>
</transfermanifest>

Attributes

This element has no supported attributes.

Element Information

Parent Element	Child Elements
None. This is the root element.	filelist, uploadinfo

uploadinfo

Contains information from the site for the upload.

Syntax

<uploadinfo
     [friendlyname = "string"]
>
     <!-- Child elements --/>
     [<htmlui>]
     [<successpage>]
     [<cancelledpage>]
     [<failurepage>]
          <!-- Text content is ignored by the OPW. --/>

</uploadinfo>

Attributes

Attribute	Description
friendlyname	If an additional link is being provided on the client-side finish page that is displayed after a successful order, this will be the text displayed in the link. See Using the htmlui Element to Display a Link for an example.

Element Information

Parent Element	Child Elements
transfermanifest	cancelledpage, htmlui, failurepage, successpage