Common behavior

Each dynamic variable is identified by a unique name. Dynamic variables do not have a separate namespace. After evaluation, dynamic variables are handled like a static IzPack variable defined in a <variables> section. This means they are visible like any other IzPack variable for replacing placeholders or as default value for user input fields assigning a value to a variable. 

If the name of a dynamic variable is also used in a variable definition in the <variables> section, the <variable> is used to set the default value for the dynamic variable .

When the dynamic variable has set the attribute checkonce="true", the dynamic variable behaves exactly like a "normal" IzPack variable with a static key-value pair after it is set for the first time. It enters the "frozen" state and can not be reset.

An IzPack installer refreshes all dynamic variables that are not "frozen" on each panel change. Changes to variables during the refresh might affect a whole chain of conditions from the <conditions> section if the variables are used in condition statements.

A dynamic variable can lose it's value if as some point it cannot be evaluated from any of its definitions. It will be reinitialized with a value as soon as at least one of its definitions can be evaluated in some later phase.

It is possible to define a dynamic variable multiple times based on different conditions (the order of the definition is relevant!):

<dynamicvariables>
  <variable name="thechoice" value="fallback value" />
  <variable name="thechoice" value="choice1" condition="cond1" />
  <variable name="thechoice" value="choice2" condition="cond2" />
</dynamicvariables>

The value of a dynamic variable is overridden if there is a subsequent definition of the same variable with a condition evaluating to "true".

See following section on the precedence rules for more details.

Lifecycle states

Since: 5.0.0 RC5

The following lifecycle states are possible for a dynamic variable defined in the installer descriptor:

• unset
  If unset, the variable is defined but does not have any active value and is invisible during the installation process.
  A variable can be defined and unset also if it depends on a condition which at the given time evaluates false, and there is no second definition of the same variable setting it.
• set
  If set, the variable has an active value, which can be still changed during panel changes depending on changing variable conditions.
  If a variable is defined more times it gets evaluated in the order of definition, thus, the last definition applying at the given time has precedence.
• frozen 
  During being frozen, the variable value cannot be changed during refresh.

Precedence rules during refreshing

If a dynamic variable is defined multiple times with the same key, all definitions are applied during refreshing in the order they are defined in the <dynamicvariables> section. If all of the currently applicable definitions would unset the variable it is unset, otherwise the last definition in the list "wins" during refreshing.

Precedence rules between value changes during refreshing and user inputs

Since: 5.0.0 RC5

A dynamic variable will not be refreshed after it has been assigned a value from a user input field. This creates a dedicate dynamic variable which behaves differently after the panel on which the user input field appears.

This means as soon as the user presses Next after filling a field which has the same name as a dynamic variable, the dynamic variable get the value entered by the user and enters the frozen state and remains in that state unless the user presses the Previous button and moves backward again over the panel containing the input field.

This means, a value entered by the user always has precedence over values that would be generated by dynamic variable refreshing in subsequent panels.

If there is more than one panel that modifies a dedicated variable, this variable is frozen immediately after the user completes the first panel by pressing Next.

In addition, if the user goes back through the panel sequence by pressing Previous, they must reach the first panel containing the variable before it will be unfrozen.

In this way, the variables can be reset to the proper values based on new conditions when the user navigates backward and forward multiple times and inputs new choices.

Global precedence for dynamic variable assignments

Since: 5.0.0 RC5

As a result of what was described above, variable assignments happen with the following precedence:

1. User input field (for instance on UserInputPanel, InstallPanel): A valid user input is assigned as a variable value and freezes the variable from further changes during refreshing.
   Note: Each panel can access an API for registering variable names it affects or override when being active. Freezing is not just limited to the UserInputPanel.
2. Refresh: try to get the last valid value in order of the definitions taking the conditions into account
3. Refresh: try to find a default value from the <variables> section
4. Refresh: unset if the variable value cannot be assigned due to no variable condition evaluating to true.