12. Installer Customization

## 12. Installer Customization

Installers created with InstallBuilder can be customized in a variety of ways, including language, size and other aspects which are described in the following sections.

### 12.1. Languages

InstallBuilder supports installations in multiple languages. The following table lists all of the available languages and their codes:

Supported Languages
code | language name
sq | Albanian
ar | Arabic
es_AR | Argentine Spanish
pt_BR | Brazilian Portuguese
bg | Bulgarian
ca | Catalan
hr | Croatian
cs | Czech
da | Danish
nl | Dutch
en | English
et | Estonian
fi | Finnish
fr | French
de | German
el | Greek
he | Hebrew
hu | Hungarian
it | Italian
ja | Japanese
ko | Korean
lv | Latvian
lt | Lithuanian
no | Norwegian
pl | Polish
pt | Portuguese
ro | Romanian
ru | Russian
sr | Serbian
zh_CN | Simplified Chinese
sk | Slovak
sl | Slovenian
es | Spanish
sv | Swedish
th | Thai
zh_TW | Traditional Chinese
tr | Turkish
va | Valencian
cy | Welsh

Right to left languages such as Arabic and Hebrew are currently only supported in InstallBuilder for Qt

By default, the language selection dialog is not displayed but it can be enabled just by modifying the `<allowLanguageSelection>` tag:

      <project>
         ...
         <allowLanguageSelection>1</allowLanguageSelection>
         ...
      </project>

By default, it will display both the English and the native version of the languages, as displayed in Figure 54. However it can also be configured to show just the English or the native version using the `<languageSelectionStyle>` project property, which allows: `default` (for both the English and the native version, Figure 54), `onlyNativeNames` (for the native representation of the language , Figure 55) and `onlyEnglishNames` (for just the English name, Figure 56)

      <project>
         ...
         <languageSelectionStyle>default</languageSelectionStyle>
         ...
      </project>

Figure 59. Default Language Selection

      <project>
         ...
         <languageSelectionStyle>onlyNativeNames</languageSelectionStyle>
         ...
      </project>

Figure 60. Native Only Language Selection

      <project>
         ...
         <languageSelectionStyle>onlyEnglishNames</languageSelectionStyle>
         ...
      </project>

Figure 61. English Only Language Selection

Out of all of the languages supported by InstallBuilder, you can configure which of them will be available in your installer using the `<allowedLanguages>` tag:

      <project>
         ...
         <allowedLanguages>en es ja</allowedLanguages>
         <defaultLanguage>es</defaultLanguage>
         ...
      </project>

The snippet above also uses the `<defaultLanguage>` tag to specify the default language to use. When enabling the language selection, this will be the selected item in the dialog and when the language selection is disabled, it will be automatically configured as the installation language.

Take into account that the `<defaultLanguage>` must be one of the allowed languages or it will be ignored, using the first allowed language instead.

You can also use the `installer-language` command line flag to overwrite the `<defaultLanguage>` setting. The allowed values will be those configured in `<allowedLanguages>`:

    $> sample-1.0-linux-installer.run --installer-language ja

#### Autodetecting the System Language

The `<defaultLanguage>` tag also allows a special code, `auto`, that will make the installer autodetect the system language and use it as the default language:

      <project>
         ...
         <defaultLanguage>auto</defaultLanguage>
         <allowedLanguages>de en es ja</allowedLanguages>
         ...
      </project>

If the autodetected language does not match any of the allowed languages configured using `<allowedLanguages>` (in case any was provided), the first language in the list will be used, `de` in the above example. If the `<allowedLanguages>` value was not specified or was set to empty, it will be ignored. In the event that the autodetected language is not supported by InstallBuilder, `en` will be used as the language.

You can also check which language was selected at runtime by accessing the built-in variable `${installation_language_code}`.

### 12.2. Changing Built-in Installer Text Strings

InstallBuilder allows customizing most of its built-in language strings using custom language files. These files are basically plain text files with an INI-style format. The keys are language string identifiers that will be shared among all languages (`database.title, database.explanation, database.description`). The values contain the corresponding text strings for each language (`Database Selection, Default database, Which database?`). For example, to modify the Welcome Page, you can create a new language file `custom-en.lng` with the strings to override the default ones:

