Extensions

## Extensions |

### 1. Introduction

All standard actions, screens and form components in install4j use the installer API themselves. With this API you can create new elements that are displayed in the standard registries by packaging a JAR file with a few special manifest entries and putting that JAR file into the `extensions` directory of your install4j installation.

### 2. Configurability

An extension to install4j will likely need to be configurable by the user. install4j uses the JavaBean specification to control the user presentation of properties in the install4j IDE. Screens, actions, and form components correspond to beans in this context.

Optionally, you can add BeanInfo classes. In essence, a BeanInfo class next to the bean itself describes which properties are editable and optionally gives details on how they should be presented. Please see the documentation of the com.install4j.api.beaninfo package for the complete documentation on how to develop BeanInfo classes. Also, the `$INSTALL4J_HOME/samples/customCode/src` directory contains a sample action with the associated BeanInfo class.

### 3. JAR manifest

In order to tell install4j which classes are screens, actions or form components, you have to use the following manifest keys:

- Install-Action
  for actions implementing `com.install4j.api.actions.InstallAction`
- Uninstall-Action
  for actions implementing `com.install4j.api.actions.UninstallAction`
- Installer-Screen
  for screens implementing `com.install4j.api.screens.InstallerScreen`
- Uninstaller-Screen
  for screens implementing `com.install4j.api.screens.UninstallerScreen`
- Form-Component
  for screens implementing `com.install4j.api.formcomponents.FormComponent`

Please note that usually you do not implement these interfaces yourself, but rather extend one of the abstract base classes.

A typical manifest with one action and one screen looks like this:

          Depends-On: driver.jar common.jar

          Name: com/mycorp/actions/MyAction.class
          Install-Action: true

          Name: com/mycorp/screens/MyScreen.class
          Installer-Screen: true
          Uninstaller-Screen: true

Note: If you only have named sections and no global section in your manifest file, the first line must be an empty line since it separates the global keys from the named sections.

The `Depends-On` manifest key can specify a number of relative JAR files separated by spaces that must be included when the extension is deployed. That key can also occur separately for each named section.

As you see in the example for the screen, each class can have multiple keys if the appropriate interfaces are implemented.

### 4. Localization

Extensions can provide localized messages. During development, you can keep these messages in the custom localization file of the project that you use for testing purposes. When packaging the extensions, these custom localization files have to be given special names and be put into a particular location in the extension JAR file.

The names of the extension localization files have to be the same as those of the system localization files in the `$INSTALL4J_HOME/resource/messages` directory, i.e. `messages_en.utf8` and similarly for other languages. Note that only UTF-8 encoding is supported for extension localization files, the java.util.Properties file encoding is not supported in this case.

When creating the extension JAR file, all extension localization files have to be put into the directory `messages`. No special directives in the manifest are required. Dependencies included with the `Depends-On` manifest key are not scanned for extension localization files.

### 5. Extension deployment

On startup, install4j will scan the manifests of all JAR files that it finds in the `$INSTALL4J_HOME/extensions` directory. Any screens, actions or form components that are found in the manifests are added to the standard registries. If a bean cannot be instantiated, the exception is printed to stderr which is captured in `$INSTALL4J_HOME/bin/error.log` and no further error is displayed.

If any of those screens, actions or form components are selected by the user, the required JAR files are deployed with the generated installers. This means that installing extensions does not create an overhead for installers that do not use them.