We need you!

Icon

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

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

When you need to capture user input that will be available to your installer then you need to use the UserInputPanel.

This panel allows you to prompt the user for data . What the user is prompted for is specified using an XML file which is included as a resource to the installer.  Most of the panels that come with IzPack take user input in some form. In some panels this is through a simple user acknowledgment in others the user can enter text or select a directory through a file open dialog. In all of those cases the user input is used for the specific purpose needed by the panel that takes the input. However, if you need user input during installation that will later on be available to your application then you need to use the user input panel.

To use this panel, list it in the install file with the class name UserInputPanel. In addition, you must write a XML specification and add it to the install resources. The name of this resource must be userInputSpec.xml.

...

languagehtml/xml

that you can use later in the installation process.


Resource "userInputSpec.xml"


The UserInputPanel is described in an XML file that you create and list as a resource with the id "userInputSpec.xml"
Then you can list it in a <panel> element with the class name "UserInputPanel".

Code Block
<resources>
    <res id="userInputSpec.xml" src="user_input_spec.xml" parse="yes" type="xml"/>
</resources>
...
<panels>
...
    <panel classname="UserInputPanel" id="userinputpanel.orderpanel1"/>
...
</panels>

A UserInputPanel can be highly dynamic from IzPack 4.3 on, as , since it will be refreshed every time the user input changes and will be rendered based on conditions.
For instance, it would be possible to enable or disable some more options by clicking a checkbox.

Here's an example userInputSpec.xml (http://%7b%7bservername%7d%7d/sample-userInputSpec.html) showing 3 panels. There are some advanced features in this example, but the general flow should be looked at first.

The user input panel is a blank panel that can be populated with UI elements through a XML specification file. The specification supports text labels, input elements, explanatory text and some minor formatting options.

Code Block
<userInput>
  <panel id="proxypanel">
    <field type="staticText" align="left" txt="Enter the Information required to connect to your proxy" id="input.title"/>
    <field type="text" variable="proxyaddress">
      <spec txt="Proxy Host:" id="input.proxy" size="25" set=""/>
    </field>
    <field type="text" variable="proxyPort">
      <spec txt="Proxy Port:" id="input.port" size="6" set=""/>
    </field>
    <field type="text" variable="proxyUsername">
      <spec txt="Proxy Username:" id="input.port" size="20" set=""/>
    </field>
    <field type="password" variable="proxyPassword">
      <spec txt="Proxy Password:" id="input.port" size="20" set=""/>
    </field>
  </panel>
</userInput>

The following types of user input elements are supported:

  • Text
  • Combo Box
  • Radio Buttons
  • Check Box
  • Password
  • File
  • Multiple files
  • Directory
  • Rule Input Field
  • Search Field
  • Custom

Additionally visual elements can be added using the following types:

  • Static Text
  • Title
  • Space
  • Divider