Built-in strings in en.lng.

    ...
    Installer.Welcome.Title=Setup - %1$s
    Installer.Welcome.Text=Welcome to the %1$s Setup Wizard.
    ...

New custom-en.lng strings.

    Installer.Welcome.Title=Installation of %1$s
    Installer.Welcome.Text=This is the installer of %1$s.

You can then load the new file in your project:

    <customLanguageFileList>
       <language>
          <code>en</code>
          <file>path/to/custom-en.lng</file>
       </language>
    </customLanguageFileList>

You can download the complete list of tags or request the latest version by writing to us at `support@bitrock.com`. A copy of the language file is also included in all InstallBuilder installations inside the `docs` directory:

    $> /home/user/installbuilder-15.1.0/docs/userguide/en.lng

Please note that although the original file contains many other strings, you only need to specify those that need to be modified in your language file.

Some of the built-in strings contain special identifiers with names like `%1$s`. This refers to a value that will be automatically substituted at runtime by the installer (in most cases the full product name). Other common fields inserted in messages are filenames when the string is related to file manipulation actions or error information:

    ...
    Installer.Welcome.Text=This is the installer of %1$s.
    ...
    Installer.Error.Installation.CreatingDirectory=Error creating directory %1$s
    ...
    Installer.Error.PostInstallScript=Error executing post installation script\n%1$s\n\%2$s
    ...

The internally provided values for the identifiers cannot be modified but if you need to display different settings, you can just use regular InstallBuilder variables. For example, to include the short name and version instead of the full name in the previous string, you could rewrite your translation as:

    ...
    Installer.Welcome.Text=This is the installer of ${project.shortName}-${project.version}.
    ...

Or mix both:

    ...
    Installer.Welcome.Text=This is the installer of %1$s (${project.shortName}-${project.version}).
    ...

Where the above string will be resolved as: `This is the installer of Sample Installer (sample-1.0).`

#### Adding New Localized Strings

InstallBuilder includes complete language translations for all its built-in messages, but if you customize the installer with new screens or dialogs, you will need to add the strings to your custom language files. You will need to provide a custom language file for each of the languages supported by your installer:

custom-en.lng:

    database.title=Database Selection
    database.explanation=Default database
    database.description=Which database?

custom-es.lng:

    database.title=Selección de base de datos
    database.explanation=Base de datos por defecto
    database.description=Qué base de datos?

Once you have created a language file for each of your supported languages, you will need to load them from your XML project:

      <project>
         ...
         <customLanguageFileList>
           <language>
             <code>en</code>
             <encoding>iso8859-1</encoding>
             <file>path/to/custom-en.lng</file>
           </language>
           <language>
             <code>de</code>
             <encoding>iso8859-1</encoding>
             <file>path/to/custom-de.lng</file>
           </language>
           <language>
             <code>fr</code>
             <encoding>iso8859-1</encoding>
             <file>path/to/custom-fr.lng</file>
           </language>
         </customLanguageFileList>
         ...
      </project>

Please note that the language files are mapped to the desired language using the `<code>`. It is also very important to configure the `<encoding>` accordingly to your language files or you could end up with an unreadable translation.

Those language files will then be included in the installer at build time and the translated strings will be available at runtime using the `${msg()}` notation. The following example shows how the strings above can be used to localize a choice parameter:

    <choiceParameter>
       <ask>1</ask>
       <default>oracle</default>
       <description>${msg(database.description)}</description>
       <explanation>${msg(database.explanation)}</explanation>
       <title>${msg(database.title)}</title>
       <name>database</name>
       <optionList>
         <option>
           <value>oracle</value>
           <text>Oracle</text>
         </option>
         <option>
           <value>mysql</value>
           <text>Mysql</text>
         </option>
       </optionList>
    </choiceParameter>

#### Component-Level Translations

Components can also provide their own `<customLanguageFileList>`. The component-level language files will be processed after the main one (project level) and the keys there will overwrite the project-level ones. This feature allows you to share translations among multiple projects.

