Fields

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

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.
readonlyno

The readonly attribute reverses the displayHidden logic described below - readonly="true" means to display a field read-only in general in case it is not disabled by a general field condition.

Example of the readonly field attribute
<panel id="panel.dbsettings">
  <field ... readonly="true">
  </field>
...
</panel>

true, false

default: false

readonlyConditionno

The readonlyCondition attribute enhances and replaces the readonly condition and makes the related behavior dependent on another condition. Thus, the related field gets displayed read-only only if it is not disabled by a general field condition and the condition defined by readonlyCondition gets true.

Example of the readonlyCondition field attribute
<panel id="panel.dbsettings" >
  <field ... readonlyCondition="isReadOnlyField">
  </field>
...
</panel>

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 field attribute
<panel id="a.panel">
	<field type="check" variable="b" conditionid="b.cond" displayHidden="true">
    	<spec id="b.id" true="true" false="false"/>
	</field>
	<field type="check" variable="c" conditionid="c.cond">
	    <spec id="c.id" true="true" false="false"/>
	</field>
<panel>

true, false

default: false

displayHiddenConditionno

The displayHiddenCondition attribute enhances and is an alternative to the displayHidden condition and makes the related behavior dependent on another condition. Thus, the related field gets displayed read-only only if a general condition on that field disables it for displaying and the condition defined by displayHiddenCondition gets true.

Example of the displayHiddenCondition field attribute
<panel id="b.panel">
	<field type="check" variable="b" conditionid="b.cond" displayHiddenCondition="isDisplayHiddenField">
    	<spec id="b.id" true="true" false="false"/>
	</field>
	<field type="check" variable="c" conditionid="c.cond">
	    <spec id="c.id" true="true" false="false"/>
	</field>
<panel>

true, false

default: false

summaryKeynoId of a string that represents what name to display in the SummaryPanel of the UserInputPanel for this field. This attribute must be defined if you would like to summarize information about the user input made in this field in the SummaryPanel. Note that you will have to add the summaryKey attribute to the panel element itself also if you would like those to show up the field information in the SummaryPanel as well.

Examples

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

<field type="text" variable="value1">
  <spec txt="The label" id="" size="20" set="default value overriding current values of 'value1'" label_both="both" control_position="both" />
</field>

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

<field type="text" variable="value1">
  <spec txt="The label" id="" size="20" set="default value overriding current values of 'value1'" label_align="right" />
</field>

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.

text - any text as fallback for missing translations

id

yes, if no txt

Unique identifier, used for finding field description translations

text - a valid translation id

The following example illustrates the general pattern for field specification:

<field type="text" variable="myFirstVariable">
  <description id="description1" txt="A description"/>
  ...
</field>

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.

Attributes of the <spec> element:

Attribute

Description

RequiredPossible ValuesDefault Value
idUnique identifier, used for finding field label translations.yes
(if txt not defined)
any string-
txtDefault label text, overridden by existing translations.yes
(if
id not defined)
any string-
sizeField size in characters for all text edit fields.nopositive integer-
setThe set attribute forces the contents of the field whenever the panel is reached during navigating, even if the user has chosen a different value when the panel already appeared before.
Variable references in the attribute's value are dynamically resolved during an installation.
notrue | false(the current variable value is used if defined)
defaultThe default attribute is the default for the contents of the field whenever the panel is reached during navigating, in case the underlying field variable is not defined during an installation at this state.
Variable references in the attribute's value are dynamically resolved during an installation.
notrue | false(the current variable value is used if defined) 
omitFromAuto

Whether to omit the field variable's value from being written to the auto-install.xml record initiated from the FinishPanel (if used).

<field type="password" variable="sql.password">
    <spec omitFromAuto="false">
        <pwd txt="Password:" size="20" />
    </spec>
</field>

notrue | falsetrue for "password" fields, otherwise false


Example

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

<field type="text" variable="value1">
  <description id="value1.description" txt="Configuration for $name1 and $name2"/>
  <spec txt="The value for $name3:" id="" size="20" set="default value" />
</field>

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.