Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

<h1>The Available Panels</h1>

<p>In this section I will introduce the various panels available in IzPack. The usage for most is pretty simple and described right here. The more elaborate ones are explained in more detail in the <em>Advanced Features</em> chapter or in their own chapter. The panels are listed by their class name. This is the name that must be used with the <code>classname</code> attribute. Please be aware that the classname is Case-Sensitive, meaning that if the case from the install.xml and the founded class file differs the installation will break. In this last case, the installer will Throw an IllegalArgumentException in the compiler if the declared class name in the xml file differs in case from the founded class file.</p>

<h2>HelloPanel</h2>

<p>This panel welcomes the user by displaying the project name, the version, the URL as well as the authors.</p>

<h2>HTMLHelloPanel</h2>

<p>This panel allows an HTML document to be used as the &quot;welcome&quot; panel. It operates like the 'HTMLInfoPanel', except that the resource name &quot;HTMLHelloPanel&quot; is used (i.e., &quot;HTMLHelloPanel.info&quot;).</p>

<h2>CheckedHelloPanel</h2>

<p>This panel welcomes the user also by displaying the project name, the version, the URL as well as the authors.</p>

<p>Additonal on windows the registry will be scanned for an entry which determines that the product is already installed. If so, a dialog will be shown which ask whether to install a second version of the product or not. If you use this panel do not forget to add the `registry feature` into your installation.</p>

<h2>InfoPanel and HTMLInfoPanel</h2>

<p>This is a kind of 'README' panel. It presents text of any length. The text is specified by the <code>(HTML)InfoPanel.info</code> resource. Starting from IzPack 3.7.0, variables substitution is allowed. To add an image to the HTMLInfoPanel you simply need to add a ressource to your install.xml with an ID decided by you, then you can call this image by refering it by this same ID.</p>

<p>In install.xml:</p>

<p>You can define multiple HTMLInfoPanel with individual HTML texts by giving them a specific id. The resources are named <code>HTMLInfoPanel.&lt;panelid&gt;</code> :</p>

<h2>LicencePanel and HTMLLicencePanel</h2>

<p>Note:* There is a mistake in the name - it should be LicensePanel. In France the word is Licence ... and one of my diploma is a 'Licence' so ...:* -)</p>

<p>Adding images to HTMLLicencePanel works exactly the same way as with HTMLInfoPanel.</p>

<p>These panels can prompt the user to acknowledge a license agreement. They block unless the user selects the 'agree' option. To specify the license agreement text you have to use the <code>(HTML)LicencePanel.licence</code> resource.</p>

<h2>PacksPanel</h2>

<p>Allows the user to select the packs he wants to install. This panel also allows grouping of packs. Look at <code>InstallationGroupPanel</code> description to get more details.</p>

<h2>ImgPacksPanel</h2>

<p>This is the same as above, but for each pack a different picture is shown to the user. The pictures are specified using the packImgId attribute for each pack in the installer XML. The initial image will be the image of the first pack that has a packImgId. The image is updated each time the user (de)selects a pack that has a packImgId. Of course it's up to you to specify an image for each pack in your installation with a unique packImgId. For instance if you have 2 packs <code>core</code> and <code>documentation</code> (in this order), and you assign both packs a packImgId that is identical to the pack's name then the resource for <code>core</code> will be <code>core</code> and the resource for <code>documentation</code> will be <code>documentation</code>. The initially shown image will be the resource <code>core</code>. The supported image formats depend on what your client's JVM supports, but starting from J2SE 1.3, <em>GIF</em>, <em>JPEG</em> and <em>PNG</em> are supported.</p>

<h2>TreePacksPanel</h2>

<p>This panel is very similar to <code>PacksPanel</code>, but instead of simple list of available packs, the tree-like list is constructed. By using the <code>parent</code> attribute of <code>pack</code> element, one can specify the hierarchy of the tree. This panel supports grouping just like <code>PacksPanel</code> does.</p>

<p>example</p>

