UserInputPanel

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

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

A UserInputPanel can be highly dynamic, 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 options by clicking a checkbox.

The user input panel can be populated with UI elements. The specification supports text labels, input elements, explanatory text and some minor formatting options.

<izpack:userinput version="5.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:izpack="http://izpack.org/schema/userinput" xsi:schemaLocation="http://izpack.org/schema/userinput http://izpack.org/schema/5.0/izpack-userinput-5.0.xsd">
  <panel id="panel1">
    <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.username" size="20" set=""/>
    </field>
    <field type="password" variable="proxyPassword">
	  <spec>
        <pwd txt="Proxy Password:" size="20" set=""/>
      </spec>	
    </field>
  </panel>
</izpack: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
• Button
• Custom

Additionally visual elements can be added using the following types:

• Static Text
• Title
• Space
• Divider

There is a more complex example of a userInputSpec.xml  at Sample userInputSpec.xml 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 the user has completed filling in the UserInputPanel, the variables and associated values are available for substitution.
This process has a number of implications of which you should be aware.

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 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.
2. The panel must be shown 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 invoking this panel any later in the process will correctly set the variables internally, it will be too late to affect the files written to disk.
3. 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 input panel in the process before the variables are used.

Hiding fields

It is possible to hide every field element based on conditions.
It is also possible to hide selected elements on the panel or to hide 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 in the src attribute in the resource "userInputSpec.xml" in the installation descriptor.

<izpack:userinput version="5.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:izpack="http://izpack.org/schema/userinput" xsi:schemaLocation="http://izpack.org/schema/userinput http://izpack.org/schema/5.0/izpack-userinput-5.0.xsd">
  <panel id="panel1">
    <field .../> 
    <field .../> 
    ...
  </panel>
  ...
</izpack:userinput>

The top level XML element is <userInput>. For most requirements it does not make sense to include more than one <panel>. 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 each panel instance.

The <panel> Element

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

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

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

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

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

Nested Elements

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.

Example:

If you have the following userInputSpec.xml and you want to internationalize input.comment, input.proxy, input.port for English and French you have to create two files named userInputLang.xml_eng and userInputLang.xml_fra:

<izpack:userinput version="5.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:izpack="http://izpack.org/schema/userinput" xsi:schemaLocation="http://izpack.org/schema/userinput http://izpack.org/schema/5.0/izpack-userinput-5.0.xsd">
  <panel id="panel1">
    <field type="staticText" align="left" txt="My comment is here." id="input.comment"/>
    <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>
  </panel>
</izpack:userinput>

<izpack:langpack version="5.0" xmlns:izpack="http://izpack.org/schema/langpack" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://izpack.org/schema/langpack http://izpack.org/schema/5.0/izpack-langpack-5.0.xsd">
  <str id="input.comment" txt="My comment is here."/>
  <str id="input.proxy" txt="Proxy Host Name:"/>
  <str id="input.port" txt="Proxy Host Port:"/>
</izpack:langpack>

<izpack:langpack version="5.0" xmlns:izpack="http://izpack.org/schema/langpack" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://izpack.org/schema/langpack http://izpack.org/schema/5.0/izpack-langpack-5.0.xsd">
  <str id="input.comment" txt="Mon commentaire est ici"/>
  <str id="input.proxy" txt="Nom de l'hôte proxy:"/>
  <str id="input.port" txt="Port de l'hôte proxy:"/>
</izpack:langpack>

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

<resources>
  ...
  <res id="userInputSpec.xml" src="userInputSpec.xml"/>
  <res id="userInputLang.xml_eng" src="userInputLang.xml_eng" />
  <res id="userInputLang.xml_fra" src="userInputLang.xml_fra" />
  ...
</resources>