Shortcut Specification

The specification for application shortcuts is provided to the Shortcut Panel in the XML file format. It must be referred in the <resources> section by a resource definition with the ID "shortcutSpec.xml":

<res id="shortcutSpec.xml" src="my-installer-files/shortcutSpec.xml/>

All contents in the referred file must be nested to the following root element:

<izpack:shortcuts version="5.0"
                  xmlns:izpack="http://izpack.org/schema/shortcuts"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xsi:schemaLocation="http://izpack.org/schema/shortcuts http://izpack.org/schema/5.0/izpack-shortcuts-5.0.xsd">

...
</izpack:shortcuts>

Nested Elements

defaultCurrentUser

The <defaultCurrentUser/> tags has no attributes or content. Makes create shortcut for: current user the default selection on the Shortcut Panel. If not specified, then all users will be the default selection (if available).

skipIfNotSupported

The <skipIfNotSupported/> tag has no attributes or content. It suppresses the default behavior on systems not supported by Shortcut Panel, forcing the installer to completely skip the display of Shortcut Panel. (The default behavior is to show an alternative UI, which displays the shortcut information that would have been created on a supported system.)

notSupported

The <notSupported/> tag has no attributes or content. Allows you to review what an end user would see if the target operating system is not supported by forcing the Shortcut Panel to behave as though running on an unsupported system.

This tag is for testing purposes only. Be sure to remove this tag before preparing your installer for production.

lateShortcutInstall

The <lateShortcutInstall/> tag has no attributes or content. Delays the creation of shortcuts until after all packs have been installed (instead of creating shortcuts as soon as 'Next' is clicked). Specify this if you want to show ShortcutPanel before InstallPanel.

previousDisabled

The <previousDisabled/> tag has no attributes or content. Specify this if you want to disable the previous navigation button for this panel. (Since: IzPack 5.1.3)

programGroup

Allows you to specify the name of the menu, or more precisely the folder, in which the shortcuts will be grouped. The exact location and appearance of the program group depends on the specific target system on which the application will be installed. This can be partially controlled by the location parameter.

Attribute Description Required

defaultName Specifies the name that the group menu should have on the target system. You should be aware that the Shortcut Panel will present this name to the user as a choice. The user can then edit this name, or select a group that already exists. No, but recommended; default is blank.

location

Specifies where the group menu should be displayed in the desktop menu. There are two choices:

applications: the group menu will be placed in the menu that is ordinarily used for application shortcuts
startMenu: the group menu will be placed at the top-most menu level available on the target system

On Unix-based systems, the applications location is already on the highest level, so setting any other value will have no effect. Depending on the target system, it might not be possible to honor this specification exactly. In such cases, the Shortcut Panel will map the choice to the location that most closely resembles your choice.

No; default is applications.

installGroup When using the Installation Group Panel, multiple programGroup elements can be specified, each defining this attribute with the name of the applicable installation group. A custom programGroup can be defined for each installation group, but Shortcut Panel will still only create one progam group folder. If no programGroup spec has an installGroup attribute matching the selected installation group name, the first defined programGroup will be used. If multiple programGroup tags with the same installGroup attribute are defined, the first will be used and all others ignored. No.

If more than one instance of <programGroup> is specified without the use of the Installation Group Panel and the installGroup parameter, only the first one will be used - all other <programGroup> tags will be ignored.

shortcut

For each shortcut you want to create, you have to add one <shortcut> tag. The attributes can be divided into two groups:

attributes that describe properties of the shortcut
attributes that define the location(s) at which a copy of the shortcut should be placed.

The attributes listed in this table are mostly common to all platforms, but some are not valid or sensible on all operating systems. These cases are noted. Additional, OS-specific attributes, are listed below.