When a specific language is needed for a particular installer, you can add a translation component that will take care of redefining some of the language strings:

      <project>
         ...
         <customLanguageFileList>
           <language>
             <code>en</code>
             <encoding>iso8859-1</encoding>
             <file>path/to/custom-en.lng</file>
           </language>
         </customLanguageFileList>
         ...
         <componentList>
           <component>
              <name>translations</name>
              <show>0</show>
              <customLanguageFileList>
                <language>
                  <code>en</code>
                  <encoding>iso8859-1</encoding>
                 <file>path/to/alternative-custom-en.lng</file>
                </language>
              </customLanguageFileList>
           </component>
         </componentList>
         ...
      </project>

#### Displaying a Localized License and Readme

You can specify multiple localized versions for your `<licenseFile>` using the `<licenseFileList>` tag. Take into account that you still need to provide a value for the `<licenseFile>` tag to make the installer show the license page. This `<licenseFile>` will be also used as the default license file in case there’s no localized license file for the current language.

Inside this tag, you can add as many `<licenseFile>` elements as localized licenses you provide. For each `<licenseFile>` element, you’ll need to provide the license file path, its language identifier and the file encoding.

Here’s an example of how it works:

    <licenseFileList>
       <licenseFile>
         <code>en</code>
         <file>/home/user/license-english.txt</file>
         <encoding>iso8859-1</encoding>
       </licenseFile>
       <licenseFile>
         <code>ja</code>
         <file>/home/user/license-japanese.txt</file>
         <encoding>utf-8</encoding>
       </licenseFile>
    </licenseFileList>

The installer will pick the right license file depending on the current selected language for the installer.

If you need to display more than one license page, or simply to make them display conditionally, you can use a `<licenseParameter>`:

    <licenseParameter>
        <name>myLicense</name>
        <title>License Agreement</title>
        <description>Please read the following License Agreement. You must accept
        the terms of this agreement before continuing with the installation.</description>
        <explanation></explanation>
        <file>some/default/license.txt</file>
        <htmlFile>some/default/license.html</htmlFile>
        <licenseFileList>
          <licenseFile>
            <code>en</code>
            <file>/home/user/license-english.txt</file>
            <htmlFile>/home/user/license-english.html</htmlFile>
            <encoding>iso8859-1</encoding>
          </licenseFile>
          <licenseFile>
            <code>ja</code>
            <htmlFile>/home/user/license-japanese.html</htmlFile>
            <file>/home/user/license-japanese.txt</file>
            <encoding>utf-8</encoding>
          </licenseFile>
        </licenseFileList>
    </licenseParameter>

You can do a similar arrangement with readme files and the `<readmeFileList>` tag:

    <readmeFileList>
      <readmeFile>
        <code>en</code>
        <file>/home/user/readme-english.txt</file>
        <encoding>iso8859-1</encoding>
      </readmeFile>
      <readmeFile>
        <code>ja</code>
        <file>/home/user/readme-japanese.txt</file>
        <encoding>utf-8</encoding>
      </readmeFile>
    </readmeFileList>

Providing a main `<readmeFile>` at the `<project>` level is required to enable the readme file. This `<readmeFile>` will be used as the default readme file in case there’s no localized readme file for the current language.

Even if the installer provides a project level `<licenseFileList>`, the license page won’t be displayed if a value is not provided to the `<licenseFile>`, the default license file will display if the localized license for the current language was not provided. The `<readmeFile>` follows the same rule. If a value is not provided for the default readme file, no readme will be displayed, despite of the value of the `<readmeFileList>`. The `<readmeFile>` will also be used if a localized readme was not provided for the current language.

| HTML license and readme files in Qt mode
Both the main license file (using the `<htmlLicenseFile>`) and the `<licenseParameter>` are capable of displaying html files in `qt` mode. As they are only allowed in `qt` mode, you still have to provide a regular `<file>`:
    <project>
       <shortName>sample</shortName>
       <fullName>Sample Project</fullName>
       <version>1.0</version>
       <installerFilename></installerFilename>
       <licenseFile>some/default-license.txt</licenseFile>
       <htmlLicenseFile>some/default-license.html</htmlLicenseFile>
       ...
       <licenseFileList>
          <licenseFile code="de" file="main-license_de.txt" htmlFile="main-license_de.html"/>
          <licenseFile code="en" file="main-license_en.txt" htmlFile="main-license_en.html"/>
          <licenseFile code="es" file="main-license_es.txt" htmlFile="main-license_es.html"/>
       </licenseFileList>
       ...
       <parameterList>
         <licenseParameter>
           <name>otherLicense</name>
           <title>Other License Agreement</title>
           <file>some/default/other-license.txt</file>
           <htmlFile>some/default/other-license.html</htmlFile>
           <licenseFileList>
              <licenseFile code="de" file="other-license_de.txt" htmlFile="other-license_de.html"/>
              <licenseFile code="en" file="other-license_en.txt" htmlFile="other-license_en.html"/>
              <licenseFile code="es" file="other-license_es.txt" htmlFile="other-license_es.html"/>
           </licenseFileList>
         </licenseParameter>
       </parameterList>
       ...
    </project>
