Message-ID: <1773208727.301563.1369140435643.JavaMail.email@example.com> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_301562_1818062149.1369140435643" ------=_Part_301562_1818062149.1369140435643 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
(by Elmar GROM)
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.=C2=A0 Most of the panels that com= e 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 a= vailable 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
A UserInputPanel can be highly dynamic from IzPack 4.3 on, a= s it will be refreshed every time the user input changes and will be render= ed based on conditions. For instance, it would be possible to enable or dis= able some more options by clicking a checkbox.
Here's an example user= InputSpec.xml (http://%7b%7bservername%7d%7d/sample-userInputSpec.html) sho= wing 3 panels. There are some advanced features in this example, but the ge= neral 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 f= ile. The specification supports text labels, input elements, explanatory te= xt and some minor formatting options.
The following types of user inp= ut elements are supported:
Additionally visual elements can be added using the following types:= p>
The way in which this panel conveys the user input to your application i= s through the variable substitution system. User input is not directly inse= rted into your configuration files but the variables that you specify for t= his panel are set in the variable substitution system. After this operation= has taken place the variables and associated values are available for all = substitutions made. This way of operation has a number of implications that= you should be aware of.
First, not only can you set additional varia= bles in this way but you can also modify variables that are defined elsewhe= re -even built in variables. For this reason you should be careful to avoid= overlaps 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 variab= les are set and when and where they are used throughout the installation pr= ocess, there might be unintended side effects.
Second, the panel must= be shown at a point during the installation process before the variables a= re used. In most cases you will use the values to substitute variables in l= aunch and configuration files that you supply with your installation. For t= his to work you place this panel before the install panel, because the inst= all panel uses the variable substitutor to replace all such variables. Alth= ough using this panel any later in the process will correctly set the varia= bles internally, there won't be any affect on the files written to disk. Yo= u can also use variables set in this way in other panels that you have writ= ten yourself. There is a section in the chapter on writing your own panel t= hat explains how to do this. Also in this case it is important to place the= associated input panel in the process before the variables are used.
At this point I would also like to mention that it is possible to hide eve= ry field element based on conditions.
It would also be possible to hi= de select elements on the panel or the panel altogether if certain packs ar= e 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 reb= uild 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.
The top level XML section is called
<userInput>. For mos=
t panels it does not make sense to present them more than once, however you=
might want to present multiple user input panels -with different content o=
f course. Therefore the
<userInput> section can contain =
multiple tags that each specify the details for one panel instance. The tag=
name for this is
tag uses the following attributes:
This is the id of the user = input panel for which this specification should be used. This id links to t= he panel specification in the install.xml file.
Sets the alignment of fields used in the panelThere are three genera=
l layout rules this panel uses, they are
right. While i think left is most commonly used, you =
might want to experiment with this attribute and see which you like best. T=
he default is
left= , center, right default: left
Normally the user input is shown with a sma=
ll border. To prevent this border set this attribute to
true, false default: true
can be used to set the column width of the two column layout. This value i=
s in percent of the whole size. If it is set to
0, which is th=
e 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
Before we div= e into the details of defining the various UI elements I would like to pres= ent XML elements and general concepts that apply throughout. This saves me = a lot of work in writing and you a lot of repetitive reading and maybe a tr= ee or two.
The UI elements are generally laid out top to bottom in th= e order they appear in the XML file. The only exception to this rule is the= title, which always appears at the very top. The layout pattern for the in= put fields is as follows: If a description is defined, it appears first, us= ing the full available layout width. The input field is placed beneath the = description. With fields such as the text field or the combo box, the label= is placed to the left and the input field to the right. Fields such as rad= io buttons and check boxes are somewhat indented and have the label text ap= pear to their right.
Each UI element is specified with a
eld> tag. The <field> tag has some common attributes:
Used to specify what kind of field you want to place.
Any valid field type
Used to change the default posit= ion of the label.
west, westonly, bot= h, eastonly, east defatul: west
Used to change the default alignment o= f the label.
left, center, right
true, false default: false
Used to change the default position of the field's control.= p>
west, westonly, both, eastonly, east <= strong>default: east
Used to change the default alignment of the control.= p>
left, center, right default:= strong> left
Controls whether or not the control is indented.
true, false default: false
yes, if input field
Specified the= variable that should be substituted with the user input.
A variable name.
Specifies the id of a condition in install.xml wh= ich must evaluate to true in order to display the field.
A valid condition id in install.xml.
In the following examp= le, the the label and the control will be shown on it's own row.
In the following example, the label is right aligned to the = control.
Almost all fields allow a description element. The descripti=
on is part of the data within the field element. There can only be one desc=
ription per field. If you add more than one description, the first descript=
ion is used and the others ignored. There are three attributes used with th=
is tag. The text is specified through the
txt or the
/code> attribute. The details on using them are described below. The attrib=
utes are all optional but you must specify text to use, either directly or =
id attribute. In addition, you can set the text ju=
right with the
yes, if no id
Specified the defau= lt text to use in absence of a language package.
yes, if no txt
Specifies text description through use of a language package.= p>
A valid id
Sets the justification of the description.= p>
left, center, right default:= strong> left
The following example il= lustrates the general pattern for field specification:
A very frequently used pattern is for the definition of text=
. Where ever text is needed (labels, descriptions, static text, choices etc=
.) it can be specified in place using the
txt attribute. This =
is convenient if you are only supporting a single language. However, if you=
would like to separate your text definitions from the panel specification =
or if you need to support multiple languages you might want to use the
an identifier that is also defined in the language package, together with =
the localized text to use. It is possible to use both the
id attribute. In this case the text from the language =
package is used. If for some reason the language package is not available o=
id is not defined there, the text specified with
xt is used as default.
All input fields can be pre-set with a =
value of your choice. Although the details vary a bit from field type to fi=
eld type, the
set attribute is always used to accomplish this.=
set attribute is of course optional. Please note that if =
you use the
set attribute, you would have to keep in mind, tha=
t the UserInputPanel will be rendered after each user input. Thus it will b=
e set back to the default value if you don't use a condition to handle that=
. IzPack generates builtin conditions for every variable used as target for=
a field to be able to check if there's any input.
All fields that ta=
ke user input use a
<spec> tag to define the details of =
the input field. In the some cases the content of this tag is rather simple=
. Input fields with a more complex nature tend to have accordingly complex =
content in this tag. Since the details vary widely, they are explained with=
each input field.
Any number of
a pack name
/> tags can be added to=
<field> sections. Th=
is tag has only one attribute and no data. The attribute is
name and specifies the name of one of the installation packs that you have de=
fined. Here is how it works: if no
<createForPack ...> t=
ag exists in a section, the entity is always created. However, if the tag e=
xists, the entity is only created if one or more of the listed packs are se=
lected for installation. As mentioned before, if you are using this feature=
, make sure the user input panel shows up after the packs panel.
, any number of
/> tags can be added to the
<field> sections. This tag has on=
ly one attribute and no data. It works exactly like createForPack except th=
at once added user input panel will appear for only NOT Selected packs. As =
mentioned earlier, you need to make sure that the user input panel shows up=
after the packs panel for this feature to work.
There is a possibili=
ty to use variables in those elements where the text is supplied via
txt attribute. This includes static fields and input fields (spec, d=
escription). The text can contain unlimited number of variables that will b=
e substituted. Variable substitution also works with language packs, just u=
se variables in your language pack, and they will be still substituted prop=
In the following example, the va= riables: name1, name2, name3 will be substituted.
To provide internationalization you can create a file named
xyz is the ISO3 code of =
the language in lowercase. Please be aware that case is significant. This f=
ile has to be inserted in the resources section of
src attributes set at the name o=
f the file.
If you have the following=
userInputSpec.xml and you want to internationalize
input.port for English and Fren=
ch you have to create two files named userInputLang.xml_eng and userInputLa=
you will also have to add the following to the install.xml f= ile------=_Part_301562_1818062149.1369140435643--