&lt;packs>
        &lt;pack name="Base"
            required="yes">
            (...)
        &lt;/pack>
        &lt;pack name="Themes"
            required="no">
            (...)
        &lt;/pack>
        &lt;pack name="Black"
            parent="Themes"
            required="no">
            (...)
        &lt;/pack>
        &lt;pack name="Red"
            parent="Themes"
            required="no">
            (...)
        &lt;/pack>
    &lt;/packs>
&lt;/installation></pre></td></tr></table>
<p>The result tree contains Base element with no children, and Themes with two children named Black and Red.</p>

<h2>TargetPanel</h2>

<p>This panel allows the user to select the installation path. It can be customized with the following resources (they are text files containing the path) :</p>

<ul>
	<li><code>TargetPanel.dir.f</code> where f stands for the family (<code>mac, macosx, windows, unix</code>)</li>
	<li><code>TargetPanel.dir</code> : the directory name, instead of the software to install name</li>
	<li><code>TargetPanel.dir.d</code> where d is a &quot;dynamic&quot; name, as returned by the JavaTM virtual machine. You should write the name in lowercase and replace the spaces with underscores. For instance, you might want a different setting for Solaris and GNU/Linux which are both Unix-like systems. The resources would be <code>TargetPanel.dir.sunos, TargetPanel.dir.linux</code>. You should have a Unix-resource in case it wouldn't work though.</li>
</ul>

<p>The 'ShowCreateDirectoryMessage' variable may be used to suppress the &quot;target directory will be created&quot; dialog. If the 'ShowCreateDirectoryMessage' variable is set to &quot;false&quot; then the dialog will not be shown. If the 'ShowCreateDirectoryMessage' variable is set to &quot;true&quot; or is not specified then the dialog will be shown if the target directory does not exist. See the &quot;Variables Element&quot; section for information on how to specify variables.</p>

<h2>DefaultTargetPanel</h2>

