Component
A Component defines a group of installation objects that must be installed or removed together. Typically, a component contains one or more files, plus any related installation objects. A component is installed if it's a top-level component or a descendant of one or more ancestor components that are selected for installation, subject to the component's Condition, Platforms, and Languages attributes (see below).
Components are not required; any installation object (file, folder, shortcut, registry value, etc.) that is not assigned to a component is installed or removed irrespective of any platform or language considerations.
Visible versus internal components
Components may be visible to the user, or they may be for internal use only.
- If a component has its Component is visible in UI option checked (see below), then it will be shown in any OptionTree control that is used in the installer's dialog pages; typically this will be the predefined OptionsDlg dialog box. The user can then select or unselect the component for installation.
- If a component does not have its Component is visible in UI option checked, then the component is not presented to the user. In that case the component's installation state is typically set through its Platforms, Languages, or Condition options (see below), or through an explicit Set Component State action.
Note that assembly-type components are never visible in the installer's user interface.
Component states
Each component has an associated state that determines if the component will be installed. The following states are available:
| State | Component is visible in UI | Component is not visible in UI | ||
|---|---|---|---|---|
| Unavailable |
|
The component is unavailable and will not be displayed in the installer's user interface. Note: This only applies if the component state is set before an OptionTree control is shown. If the component state changes to Unavailable while the control is present, the component will be shown as Disabled. |
  |
