root / tags / v1_0_2_Build_899 / install / IzPack / src / doc / chapter3.tex @ 38379
History | View | Annotate | Download (7.43 KB)
1 | 5819 | cesar | % Chapter 3 |
---|---|---|---|
2 | \chapter{Advanced Features} |
||
3 | |||
4 | % Ant Integration |
||
5 | \section{Ant Integration} |
||
6 | \label{ant-integration} |
||
7 | |||
8 | \IzPack can be easily integrated inside an Ant build process. To do so you |
||
9 | first need to tell Ant that you would like to use \IzPack{}: |
||
10 | \footnotesize |
||
11 | \begin{verbatim} |
||
12 | <!-- Allows us to use the IzPack Ant task --> |
||
13 | <taskdef name="izpack" classpath="${basedir}/lib/compiler.jar" |
||
14 | classname="com.izforge.izpack.ant.IzPackTask"/> |
||
15 | \end{verbatim} |
||
16 | \normalsize |
||
17 | |||
18 | If you want to use the standalone compiler (and therefore don't need an |
||
19 | IzPack installation for building), the task needs to be defined as follows: |
||
20 | \footnotesize |
||
21 | \begin{verbatim} |
||
22 | <!-- Allows us to use the IzPack Ant task --> |
||
23 | <taskdef name="izpack" classpath="${basedir}/lib/standalone-compiler.jar" |
||
24 | classname="com.izforge.izpack.ant.IzPackTask"/> |
||
25 | \end{verbatim} |
||
26 | \normalsize |
||
27 | |||
28 | Don't forget to add \texttt{compiler.jar} or \texttt{standalone-compiler.jar} |
||
29 | to the classpath of the Ant process. |
||
30 | |||
31 | Then you can invoke \IzPack with the \texttt{izpack} task which takes the |
||
32 | following parameters: |
||
33 | \begin{itemize} |
||
34 | |||
35 | \item \texttt{input} : the XML installation file |
||
36 | \item \texttt{output} : the output jar installer file |
||
37 | \item \texttt{installerType} : optional. \texttt{standard} or |
||
38 | \texttt{web}. If \texttt{web}, the \texttt{<webdir>} attribute |
||
39 | must be specified in the input file (see |
||
40 | section~\ref{webinstaller}). Used to force creation of a standard |
||
41 | installer when the \texttt{<webdir>} attribute has been used. |
||
42 | \item \texttt{baseDir} : the base directory to resolve the relative paths |
||
43 | \item \texttt{izPackDir}: the \IzPack home directory. Only neccessary if |
||
44 | you do not use the standalone compiler. |
||
45 | |||
46 | \end{itemize}\ |
||
47 | |||
48 | Here is a sample of the task invocation:\\ |
||
49 | \footnotesize |
||
50 | \begin{verbatim} |
||
51 | <!-- We call IzPack --> |
||
52 | <echo message="Makes the installer using IzPack"/> |
||
53 | <izpack input="${dist.dir}/IzPack-install.xml" |
||
54 | output="${dist.dir}/IzPack-install.jar" |
||
55 | installerType="standard" |
||
56 | basedir="${dist.dir}" |
||
57 | izPackDir="${dist.dir}/"/> |
||
58 | \end{verbatim} |
||
59 | \normalsize |
||
60 | |||
61 | % System properties as variables |
||
62 | \section{System properties as variable} |
||
63 | |||
64 | All system properties are available as |
||
65 | \$SYSTEM\_<variable> where <variable> is the actual name \_BUT\_ with |
||
66 | all separators replaced by '\_'. Properties with null values |
||
67 | are never stored.\\ |
||
68 | |||
69 | Examples: |
||
70 | \begin{verbatim} |
||
71 | $SYSTEM_java_version or $SYSTEM_os_name |
||
72 | \end{verbatim} |
||
73 | |||
74 | % Automated Installers |
||
75 | \section{Automated Installers} |
||
76 | |||
77 | When you conclude your installation with a FinishPanel, the user can |
||
78 | save the data for an automatic installation. With this data, he will be |
||
79 | able to run the same installation on another similar machine. In an |
||
80 | environment where many computers need to be supported this can save |
||
81 | \textsl{a lot} of time.\\ |
||
82 | |||
83 | So run once the installation on a machine and save your automatic installation |
||
84 | data in \texttt{auto-install.xml} (that's just a sample). Then put this file in |
||
85 | the same directory as the installer on another machine. Run it with:\\ |
||
86 | \texttt{java -jar installer.jar auto-install.xml}\\ |
||
87 | |||
88 | It has reproduced the same installation :-)\\ |
||
89 | |||
90 | % Picture on the Language Selection Dialog |
||
91 | \section{Picture on the Language Selection Dialog} |
||
92 | |||
93 | You can add a picture on the language selection dialog by adding the following |
||
94 | resource : \texttt{installer.langsel.img}. \textsl{GIF}, \textsl{JPEG} and |
||
95 | \textsl{PNG} pictures are supported starting from J2SE 1.3.\\ |
||
96 | |||
97 | % Installer picture |
||
98 | \section{Picture in the installer} |
||
99 | |||
100 | It is possible to specify an optional picture to display on the left side of the |
||
101 | installer. To do this, you just have to define a resource whose id is |
||
102 | \texttt{Installer.image}. For instance, |
||
103 | \begin{verbatim} |
||
104 | <res id="Installer.image" src="nice-image.png" /> |
||
105 | \end{verbatim} |
||
106 | will do that. If the resource isn't specified, no picture will be displayed at |
||
107 | all. \textsl{GIF}, \textsl{JPEG} and |
||
108 | \textsl{PNG} pictures are supported starting from J2SE 1.3.\\ |
||
109 | |||
110 | You can also give a specific picture for a specific panel by using the |
||
111 | \texttt{Installer.image.n} resource names where $n$ is the panel index. For |
||
112 | instance if you want a specific picture for the third panel, use |
||
113 | \texttt{Installer.image.2} since the indexes start from 0.\\ |
||
114 | |||
115 | % Web Installers |
||
116 | \section{Web Installers} |
||
117 | \label{webinstaller} |
||
118 | |||
119 | The web installers allow your users to download a small installer that |
||
120 | does not contain the files to install. These files will be downloaded |
||
121 | from an HTTP server such as \textit{Apache HTTPD}. If you have many |
||
122 | optional packs, this can save people's resources. Its very easy: |
||
123 | people download a small Jar file containing the installer, they launch |
||
124 | it and choose their packages. Then the installer will get the required |
||
125 | packages from individual Jar files located on a server, only |
||
126 | downloading those required. It's that simple.\\ |
||
127 | |||
128 | To create a web installer, add the \texttt{<webdir>} element to the |
||
129 | \texttt{<info>} element (see section~\ref{info-element}). The text must |
||
130 | be a valid, fully qualified URL for a direcory on the web server.\\ |
||
131 | |||
132 | \footnotesize |
||
133 | \begin{verbatim} |
||
134 | <info> |
||
135 | <appname>Super extractor</appname> |
||
136 | <appversion>2.1 beta 6</appversion> |
||
137 | <url>http://www.superextractor.com/</url> |
||
138 | <webdir>http://www.superextractor.com/download</url> |
||
139 | </info> |
||
140 | \end{verbatim} |
||
141 | \normalsize |
||
142 | |||
143 | You can force creation of a standard installer even if \texttt{webdir} |
||
144 | is specified, by specifically creating a \texttt{standard} installer |
||
145 | from the command line invocation or ant task (see |
||
146 | \label{ant-integration}). |
||
147 | |||
148 | When installing, if the user is behind a firewall, attempting download |
||
149 | the jar files may fail. If this happens, the user will be prompted to |
||
150 | enter the name hostname and port of their firewall. |
||
151 | |||
152 | You may password protect the files using mechanisms provided by your |
||
153 | web server, IzPack will prompt for a password at install time, when |
||
154 | required. |
||
155 | |||
156 | % More Internationalization |
||
157 | \section{More Internationalization} |
||
158 | |||
159 | \subsection{Special resources} |
||
160 | |||
161 | IzPack is available in several languages. However you might want to |
||
162 | internationalize some additional parts of your installer. In particular you |
||
163 | might want this for the *InfoPanel and *LicencePanel. This is actually pretty |
||
164 | easy to do. You just have to add one resource per localization, suffixed with the |
||
165 | ISO3 language code. At runtime these panels will try to load a localized version.\\ |
||
166 | |||
167 | For instance let's suppose that we use a HTMLInfoPanel. Suppose that we have it |
||
168 | in English, French and German. We want to have a French text for french users. |
||
169 | Here we add a resource pointing to the French text whose name is |
||
170 | \texttt{HTMLInfoPanel.info\_fra}. And that's it ! English and German users (or |
||
171 | anywhere other than in France) will get the default text (denoted by |
||
172 | \texttt{HTMLInfoPanel.info}) and the French users will get the French version. |
||
173 | Same thing for the other Licence and Info panels.\\ |
||
174 | |||
175 | \noindent |
||
176 | \textit{To sum up :} add \texttt{\_<iso3 code>} to the resource name for |
||
177 | \texttt{InfoPanel}, \texttt{HTMLInfoPanel}, \texttt{LicencePanel} and |
||
178 | \texttt{HTMLLicencePanel}.\\ |
||
179 | |||
180 | \subsection{Packs} |
||
181 | |||
182 | Thanks to Thorsten Kamann, it is possible to translate the packs names and |
||
183 | descriptions. To do that, you have to define a special identifier in the |
||
184 | elements of the XML installation file and add the related entries in the |
||
185 | suitable langpacks. For instance if you have the following XML snippet: |
||
186 | \begin{verbatim} |
||
187 | <pack name="core" id="core.package" ...> |
||
188 | <description/> |
||
189 | </pack> |
||
190 | \end{verbatim} |
||
191 | then the related entries of the langpacks will look like this: |
||
192 | \begin{verbatim} |
||
193 | <str id="core.package" txt="Core Package"/> |
||
194 | <str id="core.package.description" txt="The core package provides |
||
195 | \end{verbatim} |