Screens and Actions



1. Introduction

With screens and actions you configure two separate aspects of the installer: the user interface that is displayed by your installer and uninstaller and the actual installation and uninstallation. Every screen can have a list of actions attached that are executed when the user advances to the next screen. install4j offers a wide variety of pre-defined screens and actions that you can arrange according to your needs. Some of these screens and actions are quite generic and can be used as programming elements, such as the "Configurable form" screen and the "Run script" action.

2. Control flow

At runtime, install4j instantiates all screens and actions and organizes the screen flow and action execution. There are a number of aspects regarding this control flow that you can customize in the install4j IDE. Both screens and actions have an optional "Condition expression" property that can be used to conditionally show screens and execute actions. Screens have a "Validation expression" property that is invoked when the user clicks on the "Next" button allowing you to check whether the user input is valid and whether to advance to the next screen. These are the most commonly used hooks in the control flow for "programming" the installer. All "expression" properties in install4j can be simple Java expressions or scripts of Java code as described on the help page for the Java code dialog.

If you use a series of screens to query information from the user, the users expect to be able to go back to previous screens in order to review or change their input. This is fine as long as no actions are attached to the screen. When actions have been executed, the questions is what should happen if the user goes back to a screen with actions and clicks on "Next" again. By default, install4j executes actions only once, but that may not be what you want, if they operate on the user input in a screen. Since install4j has no way of knowing what should happen in this case, it applies a "Safe back button" policy by default: if the previous screen had actions attached, the back button is not visible. You can change this policy for each screen, either making the back button always visible or always hidden. The "Can be executed multiple times" property of each action is relevant in the case where you you make the back button always visible for the next screen.

Another hook into the control flow is the ability to declare every screen as a "Finish" screen, i.e. the "Next" button will be replaced with a "Finish" button and the installer will quit after that button is pressed. Consider to use a "banner" screen in that case since it alerts the user that a special screen has been reached.

3. Rollback behavior

At any time in the installation sequence the user can hit the "Cancel" button. The only exception in the standard screens is a customizable progress screen where the "Cancel" button has been disabled. install4j is able to completely roll back any modification performed by its standard actions. However, the expectation of a user might not be that the installation is rolled back. Consider a series of post-installation screens that the user doesn't feel like filling out. Depending on the installer, the user might feel that installation will work even if the installer is cancelled at that point. A complete rollback would then irritate the user. That's why install4j has the concept of a "rollback barrier". Any action or screen can be a rollback barrier which means that any actions before and including that action or screen will not be rolled back if the user cancels later on.

Be default, only the "Installation screen" is a rollback barrier. This means that if the user cancels while the installation is running, everything is rolled back. If the user cancels on any of the following screens, nothing that was performed on or before the installation screen is rolled back. With the "Rollback barrier" property of actions and screens you can make this behavior more fine-grained and customize it according to your own needs.

4. Error handling

Every action has two possible outcomes: failure or success. If an action succeeds the next action is invoked. When the last action of a screen is reached, the next screen is displayed. What should happen if an action doesn't succeed? This depends on how important the action is to your installation. If your application will not be able to run without the successful execution of this action, the installer should fail and initiate a rollback. However, many actions are of peripheral importance, such as the creation of a desktop link. Declaring that the installer has failed because a desktop link could not be created and rolling back the entire installation would be counterproductive. That's why the failure of an action is ignored by install4j by default. If a possible failure of an action is critical, you can configure its "Failure strategy" to either ask the user on whether to continue or to quit immediately.

Standard actions in install4j fail silently, i.e. the "Create a desktop link" action will not display an error message if the link could not be created. For all available failure strategies, you can configure an error message that is displayed in the case of failure. The "Install files" action has its own, more granular failure handling mechanism that is automatically invoked after the installation of each file.

5. Standard and customizable screens

install4j offers a series of standard screens that are fully localized and serve a specific purpose. These standard screens have a preferred order, when you insert such a screen it will insert itself automatically in the correct position. This order is not mandated, you can re-order the screens in any way you like, however they may not yield the desired result anymore. If for example you place the "Services" screen after the screen with the "Install service" actions (typically the "Installation" screen), the "Services" screen will not be able to modify the service installations anymore and the default values are used.

The customizable screens don't have a fully defined purpose, their messages are configurable and empty by default. For example the "Display progress" screen is similar to the "Installation" screen, however the title and the subtitle are configurable. Customizable screens also do not have any restriction with respect to how many times they can occur. While the "Installation" screen (and other screens) can occur only once for an installer, the "Display progress" screen could be used multiple times.

The "Welcome" and "Finish" screens have a special layout that is called "banner screen" in install4j. There are customizable banner screens to help you reproduce this layout if you require it in a different context. The most flexible of all customizable screens are the "configurable form" screens. They allow you to freely define the contents of a screen and are described in a separate help topic.