Read-only panels and fields have been introduced in IzPack 5.0 (since 5.0 RC5).

The following approaches are possible to get all or dedicated user input fields displayed read-only.

Panel or field attribute displayHidden

Setting displayHidden="true" means "show read-only instead of hiding it according to its condition". This is a special use case, to show panels or fields not enabled for user input, but which are otherwise valid for the installation process. Using this approach you can simply reuse panels or fields and switch single fields to read-only mode instead of hiding it completely. The advantage is being able to automatically switch to read-only mode depending on the effective panel or field condition without having a dedicated condition for the panel or field to switch to read-only mode.

<panel id="panel.dbsettings" displayHidden="true">
...
</panel>
<panel id="panel.dbsettings.review" >
  <field ... displayHidden="true">
  </field>
...
</panel>

Imagine an installer also creating or updating a user database. In case of a clean installation mode you want the user to edit database connection fields, for example:

• database name

• user name

• password 

These fields (or the whole panel) depend on a condition isInstallationFromScratch:

<conditions>
    ...
	<condition type="variable" id="isUpdate">
		<condition type="ref" refid="foundPreviousInstallation">
	</condition>
</conditions>
...
<panels>
    ...
	<panel classname="UserInputPanel" id="panel.dbsettings" condition="!isUpdate" />
	...
</panels>

For an update and without the displayHidden attribute they would not be shown at all.

Now you want to let the user review the database connection on an update of the application without giving the possibility of changing it. For this purpose you can use the following definition:

<panel id="panel.dbsettings" displayHidden="true">
	<field type="text" variable="db.name">
		<spec txt="DB name:" id="text.dbname" size="20" />
	</field>
	<field type="text" variable="db.user">
		<spec txt="DB user:" id="text.dbuser" size="20" />
	</field>
	<!-- Note that you got to explicitly override the attribute on field level even if the same value would be the default -->
    <!-- The default value gets reinitialized for all fields if you use displayHidden or displayHiddenCondition on panel level -->
	<field type="password" variable="db.password" displayHidden="false">
		<spec><pwd txt="DB password:" id="text.dbpassword" size="20" /></spec>
	</field>
</panel>

In this case, the database name and user are shown read-only just in case the condition isInstallationFromScratch evaluates false, while the password field isn't shown at all.

Panel or field attribute displayHiddenCondition

<panel id="panel.dbsettings.review" displayHiddenCondition="isInstallationFromScratch">
...
</panel>
<panel id="panel.dbsettings.review2" >
  <field ... displayHiddenCondition="SomeCondition">
  </field>
...
</panel>

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

For the above example, to get the same result you might define:

<conditions>
    ...
	<condition type="variable" id="isUpdate">
		<condition type="ref" refid="foundPreviousInstallation">
	</condition>
</conditions>
...
<panels>
    ...
	<panel classname="UserInputPanel" id="panel.dbsettings" condition="!isUpdate" />
	...
</panels>

and as UserInputSpec.xml:

<panel id="panel.dbsettings" displayHiddenCondition="isUpdate">
	<field type="text" variable="db.name">
		<spec txt="DB name:" id="text.dbname" size="20" />
	</field>
	<field type="text" variable="db.user">
		<spec txt="DB user:" id="text.dbuser" size="20" />
	</field>
    <!-- Note that you got to explicitly override the attribute on field level even if the same value would be the default -->
    <!-- The default value gets reinitialized for all fields if you use displayHidden or displayHiddenCondition on panel level -->
	<field type="password" variable="db.password" displayHidden="false">
		<spec><pwd txt="DB password:" id="text.dbpassword" size="20" /></spec>
	</field>
</panel>

Panel or field attribute readonly

The readonly attribute for panels or fields can be used to create standalone read-only panels, that are shown or hidden by the installer in the same way like other panels not using displayHidden or displayHiddenCondition.

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

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

For the above example, you might define a separate UserInputPanel with a different layout:

<conditions>
    ...
	<condition type="variable" id="isUpdate">
		<condition type="ref" refid="foundPreviousInstallation">
	</condition>
</conditions>
...
<panels>
    ...
	<panel classname="UserInputPanel" id="panel.dbsettings" condition="!isUpdate" />
	<panel classname="UserInputPanel" id="panel.dbsettings.review" condition="isUpdate" />
	...
</panels>

and as UserInputSpec.xml:

<panel id="panel.dbsettings">
	<field type="staticText" align="left" txt="Please enter the database connection for installing:" id="dbsettings.label"/>
	<field type="space" />
	<field type="text" variable="db.name">
		<spec txt="DB name:" id="text.dbname" size="20" />
	</field>
	<field type="text" variable="db.user">
		<spec txt="DB user:" id="text.dbuser" size="20" />
	</field>
	<field type="password" variable="db.password">
		<spec><pwd txt="DB password:" id="text.dbpassword" size="20" /></spec>
	</field>
</panel>
 
<panel id="panel.dbsettings.review" readonly="true">
	<field type="staticText" align="left" txt="Please review the database settings before updating:" id="dbsettings.review.label" />
	<field type="space" />
	<field type="text" variable="db.name">
		<spec txt="DB name:" id="text.dbname" size="20" />
	</field>
	<field type="text" variable="db.user">
		<spec txt="DB user:" id="text.dbuser" size="20" />
	</field>
</panel>

Panel or field attribute readonlyCondition

<panel id="panel.dbsettings.review" readonlyCondition="SomeCondition">
...
</panel>
<panel id="panel.dbsettings.review2" >
  <field ... readonlyCondition="SomeCondition">
  </field>
...
</panel>

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

For the above example, to get the same result you might define:

<conditions>
    ...
	<condition type="variable" id="isUpdate">
		<condition type="ref" refid="foundPreviousInstallation">
	</condition>
</conditions>
...
<panels>
    ...
	<panel classname="UserInputPanel" id="panel.dbsettings" />
	...
</panels>

and as UserInputSpec.xml:

<panel id="panel.dbsettings" readonlyCondition="isUpdate">
	<field type="text" variable="db.name">
		<spec txt="DB name:" id="text.dbname" size="20" />
	</field>
	<field type="text" variable="db.user">
		<spec txt="DB user:" id="text.dbuser" size="20" />
	</field>
    <!-- Note that you got to explicitly override the attribute on field level even if the same value would be the default -->
    <!-- The default value gets reinitialized for all fields if you use displayHidden or displayHiddenCondition on panel level -->
	<field type="password" variable="db.password" conditionid="!isUpdate">
		<spec><pwd txt="DB password:" id="text.dbpassword" size="20" /></spec>
	</field>
</panel>

Precedence when combining parameters affecting the read-only mode

In general, there is just supported overriding default values (non-read-only mode) by read-only mode between user input panels and their fields.

When combining the above parameters, the effective setting is chosen using the following precedence order:

displayHidden and displayHiddenCondition

1. <field displayHidden="true"/>
   Notes:
   1. The attribute must be explicitly set for the panel to get activated for fields. If the attribute is not explicitly set on field level, the setting of the panel level applies.
   2. To activate this feature on field level, you need to allow it explicitly on panel level (either <panel displayHidden="true"/> or a <panel displayHiddenCondition/> becomes true), otherwise the panel will not show up at all (it is skipped according to a false panel condition) and the settings have no effect on field level.
2. <field displayHiddenCondition="fieldCondition1"/>
   Notes:
   1. If displayHidden="true" has been additionally defined, the read-only mode gets always activated for the scope of the definition (panel, field).
   2. To activate this feature on field level, you need to allow it explicitly on panel level (either <panel displayHidden="true"/> or a <panel displayHiddenCondition/> becomes true), otherwise the panel will not show up at all (it is skipped according to a false panel condition) and the settings have no effect on field level.
3. <panel displayHidden="true"/>
Notes:
   1. This setting applies to all fields of the panel, if they are not explicitly overridden on field level.
4. <panel displayHiddenCondition="panelCondition1"/>
Notes:
   1. If <panel displayHidden="true"/> has been additionally defined, the read-only mode of hidden fields gets always activated for the scope of the definition (panel, field), unless not overridden on field level.

readonly and readonlyCondition

1. <field readonly="true"/>
   Notes:
   1. The attribute must be explicitly set for the panel to get activated for fields. If the attribute is not explicitly set on field level, the setting of the panel level applies.
2. <field readonlyCondition="fieldCondition1"/>
   Notes:
   1. If readonly="true" has been additionally defined, the read-only mode gets always activated for the scope of the definition (panel, field).
3. <panel readonly="true"/>
Notes:
   1. This setting applies to all fields of the panel, if they are not explicitly overridden on field level.
4. <panel readonlyCondition="panelCondition1"/>
Notes:
   1. If <panel readonly="true"/> has been additionally defined, the read-only mode gets always activated for the scope of the definition (panel, field), unless not overridden on field level.