root / trunk / install / IzPack / doc / izpack / html / node8.html @ 11445
History | View | Annotate | Download (45.1 KB)
1 | 5819 | cesar | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
---|---|---|---|
2 | |||
3 | <!--Converted with LaTeX2HTML 2002-2-1 (1.70)
|
||
4 | original version by: Nikos Drakos, CBLU, University of Leeds
|
||
5 | * revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
|
||
6 | * with significant contributions from:
|
||
7 | Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
|
||
8 | <HTML>
|
||
9 | <HEAD>
|
||
10 | <TITLE>User Input</TITLE> |
||
11 | <META NAME="description" CONTENT="User Input"> |
||
12 | <META NAME="keywords" CONTENT="izpack-doc"> |
||
13 | <META NAME="resource-type" CONTENT="document"> |
||
14 | <META NAME="distribution" CONTENT="global"> |
||
15 | |||
16 | <META NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1"> |
||
17 | <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css"> |
||
18 | |||
19 | <LINK REL="STYLESHEET" HREF="izpack-doc.css"> |
||
20 | |||
21 | <LINK REL="next" HREF="node9.html"> |
||
22 | <LINK REL="previous" HREF="node7.html"> |
||
23 | <LINK REL="up" HREF="izpack-doc.html"> |
||
24 | <LINK REL="next" HREF="node9.html"> |
||
25 | </HEAD>
|
||
26 | |||
27 | <BODY > |
||
28 | |||
29 | <DIV CLASS="navigation"><!--Navigation Panel--> |
||
30 | <A NAME="tex2html479" |
||
31 | HREF="node9.html"> |
||
32 | <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A> |
||
33 | <A NAME="tex2html475" |
||
34 | HREF="izpack-doc.html"> |
||
35 | <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A> |
||
36 | <A NAME="tex2html469" |
||
37 | HREF="node7.html"> |
||
38 | <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A> |
||
39 | <A NAME="tex2html477" |
||
40 | HREF="node1.html"> |
||
41 | <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A> |
||
42 | <BR>
|
||
43 | <B> Next:</B> <A NAME="tex2html480" |
||
44 | HREF="node9.html">Custom Actions</A> |
||
45 | <B> Up:</B> <A NAME="tex2html476" |
||
46 | HREF="izpack-doc.html">izpack-doc</A> |
||
47 | <B> Previous:</B> <A NAME="tex2html470" |
||
48 | HREF="node7.html">Creating Your Own Panels</A> |
||
49 | <B> <A NAME="tex2html478" |
||
50 | HREF="node1.html">Contents</A></B> |
||
51 | <BR>
|
||
52 | <BR></DIV> |
||
53 | <!--End of Navigation Panel-->
|
||
54 | <!--Table of Child-Links-->
|
||
55 | <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A> |
||
56 | |||
57 | <UL CLASS="ChildLinks"> |
||
58 | <LI><A NAME="tex2html481" |
||
59 | HREF="node8.html#SECTION00810000000000000000">The Basic XML Structure</A> |
||
60 | <LI><A NAME="tex2html482" |
||
61 | HREF="node8.html#SECTION00820000000000000000">Concepts and XML Elements Common to All Fields</A> |
||
62 | <LI><A NAME="tex2html483" |
||
63 | HREF="node8.html#SECTION00830000000000000000">Internationalization</A> |
||
64 | <LI><A NAME="tex2html484" |
||
65 | HREF="node8.html#SECTION00840000000000000000">Panel Title</A> |
||
66 | <LI><A NAME="tex2html485" |
||
67 | HREF="node8.html#SECTION00850000000000000000">Static Text</A> |
||
68 | <LI><A NAME="tex2html486" |
||
69 | HREF="node8.html#SECTION00860000000000000000">Visual Separation</A> |
||
70 | <LI><A NAME="tex2html487" |
||
71 | HREF="node8.html#SECTION00870000000000000000">Text Input</A> |
||
72 | <LI><A NAME="tex2html488" |
||
73 | HREF="node8.html#SECTION00880000000000000000">Radio Buttons</A> |
||
74 | <LI><A NAME="tex2html489" |
||
75 | HREF="node8.html#SECTION00890000000000000000">Combo Box</A> |
||
76 | <LI><A NAME="tex2html490" |
||
77 | HREF="node8.html#SECTION008100000000000000000">Check Box</A> |
||
78 | <LI><A NAME="tex2html491" |
||
79 | HREF="node8.html#SECTION008110000000000000000">Rule Input</A> |
||
80 | <UL>
|
||
81 | <LI><A NAME="tex2html492" |
||
82 | HREF="node8.html#SECTION008111000000000000000">Layout and Input Rules</A> |
||
83 | <LI><A NAME="tex2html493" |
||
84 | HREF="node8.html#SECTION008112000000000000000">Setting Field Content</A> |
||
85 | <LI><A NAME="tex2html494" |
||
86 | HREF="node8.html#SECTION008113000000000000000">The Output Format</A> |
||
87 | <LI><A NAME="tex2html495" |
||
88 | HREF="node8.html#SECTION008114000000000000000">Validating the Field Content</A> |
||
89 | <UL>
|
||
90 | <LI><A NAME="tex2html496" |
||
91 | HREF="node8.html#SECTION008114100000000000000">NotEmptyValidator</A> |
||
92 | <LI><A NAME="tex2html497" |
||
93 | HREF="node8.html#SECTION008114200000000000000">RegularExpressionValidator</A> |
||
94 | <LI><A NAME="tex2html498" |
||
95 | HREF="node8.html#SECTION008114300000000000000">Creation Your Own Custom Validator</A> |
||
96 | </UL>
|
||
97 | <LI><A NAME="tex2html499" |
||
98 | HREF="node8.html#SECTION008115000000000000000">Processing the Field Content</A> |
||
99 | <LI><A NAME="tex2html500" |
||
100 | HREF="node8.html#SECTION008116000000000000000">Summary Example</A> |
||
101 | </UL>
|
||
102 | <BR>
|
||
103 | <LI><A NAME="tex2html501" |
||
104 | HREF="node8.html#SECTION008120000000000000000">Search</A> |
||
105 | <UL>
|
||
106 | <LI><A NAME="tex2html502" |
||
107 | HREF="node8.html#SECTION008121000000000000000">Specification</A> |
||
108 | <LI><A NAME="tex2html503" |
||
109 | HREF="node8.html#SECTION008122000000000000000">Example</A> |
||
110 | </UL></UL> |
||
111 | <!--End of Table of Child-Links-->
|
||
112 | <HR>
|
||
113 | |||
114 | <H1><A NAME="SECTION00800000000000000000"></A><A NAME="chap:userinput"></A> |
||
115 | <BR>
|
||
116 | User Input |
||
117 | </H1> (by Elmar G<SMALL>ROM</SMALL>) |
||
118 | <BR>
|
||
119 | <P>
|
||
120 | Most of the panels that come with IzPack take user input in some form. |
||
121 | In some panels this is through a simple user acknowledgment in others |
||
122 | the user can enter text or select a directory through a file open |
||
123 | dialog. In all of those cases the user input is used for the specific |
||
124 | purpose needed by the panel that takes the input. However, if you need |
||
125 | user input during installation that will later on be available to your |
||
126 | application then you need to use the user input panel. |
||
127 | <BR>
|
||
128 | <P>
|
||
129 | To use this panel, list it in the install file with the class name |
||
130 | <TT>UserInputPanel</TT>. In addition, you must write a XML specification |
||
131 | and add it to the install resources. The name of this resource must be |
||
132 | <TT>userInputSpec.xml</TT>. |
||
133 | <BR>
|
||
134 | <P>
|
||
135 | The user input panel is a blank panel that can be populated with UI |
||
136 | elements through a XML specification file. The specification supports |
||
137 | text labels, input elements, explanatory text and some minor formatting |
||
138 | options. |
||
139 | <BR>
|
||
140 | <P>
|
||
141 | The following types of user input elements are supported: |
||
142 | |||
143 | <UL>
|
||
144 | <LI>Text
|
||
145 | </LI>
|
||
146 | <LI>Combo Box
|
||
147 | </LI>
|
||
148 | <LI>Radio Buttons
|
||
149 | </LI>
|
||
150 | <LI>Check Box
|
||
151 | </LI>
|
||
152 | <LI>Rule Input Field
|
||
153 | </LI>
|
||
154 | <LI>Search Field
|
||
155 | </LI>
|
||
156 | </UL>
|
||
157 | <P>
|
||
158 | The way in which this panel conveys the user input to your application |
||
159 | is through the variable substitution system. User input is not directly |
||
160 | inserted into your configuration files but the variables that you |
||
161 | specify for this panel are set in the variable substitution system. |
||
162 | After this operation has taken place the variables and associated values |
||
163 | are available for all substitutions made. This way of operation has a |
||
164 | number of implications that you should be aware of. |
||
165 | <BR>
|
||
166 | <P>
|
||
167 | First, not only can you set additional variables in this way but you can |
||
168 | also modify variables that are defined elsewhere -even built in |
||
169 | variables. For this reason you should be careful to avoid overlaps when |
||
170 | choosing variable names. Although there might be cases when it seems |
||
171 | useful to modify the value of other variables, it is generally not a |
||
172 | good idea to do so. Because you might not exactly know when other |
||
173 | variables are set and when and where they are used throughout the |
||
174 | installation process, there might be unintended side effects. |
||
175 | <BR>
|
||
176 | <P>
|
||
177 | Second, the panel must be shown at a point during the installation |
||
178 | process before the variables are used. In most cases you will use the |
||
179 | values to substitute variables in launch and configuration files that |
||
180 | you supply with your installation. For this to work you place this panel |
||
181 | before the install panel, because the install panel uses the variable |
||
182 | substitutor to replace all such variables. Although using this panel any |
||
183 | later in the process will correctly set the variables internally, there |
||
184 | won't be any affect on the files written to disk. You can also use |
||
185 | variables set in this way in other panels that you have written |
||
186 | yourself. There is a section in the chapter on writing your own panel |
||
187 | that explains how to do this. Also in this case it is important to place |
||
188 | the associated input panel in the process before the variables are |
||
189 | used. |
||
190 | <BR>
|
||
191 | <P>
|
||
192 | At this point I would also like to mention that it is possible to hide |
||
193 | select elements on the panel or the panel altogether if certain packs |
||
194 | are not selected. For this to work you must place this panel after the |
||
195 | packs panel. One side effect of using this feature is that it is not |
||
196 | possible to step back once the user input panel is displayed. This is |
||
197 | because the user might make changes in the packs selection that would |
||
198 | require a complete rebuild of the UI. Unfortunately, building the UI is |
||
199 | an irreversible process, therefore the user can not be allowed to go |
||
200 | back to the packs panel. |
||
201 | <BR>
|
||
202 | <P>
|
||
203 | |||
204 | <H1><A NAME="SECTION00810000000000000000"> |
||
205 | The Basic XML Structure</A>
|
||
206 | </H1>
|
||
207 | |||
208 | <P>
|
||
209 | The top level XML section is called <TT><userInput></TT>. For most |
||
210 | panels it does not make sense to present them more than once, however |
||
211 | you might want to present multiple user input panels -with different |
||
212 | content of course. Therefore the <TT><userInput></TT> section can |
||
213 | contain multiple tags that each specify the details for one panel |
||
214 | instance. The tag name for this is <TT><panel></TT>. |
||
215 | <BR>
|
||
216 | <P>
|
||
217 | The <TT><panel></TT> tag uses the following attributes: |
||
218 | <BR>
|
||
219 | <P>
|
||
220 | <SPAN CLASS="textbf">order</SPAN> <TT>- required</TT> |
||
221 | <BR>
|
||
222 | <P>
|
||
223 | This is the order number of the user input panel for which this |
||
224 | specification should be used. Counting starts at 0 and increments by 1 |
||
225 | for each instance of the user input panel. So if a spec should be used |
||
226 | for the second occurrence of the user input panel use |
||
227 | <TT>order="1"</TT>. |
||
228 | <BR>
|
||
229 | <P>
|
||
230 | <SPAN CLASS="textbf">layout</SPAN> <TT>- optional</TT> |
||
231 | <BR>
|
||
232 | <P>
|
||
233 | There are three general layout rules this panel uses, they are |
||
234 | <TT>left</TT>, <TT>center</TT> and <TT>right</TT>. While I think left is |
||
235 | most commonly used, you might want to experiment with this attribute and |
||
236 | see which you like best. The default is <TT>left</TT>. |
||
237 | <BR>
|
||
238 | <P>
|
||
239 | |||
240 | <H1><A NAME="SECTION00820000000000000000"> |
||
241 | Concepts and XML Elements Common to All Fields</A>
|
||
242 | </H1>
|
||
243 | |||
244 | <P>
|
||
245 | Before I dive into the details of defining the various UI elements I |
||
246 | would like to present XML elements and general concepts that apply |
||
247 | throughout. This saves me a lot of work in writing and you a lot of |
||
248 | repetitive reading and maybe a tree or two. |
||
249 | <BR>
|
||
250 | <P>
|
||
251 | The UI elements are generally laid out top to bottom in the order they |
||
252 | appear in the XML file. The only exception to this rule is the title, |
||
253 | which always appears at the very top. The layout pattern for the input |
||
254 | fields is as follows: If a description is defined, it appears first, |
||
255 | using the full available layout width. The input field is placed beneath |
||
256 | the description. With fields such as the text field or the combo box, |
||
257 | the label is placed to the left and the input field to the right. Fields |
||
258 | such as radio buttons and check boxes are somewhat indented and have the |
||
259 | label text appear to their right. |
||
260 | <BR>
|
||
261 | <P>
|
||
262 | Each UI element is specified with a <TT><field></TT> tag. The |
||
263 | <TT>type</TT> attribute is used to specify what kind of field you want |
||
264 | to place. Obviously, the <TT>type</TT> attribute is not optional. |
||
265 | <BR>
|
||
266 | <P>
|
||
267 | Each field that takes user input must also specify the variable that |
||
268 | should be substituted. This is done with the <TT>variable</TT> |
||
269 | attribute. |
||
270 | <BR>
|
||
271 | <P>
|
||
272 | <A NAME="userInput:descriptiontag"></A>Almost all fields allow a description. When a description is allowed it |
||
273 | is always added in the same way. The description is part of the data |
||
274 | within the field tag. There can only be one description per field. If |
||
275 | you add more than one, the first one is used and the others ignored. |
||
276 | There are three attributes used with this tag. The text is specified |
||
277 | through the <TT>txt</TT> or the <TT>id</TT> attribute. The details on |
||
278 | using them are described below. The attributes are all optional but you |
||
279 | must specify text to use, either directly or through the <TT>id</TT> |
||
280 | attribute. In addition, you can set the text justification to |
||
281 | <TT>left</TT>, <TT>center</TT> and <TT>right</TT> with the |
||
282 | <TT>align</TT> attribute. |
||
283 | <BR>
|
||
284 | <P>
|
||
285 | The following example illustrates the general pattern for field specification: |
||
286 | <BR>
|
||
287 | <P>
|
||
288 | <PRE>
|
||
289 | <field type="text" variable="myFirstVariable"> |
||
290 | <description align="left" txt="A description" id="description 1"/> |
||
291 | . |
||
292 | . |
||
293 | . |
||
294 | </field> |
||
295 | </PRE>
|
||
296 | <P>
|
||
297 | A very frequently used pattern is for the definition of text. Where ever |
||
298 | text is needed (labels, descriptions, static text, choices etc.) it can |
||
299 | be specified in place using the <TT>txt</TT> attribute. This is |
||
300 | convenient if you are only supporting a single language. However, if you |
||
301 | would like to separate your text definitions from the panel |
||
302 | specification or if you need to support multiple languages you might |
||
303 | want to use the <TT>id</TT> attribute instead to only specify an |
||
304 | identifier. You can then add multiple XML files with the same name as |
||
305 | this spec file (userInputSpec.xml) appended with an unserscore '_' and |
||
306 | the the appropriate three letter ISO3 language code. The content of |
||
307 | those files must conform to the specification for IzPack language |
||
308 | packages. For more details on this topic see the chapter on language |
||
309 | packages under advanced features. <TT>id</TT> defines an identifier that |
||
310 | is also defined in the language package, together with the localized |
||
311 | text to use. It is possible to use both the <TT>txt</TT> and the |
||
312 | <TT>id</TT> attribute. In this case the text from the language package |
||
313 | is used. If for some reason the language package is not available or the |
||
314 | <TT>id</TT> is not defined there, the text specified with <TT>txt</TT> |
||
315 | is used as default. |
||
316 | <BR>
|
||
317 | <P>
|
||
318 | All input fields can be pre-set with a value of your choice. Although |
||
319 | the details vary a bit from field type to field type, the <TT>set</TT> |
||
320 | attribute is always used to accomplish this. The <TT>set</TT> attribute |
||
321 | is of course optional. |
||
322 | <BR>
|
||
323 | <P>
|
||
324 | All fields that take user input use a <TT><spec></TT> tag to define the |
||
325 | details of the input field. In the some cases the content of this tag is |
||
326 | rather simple. Input fields with a more complex nature tend to have |
||
327 | accordingly complex content in this tag. Since the details vary widely, |
||
328 | they are explained with each input field. |
||
329 | <BR>
|
||
330 | <P>
|
||
331 | Any number of <TT><createForPack name=''a pack name'' /></TT> tags can be |
||
332 | added to the <TT><panel></TT> and <TT><field></TT> sections. This tag |
||
333 | has only one attribute and no data. The attribute is <TT>name</TT> and |
||
334 | specifies the name of one of the installation packs that you have |
||
335 | defined. Here is how it works: if no <TT><createForPack ...></TT> tag |
||
336 | exists in a section, the entity is always created. However, if the tag |
||
337 | exists, the entity is only created if one or more of the listed packs |
||
338 | are selected for installation. As mentioned before, if you are using |
||
339 | this feature, make sure the user input panel shows up after the packs |
||
340 | panel. |
||
341 | <BR>
|
||
342 | <P>
|
||
343 | |||
344 | <H1><A NAME="SECTION00830000000000000000"> |
||
345 | Internationalization</A>
|
||
346 | </H1>
|
||
347 | |||
348 | <P>
|
||
349 | To provide internationalization you can create a file named |
||
350 | <TT>userInputLang.xml_xyz</TT> where <TT>xyz</TT> is the ISO3 code of the language |
||
351 | in lowercase. Please be aware that case is significant. This file has to be inserted in the resources section |
||
352 | of <TT>install.xml</TT> with the <TT>id</TT> and <TT>src</TT> attributes |
||
353 | set at the name of the file. |
||
354 | <BR>
|
||
355 | <P>
|
||
356 | Example: |
||
357 | <BR>
|
||
358 | <P>
|
||
359 | If you have the following userInputSpec.xml |
||
360 | and you want to internationalize <TT>input.comment</TT>, <TT>input.proxy</TT>, <TT>input.port</TT> for |
||
361 | english and french you have to create two files named userInputLang.xml_eng and userInputLang.xml_fra: |
||
362 | <PRE>
|
||
363 | <userInput> |
||
364 | <panel order="0"> |
||
365 | <field type="staticText" align="left" txt="My comment is here." id="input.comment"/> |
||
366 | <field type="text" variable="proxyAddress"> |
||
367 | <spec txt="Proxy Host:" id="input.proxy" size="25" set=""/> |
||
368 | </field> |
||
369 | <field type="text" variable="proxyPort"> |
||
370 | <spec txt="Proxy Port:" id="input.port" size="6" set=""/> |
||
371 | </field> |
||
372 | </panel> |
||
373 | </userInput> |
||
374 | </PRE>
|
||
375 | |||
376 | <P>
|
||
377 | userInputLang.xml_eng file contains: |
||
378 | <PRE>
|
||
379 | <langpack> |
||
380 | <str id="input.comment" txt="English:My comment is here."/> |
||
381 | <str id="input.proxy" txt="English:Proxy Host:"/> |
||
382 | <str id="input.port" txt="English:Proxy Port:"/> |
||
383 | </langpack> |
||
384 | </PRE>
|
||
385 | |||
386 | <P>
|
||
387 | userInputLang.xml_fra file contains: |
||
388 | <PRE>
|
||
389 | <langpack> |
||
390 | <str id="input.comment" txt="French:My comment is here."/> |
||
391 | <str id="input.proxy" txt="French:Proxy Host:"/> |
||
392 | <str id="input.port" txt="French:Proxy Port:"/> |
||
393 | </langpack> |
||
394 | </PRE>
|
||
395 | |||
396 | <P>
|
||
397 | you will also have to add the following to the install.xml file |
||
398 | <PRE>
|
||
399 | <resources> |
||
400 | ... |
||
401 | <res id="userInputSpec.xml" src="userInputSpec.xml"/> |
||
402 | <res id="userInputLang.xml_eng" src="userInputLang.xml_eng" /> |
||
403 | <res id="userInputLang.xml_fra" src="userInputLang.xml_fra" /> |
||
404 | ... |
||
405 | </resources> |
||
406 | </PRE>
|
||
407 | |||
408 | <P>
|
||
409 | |||
410 | <H1><A NAME="SECTION00840000000000000000"> |
||
411 | Panel Title</A>
|
||
412 | </H1>
|
||
413 | |||
414 | <P>
|
||
415 | You can place an optional title at the top of the panel. Though it is |
||
416 | not possible to select a font for the title that is different form the |
||
417 | one used on the rest of the panel, it is possible to modify the font to |
||
418 | some extent. To specify the title create a <TT><field></TT> tag and use |
||
419 | the <TT>type</TT> attribute with the value <TT>title</TT>. In addition |
||
420 | to the <TT>txt</TT> and <TT>id</TT> attributes, the following attributes |
||
421 | are supported: |
||
422 | <BR>
|
||
423 | <P>
|
||
424 | <SPAN CLASS="textbf">italic</SPAN> <TT>- optional</TT> |
||
425 | <BR>
|
||
426 | <P>
|
||
427 | With a value of <TT>true</TT> specifies that the title font should be in italics. |
||
428 | <BR>
|
||
429 | <P>
|
||
430 | <SPAN CLASS="textbf">bold</SPAN> <TT>- optional</TT> |
||
431 | <BR>
|
||
432 | <P>
|
||
433 | With a value of <TT>true</TT> specifies that the title font should be bold. |
||
434 | <BR>
|
||
435 | <P>
|
||
436 | <SPAN CLASS="textbf">size</SPAN> <TT>- optional</TT> |
||
437 | <BR>
|
||
438 | <P>
|
||
439 | This attribute specifies the size of the title font. Please note that |
||
440 | the size is not specified in points but as a relative size multiplier |
||
441 | compared to the body font on the panel. The default value is 2. |
||
442 | <BR>
|
||
443 | <P>
|
||
444 | |||
445 | <H1><A NAME="SECTION00850000000000000000"> |
||
446 | Static Text</A>
|
||
447 | </H1>
|
||
448 | |||
449 | <P>
|
||
450 | Static text is simply text that is placed on the panel without direct |
||
451 | connection to any of the input elements. It is laid out to use the |
||
452 | entire layout width available on the panel and is broken into multiple |
||
453 | lines if necessary. To specify static text create a <TT><field></TT> tag |
||
454 | and use the <TT>type</TT> attribute with a value of <TT>staticText</TT>. |
||
455 | In addition to the <TT>txt</TT> and <TT>id</TT> attributes, the text can |
||
456 | be justified <TT>left</TT>, <TT>center</TT> or <TT>right</TT> with the |
||
457 | <TT>align</TT> attribute. It is not possible to format this text in any way. |
||
458 | <BR>
|
||
459 | <P>
|
||
460 | <SPAN CLASS="textbf">Example</SPAN> |
||
461 | <BR>
|
||
462 | <P>
|
||
463 | The following example inserts some static text in the panel. |
||
464 | |||
465 | <P>
|
||
466 | <PRE>
|
||
467 | <field type="staticText" align="left"
|
||
468 | txt="This is just some simple static text." |
||
469 | id="staticText.text"/>
|
||
470 | </PRE>
|
||
471 | <P>
|
||
472 | |||
473 | <H1><A NAME="SECTION00860000000000000000"> |
||
474 | Visual Separation</A>
|
||
475 | </H1>
|
||
476 | |||
477 | <P>
|
||
478 | Sometimes it is desirable to separate different entities visually. This |
||
479 | can be accomplished by inserting a space or a divider. A space simply |
||
480 | inserts a vertical separation of the average height of a single line |
||
481 | entity, such as a line of text or a an input field. A divider inserts |
||
482 | the same amount of space but also draws a division line which can be |
||
483 | either aligned at the top or bottom of the separation. |
||
484 | <TT><space></TT>, <TT><divider></TT> |
||
485 | |||
486 | <P>
|
||
487 | ..... maybe I should draw the line myself and add no additional space at all ... |
||
488 | |||
489 | <P>
|
||
490 | |||
491 | <H1><A NAME="SECTION00870000000000000000"> |
||
492 | Text Input</A>
|
||
493 | </H1>
|
||
494 | |||
495 | <P>
|
||
496 | A text input field allows the user to enter and edit a single line of |
||
497 | text, without length restriction. The input field can have a label, |
||
498 | which will show to the left of the input field and a description, which |
||
499 | can span multiple lines. The description is placed above the input field |
||
500 | and uses the entire available layout width. The width of the input field |
||
501 | must be explicitly set, otherwise it will only accommodate a single |
||
502 | character. To specify a text input field create a <TT><field></TT> tag |
||
503 | and use the <TT>type</TT> attribute with a value of <TT>text</TT>. The |
||
504 | <TT>txt</TT> and <TT>id</TT> attributes are not supported here. The |
||
505 | <TT>variable</TT> attribute specifies the variable that should be |
||
506 | replaced with the text taken from the input field. |
||
507 | <BR>
|
||
508 | <P>
|
||
509 | <SPAN CLASS="textbf">The Data</SPAN> |
||
510 | <BR>
|
||
511 | <P>
|
||
512 | The data consists of two items, a description and the spec. The |
||
513 | <TT><spec></TT> tag uses four attributes. The label text is specified with |
||
514 | <TT>txt</TT> and/or <TT>id</TT> as described above. In addition, the |
||
515 | width of the input field as it appears on the panel can be set with the |
||
516 | <TT>size</TT> attribute. The value must be an integer and sets the field |
||
517 | width based on the average character width of the active font. If this |
||
518 | is not specified, then you will end up with a very narrow field that is |
||
519 | practically unusable. |
||
520 | <BR>
|
||
521 | <P>
|
||
522 | The fourth attribute <TT>set</TT> is optional. It takes a text string to |
||
523 | pre-fill the input field. |
||
524 | <BR>
|
||
525 | <P>
|
||
526 | <SPAN CLASS="textbf">Example</SPAN> |
||
527 | <BR>
|
||
528 | <P>
|
||
529 | The following example creates a text input field with a label and |
||
530 | description. The width of the input field will be enough to accommodate |
||
531 | 15 characters. The field will be pre-set with the text 'some text' when |
||
532 | the UI is first presented. |
||
533 | <BR>
|
||
534 | <P>
|
||
535 | <PRE>
|
||
536 | <field type="text" variable="textInput"> |
||
537 | <description align="left" txt="A description for a text input field"
|
||
538 | id="description.text"/>
|
||
539 | <spec txt="Enter some text:" id="text.label" size="15" set="some text"/> |
||
540 | </field> |
||
541 | </PRE>
|
||
542 | <P>
|
||
543 | |||
544 | <H1><A NAME="SECTION00880000000000000000"> |
||
545 | Radio Buttons</A>
|
||
546 | </H1>
|
||
547 | |||
548 | <P>
|
||
549 | The radio buttons are useful when the user needs to select a specific |
||
550 | option out of a pre-defined list of choices. This field offers an |
||
551 | arbitrary number of mutually exclusive buttons, each with its own label. |
||
552 | The placement of the buttons and labels is different form other fields. |
||
553 | First, the button is placed to the left and the label text to the right. |
||
554 | Second, the buttons are not lined up all the way to the left as other |
||
555 | labels are but they are indented from that location. As with other |
||
556 | fields, the description is placed above the list of radio buttons and |
||
557 | uses the entire available layout width. To specify a set of radio |
||
558 | buttons create a <TT><field></TT> tag and use the <TT>type</TT> |
||
559 | attribute with a value of <TT>radio</TT>. The <TT>txt</TT> and |
||
560 | <TT>id</TT> attributes are <SPAN CLASS="textbf">not</SPAN> supported here. As with all |
||
561 | other input fields, the <TT>variable</TT> attribute specifies that |
||
562 | variable that should be replaced with the user selection. |
||
563 | <BR>
|
||
564 | <P>
|
||
565 | <SPAN CLASS="textbf">The Data</SPAN> |
||
566 | <BR>
|
||
567 | <P>
|
||
568 | The data consists of two items, a description and the spec. The |
||
569 | <TT><spec></TT> tag has no attributes, instead the specification details |
||
570 | are entered as data within the <TT><spec></TT> tag. The <TT><spec></TT> |
||
571 | data consists of one or more <TT><choice></TT> tags. One |
||
572 | <TT><choice></TT> tag is required for each radio button. The |
||
573 | <TT><choice></TT> tag accepts the usual <TT>txt</TT> and <TT>id</TT> |
||
574 | attributes, which are used to specify the label text. In addition the |
||
575 | following attributes are supported: |
||
576 | <BR>
|
||
577 | <P>
|
||
578 | <SPAN CLASS="textbf">value</SPAN> <TT>- required</TT> |
||
579 | <BR>
|
||
580 | <P>
|
||
581 | The <TT>value</TT> attribute is used to specify which value to insert if |
||
582 | this associated radio button is selected. In other words, the label text |
||
583 | has nothing to do with the value that is actually substituted for the |
||
584 | variable. For this reason there is never an issue if multiple languages |
||
585 | are used, the value is always the same for a given selection. |
||
586 | <BR>
|
||
587 | <P>
|
||
588 | <SPAN CLASS="textbf">set</SPAN> <TT>- optional</TT> |
||
589 | <BR>
|
||
590 | <P>
|
||
591 | The <TT>set</TT> attribute accepts the values <TT>true</TT> and |
||
592 | <TT>false</TT>. Since the attribute is optional it can also be omitted, |
||
593 | which is interpreted as <TT>false</TT>. If a value of <TT>true</TT> is |
||
594 | used, the associated radio button will be selected when the UI is first |
||
595 | presented. Obviously, only one of the buttons in a set should be set to |
||
596 | <TT>true</TT>. |
||
597 | <BR>
|
||
598 | <P>
|
||
599 | <SPAN CLASS="textbf">Example</SPAN> |
||
600 | <BR>
|
||
601 | <P>
|
||
602 | The following example creates a set of four radio buttons with |
||
603 | description. The second button will be selected when the UI is first |
||
604 | presented. |
||
605 | <BR>
|
||
606 | <P>
|
||
607 | <PRE>
|
||
608 | <field type="radio" variable="radioSelection"> |
||
609 | <description align="left" txt="This is a description for radio buttons"
|
||
610 | id="description.radio"/>
|
||
611 | <spec> |
||
612 | <choice txt="the first choice" id="radio.label.1" value="1 selected" /> |
||
613 | <choice txt="the second choice" id="radio.label.2" value="2 selected"
|
||
614 | set="true" />
|
||
615 | <choice txt="the third choice" id="radio.label.3" value="3 selected" /> |
||
616 | <choice txt="the fourth choice" id="radio.label.4" value="4 selected" /> |
||
617 | </spec> |
||
618 | </field> |
||
619 | </PRE>
|
||
620 | <P>
|
||
621 | |||
622 | <H1><A NAME="SECTION00890000000000000000"> |
||
623 | Combo Box</A>
|
||
624 | </H1>
|
||
625 | |||
626 | <P>
|
||
627 | The combo box provides essentially the same functionality as do the |
||
628 | radio buttons, just in a different presentation stile. The advantage of |
||
629 | the combo box is that it is easier to deal with a long list of |
||
630 | choices. |
||
631 | <BR>
|
||
632 | <P>
|
||
633 | |||
634 | <H1><A NAME="SECTION008100000000000000000"> |
||
635 | Check Box</A>
|
||
636 | </H1>
|
||
637 | |||
638 | <P>
|
||
639 | If there are a number of choices and any combination of them could be |
||
640 | selected, not just a single one, then radio buttons are not the way to |
||
641 | go. You might be better off using a number of check boxes. The layout |
||
642 | for a check box works in the same way as for radio buttons. The check |
||
643 | box is placed indented from the left most edge and the label text is |
||
644 | placed to the right of it. Other than with radio buttons, you cannot |
||
645 | define any number of check boxes. This field allows the definition of |
||
646 | only one check box, which is associated with one variable. If you need |
||
647 | multiple check boxes you need to define one field for each of them. To |
||
648 | make it look like a cohesive group you simply provide a description only |
||
649 | for the first check box. All of the check boxes will be positioned in |
||
650 | such a way that they look like a group, even though they are separate |
||
651 | entities and their selections are conveyed to different variables. The |
||
652 | description is placed above the check box and uses the entire available |
||
653 | layout width. To specify a check box create a <TT><field></TT> tag and |
||
654 | use the <TT>type</TT> attribute with a value of <TT>check</TT>. As with |
||
655 | all other input fields, the <TT>variable</TT> attribute specifies the |
||
656 | variable that should be replaced with the user input. |
||
657 | <BR>
|
||
658 | <P>
|
||
659 | <SPAN CLASS="textbf">The Data</SPAN> |
||
660 | <BR>
|
||
661 | <P>
|
||
662 | The data consists of two items, a description and the spec. The |
||
663 | <TT><spec></TT> tag accepts the usual <TT>txt</TT> and <TT>id</TT> |
||
664 | attributes, which are used to specify the label text. In addition, the |
||
665 | following attributes are supported: |
||
666 | <BR>
|
||
667 | <P>
|
||
668 | <SPAN CLASS="textbf">true</SPAN> <TT>- required</TT> |
||
669 | <BR>
|
||
670 | <P>
|
||
671 | The <TT>true</TT> attribute specifies the value to use for substitution |
||
672 | when the box is selected. |
||
673 | <BR>
|
||
674 | <P>
|
||
675 | <SPAN CLASS="textbf">false</SPAN> <TT>- required</TT> |
||
676 | <BR>
|
||
677 | <P>
|
||
678 | The <TT>false</TT> attribute specifies the value to use for substitution |
||
679 | when the box is not selected. |
||
680 | <BR>
|
||
681 | <P>
|
||
682 | <SPAN CLASS="textbf">set</SPAN> <TT>- optional</TT> |
||
683 | <BR>
|
||
684 | <P>
|
||
685 | The <TT>set</TT> attribute accepts the values <TT>true</TT> and |
||
686 | <TT>false</TT>. Since the attribute is optional it can also be omitted, |
||
687 | which is interpreted as <TT>false</TT>. If a value of <TT>true</TT> is |
||
688 | used, the check box will be selected when the UI is first presented. |
||
689 | <BR>
|
||
690 | <P>
|
||
691 | <SPAN CLASS="textbf">Example</SPAN> |
||
692 | <BR>
|
||
693 | <P>
|
||
694 | The following example creates a check box with description. The check |
||
695 | box will not be selected when the UI is first presented. This could also |
||
696 | be accomplished by omitting the <TT>set</TT> attribute. |
||
697 | <BR>
|
||
698 | <P>
|
||
699 | <PRE>
|
||
700 | <field type="check" variable="chekSelection.1"> |
||
701 | <description align="left" txt="This is a description for a check box"
|
||
702 | id="description.check.1"/>
|
||
703 | <spec txt="check box 1" id="check.label.1" true="on" false="off"
|
||
704 | set="false"/>
|
||
705 | </field> |
||
706 | </PRE>
|
||
707 | <P>
|
||
708 | |||
709 | <H1><A NAME="SECTION008110000000000000000"> |
||
710 | Rule Input</A>
|
||
711 | </H1>
|
||
712 | |||
713 | <P>
|
||
714 | The rule input field is the most powerful and complex one of all the |
||
715 | input fields offered by this panel. In its most simple incarnation it |
||
716 | looks and works like a regular text input field. There is also only an |
||
717 | incremental increase of the complexity in the specification for this |
||
718 | case. However, it is unlikely that you would use it for such a purpose. |
||
719 | The real power of this input field comes from the fact that rules can be |
||
720 | applied to it that control many aspects of its look as well as overt and |
||
721 | covert operation. |
||
722 | <BR>
|
||
723 | <P>
|
||
724 | |||
725 | <H2><A NAME="SECTION008111000000000000000"> |
||
726 | Layout and Input Rules</A>
|
||
727 | </H2>
|
||
728 | |||
729 | <P>
|
||
730 | The basic nature of this input field is that of a text input field and |
||
731 | as mentioned before, in its most simple incarnation that is what it |
||
732 | looks like and how it operates. However, the layout of the field can be |
||
733 | defined in such a way that there are multiple logically interconnected |
||
734 | text input fields, adorned with multiple labels. Further more, each of |
||
735 | these fields can be instructed to restrict the type of input that will |
||
736 | be accepted. Now you might ask what this could be useful for. As an |
||
737 | answer, let me present a few examples that show how this feature can be |
||
738 | used. Before I do this however, I would like to describe the |
||
739 | specification syntax, so that the examples can be presented together |
||
740 | with the specifications that make them work in a meaningful way. |
||
741 | <BR>
|
||
742 | <P>
|
||
743 | The actual specification of the layout, the labels and the type of input |
||
744 | each field accepts all happens in a single string with the |
||
745 | <TT>layout</TT> attribute. First let us have a look at the specification |
||
746 | format for a single field. This format consists of a triplet of |
||
747 | information, separated by two colons ':'. A typical field spec would |
||
748 | look like this: <TT>N:4:4</TT>, where the first item is a key that |
||
749 | specifies the type of input this particular field will accept - numeric |
||
750 | input in the example. The second item is an integer number that |
||
751 | specifies the physical width of the field, this is the same as in the |
||
752 | with of any regular text field. Therefore the field in the example will |
||
753 | provide space to display four characters. The third item specifies the |
||
754 | editing length of the string or in other words, the maximum length of |
||
755 | the string that will be accepted by the field. In the <TT>layout</TT> |
||
756 | string you can list as may fields as you need, each with its own set of |
||
757 | limitations. In addition you can add text at the front, the end and in |
||
758 | between the fields. The various entities must be separated by white |
||
759 | space. The behavior of this field is such that when the editing length |
||
760 | of a field has been reached, the cursor automatically moves on to the |
||
761 | next field. Also, when the backspace key is used to delete characters |
||
762 | and the beginning of a field has been reached, the cursor automatically |
||
763 | moves on to the previous field. So let us have a look a some examples. |
||
764 | <BR>
|
||
765 | <P>
|
||
766 | <SPAN CLASS="textbf">Phone Number</SPAN> |
||
767 | |||
768 | <P>
|
||
769 | The following specification will produce a pre formatted input field to |
||
770 | accept a US phone number with in-house extension. Even though the |
||
771 | pattern is formatted into number groups as customary, complete with |
||
772 | parentheses '(' and dash '-', entering the number is as simple as typing |
||
773 | all the digits. There is no need to advance using the tab key or to enter |
||
774 | formatting characters. Because the fields only allow numeric entry, there |
||
775 | is a much reduced chance for entering erroneous information. |
||
776 | <TT>"( N:3:3 ) N:3:3 - N:4:4 x N:5:5"</TT>. Each of the fields uses the |
||
777 | 'N' key, indicating that only numerals will be accepted. Also, each of |
||
778 | the fields only accepts strings of the same length as the physical width |
||
779 | of the field. |
||
780 | <BR>
|
||
781 | <P>
|
||
782 | <DIV ALIGN="CENTER"> |
||
783 | <!-- MATH
|
||
784 | $\fbox{\includegraphics[scale=1.0]{img/userInput-phone}}$
|
||
785 | -->
|
||
786 | <SPAN CLASS="MATH"><IMG |
||
787 | WIDTH="332" HEIGHT="122" ALIGN="MIDDLE" BORDER="0" |
||
788 | SRC="img7.png" |
||
789 | ALT="\fbox{\includegraphics[scale=1.0]{img/userInput-phone}}"></SPAN> |
||
790 | </DIV>
|
||
791 | |||
792 | <P>
|
||
793 | <SPAN CLASS="textbf">E-Mail Address</SPAN> |
||
794 | |||
795 | <P>
|
||
796 | This specification creates a pattern that is useful for entering an |
||
797 | e-mail address <TT>"AN:15:U @ AN:10:40 . A:4:4"</TT>. Even though the |
||
798 | first field is only fifteen characters wide it will accept a string of |
||
799 | unlimited length, because the 'U' identifier is used for the edit |
||
800 | length. The second field is a bit more restrictive by only accepting a |
||
801 | string up to forty characters long. |
||
802 | <BR>
|
||
803 | <P>
|
||
804 | <DIV ALIGN="CENTER"> |
||
805 | <!-- MATH
|
||
806 | $\fbox{\includegraphics[scale=1.0]{img/userInput-email}}$
|
||
807 | -->
|
||
808 | <SPAN CLASS="MATH"><IMG |
||
809 | WIDTH="453" HEIGHT="131" ALIGN="MIDDLE" BORDER="0" |
||
810 | SRC="img8.png" |
||
811 | ALT="\fbox{\includegraphics[scale=1.0]{img/userInput-email}}"></SPAN> |
||
812 | </DIV>
|
||
813 | |||
814 | <P>
|
||
815 | <SPAN CLASS="textbf">IP Address</SPAN> |
||
816 | |||
817 | <P>
|
||
818 | It might not be uncommon to require entering of an IP address. The |
||
819 | following simple specification will produce the necessary input field. |
||
820 | All fields are the same, allowing just three digits of numerical entry. |
||
821 | <TT>"N:3:3 . N:3:3 . N:3:3 . N:3:3"</TT> |
||
822 | <BR>
|
||
823 | <P>
|
||
824 | <DIV ALIGN="CENTER"> |
||
825 | <!-- MATH
|
||
826 | $\fbox{\includegraphics[scale=1.0]{img/userInput-IP}}$
|
||
827 | -->
|
||
828 | <SPAN CLASS="MATH"><IMG |
||
829 | WIDTH="281" HEIGHT="131" ALIGN="MIDDLE" BORDER="0" |
||
830 | SRC="img9.png" |
||
831 | ALT="\fbox{\includegraphics[scale=1.0]{img/userInput-IP}}"></SPAN> |
||
832 | </DIV>
|
||
833 | |||
834 | <P>
|
||
835 | <SPAN CLASS="textbf">Serial Number or Key Code</SPAN> |
||
836 | |||
837 | <P>
|
||
838 | If you ship your product with a CD key code or serial number and require |
||
839 | this information for registration, you might want to ask the customer to |
||
840 | transcribe that number from the CD label, so that it is later on |
||
841 | accessible to your application. As this is always an error prone |
||
842 | operation, the predefined pattern with the easy editing support and |
||
843 | restriction of accepted data helps to reduce transcription errors |
||
844 | <TT>"H:4:4 - N:6:6 - N:3:3"</TT>. This particular specification will |
||
845 | produce three fields, the first accepting four hexadecimal, the second |
||
846 | six numerical and the third three numerical digits. |
||
847 | <BR>
|
||
848 | <P>
|
||
849 | <DIV ALIGN="CENTER"> |
||
850 | <!-- MATH
|
||
851 | $\fbox{\includegraphics[scale=1.0]{img/userInput-serial}}$
|
||
852 | -->
|
||
853 | <SPAN CLASS="MATH"><IMG |
||
854 | WIDTH="265" HEIGHT="131" ALIGN="MIDDLE" BORDER="0" |
||
855 | SRC="img10.png" |
||
856 | ALT="\fbox{\includegraphics[scale=1.0]{img/userInput-serial}}"></SPAN> |
||
857 | </DIV>
|
||
858 | |||
859 | <P>
|
||
860 | <SPAN CLASS="textbf">Limitations</SPAN> |
||
861 | |||
862 | <P>
|
||
863 | Even though the above examples all use single character labels between |
||
864 | fields, there is no restriction on the length of these labels. In |
||
865 | addition, it is possible to place label text in front of the first field |
||
866 | and after the last field and the text can even contain spaces. The only |
||
867 | limitation in this regard is the fact that all white space in the text |
||
868 | will be reduced to a single space on the display. This means that it is |
||
869 | not possible to use multiple spaces or tabs in the text. |
||
870 | <BR>
|
||
871 | <P>
|
||
872 | The following table lists and describes all the keys that can be used in |
||
873 | the specification string. |
||
874 | <BR>
|
||
875 | <P>
|
||
876 | <DIV ALIGN="CENTER"> |
||
877 | <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%"> |
||
878 | <TR><TH ALIGN="LEFT"><SPAN CLASS="textit">Key</SPAN></TH> |
||
879 | <TH ALIGN="LEFT"><SPAN CLASS="textit">Meaning</SPAN></TH> |
||
880 | <TH ALIGN="LEFT"><SPAN CLASS="textit">Description</SPAN></TH> |
||
881 | </TR>
|
||
882 | <TR><TD ALIGN="LEFT">N</TD> |
||
883 | <TD ALIGN="LEFT">numeric</TD> |
||
884 | <TD ALIGN="LEFT">The field will accept only numerals.</TD> |
||
885 | </TR>
|
||
886 | <TR><TD ALIGN="LEFT">H</TD> |
||
887 | <TD ALIGN="LEFT">hexadecimal</TD> |
||
888 | <TD ALIGN="LEFT">The field will accept only hexadecimal numerals, that is all numbers from 0-F.</TD> |
||
889 | </TR>
|
||
890 | <TR><TD ALIGN="LEFT">A</TD> |
||
891 | <TD ALIGN="LEFT">alphabetic</TD> |
||
892 | <TD ALIGN="LEFT">The field will accept only alphabetic characters. Numerals and punctuation marks will not be accepted.</TD> |
||
893 | </TR>
|
||
894 | <TR><TD ALIGN="LEFT">AN</TD> |
||
895 | <TD ALIGN="LEFT">alpha-numeric</TD> |
||
896 | <TD ALIGN="LEFT">The field will accept alphabetic characters and numerals but no punctuation marks.</TD> |
||
897 | </TR>
|
||
898 | <TR><TD ALIGN="LEFT">O</TD> |
||
899 | <TD ALIGN="LEFT">open</TD> |
||
900 | <TD ALIGN="LEFT">The filed will accept any input, without restriction.</TD> |
||
901 | </TR>
|
||
902 | <TR><TD ALIGN="LEFT">U</TD> |
||
903 | <TD ALIGN="LEFT">unlimited</TD> |
||
904 | <TD ALIGN="LEFT">This key is only legal for specifying the editing length of a fields. If used, the field imposes no length restriction on the text entered.</TD> |
||
905 | </TR>
|
||
906 | </TABLE>
|
||
907 | </DIV>
|
||
908 | |||
909 | <P>
|
||
910 | |||
911 | <H2><A NAME="SECTION008112000000000000000"> |
||
912 | Setting Field Content</A>
|
||
913 | </H2>
|
||
914 | |||
915 | <P>
|
||
916 | Like all other input fields the rule input field can also be pre-filled |
||
917 | with data and as usual, this is accomplished thought the <TT>set</TT> |
||
918 | attribute. As you might expect, the details of setting this field are |
||
919 | rather on the complicated side. In fact you can set each sub field |
||
920 | individually and you can leave some of the fields blank in the process. |
||
921 | The <TT>set</TT> specification for all sub fields is given in a single |
||
922 | string. Each field is addressed by its index number, with the count |
||
923 | starting at 0. The index is followed by a colon ':' and then by the |
||
924 | content of the field. The string "0:1234 1:af415 3:awer" would fill the |
||
925 | first subfield with <TT>1234</TT>, the second one with <TT>af415</TT> and |
||
926 | the fourth with <TT>awer</TT>. The third subfield would stay blank |
||
927 | and so would any additional fields that might follow. |
||
928 | <BR>
|
||
929 | <P>
|
||
930 | The individual field specs must be separated with spaces. Spaces within |
||
931 | the pre-fill values are not allowed, otherwise the result is undefined. |
||
932 | <BR>
|
||
933 | <P>
|
||
934 | |||
935 | <H2><A NAME="SECTION008113000000000000000"> |
||
936 | The Output Format</A>
|
||
937 | </H2>
|
||
938 | |||
939 | <P>
|
||
940 | The user input from all subfields is combined into one single value and |
||
941 | used to replace the variable associated with the field. You can make a |
||
942 | number of choices when it comes to the way how the subfield content is |
||
943 | combined. This is done with the <TT>resultFormat</TT> and |
||
944 | <TT>separator</TT> attributes. The <TT>resultFormat</TT> attribute can |
||
945 | take the following values: |
||
946 | <BR>
|
||
947 | <P>
|
||
948 | <DIV ALIGN="CENTER"> |
||
949 | <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%"> |
||
950 | <TR><TH ALIGN="LEFT"><SPAN CLASS="textit">Value</SPAN></TH> |
||
951 | <TH ALIGN="LEFT"><SPAN CLASS="textit">Meaning</SPAN></TH> |
||
952 | </TR>
|
||
953 | <TR><TD ALIGN="LEFT"><TT>plainString</TT></TD> |
||
954 | <TD ALIGN="LEFT">The content of all subfields is simply concatenated into one long string.</TD> |
||
955 | </TR>
|
||
956 | <TR><TD ALIGN="LEFT"><TT>displayFormat</TT></TD> |
||
957 | <TD ALIGN="LEFT">The content of all subfields and all labels -as displayed- is concatenated into one long string.</TD> |
||
958 | </TR>
|
||
959 | <TR><TD ALIGN="LEFT"><TT>specialSeparator</TT></TD> |
||
960 | <TD ALIGN="LEFT">The content of all subfields is concatenated into one string, using the string specified withe the <TT>separator</TT> attribute to separate the content of the subfields.</TD> |
||
961 | </TR>
|
||
962 | <TR><TD ALIGN="LEFT"><TT>processed</TT></TD> |
||
963 | <TD ALIGN="LEFT">The content is processed by Java code that you supply before replacing the variable. How to do this is described below.</TD> |
||
964 | </TR>
|
||
965 | </TABLE>
|
||
966 | </DIV>
|
||
967 | |||
968 | <P>
|
||
969 | |||
970 | <H2><A NAME="SECTION008114000000000000000"> |
||
971 | Validating the Field Content</A>
|
||
972 | </H2>
|
||
973 | |||
974 | <P>
|
||
975 | You can provide runtime validation for user input into a rule field via the |
||
976 | <TT>validator</TT> element (which is a child of the <TT>field</TT> element. |
||
977 | There are two types of built-in validators already provided: a |
||
978 | <TT>NotEmptyValidator</TT> and a <TT>RegularExpressionValidator</TT>. You can |
||
979 | also easily create your own validator. In all cases, if the chosen validator |
||
980 | returns <TT>false</TT>, a messagebox will display the contents of the |
||
981 | <TT>txt</TT> attribute and the user will be unable to continue to the next panel. |
||
982 | <BR>
|
||
983 | <P>
|
||
984 | You can specify a processor for a combobox: |
||
985 | <PRE>
|
||
986 | <choice processor="fully.qualified.class.name"
|
||
987 | set="selectedValue"/>
|
||
988 | </PRE>
|
||
989 | so that you can fill a combobox with data on a simple way. |
||
990 | |||
991 | <P>
|
||
992 | |||
993 | <H3><A NAME="SECTION008114100000000000000"> |
||
994 | NotEmptyValidator</A>
|
||
995 | </H3>
|
||
996 | |||
997 | <P>
|
||
998 | The <TT>NotEmptyValidator</TT> simply checks that the user entered a non-null |
||
999 | value into each subfield, and returns <TT>false</TT> otherwise. |
||
1000 | <BR>
|
||
1001 | <P>
|
||
1002 | |||
1003 | <H3><A NAME="SECTION008114200000000000000"> |
||
1004 | RegularExpressionValidator</A>
|
||
1005 | </H3>
|
||
1006 | |||
1007 | <P>
|
||
1008 | The <TT>RegularExpressionValidator</TT> checks that the user entered a |
||
1009 | value which matches a specified regular expression, as accepted by the Jakarta |
||
1010 | Regexp library |
||
1011 | (<TT><A NAME="tex2html28" |
||
1012 | HREF="http://jakarta.apache.org/regexp/">http://jakarta.apache.org/regexp/</A></TT>). The syntax of this implementation |
||
1013 | is described in the javadoc of the <TT>RE</TT> class |
||
1014 | (<TT><A NAME="tex2html29" |
||
1015 | HREF="http://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.html">http://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.html</A></TT>). |
||
1016 | |||
1017 | <P>
|
||
1018 | You can specify the regular |
||
1019 | expression to be tested by passing a parameter with a name of <TT>pattern</TT> |
||
1020 | to the validator (via the <TT>param</TT> element), with the regular expression |
||
1021 | as the <TT>value</TT> attribute. For example, the following would validate |
||
1022 | an e-mail address: |
||
1023 | <BR>
|
||
1024 | <P>
|
||
1025 | <PRE>
|
||
1026 | <field type="rule" variable="EMAILADDRESS"> |
||
1027 | <spec
|
||
1028 | txt="Your Email Address:" layout="O:12:U @ O:8:40 . A:4:4" |
||
1029 | set="0: 1:domain 2:com" resultFormat="displayFormat" |
||
1030 | />
|
||
1031 | <validator class="com.izforge.izpack.util.RegularExpressionValidator"
|
||
1032 | txt="Invalid email address!">
|
||
1033 | <param
|
||
1034 | name="pattern" |
||
1035 | value="[a-zA-Z0-9._-]{3,}@[a-zA-Z0-9._-]+([.][a-zA-Z0-9_-]+)*[.][a-zA-Z0-9._-]{2,4}" |
||
1036 | />
|
||
1037 | </validator> |
||
1038 | </field> |
||
1039 | </PRE>
|
||
1040 | <P>
|
||
1041 | You can test your own regular expressions using the handy applet at |
||
1042 | <TT><A NAME="tex2html30" |
||
1043 | HREF="http://jakarta.apache.org/regexp/applet.html">http://jakarta.apache.org/regexp/applet.html</A></TT> . |
||
1044 | <BR>
|
||
1045 | <P>
|
||
1046 | |||
1047 | <H3><A NAME="SECTION008114300000000000000"> |
||
1048 | Creation Your Own Custom Validator</A>
|
||
1049 | </H3>
|
||
1050 | |||
1051 | <P>
|
||
1052 | You can create your own custom Validator implementation simply by creating a |
||
1053 | new class which implements the <TT>com.izforge.izpack.panels.Validator</TT> |
||
1054 | interface. This interface specifies a single method: |
||
1055 | <TT>validate(ProcessingClient client)</TT> , which returns a <TT>boolean</TT> |
||
1056 | value. You can retrieve the value entered by the user by casting the input |
||
1057 | ProcessingClient as a <TT>RuleInputField</TT> and calling the |
||
1058 | <BR><TT>RuleInputField.getText()</TT> method. You can also retrieve any |
||
1059 | parameters to your custom <TT>Validator</TT> by calling the |
||
1060 | <BR><TT>RuleInputField.getValidatorParams()</TT> which returns a <TT>java.util.Map</TT> |
||
1061 | object containing parameter names mapped to parameter values. For an example, take a |
||
1062 | look at |
||
1063 | <BR><TT>com.izforge.izpack.util.RegularExpressionValidator</TT>. |
||
1064 | <BR>
|
||
1065 | <P>
|
||
1066 | Set values in the RuleInputField can be preprocessed. At now you can specify a |
||
1067 | processor class to pre process a value to be set at initial value of a |
||
1068 | RuleInputField. Syntax: |
||
1069 | <PRE>
|
||
1070 | <spec set="0:defaultVal:classname" .../> |
||
1071 | </PRE>
|
||
1072 | The class name is an optional value. The class must implement the |
||
1073 | <TT>Processor</TT> interface. |
||
1074 | <BR>
|
||
1075 | <P>
|
||
1076 | |||
1077 | <H2><A NAME="SECTION008115000000000000000"> |
||
1078 | Processing the Field Content</A>
|
||
1079 | </H2>
|
||
1080 | |||
1081 | <P>
|
||
1082 | This feature needs to be documented. |
||
1083 | |||
1084 | <P>
|
||
1085 | |||
1086 | <H2><A NAME="SECTION008116000000000000000"> |
||
1087 | Summary Example</A>
|
||
1088 | </H2>
|
||
1089 | |||
1090 | <P>
|
||
1091 | <PRE>
|
||
1092 | <field type="rule" variable="test1"> |
||
1093 | <description align="left" txt="A description for a rule input field."
|
||
1094 | id="description.rule.1"/>
|
||
1095 | <spec txt="Please enter your phone number:"
|
||
1096 | layout="( N:3:3 ) N:3:3 - N:4:4 x N:5:5" |
||
1097 | resultFormat="specialSeparator" separator="."/>
|
||
1098 | <validator class="com.izforge.izpack.util.NotEmptyValidator"
|
||
1099 | txt="The phone number is mandatory!" />
|
||
1100 | <!--processor class=""/--> |
||
1101 | </field> |
||
1102 | </PRE>
|
||
1103 | <P>
|
||
1104 | |||
1105 | <H1><A NAME="SECTION008120000000000000000"> |
||
1106 | Search</A>
|
||
1107 | </H1>
|
||
1108 | |||
1109 | <P>
|
||
1110 | The search input field allows the user to choose the location of files or |
||
1111 | directories. It also supports auto-detection of the location using a list of |
||
1112 | suggestions. The field is basically a combobox with an extra button to |
||
1113 | trigger auto-detection (again). |
||
1114 | |||
1115 | <P>
|
||
1116 | <DIV ALIGN="CENTER"> |
||
1117 | <!-- MATH
|
||
1118 | $\fbox{\includegraphics[scale=0.8]{img/userInput-search}}$
|
||
1119 | -->
|
||
1120 | <SPAN CLASS="MATH"><IMG |
||
1121 | WIDTH="470" HEIGHT="165" ALIGN="MIDDLE" BORDER="0" |
||
1122 | SRC="img11.png" |
||
1123 | ALT="\fbox{\includegraphics[scale=0.8]{img/userInput-search}}"></SPAN> |
||
1124 | </DIV>
|
||
1125 | |||
1126 | <P>
|
||
1127 | |||
1128 | <H2><A NAME="SECTION008121000000000000000"> |
||
1129 | Specification</A>
|
||
1130 | </H2>
|
||
1131 | |||
1132 | <P>
|
||
1133 | The <TT><description></TT> tag is the same as with other fields (see |
||
1134 | <A HREF="#userInput:descriptiontag">6.2</A> on page <A HREF="node8.html#userInput:descriptiontag"><IMG ALIGN="BOTTOM" BORDER="1" ALT="[*]" SRC="crossref.png"></A>). The |
||
1135 | <TT><spec></TT> tag supports the following attributes: |
||
1136 | |||
1137 | <P>
|
||
1138 | |||
1139 | <UL>
|
||
1140 | <LI><TT>filename</TT> - the name of the file or directory to search for |
||
1141 | </LI>
|
||
1142 | <LI><TT>type</TT> - what to search for |
||
1143 | |||
1144 | <UL>
|
||
1145 | <LI><TT>file</TT> - search for a file |
||
1146 | </LI>
|
||
1147 | <LI><TT>directory</TT> - search for a directory |
||
1148 | |||
1149 | </LI>
|
||
1150 | </UL>
|
||
1151 | </LI>
|
||
1152 | <LI><TT>result</TT> - what to return as the search result |
||
1153 | |||
1154 | <UL>
|
||
1155 | <LI><TT>file</TT> - result of search is whole pathname of file or directory found |
||
1156 | </LI>
|
||
1157 | <LI><TT>directory</TT> - only return directory where the file was found (this is the same as <TT>file</TT> when searching for directories) |
||
1158 | </LI>
|
||
1159 | <LI><TT>parentdir</TT> - return the full path of the parent directory where the file was found |
||
1160 | |||
1161 | </LI>
|
||
1162 | </UL>
|
||
1163 | </LI>
|
||
1164 | <LI><TT>checkfilename</TT> - the name of a file or directory to check for existence (this can be used to validate the user's selection) |
||
1165 | </LI>
|
||
1166 | </UL>
|
||
1167 | |||
1168 | <P>
|
||
1169 | |||
1170 | <H2><A NAME="SECTION008122000000000000000"> |
||
1171 | Example</A>
|
||
1172 | </H2>
|
||
1173 | |||
1174 | <P>
|
||
1175 | <PRE>
|
||
1176 | <field type="search" variable="java_sdk_home"> |
||
1177 | <description align="left"
|
||
1178 | txt="This is a description for a search input field." |
||
1179 | id="description.java_sdk_home"/>
|
||
1180 | <spec txt="Path to Java SDK:" checkfilename="lib/tools.jar"
|
||
1181 | type="file" result="directory">
|
||
1182 | <choice value="/usr/lib/java/" os="unix" /> |
||
1183 | <choice value="/opt/java" os="unix" /> |
||
1184 | <choice value="C:\Program Files\Java" os="windows" /> |
||
1185 | <choice value="C:\Java" os="windows" /> |
||
1186 | </spec> |
||
1187 | </field> |
||
1188 | </PRE>
|
||
1189 | <P>
|
||
1190 | |||
1191 | <DIV CLASS="navigation"><HR> |
||
1192 | <!--Navigation Panel-->
|
||
1193 | <A NAME="tex2html479" |
||
1194 | HREF="node9.html"> |
||
1195 | <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A> |
||
1196 | <A NAME="tex2html475" |
||
1197 | HREF="izpack-doc.html"> |
||
1198 | <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A> |
||
1199 | <A NAME="tex2html469" |
||
1200 | HREF="node7.html"> |
||
1201 | <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A> |
||
1202 | <A NAME="tex2html477" |
||
1203 | HREF="node1.html"> |
||
1204 | <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A> |
||
1205 | <BR>
|
||
1206 | <B> Next:</B> <A NAME="tex2html480" |
||
1207 | HREF="node9.html">Custom Actions</A> |
||
1208 | <B> Up:</B> <A NAME="tex2html476" |
||
1209 | HREF="izpack-doc.html">izpack-doc</A> |
||
1210 | <B> Previous:</B> <A NAME="tex2html470" |
||
1211 | HREF="node7.html">Creating Your Own Panels</A> |
||
1212 | <B> <A NAME="tex2html478" |
||
1213 | HREF="node1.html">Contents</A></B> </DIV> |
||
1214 | <!--End of Navigation Panel-->
|
||
1215 | <ADDRESS>
|
||
1216 | Julien Ponge |
||
1217 | 2005-04-22 |
||
1218 | </ADDRESS>
|
||
1219 | </BODY>
|
||
1220 | </HTML> |