Page tree
Skip to end of metadata
Go to start of metadata

Panels

Here you tell the compiler which panels you want to use. They will appear in the installer in the order in which they are listed in your XML installation file.

The section Built-in Panel Types introduces the various panels available in IzPack. The usage of each is described, and the panels are listed by their class name (this is the name that must be used with the classname attribute). 

Attributes

AttributeDescriptionRequired
classnameThe class name of the panel. The class name is case-sensitive. The compiler will throw an IllegalArgumentException if the class can not be found.. Yes
idA unique identifier for a panel which can be used to reference this panel in userinput panel definitions.No
conditionThe id of a condition that has to evaluate to true in order for this panel to appear. If this attribute is not specified. the panel is always shown.No
jarThe jar file where the classes for this panel can be found. If this attribute is empty or unspecified, the classes for this panel must be merged using the <jar> tag.No
allowClose

Determines whether confirmation is required when quitting the installer from this panel and panels defined before this panel. 

Set to "true" to allow the installer to be closed using the "Quit" or "Done" button without confirmation on this panel, but require confirmation on previous panels without this attribute. 

Set to "false" to prompt for confirmation when Quit or Done is pressed on this and previous panels without this attribute. 

If there is no "allowClose" attribute IzPack will exhibit its classic behavior, which is to prompt for confirmation until the files are copied unless the Previous and Next buttons are both disabled.

For example, to force confirmation when quitting from all but the last panel, specify allowClose="true" on the last and only the last panel, as seen in the following example.

Example
<panels>
  <panel classname="HTMLHelloPanel"/>
  <panel classname="HTMLInfoPanel"/>
  <panel classname="HTMLLicencePanel"/>
  <panel classname="TargetPanel"/>
  <panel classname="PacksPanel"/>
  <panel classname="InstallPanel"/>
  <panel classname="ShortcutPanel"/>
  <panel classname="SimpleFinishPanel" allowClose="true"/>
</panels>

Since: IzPack 5.0 RC5

No

Nested Elements 

Configuration

Specify optional, custom configuration parameters for a custom panel using the <configuration> element. Each parameter is specified using a nested <param> element, which must have both a name and a value attribute. 

Help

Specifies an optional help file for a panel. The contents of the help file is shown in a small window on the panel, when the user clicks on the Help button.

The help file text can contain HTML elements(<p>,<h1>,<ul>,<li>, etc.) to specify the format.

The button is only shown when a help for the language exists.

AttributeDescriptionRequired
iso3The ISO3 representation of the language in which the help is written.Yes
srcThe path to the help file to be displayed.Yes

Validator

Specifies an optional panel data validator. See the section Panel Validators.

Actions

Specifies one or more optional panel life-cycle actions.  See the section Panel Actions.

Examples

A panel with help files in German and English.
<panel classname="HelloPanel" id="hello"  condition="verbosemode">
  <help iso3="deu" src="HelloPanelHelp_deu.html" />
  <help iso3="eng" src="HelloPanelHelp_eng.html" />
</panel>

 

A typical selection of panels, including a panel with a condition and a panel invoking custom code contained in a jar file, with a custom configuration providing parameters to the "finishPanel" class. 

Basic selection of panels
<panels>
    <panel classname="HelloPanel">
      <help iso3="deu" src="HelloPanelHelp_deu.html" />
      <help iso3="eng" src="HelloPanelHelp_eng.html" />        
    </panel>
    <panel classname="LicencePanel"/>
    <panel classname="TargetPanel"/>
    <panel classname="InstallPanel"/>
    <panel classname="UserInputPanel" id="myuserinput" condition="pack2selected" />
    <panel classname="FinishPanel" jar="MyFinishPanel.jar">
      <configuration>
        <param name="MyParam1" value="some value"/>
        <param name="MyParam2" value="some other value"/>
      </configuration>
    </panel>
</panels>

 

A installation file showing the <panels> section in context.

