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.

• unset
  If unset, the variable is defined but does not have any active value and is invisible during the installation process.
• set
  If set, the variable has an active value, which can be still changed during panel changes depending on changing variable conditions.
• frozen 
  If frozen, the variable's value is not changed during the refresh process on panel changes.

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 means as soon as the user presses Next after filling a field which has the same name as a dynamic variable, the dynamic variable is set to the value entered by the user and remains frozen unless the user and moves backward again over the panel containing the input field by pressing the Previous button.

In consequence, 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 one and the same variable, this variable is frozen immediately after the user completes the first panel containing the variable 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 and the unset  attribute is not set to false for that certain variable definition.