Although the `<readmeFile>` cannot display HTML text, you could use an `<infoParameter>` instead:
    <infoParameter>
      <name>readme</name>
      <title>Readme</title>
      <explanation>Readme</explanation>
      <value>${textValue}</value>
      <htmlValue>${htmlValue}</htmlValue>
       <preShowPageActionList>
         <readFile>
            <path>${installdir}/readme.html</path>
            <name>htmlValue</name>
         </readFile>
         <readFile>
            <path>${installdir}/readme.txt</path>
            <name>textValue</name>
         </readFile>
       </preShowPageActionList>
    </infoParameter>

### 12.3. Images

InstallBuilder provide default images for all the generated installers but you can also configure them. All images need to be provided in PNG format except for:

- Windows installer and uninstaller icons (which must be provided in ICO format)
- OS X installer and uninstaller icons (which must be provided in ICNS format)

#### Splash Screen

It is possible to configure the splash screen image and the time while it will be displayed:

    <project>
       ...
       <splashImage>path/to/mySplash.png</splashImage>
       <!-- Additional delay in milliseconds -->
       <splashScreenDelay>3000</splashScreenDelay>
       ...
    </project>

The splash image will be displayed for an additional 3 seconds (in addition to the built-in delay of 1 second).

The splash screen can be also disabled using the `<disableSplashScreen>` setting:

    <project>
       ...
       <disableSplashScreen>1</disableSplashScreen>
       ...
    </project>

Figure 62. Splash Screen

#### Left and Top Images

It is possible to configure the images that will appear on the left side and the top right corner of the wizard UI, as shown below:

    <project>
       ...
       <style>standard</style>
       <logoImage>path/to/topImage.png</logoImage>
       <leftImage>path/to/leftImage.png</leftImage>
       ...
    </project>

The layout of the installer pages and when the left and top images are displayed depends on the `<style>` configured in the project.

InstallBuilder supports two display styles:

- Standard Style:

In the standard style, the left image is displayed in the welcome and the final page and the top image is displayed in all the parameter pages and the readytoinstall page. The installation page will also display the top image if no slideshow images were configured or the slideshow if they were.

    <project>
       ...
       <style>standard</style>
       ...
    </project>

- Custom Style:

When using the `custom` style, no top right image is displayed and all of the pages will show the left image. Parameter pages can configure the left image displayed through their `<leftImage>` property:

    <project>
       ...
       <style>custom</style>
       ...
       <parameterList>
          <directoryParameter>
             <name>installdir</name>
             <description>Installer.Parameter.installdir.description</description>
             ...
             <leftImage>path/to/installdir_image.png</leftImage>
             ...
          </directoryParameter>
       </parameterList>
       ...
    </project>

Figure 63. Custom Style Welcome

Figure 64. Custom Style Parameter Page

Figure 65. Custom Style Ready to Install

Figure 66. Custom Style Installation Page

Figure 67. Custom Style Installation Finished

The installation page will also display the project level left image if no slideshow images were configured or the slideshow if they were.

    <project>
       ...
       <style>custom</style>
       ...
    </project>

#### Windows specific images

##### Windows Icons

Windows icons are also customizable for both the installer and the uninstaller. InstallBuilder expects an ICO file containing the below images:

- 64 x 64 pixels, 32bpp (16.7 million Colors)
- 48 x 48 pixels, 32bpp (16.7 million Colors)
- 32 x 32 pixels, 32bpp (16.7 million Colors)
- 24 x 24 pixels, 32bpp (16.7 million Colors)
- 16 x 16 pixels, 32bpp (16.7 million Colors)
- 48 x 48 pixels, 8bpp (256 Colors)
- 32 x 32 pixels, 8bpp (256 Colors)
- 16 x 16 pixels, 8bpp (256 Colors)