Panel in the context of an installation specification
<installation version="5.0"
              xmlns:izpack="http://izpack.org/schema/installation"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://izpack.org/schema/installation http://izpack.org/schema/5.0/izpack-installation-5.0.xsd">

  <info>
    <appname>Test</appname>
    <appversion>0.0</appversion>
    <appsubpath>myapp</appsubpath>
    <javaver   sion>1.6</javaversion>
  </info>
  <resources>
    <res id="InfoPanel.info" src="doc/readme.txt" parse="yes"/>
    <res id="LicencePanel.licence" src="legal/License.txt"/>
  </resources> 

  <guiprefs width="800" height="600" resizable="no">
    <splash>images/peas_load.gif</splash>
    <laf name="substance">
      <os family="windows" />
      <os family="unix" />
      <param name="variant" value="mist-silver" />
    </laf>
    <laf name="substance">
      <os family="mac" />
      <param name="variant" value="mist-aqua" />
    </laf>
   <modifier key="useHeadingPanel" value="yes" />
 </guiprefs>

 <panels>
   <panel classname="HelloPanel">
      <help iso3="deu" src="HelloPanelHelp_deu.html" />
      <help iso3="eng" src="HelloPanelHelp_eng.html" />        
   </panel>
   <panel classname="LicencePanel"/>
   <panel classname="TargetPanel"/>
   <panel classname="InstallPanel"/>
   <panel classname="UserInputPanel" id="myuserinput" condition="pack2selected" />
   <panel classname="FinishPanel" jar="MyFinishPanel.jar">
     <configuration>
        <param name="MyParam1" value="some value"/>
        <param name="MyParam2" value="some other value"/>
      </configuration>
   </panel>
  </panels>
  ...

</installation>
  • No labels

8 Comments

  1. In allowClose it says "Default:unspecified"

    Above it says "If there is no "allowClose" attribute IzPack will exhibit its classic behavior, which is to prompt for confirmation until the files are copied unless the Previous and Next buttons are both disabled."

    Is "allowClose="" the case that the "Default:unspecified" note is supposed to cover?

    It seems that "Default:unspecified" could be removed.

    1. I removed this, thank you.

  2. What do I have to do, when I want to get the values of "MyParam1" and "MyParam2" in my own new Panel?

    1. This is a very good question for add-on developers, because it isn't that much documented and there is missing an example in the documentation. The only example is the IzPack source code itself (smile)

      Each panel is an implementation of com.izforge.izpack.api.data.Panel and implements the com.izforge.izpack.api.data.Configurable interface (by extending the dedicated com.izforge.izpack.api.handler.DefaultConfigurationHandler). You can therefore add parameters with any name to all panel s of each type.

      The Configurable interface (and its default implementation DefaultConfigurationHandler) describe how to read this parameters in the implementation of the panel class. It depends on the specific panel class whether it reads parameters and which parameters in particular.

      For an example for both, GUI and console installer mode, see:

      Everyone is invited to improve the according documentation.

  3. Thank your for this info. 

    Maybe i didn't find the info i needed, but what if want to perform an action after "Quit" has been pressed? is there a way to inject a handler or catch this event? or do you have any other idea how to handle this?

    thanks and greetings

    or let me answer in a better way, according to source you can add an ActionListener. I may implement my own ActionListener and then add this implementation into the created button, or is there a more comfortable way to achieve this?

  4. seems to be more complicated then i thought. Somehow i can't add a custom actionlisterner to the quit button? It's more like i need to alter IzPack code, which I don't want to do.

    On the other hand, it would be more or less hacky, because i'd expose in InstallerFrame the member "navigator" in order to set my own quit button with an own action listener.

    solution: called getInstallerFrame().getNavigator().setQuitVisible(false); , and then added my own JButton with an own listener.

    1. Hi Antonio, you can't bind ActionListeners to the navigation buttons. They are not the same like action listeners in Swing. IzPack "listeners" can be bound to packs only (phases beforepacks, beforepack, afterpack, afterpacks).

      One reason for this is that there are different modes an installer can run in, there are also a console mode (without any button), or several unattended modes. In each of these modes the installer must provide the same behavior.

      The implementation for this can be seen in the source code, com.izforge.izpack.installer.gui.DefaultNavigator. The default handler for these buttons is com.izforge.izpack.installer.gui.DefaultNavigator.NavigationHandler.

      As there can be seen already from the package names this is valid for the GUI installation mode, only.

      Update: I'm currently not aware whether it is currently easily possible to replace the DefaultNavigator completely by a custom implementation. The name indicates this has been probably the original intention when implementing it.

    2. solution: called getInstallerFrame().getNavigator().setQuitVisible(false); , and then added my own JButton with an own listener.

      As already mentioned, most probably this kind fo implementation breaks the other possible installation modes. This is only valid if you use your installer in GUI mode exclusively.