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: 

<panel id="panel.dbsettings">
  <field ... readonly="true">
  </field>
...
</panel>

<panel id="panel.dbsettings" >
  <field ... readonlyCondition="isReadOnlyField">
  </field>
...
</panel>

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

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

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 left, center and right with the align attribute.

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:

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