Putting the “Wizard” in Wizard Pages

While InstallShield makes it easy to change the UI of your Suite project in small ways, such as editing the text on a wizard page, or moving a control by a few pixels, sometimes that’s not enough. Sometimes you need to add a new page to your wizard. There are three approaches you can take to adding a new page. I want to share them and tell you a way to make the third one even more powerful.

The Role of an Intern

The first way to add a page to the wizard is completely manually. In the Wizard Interface view, right-click the Wizard Pages node and select Add Blank Page. Set its title, turn on wizard buttons, add controls, and configure any additional settings to make the page do what you want.

If the new page you want is similar to one you have, either because you just created one of several similar pages, or because InstallShield already provided one that was close, you can copy and paste in the list of pages to clone a page into a new one.

The Role of a Development Tool

The second way to add a page is through copy and paste in the project file (.issuite). Cloning a wizard page in the IDE can work wonders. However it comes with one major limitation: you can clone a page only within the same project. So if you need to go between two projects, you can open the project in an XML editor to copy pages from one project to another. Look for the Page elements with the Name attributes matching the pages you want to copy. They appear in the same order that you saw the pages in the Wizard Interface view, so they should be easy to find. Copy entire Page elements (from <Page …> to </Page>) and paste them in your other project.

If the page you copy uses only strings that are provided by InstallShield, you’re done. However if it references any strings that you added yourself, you’ll probably see things like ID_STRING17 when you run your Suite. To fix this you may need to copy the string definitions too. You can find them under the Languages element, one copy of your string in an element of the string ID’s name, for each Language element.

The Role of an Architect

The third way to add a page to your wizard is by inserting it from the User Interface Wizard, which you access by right-clicking the Wizard Pages node and selecting Add Predefined Page…. InstallShield 2012 comes with six predefined pages that range from selecting a package’s INSTALLDIR to accepting a supplemental EULA. The Wizard asks you where to sequence the new page, and may ask one more question such as which package’s INSTALLDIR you want to change, or what EULA file you want to show.

But that’s not all. If you want to change how a page looks in most of your Suites, including some you’ve already created, you can create your own template page with these changes in place. Start by modifying the InstallationWelcome page’s layout to match what you want. For example, resize the labels to stretch the whole width, set the SS_CENTER Style on all the labels, and center the image above. Save the project, and go find its Page element, and copy it.

Then open <InstallShield>Support409SuiteTemplates.xml. This file contains definitions for all the templates shown in the wizard, in a format very similar to that in a project. Put in some boilerplate information, including a name and description for your new page template.

Paste your page definition inside the v:WizardPage element.

For simple pages, save it and you’re done. Now you can add your custom welcome page to any project; just remove the original and your Suite is ready to go.

For more complex pages, you can tell the User Interface Wizard to ask for a package or a file by including a Variable element with a Choose attribute of Parcel or File; see a template that uses those to figure out how they work. Note that references to variables need to be in attributes that have a v prefix on their attribute name, and the reference uses double hashes. Some variable names also receive several sub-variables. You can see most of this in the View and accept supplemental license agreement template (the remaining capabilities show up in the Browse for installation folder template):

Just remember that this is currently an implementation detail of InstallShield 2012. We expect to have to change the project’s XML format over time, and that will result in changes to the SuiteTemplates.xml format as well. If nothing else, expect the namespace to be updated, so be very careful about blindly copying any of your customizations of SuiteTemplates.xml to a new version of InstallShield.