Scripts

All configurable beans on the Installer->Screens & Actions step have script properties that allow you to customize their behavior, such as executing some code when a button is clicked or a custom initialization of a text field. Also, control flow in the screen and action system is done with scripts and expressions.

Design-time JDK

By default, install4j uses the bundled JRE for compiling scripts up to the Java major version that install4j runs with itself. For JRE bundles with higher Java major versions, install4j uses the current JRE instead.

For special requirements, you can invoke "Settings->Java Editor Settings" in the script editor and select a different JDK for that purpose. The list of available design-time JDKs is saved globally for your entire install4j installation and not for the current project. The only information saved in your project is the name of the JDK configuration. In this way, you can bind a suitable JDK on other installations and on other platforms.

The design-time JDK is used for the following purposes:

The code editor

The Java code editor is shown for script properties on the Installer->Screens & Actions step for any configurable bean including screens, actions, form components and groups, or when you edit the code for static fields and methods on the Installer->Screens & Actions->Custom Code step.

The box above the text editor shows the available parameters as well as the required return type. If parameters or return type are classes - and not primitive types - they will be shown as hyperlinks. Clicking on such a hyperlink opens the Javadoc in the external browser.

To get more information on classes from the com.install4j.* packages, choose Help->Show API Documentation from the menu and read the help topic for the install4j API.

A number of packages can be used without using fully-qualified class names. Those packages are:

You can put a number of import statements as the first lines in the text area in order to avoid using fully qualified class names. For example: 

import java.awt.Color;
import java.awt.EventQueue;

EventQueue.invokeLater(() -> {
    JTextField textField = (JTextField)formEnvironment.getFormComponentById("123").getConfigurationObject();
    textField.setBackground(Color.RED);
});

If the gutter icon in the top right corner of the dialog is green, your script is going to compile unless you have disabled error analysis in the Java editor settings that are accessible in the menu of the script editor dialog.

In some situations, you may want to try the actual compilation. Choosing Code->Test Compile from the menu will compile the script and display any errors in a separate dialog. Saving your script with the OK button will not test the syntactic correctness of the script. When your install4j project is compiled, the script will also be compiled and errors will be reported.

Expressions or scripts

Java code properties can either be expressions or scripts. install4j automatically detects whether you have entered an expression or a script.

An expression does not have a trailing semicolon and evaluates to the required return type. For example: 

!context.isUnattended() && !context.isConsole()

The above example would work as the condition expression of an action and skip the action for unattended or console installations.

A script consists of a series of Java statements with a return statement of the required return type as the last statement. For example: 

if (!context.getBooleanVariable("enterDetails")) {
  context.goForward(2, true, true);
}
return true;

The above example would work as the validation expression of a screen. If the variable with name "enterDetails" is not set to true, it would skip two screens forward, checking the conditions of the target screen as well as executing the actions of the current screen.

Script parameters

The primary interface to interact with the installer or uninstaller is the context which is nearly always among the available parameters. The context provides information about the current installation and gives access to variables, screens, actions and other elements of the installation or uninstallation. The parameter is of type

Apart from the context, the available parameters include the action, screen or form component to which the Java code property belongs. If you know the implementation class, you can cast to it and modify the object as needed.

Many other useful static methods are also contained in the class com.install4j.api.Util, for example OS detection methods or methods to display messages in a way that works for all installer modes: 

if (Util.isMacOS()) {
    Util.showWarningMessage("This warning is only shown on macOS");
}

Editor features

The Java editor offers the following code assistance powered by the eclipse platform:

Key bindings

All key bindings in the Java code editor are configurable. The key map editor is displayed by choosing Settings->Key map from the menu in the Java code editor dialog. On macOS, that menu is shown as a "hamburger" menu on the right side of the tool bar.

The active key map controls all key bindings in the editor. By default, the [Default] key map is active. The default key map cannot be edited directly, to customize key bindings, you first have to copy it. Except for the default key map, the name of a key map can be edited by double-clicking on it.

When assigning new keystrokes or removing existing key strokes from a copied map, the changes to the base key map will be shown as "overridden" in the list of bindings. The key map editor also features search functionality for locating bindings as well a conflict resolution mechanism.

Key bindings are saved in the file $CONFIG_DIR/install4j/v9/editor_keymap.xml where $CONFIG_DIR is %USERPROFILE%\AppData\Local on Windows, $HOME/.config on Linux and $HOME/Library/Application Support on macOS. This file only exists if the default key map has been copied. When migrating an install4j installation to a different computer, you can copy this file.

Code gallery

The Java code editor offers a code gallery containing useful snippets that show you how to get started with using the install4j API. The code gallery is displayed with the "Code gallery" tool bar button in the script editor.

You can either copy a portion of the script with CTRL-C or click OK to insert the entire script at the current cursor position.

Not all code snippets are directly usable in the script that you are editing. Also, some script properties have special code snippets that are only shown for this property. If such code snippets exist, they are displayed in bold in a separate category with the name of the script property.

Installer variables and scripts

Screens, actions and form components are wired together with installer variables that can be set and retrieved with little code snippets that make use of the context parameter that is available for most scripts. Any object can be used as the value for a variable, for a condition you can use boolean values. In a "Run script" action, you could set a boolean variable like this: 

boolean myCondition = ...
context.setVariable("myCondition", myCondition);

Instead of calling setVariable in a "Run script" action, you can also use a "Set a variable" action where the return value of the script is saved to an installer variable.

Getting installer variables is done with the context.getVariable(String variableName) method. The convenience method context.getBooleanVariable(String variableName) makes it easier to check conditions and write them as expressions without a return value: 

context.getBooleanVariable("myCondition")

To use installer variables with a string value in text properties of actions, screens and form components, write them as ${installer:myVariableName} or use the variable selector button that inserts them with the correct syntax.