Component Error Example | Qt Installer Framework Documentation

- Qt Installer Framework Documentation
- Tutorials and Examples
- Component Error Example

# Component Error Example

Using a component script to stop the installation if the components cannot be installed.

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 sets the application name and adds it to the page name and introduction text.
- The `<Version>` element sets the application version number.
- The `<Title>` element sets the installer name and displays it on the title bar.
- The `<Publisher>` element sets the publisher of the software (as shown in the Windows Control Panel, for example).
- The `<StartMenuDir>` element sets the name of the default program group for the product in the Windows Start menu.
- The `<TargetDir>` element sets the default target directory location to be within the `IfwExamples` directory in the home directory of the current user (because it uses the pre-existing variable `,` @HomeDir@, as 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 sets the human-readable name of the component.
- The `<Description>` element sets the human-readable description of the component.
- The `<Version>` element sets the version number of the component.
- The `<ReleaseDate>` element sets the date of release for this component version.

- 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 macOS:

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

This creates the installer to the current directory.

Files:

- componenterror/componenterror.pro
- componenterror/config/config.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/packages/root/meta/installscript.js
- componenterror/packages/root/meta/package.xml