Attribute	Description	Required
name	The name that the shortcut will have. This is the text that makes up the menu name if the shortcut is placed in a menu or the caption that is displayed with the shortcut if it is placed on the desktop.	Yes
target	The application that should be launched when the shortcut is clicked. The value is translated through the variable substitutor, so variables such as `$INSTALL_PATH` can be used in the path. Use of this attribute may change once other operating systems are supported.	Yes
commandLine	Specifies command line arguments to pass to the `target` through the shortcut. Command line arguments are not supported by all operating systems. As a result, your applications will not be portable if they depend on command line arguments. Instead, consider using system properties or configuration files. See Shortcut Tips on command line arguments.	No
workingDirectory	Defines the working directory for the application at the time it is launched. Exercise caution in relying on this too heavily if your application should be portable, since this might not be supported by all operating systems. The value is translated through the variable substitutor, so variables such as `$INSTALL_PATH` can be used to describe the directory.	No
description	The value of this attribute will be visible to the user when a brief description about associated application is requested. The form of the request and the way in which this description is displayed varies between operating systems. On Windows, the description is shown as a tool tip when the mouse cursor hovers over the icon for a few seconds. On some operating systems this feature might not be supported.	No
iconFile	A file that holds the icon that should be displayed as a symbol for this shortcut. This value is translated through the variable substitutor, so variables such as `$INSTALL_PATH` can be used. If this attribute is omitted, no icon will be specified for the shortcut. Usually this causes the OS to display an OS-supplied default icon. Use of this attribute may change once other operating systems are supported. See Shortcut Tips on shortcut icons.	No
iconIndex	If the file type for the icon supports multiple icons in one file, then this attribute may be used to specify the correct index for the icon. In file formats that do not support multiple icons, this value is ignored. This is only likely to be useful for Windows shortcuts, if the icon is in a multiple-icon ICO, or embedded in a DLL or EXE file. See Shortcut Tips on shortcut icons.	No
initialState	If the target operating system supports this feature, then this value will set the initial window state of the application. Valid options are: `normal` `minimized (`not valid on Unix `maximized` (not valid on Unix) `noShow`(not valid on Unix) The `noShow` option is particularly useful when launching batch scripts on Windows, as no command window will be visible with this option. For instance, a shortcut to a batch file that launches a Java application has the less-than-pretty side effect that two windows show: the DOS command prompt and the Java application window. Even if the shortcut is configured to show `minimized`, there will be buttons for both windows in the task bar. Using `noShow` will completely eliminate this effect, only the Java application window will be visible.	No; default is `normal`
programGroup	If the value is `true`, then a copy of this shortcut will be placed in the group menu (see programGroup). On Unix (KDE) this will always be placed on the top level.	At least one location attribute is required, as all default to `false`. If no location attribute is `true`, the shortcut will not be displayed anywhere. If multiple locations attributes are `true`, a copy of the shortcut will be displayed in all of those locations.
desktop	If the value is `true`, then a copy of the shortcut is placed on the desktop. On Unix the shortcuts will only be placed on the KDE desktop of the user currently running the installer. For Gnome the user can simply copy the `.desktop` files from `*/Desktop` to `/gnome-desktop`.
applications	If the value is `true`, then a copy of the shortcut is placed in the applications menu (if the target operating system supports this). This is the same location as the `applications` choice for the `programGroup` element. Setting `applications="true"` is equivalent to setting `programGroup="true"` on Unix.
startMenu	If the value is `true`, then a copy of the shortcut is placed directly in the top most menu that is available for placing application shortcuts. This is not supported on Unix.
startup	If the value is `true`, then a copy of the shortcut is placed in a location where all applications get automatically started at OS launch time, if this is available on the target OS. This is not supported on Unix.
subgroup	Specifies a sub-path (i.e. a sub-folder) of the main program group in which this shortcut will be placed. This is not supported on Unix.	No; has no effect unless `programGroup` is `true`.
condition	Specifies the name of an installer condition that must evaluate to true for this shortcut to be created. If the condition does not exist, the shortcut is created.	No

Unix-specific attributes

These attributes apply only to Unix-based systems (including Linux).

Attribute	Description	Required
type	Specifies the type of shortcut. Valid values are: Application Creates a shortcut to start any application (native, Java, or shell-script). The GUI-System will launch this Application through its native shell or application launcher. In this case, note that the right `workingDirectory` is always important on Unix platforms. If the user's PATH environment variable does not contain the application path, this application will not run unless `workingDirectory` specifies the application path. The "current path" placeholder (i.e. '`.`') must exist on the PATH, as is the case by default on most systems. Consult the Unix manuals for more details. Link Creates a shortcut to open a URL in the user's default web browser. In this case, the `url` attribute must be set.	Yes
url	Specifies a locally installed HTML file, other file with a known MIME type (e.g. plain text), or a WWW URL (e.g. `http://izpack.org/`). This value is translated through the variable substitutor, so variables such as `$INSTALL_PATH` (for local documents) can be used.	Yes, if `type=link`
mimetype	Specifies the MIME type for links pointing to local files when using `type=link`.	No; recommended if `type=link` and `url` points to a local file.
encoding	This should always set to `UTF-8`.	Yes
terminal	Set to `true` to allow the user to see the console output of a program (e.g. in Java applications "System.out").	No; defaults to `false`.
terminalOptions	Specifies attributes for terminal windows when `terminal=true` (see man pages for `setterm`).	No
KdeSubstUID	This is the sudo option for a shortcut. If set to `true`, you will be asked for the password of the `KdeUsername`.	No; defaults to `false`.
KdeUsername	The username with correct sudo permissions where `KdeSubstUID` is `true`. This is `root` in most cases.	No; defaults to `root`.
createForAll	If a user with administrative rights, such as root, performs the installation, set to `true` to make this shortcut appear to other users as well as root.	No; defaults to `false`.
categories	The category in the Desktop Application Menu where the shortcut will be placed. Here are some sample categories and their apps. For more examples, examine the desktop files in `/usr/share/applications` in the target environment. Categories="Application;Network;WebDevelopment;" - Nvu Categories="Qt;Development;GUIDesigner;" - QtDesigner3 Categories="Application;System;" - VMwareServer-console Categories="Network;WebBrowser;" - Opera Categories="Development;Debugger;" - DDD debugger Categories="Development;IDE;" - Eclipse IDE Categories="SystemSetup;X-SuSE-Core-System;" - Yast2 Categories="System;Archiving;" - Sesam archiving Categories="System;Database;" - MySQL Administrator	No; no default.
tryexec	Specifies a command to pass through 'raw' to the operating system.	No; default is to use `target` and (where present) `commandLine`

Windows-specific attributes

These attributes apply only to Windows-based systems.

Attribute	Description	Required
runAsAdministrator	Determines if the target of the shortcut should be run with administrator privileges (since 5.0.0-rc1)	No; defaults to `false`.

createForPack

This is an optional nested element, with one required attribute, name, specifying the name of a pack that must be selected for this shortcut to be created. Multiple <createForPack> elements can be nested in the same <shortcut>.

<createForPack name="Pack 1" />
<createForPack name="Pack 2"/>