The way in which this panel conveys the user input to your application is through the variable substitution system. User There is a more complex example of a userInputSpec.xml at  (http://%7b%7bservername%7d%7d/sample-userInputSpec.html) showing 3 panels. There are some advanced features in this example, but the general flow should be looked at first.

Accessing User Input


User input is not directly inserted into your configuration files but the variables that you specify for this panel are set in the variable substitution system. After this operation has taken place the the user has completed filling in the UserInputPanel, the variables and associated values are available for all substitutions madesubstitution.
This way of operation process has a number of implications that of which you should be aware of.First, not

  1. Not only can you set additional variables in this way but you can also modify variables that are defined elsewhere - even built in variables. For this reason you should be careful to avoid

...

  1. conflicts when choosing variable names. Although there might be cases when it seems useful to modify the value of other variables, it is generally not a good idea to do so. Because you might not exactly know when other variables are set and when and where they are used throughout the installation process, there might be unintended side effects.

...

  1. The panel must be shown

...

  1. before the variables are used. In most cases you will use the values to substitute variables in launch and configuration files that you supply with your installation. For this to work you place this panel before the install panel, because the install panel uses the variable substitutor to replace all such variables. Although

...

  1. invoking this panel any later in the process will correctly set the variables internally,

...

  1. it will be too late to affect the files written to disk.
  2. You can also use variables set in this way in other panels that you have written yourself.There is a section in the chapter on writing your own panel that explains how to do this. Also in this case it is important to place the

...

  1. input panel in the process before the variables are used.

...

Hiding fields


It is possible to hide every field element based on conditions.
It would also be possible to hide select elements on the panel or the panel altogether if certain packs are not selected. For this to work you must place this panel after the packs panel. One side effect of using this feature is that it is not possible to step back once the user input panel is displayed. This is because the user might make changes in the packs selection that would require a complete rebuild of the UI. Unfortunately, building the UI is an irreversible process, therefore the user can not be allowed to go back to the packs panel.

...

XML Structure for the UserInputPanel Definition

A UserInputPanel is defined in a separate descriptor file, referred to as in the src attribute in the resource "userInputSpec.xml" from in the installation descriptor.

Code Block
titleBasic syntax of a UserInputPanel definition
languagehtml/xml
<userInput>
  <panel id="panel1">
    <field .../> 
    <field .../> 
    ...
  </panel>
  ...
</userInput>

The top level XML section is called element is <userInput>. For most panels requirements it does not make sense to present them include more than onceone <panel>. However, however you might want to present multiple user input panels - with different content of course. Therefore the <userInput> section can contain multiple <panel> tags that each specify the details for one each panel instance.

The <panel> Element

The tag name for this is <panel>The <panel> tag uses the following attributes:

Name

Required

Description

Values

id

yes

This is the id of the user input panel for which this specification should be used. This id links to the panel specification in the install.xml file.

String Value

layout

no

Sets the alignment of fields used in the panelThere are three general layout rules this panel uses, they are left, center and right. While i think left is most commonly used, you might want to experiment with this attribute and see which you like best. The default is left.

left, center, right default: left

border

no

Normally the user input is shown with a small border. To prevent this border set this attribute to false.

true, false default: true

column_width

no

This can be used to set the column width of the two column layout. This value is in percent of the whole size. If it is set to 0, which is the default, the with will be set automatically. It it is set to 50 the gap between the left and right column is in the middle of the panel. This makes it possible to make a centered layout.

0-100 percent default: 0

Each panel can have a number of visible elements, fields.

Internationalization

...

summaryKeynoId of a string that represents what header name to display in the SummaryPanel of the UserInputPanel. This attribute must be defined if you would like to summarize the UserInputPanel. Note that you will have to add the summaryKey attribute to the fields you would like those to show up in the SummaryPanel as well.String Value
readonlyno

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

Code Block
titleExample of the readonly attribute
languagexml
collapsetrue
<panel id="panel.dbsettings" readonly="true">
  <field ... >
  </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, all fields on the panel get displayed read-only only if it is not disabled by a general panel condition and the condition defined by readonlyCondition gets true.

Code Block
titleExample of the readonlyCondition attribute
languagexml
collapsetrue
<panel id="panel.dbsettings" readonlyCondition="isReadOnlyPanel">
  <field ...>
  </field>
...
</panel>
true, false default: false
displayHiddenno

Setting displayHidden attribute in the <panel> element causes all fields within the panel to be shown regardless of what each field's conditionid evaluates to.

Displayed hidden fields are disabled (ie. "greyed out") .

But if the conditionid of the panel evaluates to false, display all fields on the panel just as disabled instead of hiding it.

Code Block
titleExample of the displayHidden attribute
languagexml
collapsetrue
<panel id="a.panel" displayHidden="true">
	<field type="check" variable="b" conditionid="b.cond">
    	<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, all fields on the panel get displayed read-only only if a general condition on that panel disables it for displaying and the condition defined by displayHiddenCondition gets true.

Code Block
titleExample of the displayHiddenCondition attribute
languagexml
collapsetrue
<panel id="b.panel" displayHiddenCondition="isDisplayHiddenPanel">
	<field type="check" variable="b" conditionid="b.cond">
    	<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

 

Nested Elements

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.
fieldnoOne or more user input field definitions, described on the page Fields.Valid user input field definitions, see Fields for more information.

 

Internationalization

To provide internationalization, you create a file named userInputLang.xml_xyz where xyz is the ISO3 code of the language in lowercase. Please be aware that case is significant. This file has to be inserted in the resources section of install.xml with the id and src attributes set at the name of the file.

...

Code Block
titleuserInputLang.xml_eng
languagehtml/xml
<langpack>
  <str id="input.comment" txt="English:My comment is here."/>
  <str id="input.proxy" txt="English:Proxy Host:"/>
  <str id="input.port" txt="English:Proxy Port:"/>
</langpack>
Code Block
titleuserInputLang.xml_fra
languagehtml/xml
<langpack>
  <str id="input.comment" txt="French:MyMon commentcommentaire isest here.ici"/>
  <str id="input.proxy" txt="French:Proxy HostNom de l'hôte proxy:"/>
  <str id="input.port" txt="French:Proxy PortPort de l'hôte proxy:"/>
</langpack>

you will also have to add the following to the install.xml file

...