Although some of them can be skipped, you must at least provide the following sizes:

- 48 x 48 pixels, 32bpp (16.7 million Colors) or 8bpp (256 Colors)
- 32 x 32 pixels, 32bpp (16.7 million Colors) or 8bpp (256 Colors)
- 16 x 16 pixels, 32bpp (16.7 million Colors) or 8bpp (256 Colors)

If your icon file contains any additional images (such as a 256x256 image), they will just be ignored.

Those icons must then be configured in your project:

    <project>
       ...
       <windowsExecutableIcon>path/to/installer.ico</windowsExecutableIcon>
       <windowsUninstallerExecutableIcon>path/to/uninstaller.ico</windowsUninstallerExecutableIcon>
       ...
    </project>

If the uninstaller icon is not configured explicitly, the installer icon will be used instead. Similarly, if no installer icon is specified, the default InstallBuilder icon will be used.

The locations specified in the `<windowsExecutableIcon>` and `<windowsUninstallerExecutableIcon>` refer to files in the build machine.

##### Other Windows images

Apart from the installer and uninstaller icons, you can also provide images for other settings:

- Add/Remove Programs Menu Icon: This icon is configured through the `<productDisplayIcon>` tag and will be displayed in the ARP menu in addition to your application details. The icon is configured at runtime so the provided location must point to a file in the target machine, in most of the cases, installed by your application:

    <project>
       ...
       <!-- Path in the target machine -->
       <productDisplayIcon>${installdir}/icons/arp.ico</productDisplayIcon>
       ...
       <componentList>
         <component>
            <name>windowsComponent</name>
            <folderList>
              <folder>
                <name>icons</name>
                 <destination>${installdir}</destination>
                   <distributionFileList>
                      <!-- Directory containing arp.ico icon -->
                      <distributionDirectory origin="/path/to/icons"/>
                   </distributionFileList>
              </folder>
            </folderList>
         </component>
       </componentList>
    </project>

- Shortcuts icons: When creating shortcuts to executables on Windows, the icon of the application will be used. If the shortcut points to a different file-type such as a `.txt` or `.bat` file, the icon of the associated program will be displayed. Of course, you can also provide your own custom icon:

     <createShortcuts>
        <destination>${windows_folder_startmenu}/${project.fullName}</destination>
        <shortcutList>
          <shortcut>
            <comment>Launches ${project.fullName}</comment>
            <name>Launch ${project.fullName}</name>
            <windowsIcon>${installdir}/icons/custom.ico</windowsIcon>
            <windowsExec>${installdir}/myApp.exe</windowsExec>
          </shortcut>
        </shortcutList>
      </createShortcuts>

The `<windowsIcon>` tag can also point to an executable. In that case, the icon of the referenced binary will be used. For example, to configure you `.bat` files to look like a `cmd` prompt:

     <createShortcuts>
        <destination>${windows_folder_startmenu}/${project.fullName}</destination>
        <shortcutList>
          <shortcut>
            <comment>Launches ${project.fullName}</comment>
            <name>Launch ${project.fullName}</name>
            <windowsIcon>%SystemRoot%\system32\cmd.exe</windowsIcon>
            <windowsExec>${installdir}/script/wrapped-shell.bat</windowsExec>
          </shortcut>
        </shortcutList>
      </createShortcuts>

#### OS X Icons

Similarly to Windows, OS X installer and uninstaller application bundles can also include custom icons, provided using the `<osxApplicationBundleIcon>` and `<osxUninstallerApplicationBundleIcon>` project properties:

    <project>
       ...
       <osxApplicationBundleIcon>path/to/Bundle.icns</osxApplicationBundleIcon>
       <osxUninstallerApplicationBundleIcon>path/to/UninstallerBundle.icns</osxUninstallerApplicationBundleIcon>
       ...
    </project>

InstallBuilder will check if the provided icons are valid .icns files and will throw an error if the check fails. In addition, you must take into account the required icons in your .icns file as described in the Apple guidelines. At a minimum, the icon bundle must contain the following sizes:

- 512 x 512 pixels (For finder icons in OS X 10.5 and later)
- 128 x 128 pixels
- 32 x 32 pixels
- 16 x 16 pixels

#### Other images

