We need you!

Icon

The IzPack documentation needs work, and you are invited to edit it!

Skip to end of metadata
Go to start of metadata

The <field> Element

Before we dive into the details of defining the various UI elements I would like to present XML elements and general concepts that apply throughout. This saves me a lot of work in writing and you a lot of repetitive reading and maybe a tree or two.

The UI elements are generally laid out top to bottom in the order they appear in the XML file. The only exception to this rule is the title, which always appears at the very top. The layout pattern for the input fields is as follows: If a description is defined, it appears first, using the full available layout width. The input field is placed beneath the description. With fields such as the text field or the combo box, the label is placed to the left and the input field to the right. Fields such as radio buttons and check boxes are somewhat indented and have the label text appear to their right.

Each UI element is specified with a <field> tag. The <field> tag has some common attributes: 

 

Name

Required

Description

Value

type

yes

Used to specify what kind of field you want to place.

Any valid field type

label_position

no

Used to change the default position of the label.

west, westonly, both, eastonly, east defatul: west

label_align

no

Used to change the default alignment of the label.

left, center, right default: left

label_indent

no

Controls whether or not the label is indented.

true, false default: false

control_position

no

Used to change the default position of the field's control.

west, westonly, both, eastonly, east default: east

control_align

no

Used to change the default alignment of the control.

left, center, right default: left

control_indent

no

Controls whether or not the control is indented.

true, false default: false

variable

yes, if input field

The variable that should be substituted with the user input.

A variable name.

conditionid

no

The ID of a condition in install.xml which must evaluate to true in order to display the field.

A valid condition id in install.xml.

tooltipnoThe ID of a string to be displayed as the tooltip for the GUI components in this field.The id of a string from langpacks.
omitFromAuto
noWhether to omit the field variable's value from being written to the auto-install.xml record initiated from the FinishPanel (if used).true, false default: false
displayHiddenno

Enables to "grey out" the field not matching its specific condition. Makes just sense if a conditionid has been defined.

Setting displayHidden attribute in the that specific field within the panel be shown regardless of what the field's conditionid evaluates to. But if the conditionid evaluates to false, display the field as disabled instead of hiding it.

 

Example of the displayHidden attribute  Expand source
true, false default: false

Examples

In the following example, the the label and the control will be shown on it's own row.

In the following example, the label is right aligned to the control.

Nested elements of <field>

The <description> Element

Almost all fields allow a description element (exception: directory and file chooser). The description is part of the data within the field element. There can only be one description per field. If you add more than one description, the first description is used and the others ignored. There are three attributes used with this tag. The text is specified through the txt or the id attribute. The details on using them are described below. The attributes are all optional but you must specify text to use, either directly or through the id attribute. In addition, you can set the text justification to leftcenter and right with the align attribute.

Name

Required

Description

Value

txt

yes, if no id

Specified the default text to use in absence of a language package.

Any text

id

yes, if no txt

Specifies text description through use of a language package.

A valid id

align

no

Sets the justification of the description.

left, center, right default: left

The following example illustrates the general pattern for field specification:

A very frequently used pattern is for the definition of text. Where ever text is needed (labels, descriptions, static text, choices etc.) it can be specified in place using the txt attribute. This is convenient if you are only supporting a single language. However, if you would like to separate your text definitions from the panel specification or if you need to support multiple languages you might want to use the id attribute instead to only specify an identifier. You can then add multiple XML files with the same name as this spec file (userInputSpec.xml) appended with an underscore '_' and the the appropriate three letter ISO3 language code. The content of those files must conform to the specification for IzPack language packages. For more details on this topic see the chapter on language packages under advanced features. id defines an identifier that is also defined in the language package, together with the localized text to use. It is possible to use both the txt and the id attribute. In this case the text from the language package is used. If for some reason the language package is not available or the id is not defined there, the text specified with txt is used as default.

All input fields can be pre-set with a value of your choice. Although the details vary a bit from field type to field type, the set attribute is always used to accomplish this. The set attribute is of course optional. Please note that if you use the set attribute, you would have to keep in mind, that the UserInputPanel will be rendered after each user input. Thus it will be set back to the default value if you don't use a condition to handle that. IzPack generates builtin conditions for every variable used as target for a field to be able to check if there's any input.

The <spec> Element

All fields that take user input use a <spec> tag to define the details of the input field. In the some cases the content of this tag is rather simple. Input fields with a more complex nature tend to have accordingly complex content in this tag. Since the details vary widely, they are explained with each input field.

Any number of <createForPack name=a pack name /> tags can be added to the <panel> and <field> sections. This tag has only one attribute and no data. The attribute is name and specifies the name of one of the installation packs that you have defined. Here is how it works: if no <createForPack ...> tag exists in a section, the entity is always created. However, if the tag exists, the entity is only created if one or more of the listed packs are selected for installation. As mentioned before, if you are using this feature, make sure the user input panel shows up after the packs panel.

Also, any number of <createForUnselectedPack name=a pack name /> tags can be added to the <panel> and <field> sections. This tag has only one attribute and no data. It works exactly like createForPack except that once added user input panel will appear for only NOT Selected packs. As mentioned earlier, you need to make sure that the user input panel shows up after the packs panel for this feature to work.

There is a possibility to use variables in those elements where the text is supplied via txt attribute. This includes static fields and input fields (spec, description). The text can contain unlimited number of variables that will be substituted. Variable substitution also works with language packs, just use variables in your language pack, and they will be still substituted properly.

Example

In the following example, the variables: name1, name2, name3 will be substituted.

Nested Constraints for Visibility

NameRequiredDescriptionValues
createForPacknoIf this tag is present the appropriate user input panel gets activated just if the mentioned pack is selected by the user in the PacksPanel.Valid pack names, see PacksPanel.
createForUnselectedPacknoIf this tag is present the appropriate user input panel gets activated just if the mentioned pack is selected by the user in the PacksPanel .Valid pack names, see PacksPanel.
osnoOperating system-specific constraints.Valid OS constraints, see OS Restrictions.
  • No labels