Windows HTML‐based wizards - atauenis/webone GitHub Wiki

Some Microsoft Windows components includes parts of user interface from online Internet services. This include shell wizards that interacting with third-party online services in Windows XP/2003 and up.

Wizards listed here are displaying most of steps from online service selected at start of the wizard. So, for example, the online service prompts users for options such as contact and payment information, in addition to file selection or other things.

WebOne with correct configuration can be utilized to add new (currently live) services via these wizards.

Table of contents:

Introduction

All wizards are connecting to a HTTP server (using MSIE engine) and downloading the wizard's HTML file. Then MSIE engine checks that it is a wizard, not a regular HTML page, by looking to its JS or VBS code. If the page looks as a wizard, it gets displayed in wizard window. If the page is not a wizard, system rejects it and an error gets displayed.

sample error

Each HTML wizard page must provide a handler for OnBack, OnNext, and OnCancel events. The OnNext handler will also handle the Finish event. A page that does not implement an OnBack function is considered invalid and will cause an error page to be displayed (res://shell32.dll/WebServiceError.htm). These events are fired when user clicking Back, Next (Finish) and Cancel buttons.

The programming of wizards is doing via JavaScript and Dynamic HTML. In addition to MSIE features, wizard pages can interact with wizard host window via window.external object.

For multilanguage support, Windows appends system language as HTTP query argument to URL of wizard.

Main MSDN page: https://learn.microsoft.com/en-us/windows/win32/lwef/pubwiz-client

Samples

Simple page

<html>
    <head>
        <script language="JavaScript">
            function window.onload()
            {
                window.external.SetWizardButtons(1, 0, 0);    
                <!-- Back button enabled -->
            }

            function window.onback()
            {
                window.external.FinalBack();
            }
        </script>
    </head>
    <body>Here is HTML body.</body>
</html>

Default error page

Source code of res://shell32.dll/WebServiceError.htm. Consider use it as template for wizard pages as it uses system color and font scheme.

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

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

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

    </script>
    </head>
    <body bgcolor=threedface>
        <font id=l1 face="Tahoma" size=2>
            <P id=l2>The wizard could not connect to the Internet, or the Web service returned a wizard page that is not valid.</P>
            <P id=l3>To try again, click Back.</P>
            <P id=l4>To close this wizard, click Cancel.</P>
        </font>
    </body>
</html>

Note: The error page looks a bit inconsistent in Windows Vista if Aero theme is enabled. It is need to use white background and Segoe UI font in case of non-Classic theme enabled, but the page code has not been updated.

JavaScript API

Main article: https://learn.microsoft.com/en-us/windows/win32/shell/webwizardhost

HTML wizard pages can interact with wizard host via JS/VBS methods from window.external object.

Method Description
Cancel() Simulates a Cancel button click.
FinalBack() Navigates to the client-side page immediately preceding the page hosting the server-side HTML pages.
FinalNext() Navigates to the client-side wizard page that follows the page that hosts the server-side HTML pages, or finishes the wizard if there are no further client-side pages.
SetHeaderText(...) Sets the title and subtitle that appear in the wizard header. In general, the client will display the header above the HTML and below the title bar.
SetWizardButtons(...) Updates the Back, Next, and Finish buttons in the client's wizard frame.
PassportAuthenticate(...) Enables server-side pages hosted in a wizard to verify that the user has been authenticated through a Microsoft account.

The methods have no arguments unless additionally said.

SetHeaderText

Sets the title and subtitle that appear in the wizard header. The wizard host window displays the header above the HTML box and below the title bar.

window.external.SetHeaderText(
  bstrHeaderTitle,
  bstrHeaderSubtitle
)

SetWizardButtons

Set state of the Back and Next/Finish buttons in the wizard host window. All arguments are boolean values.

window.external.SetWizardButtons(
  vbEnableBack,
  vbEnableNext,
  vbLastPage
)

vbLastPage enables the Finish button instead of Next. States that this is the last step page.

Be sure to implement handler functions in each server-side page for OnBack() and OnNext(), corresponding to the wizard buttons Back and Next. And on some appropriate time it is need to call SetWizardButtons with vbLastPage=true, which will enable the Finish button. Then clicking it also calls FinalNext and moving the wizard to exit step page.

PassportAuthenticate

In some cases it is possible to use .NET Passport authentication in wizards (via WebOne, Escargot accounts will be used instead).

window.external.PassportAuthenticate(
  bstrSignInUrl
)

bstrSignInUrl is a string containing the URL of a webpage that redirects to the Microsoft account log on UI. The method returns true if authentication succeeds, false otherwise. This method may be called even if a user is already logged on to a Microsoft account. In that case, the method returns true without displaying the Microsoft account log on UI.

Property

Also it is possible to read or set some properties of wizard host via JavaScript code:

Property = window.external.Property(bstrPropertyName)
window.external.Property = Property

Currently it is not known fully which properties can be accessed here.

Events

Wizard host window can produce events, which can be handled by JS code of the wizard: window.OnBack(), window.OnNext(), window.OnCancel().

.NET Passport Wizard

This is a wizard that helps user log in to or register a .NET Passport account. Later it were renamed to Windows Live ID, and now it is called Microsoft Account. The wizard is located in User Accounts control panel.

The wizard first attempts to connect to .NET Passport (aka Nexus) server for configuration data. Then it loads page specified in DAReg option (by default, https://register.passport.com/defaultwiz.asp) as a regular HTML-based wizard.

The wizard helped user to log in via Microsoft account (the login state is system-wide, at least in MSIE and Windows Messenger).

After successful end of wizard, the finish page shows .NET Passport user name. And, as the system goes to logged-on state, a Passport management UI of User Account control panel becomes enabled.

This wizard is Windows XP/2003-only. It can be launched via User Accounts control panel or via rundll32 netplwiz.dll,PassportWizardRunDll. However MSDN telling that it is limited to some service packs, in fact it is available from Windows XP RTM to fully updated POSReady 2009.

Web Publishing Wizard

This is a wizard, intended to integrate cloud file sharing services into Windows Explorer. When user clicked "Publish this folder to the Web" or "Publish this file to the Web" link in Windows XP Explorer sidebar, the wizard starts.

First it is downloading configuration file from http://shell.windows.com/publishwizard/usa.xml (or other country instead of usa, depending of Windows language settings). WebOne loads archived copy of USA file always.

In the downloaded manifest it looks to PublishingWizard scope of it, and displays available services. Also it's looking offline to HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\PublishingWizard\PublishingWizard\Providers registry keys for same info. When user chooses the service, its start page opens in the wizard window.

The HTML-based wizard can access information about files to upload via window.external.Property("TransferManifest") Msxml2.DOMDocument. Main article: https://learn.microsoft.com/en-us/windows/win32/shell/manifest-schema

After successful file upload, the page should call FinalNext() to exit the wizard.

shell-pubwiz-provs

This wizard is removed in Windows Vista.

Online Print Ordering Wizard

Other Windows shell wizard, designed to order JPEG file printing on photo paper. It is launching by click "Order prints online" link on XP's Explorer sidebar. On Windows Vista, 7 and up, the Windows Photo Gallery (Windows Photo Viewer) contains the feature in its toolbar menu. Also the dialog can be accessed from Windows Live Photo Gallery 2009/2011/2012 on all systems.

The wizard is designed like Web Publishing Wizard, and most of things are similar. The exception is that it loading list of services from InternetPhotoPrinting scope of configuration manifest.

Windows Photo Gallery on Vista is using http://shell.windows.com/publishwizard/vista/rus.xml. Windows Photo Viewer and Windows Live Photo Gallery on Windows 7 and up are using http://go.microsoft.com/fwlink/?LinkID=118706&Loc=RUS URL, which redirects to http://shell.windows.com/publishwizard/getopwproviderlist.asp?Loc=RUS (tested on Russian-localized system).

Add Network Place Wizard

It is a wizard which helps adding WebDAV-based cloud file sharing services into My Network Places (Network in Windows Vista) folder. Designed a bit similar to Web Publishing Wizard and Online Print Ordering Wizard, it is working with AddNetPlace scope of manifest.

Windows Vista is using same URL as XP (http://shell.windows.com/publishwizard/usa.xml), and Windows 7 is using http://shell.windows.com/publishwizard/Win7/usa.xml service list file.

Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️