The component or assembly is not selected. |
| Disabled |   |
The component is displayed in the installer's user interface, but in a disabled state and cannot be selected by the user. | |
The component or assembly is not selected. |
| Not selected |   |
The component is displayed in the installer's user interface, but not selected. |   |
The component or assembly is not selected. |
| Selected |   |
The component is displayed and selected in the installer's user interface. | |
The component or assembly is selected. |
| Always selected |   |
The component is displayed and selected in the installer's user interface, and cannot be unselected. |   |
The component or assembly is selected. |
Component state during installation
During installation, the installer determines the actual component's state as follows.
- The initial state is based on the Initial state and If condition true fields that you define for the component in your InstallMate project, plus the Platforms, Language, and Condition fields as evaluated by the installer at runtime:
Platforms, Language Condition Component state Evaluate to FALSE ignored Set to Unavailable Evaluate to TRUE empty Set to value of Initial state field Evaluates to FALSE Set to value of Initial state field Evaluates to TRUE Set to value of If condition true field - If a previous version of the same product is already present on the target system, then its component states are loaded and applied to the components. This may override the states determined in step 1.
- If one or more $comp=state options are present on the installer's command line, then they are evaluated and may override in turn the results from the previous steps.
- If the the Component is visible in UI option is set (see below), then the user may change the component's state if at least one of the the installer's dialog boxes includes an OptionTree control. (The predefined OptionsDlg dialog box includes this control, for example.)
- Finally, any Set Component State actions that the installer encounters may further modify the component's state.
Component actions
After the component state is determined as documented above, the installer sets the component action based on the criteria shown in the following table.
| Current status | Component state | Action | |
|---|---|---|---|
| Not installed for this product | Hidden, Disabled, or Not selected | ignored | No action |
| No parent, or parent state is Selected or Always selected | Hidden, Disabled, or Not selected | No action | |
| Selected or Always selected | Install component | ||
| Installed for this product | Hidden, Disabled, or Not selected | ignored | Remove component |
| No parent, or parent state is Selected or Always selected | Hidden, Disabled, or Not selected | Remove component | |
| Selected or Always selected | Install (update) component |
*The effective parent state is the state that results from all the component's ancestors, starting from the top-most one.
Attributes
The following attributes and options are available.
| Attribute | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| Name | Enter the name of the component. This name is used to refer to the component in conditional expressions and symbolic expressions elsewhere in the project, but is not visible to the user. Each component must have a name that is unique within the project. | ||||||||
| Display title | Enter the name of the component for display in the installer's user interface OptionTree control. This only applies if the Component is visible in UI option is selected. | ||||||||
| Localized | Check this box to localize the Display title field and use different titles for different languages. | ||||||||
| Description | Enter the description of the component for display in the installer's user interface. This only applies if the Component is visible in UI option is selected. | ||||||||
| Localized | Check this box to localize the Description field and use different descriptions for different languages. | ||||||||
| Component is visible in UI |
Check this box to make the component visible and selectable in the installer's user interface, through the OptionTree control; clear the box to hide the component from view and use it internally only. | ||||||||
| Mutually exclusive subcomponents |
Check this box to configure the component's subcomponents as mutually exclusive; clear it for regular subcomponents. Mutually exclusive subcomponents appear as radio buttons instead of check boxes; only one mutually exclusive subcomponent can be selected at a time. | ||||||||
| Allow folder browsing |
Check this box to allow the user to select the folder path for the component's folder as defined by its Linked folder attribute; clear it to prevent folder browsing. This only applies if the Component is visible in UI option is selected. InstallMate implements folder browsing by linking an EditText control to the appropriate folder alias, optionally combined with a Browse for Folder Standard Dialog action. The control or dialog should be linked indirectly to the TsuFeatureFolderAlias variable to follow the currently selected feature in the OptionTree control, or linked directly to any other folder alias variable. The default OptionsDlg dialog box demonstrates this. |
||||||||
| Linked folder | Enter the folder alias of the installation folder that is associated with the component, or click ... (browse) to open the Select Installation Folder dialog box that allows you to select one. The path to this folder can be configured in the installer's user interface if you select the Allow folder browsing option. | ||||||||
| Initial state | Select the initial component state from the drop-down list. The available states are shown in the section Component states. In conjunction with the Condition field, this field determines the component's initial selection state during installation, as shown in Component states. If the Component is visible in UI option is checked, then the user may override this state. |
||||||||
| If condition true | Select the conditional component state from the drop-down list. The available states are shown in the section Component states. In conjunction with the Condition field, this field determines the component's conditional selection state during installation, as shown in Component states. If the Component is visible in UI option is checked, then the user may override this state. |
||||||||
| Condition | Enter a conditional expression that determines if the component will be installed according to Initial state or If condition true, or leave empty if the component must be installed according to Initial state. | ||||||||
| Platforms... | Click this button to open the Select Installation Platforms dialog box that allows you to select the Windows versions on which the component must be installed. This platform selection acts as a prerequisite for the component. See the section Component states for details. Note: Platform selection can occur during build time or installation time. When a Package is being built InstallMate will include or exclude components depending on the overlap between the component's Platforms selection and the package's build platforms. A BLD:Q0062 diagnostic message will be issued if a component is excluded based on the build platforms. Further platform selection may occur at installation time. |
||||||||
| Languages... | Click this button to open the Select Installation Languages dialog box that allows you to select the languages for which the component must be installed. This language selection acts as a prerequisite for the component. See the section Component states for details. Note: Language selection can occur during build time or installation time. When a Package is being built InstallMate will include or exclude components depending on the overlap between the component's Languages selection and the package's build language. A BLD:Q0063 diagnostic message will be issued if a component is excluded based on the build languages. Further language selection may occur at installation time (for multilingual installers). |
||||||||
| Extra size | Enter the additional installation size (in bytes) for the component, or leave empty if the option only installs what its components and subcomponents contain. This option is useful if you use the component as a user-selectable option that is used in custom actions to download, copy, or otherwise install additional files. Setting this option to the (approximate) additional installation size then helps the user and the installer to estimate the required total installation size. |
||||||||
| Build condition | Enter a conditional expression that determines if the component will be included in the build, or leave empty if the component must be included in all builds. The build condition is evaluated during the preflight test for each installation package; you can use the Build variables attribute in the Package pane to control if the component will be included for a particular installation package. If the condition evaluates to false, the component and all the installation objects that are controlled by it are excluded from the build process for the installation package. |
||||||||
| Packaging | Select the desired packaging option for the files that belong to the component. The packaging option that you select here overrides the packaging option from the package. The following choices are available:
|
||||||||
| Comment | Free-form text field in which you can enter annotations for the component. This field is not used by the installer; it is only intended for your own documentation. |