##### Window Manager Image

The `<wmImage>` tag expects a `48x48 GIF` or `PNG` logo image that will be shown in the window manager task bar. On Windows and OS X, when running in Qt mode, it will also be used as the window icon (displayed in the window title bar). On Windows, in modes other than Qt, the window icon will be obtained from the 16pixel image included in the executable.

If a `<wmImage>` is not provided, a default image is displayed.

      <project>
        ...
        <wmImage>path/in/the/build/machine/logo.png</wmImage>
        ...
      </project>

##### Slide Show Images

InstallBuilder allows displaying a slide show while the files are being copied. This is really useful to show your application features or promote other products or services from your company. Each slide is represented by a `500x222 GIF` or `PNG` image configured using a `<slideShowImage>` element:

      <project>
        ...
        <slideShowImageList>
           <slideShowImage>
              <path>path/to/image1.png</path>
           </slideShowImage>
           <slideShowImage>
              <path>path/to/image2.png</path>
           </slideShowImage>
           <slideShowImage>
              <path>path/to/image3.png</path>
           </slideShowImage>
        </slideShowImageList>
        ...
      </project>

Where the paths to the images correspond to where they are located at build time.

The behavior of the slide show can be configured to continuously loop during the installation (through the `<slideShowLoop>` tag) or not. The number of seconds that each image will be displayed can be also defined (specified in the `<slideShowTiming>` tag). For example, if you want to display 5 slides without repeating them with 10 seconds for each of them, you can use:

      <project>
        ...
        <slideShowLoop>0</slideShowLoop>
        <slideShowTiming>10</slideShowTiming>
        <slideShowImageList>
           <slideShowImage>
              <path>path/to/feature1.png</path>
           </slideShowImage>
           <slideShowImage>
              <path>path/to/feature2.png</path>
           </slideShowImage>
           <slideShowImage>
              <path>path/to/feature3.png</path>
           </slideShowImage>
           <slideShowImage>
              <path>path/to/feature4.png</path>
           </slideShowImage>
           <slideShowImage>
              <path>path/to/feature5.png</path>
           </slideShowImage>
        </slideShowImageList>
        ...
      </project>

##### Label Parameter Images

It is also possible to display images in custom parameter pages using a `<labelParameter>`, which allows providing an image in its `<image>` tag:

    <parameterGroup>
        <name>autoupdate</name>
        <title>AutoUpdate</title>
        <orientation>horizontal</orientation>
        <parameterList>
            <labelParameter>
                <name>autoUpdateImage</name>
                <image>/path/to/autoupdate.png</image>
            </labelParameter>
            <booleanParameter>
                <name>includeAutoUpdate</name>
                <description>Install AutoUpdate</description>
                <default>1</default>
                <displayStyle>radiobuttons</displayStyle>
            </booleanParameter>
        </parameterList>
    </parameterGroup>

Figure 68. Image in a Label Parameter

##### Option Images

It is also possible to add images to the `<option>` elements used in a `<choiceParameter>`:

    <choiceParameter>
       <name>dbmsserver</name>
       <description>DBMS</description>
       <explanation>Database server</explanation>
       <allowEmptyValue>1</allowEmptyValue>
       <displayType>combobox</displayType>
       <optionList>
         <option>
           <description>MySQL server</description>
           <text>MySQL</text>
           <value>mysql</value>
           <image>${build_project_directory}/img/mysql-logo.png</image>
         </option>
         <option>
           <description>PostgreSQL server</description>
           <text>PostgreSQL</text>
           <value>postgres</value>
           <image>${build_project_directory}/img/postgresql-logo.png</image>
         </option>
       </optionList>
    </choiceParameter>

#### Recommended Image Sizes

Although InstallBuilder will try to accommodate the layout of the pages to any image size, there are recommended sizes for some of them. The table below summarizes those sizes:

Table 4. Recommended image sizes

Image | Width | Height
--- | --- | ---
Left panel image (`<leftImage>`) | 163 pixels | 314 pixels
Top right image (`<logoImage>`) | 48 pixels | 48 pixels
SlideShow image (`<slideShowImage>`) | 500 pixels | 222 pixels
Splash screen (`<splashImage>`) | 300-350 pixels | 100-150 pixels

11. Menus and Shortcuts |  | 13. Running the Installer