<p>The default installation directory is specified as in the TargetPanel (using identical names (TargetPanel... not DefaultTargetPanel...), but will not allow the user to change the installation path. It can be used when software must be installed in a specific location.</p>

<h2>InstallPanel</h2>

<p>You should always have this one as it launches the installation process !</p>

<h2>XInfoPanel</h2>

<p>A panel showing text parsed by the variable substitutor. The text can be specified through the <code>XInfoPanel.info</code> resource. This panel can be useful when you have to show information after the installation process is completed (for instance if the text contains the target path). The font can be set on this text through the optional variable <code>XinfoPanel.font</code>, and its value is to be formatted consistent with the support provided by java.awt.Font.decode().</p>

<p>In the following example the font size and type are omitted, but they can also be part of the value:</p>

<h2>FinishPanel</h2>

<p>A ending panel, able to write automated installer information. For details see the chapter on 'Advanced Features'.</p>

<h2>SimpleFinishPanel</h2>

<p>Same as <code>FinishPanel</code>, but without the automated installer features. It is aimed at making the life easier for end-users who will never encounter the automated installer extra feature.</p>

<h2>ShortcutPanel</h2>

<p>This panel is used to create desktop shortcuts. For details on using the ShortcutPanel see the chapter 'Desktop Shortcuts'.</p>

<h2>UserInputPanel</h2>

<p>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.</p>

<h2>CompilePanel</h2>

<p>This panel allows you to compile just installed Java sourcecode. The details for the compilation are specified using the resource <code>CompilePanel.Spec.xml</code>. The XML file has the following format:</p>

<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>&lt;compilation>
  &lt;global>
    &lt;compiler>
      &lt;choice value="$JAVA_HOME/bin/javac" />
      &lt;choice value="jikes" />
    &lt;/compiler>
    &lt;arguments>
      &lt;choice value="-O -g:none" />
      &lt;choice value="-O" />
      &lt;choice value="-g" />
      &lt;choice value="" />
    &lt;/arguments>
  &lt;/global>
  &lt;jobs>
    &lt;classpath add="$INSTALL_PATH/src/classes/" />
    &lt;job name="optional name">
      &lt;directory name="$INSTALL_PATH/src/classes/xyz" />
    &lt;/job>
    &lt;job name="another job">
      &lt;packdepency name="some package name" />
      &lt;classpath sub="$INSTALL_PATH/" />
      &lt;directory name="$INSTALL_PATH/src/classes/abc" />
      &lt;file name="$INSTALL_PATH/some/file.java" />
    &lt;/job>
  &lt;/jobs>
&lt;/compilation></pre></td></tr></table>
<p>In theory, jobs can be nested but this has not been tested at all. A change to the classpath within a job only affects this job and nested jobs. The classpath should be specified before any files or directories.</p>

<p>The user can change the compiler to use and choose from some default compilation options before compilation is started.</p>

<h2>ProcessPanel</h2>

<p>This panel allows you to execute arbitrary files after installation. The details for the compilation are specified using the resource <code>ProcessPanel.Spec.xml</code>.</p>

<p>The XML file has the following format:</p>

<p>In addition to <code>&lt;arg&gt;</code> elements, the <code>&lt;executefile&gt;</code> element also accepts <code>&lt;env&gt;</code> elements to set variables in the environment of the target process. This can be useful if this process requires some environment variables, such as its installation directory, to work properly. An <code>&lt;env&gt;</code> element has the following syntax: <code>&lt;env&gt;variable=value&lt;/env&gt;</code>. Note the value supports variable substitution, for example: <code>&lt;env&gt;MY_PRODUCT_HOME=$INSTALL_PATH&lt;/env&gt;</code>.  The workingDir attribute for the &lt;executefile&gt; element adds the ability to set the working directory of the process spawned by the <a href="http://download.oracle.com/javase/6/docs/api/java/lang/ProcessBuilder.html">ProcessBuilder</a> object, much as &lt;env&gt; elements refer to the <a href="http://download.oracle.com/javase/6/docs/api/java/lang/ProcessBuilder.html#environment()">environment</a> object of ProcessBuilder.</p>

<p>The ProcessPanel now also supports configurable behaviour for the panel's &quot;Previous&quot; and &quot;Next&quot; buttons. By adding <code>&lt;onFail&gt;</code> and <code>&lt;onSuccess&gt;</code> childs to the <code>&lt;processing&gt;</code> element, you define which buttons you want unlocked in case of failure and in case of success, respectively.</p>

<h3><code>&lt;executeclass&gt;</code> - Execute Java Classes</h3>

<p>It is also possible to execute Java classes from this panel. Here's what this feature author (Alex Bradley) says:</p>

<p>&gt; i've been able to work around my requirements by extending the <code>ProcessPanelWorker</code> functionality to run user-specified classes. i've extended the DTD of the <code>ProcessPanel.Spec.xml</code> to include a new element:</p>

<p>To use the executeclass facility, you will need to create a jar file with your class and then add it to the installer with the `The Jar Merging Element`.</p>

<h3><code>&lt;executeForPack&gt;</code> - Only execute the job for certain packs</h3>

<p>This can be be used to run the job only if the pack is enabled. For example, the batch file will if either the <code>Sources</code> or <code>Executables</code> packs are selected at install time.</p>

<h3><code>&lt;logfiledir&gt;</code> - Output of the processPanel saved to a log</h3>

<p>New with version 3.7 is the possibility to tee output that is written to the ProcessPanel's textarea into an optional logfile. Using this feature is pretty much straightforward, you only have to add a line in <code>ProcessPanel.Spec.xml</code> that will tell IzPack the location, where the logfile should be stored.</p>

<p>Variable substitution is performed, so you can use <code>$INSTALL_PATH</code> as example.</p>

<p>The name of the logfile is not (yet) configurable but should fit in most cases. It will be named</p>

<p><code>ProcessPanelWorker</code> will write all output that is directed to <code>stdout</code> and <code>stderr</code> to this file if <code>ProcessPanel.Spec.xml</code> contains the <code>logfiledir</code> entry.</p>

<p>Please note that this one file is used for storing the complete output of all jobs and not a file for each job that is run.</p>

<h2>JDKPathPanel</h2>

<p>This panel allows the user to select a JDK path. The variable JAVA_HOME does not point to a JDK, else to a JRE also the environment variable points to a JDK. This is not a bug, this is the behavior of the VM. But some products needs a JDK, for that this panel can be used. There is not only a selection of the path else a validation. The validation will be done with the file JDKPath/lib/tools.jar. If JAVA_HOME points to the VM which is placed in the JDK, the directory will be used as default (JAVA_HOME/..). If there is the variable</p>

<h2>SelectPrinterPanel</h2>

<p>This panel will look at the local printers installed and propose a list box with all of them. Once chosen, the variable $SELECTED_PRINTER is set to the user choice.</p>

<h2>DataCheckPanel</h2>

<p>DataCheckPanel is not for inclusion in an actuall install, but is a debugging resource for developers writing custom panels or code to be included in IzPack. It creates a list of all the variables in InstallData, their values and a list of all packs, indicating which are selected. This list is printed to the console and appears in a scrollable text area on the panel. Put the panel in wherever you want to see any variables in InstallData or a listing of the packs with a line like this in the &lt;panels&gt; section of install.xml:</p>

<p>&lt;panel classname=&quot;DataCheckPanel&quot; /&gt;</p>

<p>It will automatically give you a full list of all the variables and packs whenever the panel is made active.</p>

<h2>SummaryPanel</h2>

<p>This panel gives a summary of all shown panels. The best place for it is just infront of the InstallPanel. Normaly it contains a warning that this is the last panel before installation. The panel contains a scrollable HTML text area to display the summary. The informations are collected from each panel by calling the methods <code>getSummaryCaption</code> and <code>getSummaryBody</code>. <code>getSummaryCaption</code> is implemented in <code>IzPanel</code> with a panel name default text. <code>getSummaryBody</code> has to be implemented in all panels which should be presented in the summary. If the secound method is not implemented, no summary of this panel will be shown.</p>

<p>Additional it is possible to `log the contents` of the summary panel into a HTML file.</p>

<h2>InstallationGroupPanel</h2>

<p>This Panel groups the pack together. A panel which displays the available <em>installGroups</em> found on the packs to allow the user to select a subset of the packs based on the pack <em>installGroups</em> attribute. This panel will be skipped if there are no pack elements with an <em>installGroups</em> attribute. For example</p>

&lt;packs>
        &lt;pack name="Base"
            installGroups="Group1"
            required="yes">
            (...)
        &lt;/pack>
        &lt;pack name="Docs"
            installGroups="Group1,Group2"
            required="no">
            (...)
        &lt;/pack>
        &lt;pack name="Sources"
            installGroups="Group3,Group2"
            required="no">
            (...)
        &lt;/pack>
    &lt;/packs>
&lt;/installation></pre></td></tr></table>
<p>In above example when InstallationGroupPanel is displayed, it contains three radios named Group1, Group2 and Group3. Depending on what user selects, the respective Packs will be displayed in PacksPanel. InstallationGroupPanel will look for a description corresponding to the key &quot;InstallationGroupPanel.description.Group1&quot;, &quot;InstallationGroupPanel.description.Group2&quot; etc in installation langpacks and variables and displays this description for each of the Group_i.</p>

<p>You may also define a sortKey in the variables section of the installer.xml to define an alternative sorting. The default sorting is based on the Group Name.</p>

<p>Here is an example for alternative sorting of groups:</p>

<p>Here is an example to localize groups into French (these lines have to be put in your <code>packsLang.xml_fra</code> resource) :</p>

<p>&lt;str id=&quot;InstallationGroupPanel.group.Core&quot; txt=&quot;Noyau de l'application&quot; /&gt; &lt;str id=&quot;InstallationGroupPanel.description.Core&quot; txt=&quot;Fichiers principaux, indispensables au fonctionnement de l'application&quot; /&gt; &lt;str id=&quot;InstallationGroupPanel.group.Samples&quot; txt=&quot;Fichiers d'exemple&quot; /&gt; &lt;str id=&quot;InstallationGroupPanel.description.Samples&quot; txt=&quot;Fichiers d'exemples&quot; /&gt;</p>

<p>If you want to add html markup to those strings, add <code>.html</code> at the end of the string id (after the group name).</p>

<h2>UserPathPanel</h2>

<p>This panel allows the user to select a path similar to the installation path. Like the installation path, this panel will allow the directory to be created if it does not already exist. It can also be pre-loaded with a path and set to only display if a certain pack is selected using the following variables:</p>

<p>Messages for the UserPathPanel can be customized by creating a custom lang pack and overriding the following values (attribute values wrapped for readability):</p>

<h2>LoadPropertiesPanel</h2>

<p>This panel is a non-visible panel. It simply loads values from a properties file specified by the variable <code>load.properties.file</code> and sets them to their respective variables. The panel is designed to allow loading and setting variable values from an external resource at runtime. This maybe useful when values are unknown when the installer is built.</p>

<p>The <code>load.properties.file</code> variable is expected to be set before the panel is activated. For instance, the variable maybe specified through a file field on a <code>UserInputPanel</code> displayed prior to the <code>LoadPropertiesPanel</code>. Nothing is loaded if the variable is not set when the panel is activated.</p>

<p>An example use case for this panel would be an installer for an enterprise application deployed in multiple environments (e.g. UAT, Production, etc.) with each deployment requiring many environment-specific settings such as database information, application URL, etc. While several <code>UserInputPanel</code> instances can be used to prompt the user for data, it maybe impossible to set suitable default values for each different environments at the installer build time. Furthermore, it would be inconvenient and error-prone to have the user manually input all values into the panels.</p>

<p>One solution would be to have environment-specific properties files-<span style="text-decoration: line-through;">external to the installer</span>-for each environment. During installation, the user can then specify the path to the properties file on a <code>UserInputPanel</code> (which sets the <code>load.properties.file</code> variable) then have the values loaded by a <code>LoadPropertiesPanel</code>. The loaded values can be used to set the default values in another <code>UserInputPanel</code> for the user to inspect and modify, if required. Example:</p>

<p><strong>install.xml:</strong></p>

&lt;panels>
    (...)
    &lt;panel classname="UserInputPanel" id="userinputpanel.0"/>
    &lt;panel classname="LoadPropertiesPanel" id="loadpropertiespanel"/>
    &lt;panel classname="UserInputPanel" id="userinputpanel.1"/>
    (...)
&lt;/panels></pre></td></tr></table>
<p><strong>user_input_spec.xml:</strong></p>

<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>&lt;userInput>
    &lt;panel order="0">
        (...)
        &lt;field type="file" variable="load.properties.file">
            &lt;spec txt="Environment Properties File:" size="25" set=""/>
            &lt;str id="UserInputPanel.file.notfile.message" txt="The properties file you have chosen either does not exist or is not valid."/>
            &lt;str id="UserInputPanel.file.notfile.caption" txt="Invalid File"/>
            &lt;validator class="com.izforge.izpack.panels.userinput.validator.RegularExpressionValidator" txt="Invalid properties file!">
                &lt;param name="pattern" value=".*[.]properties|.*[.]PROPERTIES}"/>
            &lt;/validator>
        &lt;/field>
        (...)
    &lt;/panel>
    &lt;panel order="1">
        (...)
        &lt;field type="text" variable="db.host">
            &lt;spec txt="Database Host:" size="25" set="${DB_HOST}"/>
        &lt;/field>
        &lt;field type="text" variable="db.port">
            &lt;spec txt="Database Port:" size="25" set="${DB_PORT}"/>
        &lt;/field>
        &lt;field type="text" variable="db.username">
            &lt;spec txt="Database Username:" size="25" set="${DB_USERNAMES}"/>
        &lt;/field>
        (...)
    &lt;/panel>
&lt;/userInput></pre></td></tr></table>
<p><strong>Sample properties file for UAT environment:</strong></p>