Component Error Example | Qt Installer Framework Manual

Qt Installer Framework Manual | Qt Installer Framework Examples | Component Error Example

# Component Error Example

Component Error demonstrates how to stop the installation and display error messages if one or several components cannot be installed.

## Configuring the Example Installer

The installer configuration file, config.xml, in the `config` directory specifies the text and default values used in the installer:

- The `<Name>` element specifies the application name that is added to the page name and introduction text.
- The `<Version>` element specifies the application version number.
- The `<Title>` element specifies the installer name displayed on the title bar.
- The `<Publisher>` element specifies the publisher of the software (as shown in the Windows Control Panel, for example).
- The `<StartMenuDir>` element specifies the name of the default program group for the product in the Windows Start menu.
- The `<TargetDir>` element specifies that the default target directory is located in the `IfwExamples` directory in the home directory of the current user (because the predefined variable`@HomeDir@` is used as a part of the value). For more information, see Predefined Variables.

      <?xml version="1.0" encoding="UTF-8"?>
      <Installer>
          <Name>Component Error Example</Name>
          <Version>1.0.0</Version>
          <Title>Component Error Example</Title>
          <Publisher>Qt-Project</Publisher>
          <StartMenuDir>Qt IFW Examples</StartMenuDir>
          <TargetDir>@HomeDir@/IfwExamples/componenterror</TargetDir>
      </Installer>

## Creating the Example Package Information File

The installer package information file, package.xml, in the `meta` directory specifies the components that are available for installation:

- The `<DisplayName>` element specifies the human-readable name of the component.
- The `<Description>` element specifies the human-readable description of the component.
- The `<Version>` element specifies the version number of the component.
- The `<ReleaseDate>` element specifies the date when this component version was released.

- The `<Script>` element specifies the file name of the JavaScript file that is loaded to perform operations.

      <?xml version="1.0"?>
      <Package>
          <DisplayName>Root Component</DisplayName>
          <Description>This component handles the errors in the other components.</Description>
          <Version>1.0.1</Version>
          <ReleaseDate>2013-08-21</ReleaseDate>
          <Script>installscript.js</Script>
      </Package>

This example attempts to install three components, so we create a package.xml file in each component directory: `root`, `root.component1`, and `root.component2` and specify the component name and description in each of them.

## Stopping the Installation on Errors

In installscript.js in the `root` directory, we call the `abortInstaller()` function to hide all the default installer pages and to display an error message if the components contain errors:

      function abortInstaller()
      {
          installer.setDefaultPageVisible(QInstaller.Introduction, false);
          installer.setDefaultPageVisible(QInstaller.TargetDirectory, false);
          installer.setDefaultPageVisible(QInstaller.ComponentSelection, false);
          installer.setDefaultPageVisible(QInstaller.ReadyForInstallation, false);
          installer.setDefaultPageVisible(QInstaller.StartMenuSelection, false);
          installer.setDefaultPageVisible(QInstaller.PerformInstallation, false);
          installer.setDefaultPageVisible(QInstaller.LicenseCheck, false);

          var abortText = "<font color='red' size=3>" + qsTr("Installation failed:") + "</font>";

          var error_list = installer.value("component_errors").split(";;;");
          abortText += "<ul>";
          // ignore the first empty one
          for (var i = 0; i < error_list.length; ++i) {
              if (error_list[i] !== "") {
                  console.log(error_list[i]);
                  abortText += "<li>" + error_list[i] + "</li>"
              }
          }
          abortText += "</ul>";
          installer.setValue("FinishedText", abortText);
      }

We use the `reactOnAbortInstallerChange()` signal to stop the installation if `ComponentError` is `true`:

      function reactOnAbortInstallerChange()
      {
          if (installer.value("ComponentError") === "true")
              abortInstaller();
      }

We use the `Component()` function to connect to the `reactOnAbortInstallerChange()` signal when the list of new root components has been updated:

      function Component()
      {
          installer.finishAllComponentsReset.connect(reactOnAbortInstallerChange);
      }

To open the page that displays the error message, we create fake errors by setting `ComponentError` to `true` in installscript.js in the `root.component1` and `root.component2` directories:

      function Component()
      {
          var error = true;
          if (error) {
              installer.setValue("component_errors", installer.value("component_errors") + ";;;"
                  + "Error in component: " + component.name);
          }
          installer.setValue("ComponentError", true);
      }

Each component adds a message to the `component_errors` variable. In your app, the `error` variable should return the results of a real check for an existing file or system feature.

## Generating the Example Installer

To create the example installer, switch to the example source directory on the command line and enter the following command:

- On Windows:

        ..\..\bin\binarycreator.exe -c config\config.xml -p packages installer.exe

- On Linux or OS X:

        ../../bin/binarycreator -c config/config.xml -p packages installer

The installer is created in the current directory.

Files:

- componenterror/config/config.xml
- componenterror/packages/root/meta/installscript.js
- componenterror/packages/root/meta/package.xml
- componenterror/packages/root.component1/meta/installscript.js
- componenterror/packages/root.component1/meta/package.xml
- componenterror/packages/root.component2/meta/installscript.js
- componenterror/packages/root.component2/meta/package.xml
- componenterror/componenterror.pro