← Back to branch summary

~ubuntu-branches/ubuntu/trusty/libstruts1.2-java/trusty-proposed

« back to all changes in this revision

Viewing changes to legacy/api-1.1/org/apache/struts/taglib/nested/package-summary.html

  • Committer: Bazaar Package Importer
  • Author(s): Arnaud Vandyck
  • Date: 2004-11-19 15:35:25 UTC
  • Revision ID: james.westby@ubuntu.com-20041119153525-mdu08a76z4zo67xt
Tags: upstream-1.2.4
Import upstream version 1.2.4

Show diffs side-by-side

added added

removed removed

Lines of Context:
legacy/api-1.1/org/apache/struts/taglib/nested/package-summary.html
 
1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN""http://www.w3.org/TR/REC-html40/loose.dtd">
 
2
<!--NewPage-->
 
3
<HTML>
 
4
<HEAD>
 
5
<!-- Generated by javadoc on Fri Aug 22 03:43:55 EDT 2003 -->
 
6
<TITLE>
 
7
org.apache.struts.taglib.nested (Apache Struts API Documentation)
 
8
</TITLE>
 
9
<META NAME="keywords" CONTENT="org.apache.struts.taglib.nested package">
 
10
<LINK REL ="stylesheet" TYPE="text/css" HREF="../../../../../stylesheet.css" TITLE="Style">
 
11
</HEAD>
 
12
<SCRIPT>
 
13
function asd()
 
14
{
 
15
parent.document.title="org.apache.struts.taglib.nested (Apache Struts API Documentation)";
 
16
}
 
17
</SCRIPT>
 
18
<BODY BGCOLOR="white" onload="asd();">
 
19
 
 
20
<!-- ========== START OF NAVBAR ========== -->
 
21
<A NAME="navbar_top"><!-- --></A>
 
22
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0">
 
23
<TR>
 
24
<TD COLSPAN=3 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
 
25
<A NAME="navbar_top_firstrow"><!-- --></A>
 
26
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3">
 
27
  <TR ALIGN="center" VALIGN="top">
 
28
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
 
29
  <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT>&nbsp;</TD>
 
30
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <FONT CLASS="NavBarFont1">Class</FONT>&nbsp;</TD>
 
31
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
 
32
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
 
33
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
 
34
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
 
35
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
 
36
  </TR>
 
37
</TABLE>
 
38
</TD>
 
39
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
 
40
</EM>
 
41
</TD>
 
42
</TR>
 
43
 
 
44
<TR>
 
45
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
 
46
&nbsp;<A HREF="../../../../../org/apache/struts/taglib/logic/package-summary.html"><B>PREV PACKAGE</B></A>&nbsp;
 
47
&nbsp;<A HREF="../../../../../org/apache/struts/taglib/nested/bean/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD>
 
48
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
 
49
  <A HREF="../../../../../index.html" TARGET="_top"><B>FRAMES</B></A>  &nbsp;
 
50
&nbsp;<A HREF="package-summary.html" TARGET="_top"><B>NO FRAMES</B></A>  &nbsp;
 
51
&nbsp;
 
52
<SCRIPT>
 
53
  <!--
 
54
  if(window==top) {
 
55
    document.writeln('<A HREF="../../../../../allclasses-noframe.html" TARGET=""><B>All Classes</B></A>');
 
56
  }
 
57
  //-->
 
58
</SCRIPT>
 
59
<NOSCRIPT>
 
60
<A HREF="../../../../../allclasses-noframe.html" TARGET=""><B>All Classes</B></A>
 
61
</NOSCRIPT>
 
62
</FONT></TD>
 
63
</TR>
 
64
</TABLE>
 
65
<!-- =========== END OF NAVBAR =========== -->
 
66
 
 
67
<HR>
 
68
<H2>
 
69
Package org.apache.struts.taglib.nested
 
70
</H2>
 
71
Nested tags &amp; supporting classes extend the base struts tags to
 
72
allow   them to relate to each other in a nested nature.
 
73
<P>
 
74
<B>See:</B>
 
75
<BR>
 
76
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#package_description"><B>Description</B></A>
 
77
<P>
 
78
 
 
79
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
 
80
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
 
81
<TD COLSPAN=2><FONT SIZE="+2">
 
82
<B>Interface Summary</B></FONT></TD>
 
83
</TR>
 
84
<TR BGCOLOR="white" CLASS="TableRowColor">
 
85
<TD WIDTH="15%"><B><A HREF="NestedNameSupport.html"><I>NestedNameSupport</I></A></B></TD>
 
86
<TD>This is so that managing classes can tell if a nested tag needs to have its
 
87
 <i>name</i> property set.</TD>
 
88
</TR>
 
89
<TR BGCOLOR="white" CLASS="TableRowColor">
 
90
<TD WIDTH="15%"><B><A HREF="NestedParentSupport.html"><I>NestedParentSupport</I></A></B></TD>
 
91
<TD>This interface is so managing classes of the nested tag can identify a tag
 
92
 as a parent tag that other tags retrieve nested properties from.</TD>
 
93
</TR>
 
94
<TR BGCOLOR="white" CLASS="TableRowColor">
 
95
<TD WIDTH="15%"><B><A HREF="NestedPropertySupport.html"><I>NestedPropertySupport</I></A></B></TD>
 
96
<TD>This interface is for managing classes of the nested extension, so they can
 
97
 know to set the tag's <i>property</i> property.</TD>
 
98
</TR>
 
99
<TR BGCOLOR="white" CLASS="TableRowColor">
 
100
<TD WIDTH="15%"><B><A HREF="NestedTagSupport.html"><I>NestedTagSupport</I></A></B></TD>
 
101
<TD>This is to simply allow managing classes to identify the tags to invoke
 
102
 common methods against them.</TD>
 
103
</TR>
 
104
</TABLE>
 
105
&nbsp;
 
106
 
 
107
<P>
 
108
 
 
109
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
 
110
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
 
111
<TD COLSPAN=2><FONT SIZE="+2">
 
112
<B>Class Summary</B></FONT></TD>
 
113
</TR>
 
114
<TR BGCOLOR="white" CLASS="TableRowColor">
 
115
<TD WIDTH="15%"><B><A HREF="NestedPropertyHelper.html">NestedPropertyHelper</A></B></TD>
 
116
<TD>A simple helper class that does everything that needs to be done to get
 
117
 the nested tag extension to work.</TD>
 
118
</TR>
 
119
<TR BGCOLOR="white" CLASS="TableRowColor">
 
120
<TD WIDTH="15%"><B><A HREF="NestedPropertyTag.html">NestedPropertyTag</A></B></TD>
 
121
<TD>NestedPropertyTag.</TD>
 
122
</TR>
 
123
<TR BGCOLOR="white" CLASS="TableRowColor">
 
124
<TD WIDTH="15%"><B><A HREF="NestedReference.html">NestedReference</A></B></TD>
 
125
<TD>So that a nested hierarchy can penetrate a dynamic JSP include, this class
 
126
 will hold the details of a bean name and nested property.</TD>
 
127
</TR>
 
128
<TR BGCOLOR="white" CLASS="TableRowColor">
 
129
<TD WIDTH="15%"><B><A HREF="NestedRootTag.html">NestedRootTag</A></B></TD>
 
130
<TD>NestedRootTag.</TD>
 
131
</TR>
 
132
<TR BGCOLOR="white" CLASS="TableRowColor">
 
133
<TD WIDTH="15%"><B><A HREF="NestedWriteNestingTag.html">NestedWriteNestingTag</A></B></TD>
 
134
<TD>NestedWriteNestingTag.</TD>
 
135
</TR>
 
136
</TABLE>
 
137
&nbsp;
 
138
 
 
139
<P>
 
140
<A NAME="package_description"><!-- --></A><H2>
 
141
Package org.apache.struts.taglib.nested Description
 
142
</H2>
 
143
 
 
144
<P>
 
145
Nested tags &amp; supporting classes extend the base struts tags to
 
146
allow   them to relate to each other in a nested nature. The fundamental
 
147
logic of   the original tags don't change, except in that all references
 
148
to beans and   bean properties will be managed in a nested context. <br>
 
149
<br>
 
150
<a name="doc.Description"></a>
 
151
<div align="Center"> [&nbsp;<a href="#doc.Intro">Introduction</a>
 
152
    &nbsp;] [&nbsp;<a href="#doc.FoundationConcepts">Foundation&nbsp;Concepts&nbsp;-&nbsp;model</a>
 
153
    &nbsp;] [&nbsp;<a href="#doc.TaggingConcepts">Foundation&nbsp;Concepts&nbsp;-&nbsp;tags</a>
 
154
    &nbsp;] [&nbsp;<a href="#doc.TagList">Nested&nbsp;Tag&nbsp;List</a>
 
155
    &nbsp;] [&nbsp;<a href="#doc.PropertyProperty">The&nbsp;"property"&nbsp;Property</a>
 
156
    &nbsp;] [&nbsp;<a href="#doc.ImplementationDetails">Implementation&nbsp;Details</a>
 
157
    &nbsp;] </div>
 
158
<hr><a name="doc.Intro"></a>
 
159
<h3>Introduction</h3>
 
160
<p>The nesting extension provides the ability to define a nested object model
 
161
  and   efficiently represent and manage that model through JSP's custom
 
162
tags.</p>
 
163
<p>It's written in a layer that extends the current Struts tags, building
 
164
  on   their logic and functionality. The layer enables the tags to be aware
 
165
  of the   tags which surround them so they can correctly provide the nesting
 
166
  property   reference to the Struts system. Struts already supported properties
 
167
  which use   "dot notation" in accessing nested objects and properties.</p>
 
168
<pre>e.g. myProperty.childProperty.finalProperty</pre>
 
169
<p>Because of this the controller servlet excellently manages this nested 
 
170
    model. These tags are about bringing such ease of management to the JSP
 
171
  view   of the architecture.</p>
 
172
<hr><a name="doc.FoundationConcepts"></a>
 
173
<h3>Foundation Concepts - model.</h3>
 
174
<p>   A bean holds a reference to another bean internally, and all access
 
175
  to that    bean is handled through the current bean. This act of having
 
176
one  bean's access    go through another bean is known as "nesting beans".
 
177
The  first bean is known    as the parent bean. The bean which it references,
 
178
 is known as a child bean.    The terms "parent" and "child" are commonly
 
179
used to describe the model's    hierarchy.   </p>
 
180
<p><b>A simple example...</b><br />
 
181
       Take an object which represents a monkey. The monkey's job is to pick
 
182
  bunches    of bananas. On each bunch picked hangs many bananas. If this
 
183
case  was    translated to bean objects, the monkey object would have a reference
 
184
  to the    bunch objects he picked, and each bunch object would hold a reference
 
185
  to the    bananas hanging in the bunch.   </p>
 
186
<p><b>To describe this...</b><br />
 
187
       The monkey object is the parent to the bunch object, and the bunch 
 
188
object  is a    child of the monkey object. The bunch object is parent to 
 
189
its child  banana    objects, and the child banana objects children of the 
 
190
bunch object.  The monkey    is higher in the hierarchy than the bananas, 
 
191
and the bananas  lower in the    hierarchy to the bunches.   </p>
 
192
<p>   One special term to remember is for the most parent class, which is
 
193
  known as    the "root" object which starts the hierarchy.   </p>
 
194
<hr><a name="doc.TaggingConcepts"></a>
 
195
<h3>Foundation Concepts - tags.</h3>
 
196
<p>   What the tags provide is an efficient way or representing the above
 
197
  models   within JSP tag markup. As a result the tags take on similar relationships
 
198
  to   each other. A tag can be the parent of another, and similarly be a
 
199
child  of a   parent tag. However the most important part to remember, is
 
200
that the    properties of parent tags define the nested property for the
 
201
child tags'    properties.   </p>
 
202
<p>   One issue which may confuse the new developer, is that even though
 
203
a tag   is a parent tag in a markup sense (the opening tag and closing tag
 
204
are either   side of another tag) does not immediately mean that the child
 
205
tag will be   relative to that tag. Why? Some tags make bad parents. In other
 
206
  words, they're   not logical steps in defining a hierarchy.   </p>
 
207
<p>   For example the relationship between the select tag and the options
 
208
  tag. The   html:options tag "must" be surrounded by a parent html:select
 
209
 tag.   </p>
 
210
<pre>eg:<br>  &lt;html:select name="myBean" property="mySelectProperty" &gt;<br>    &lt;html:options name="myBean" property="myOptionsProperty" &gt;<br>  &lt;/html:select&gt;</pre>
 
211
<p>   In the nested context, this would cause undesired results if the select
 
212
  tag   was a parent. The bean reference would become...   </p>
 
213
<pre>  mySelectProperty.myOptionsProperty</pre>
 
214
       ...which when translated, Struts would go to the value of the select 
 
215
 property    and then try to get your options list from that returned value. 
 
216
 The extended    logic tags are the same. You don't want to extend your properties 
 
217
 within the   objects the logic tags are evaluating.       
 
218
<p>   To get manage this, the tags in the nested extension are categorised
 
219
  into   parent tags and non-parent tags. Those which implement   <code>org.apache.struts.taglib.nested.NestedParentSupport</code>
 
220
     are classed   as parents, and the nested system knows they define levels
 
221
  in the nested   hierarchy. Every other tag, does not, and will be skipped
 
222
  if found to be a   "markup parent" (like our select tag) and not a "nested
 
223
  parent".   </p>
 
224
<p>   There are also the special case of starting off the hierarchy with
 
225
a "root"   tag. These tags are what the extension requires to provide them
 
226
with the bean   by which the structure will be based on.   </p>
 
227
<hr><a name="doc.TagList"></a>
 
228
<h3>Nested Tag List.</h3>
 
229
<p>   Here's a list of tags in the nested extension, grouped by parent/context 
 
230
    functionality. "root", "nested parent", "markup parent" &amp; "basic". 
 
231
   </p>
 
232
<p><b>Root Tags</b>
 
233
<table border="1">
 
234
  <tbody>
 
235
    <tr>
 
236
      <th>markup name</th>
 
237
      <th>brief description</th>
 
238
    </tr>
 
239
    <tr>
 
240
      <td>html:form</td>
 
241
      <td>For backwards compatibility, you can use the typical form tag 
 
242
to             implement your nested hierarchy.</td>
 
243
    </tr>
 
244
    <tr>
 
245
      <td>nested:form</td>
 
246
      <td>An extension of the above <code>html:form</code>, this is just
 
247
  to             provide definition in the nested tag library.</td>
 
248
    </tr>
 
249
    <tr>
 
250
      <td>nested:root</td>
 
251
      <td>When you don't want to configure a form, you can use any bean 
 
252
which             is in "scope" by specifying its name within this tag.</td>
 
253
    </tr>
 
254
  </tbody>
 
255
</table>
 
256
</p>
 
257
<br />
 
258
<p><b>Nested Parent Tags</b> (Affect the hierarchy)       
 
259
<table border="1">
 
260
  <tbody>
 
261
    <tr>
 
262
      <th>markup name</th>
 
263
      <th>brief description</th>
 
264
    </tr>
 
265
    <tr>
 
266
      <td>nested:nest</td>
 
267
      <td>This tag executes no logic, simply representing a nesting level 
 
268
              for the rest of the markup to relate to.</td>
 
269
    </tr>
 
270
    <tr>
 
271
      <td>nested:iterate</td>
 
272
      <td>Extension of <code>logic:iterate</code> you can use it to iterate 
 
273
              through a list, and have all child references nest within the
 
274
  beans             returned from this iterated collection.</td>
 
275
    </tr>
 
276
  </tbody>
 
277
</table>
 
278
</p>
 
279
<br />
 
280
<p><b>Markup Parent Tags</b> (marked-up like parent tags, but don't affect
 
281
  the hierarchy)       
 
282
<table border="1">
 
283
  <tbody>
 
284
    <tr>
 
285
      <th>markup name</th>
 
286
      <th>brief description</th>
 
287
    </tr>
 
288
    <tr>
 
289
      <td>nested:select</td>
 
290
      <td><code>html:select</code> extension. Provides the logic to render 
 
291
              a select box in Html.</td>
 
292
    </tr>
 
293
    <tr>
 
294
      <td>nested:empty</td>
 
295
      <td><code>logic:empty</code> extension.</td>
 
296
    </tr>
 
297
    <tr>
 
298
      <td>nested:notEmpty</td>
 
299
      <td><code>logic:notEmpty</code> extension.</td>
 
300
    </tr>
 
301
    <tr>
 
302
      <td>nested:equal</td>
 
303
      <td><code>logic:equal</code> extension.</td>
 
304
    </tr>
 
305
    <tr>
 
306
      <td>nested:notEqual</td>
 
307
      <td><code>logic:notEqual</code> extension.</td>
 
308
    </tr>
 
309
    <tr>
 
310
      <td>nested:greaterEqual</td>
 
311
      <td><code>logic:greaterEqual</code> extension.</td>
 
312
    </tr>
 
313
    <tr>
 
314
      <td>nested:greaterThan</td>
 
315
      <td><code>logic:greaterThan</code> extension.</td>
 
316
    </tr>
 
317
    <tr>
 
318
      <td>nested:lessEqual</td>
 
319
      <td><code>logic:lessEqual</code> extension.</td>
 
320
    </tr>
 
321
    <tr>
 
322
      <td>nested:lessThan</td>
 
323
      <td><code>logic:lessThan</code> extension.</td>
 
324
    </tr>
 
325
    <tr>
 
326
      <td>nested:match</td>
 
327
      <td><code>logic:match</code> extension.</td>
 
328
    </tr>
 
329
    <tr>
 
330
      <td>nested:notMatch</td>
 
331
      <td><code>logic:notMatch</code> extension.</td>
 
332
    </tr>
 
333
    <tr>
 
334
      <td>nested:present</td>
 
335
      <td><code>logic:present</code> extension.</td>
 
336
    </tr>
 
337
    <tr>
 
338
      <td>nested:notPresent</td>
 
339
      <td><code>logic:notPresent</code> extension.</td>
 
340
    </tr>
 
341
  </tbody>
 
342
</table>
 
343
</p>
 
344
<br />
 
345
<p><b>Basic tags</b> (usually a tag which has no body content)
 
346
<table border="1">
 
347
  <tbody>
 
348
    <tr>
 
349
      <th>markup name</th>
 
350
      <th>brief description</th>
 
351
    </tr>
 
352
    <tr>
 
353
      <td>nested:checkbox</td>
 
354
      <td><code>html:</code> extension.</td>
 
355
    </tr>
 
356
    <tr>
 
357
      <td>nested:hidden</td>
 
358
      <td><code>html:hidden</code> extension.</td>
 
359
    </tr>
 
360
    <tr>
 
361
      <td>nested:define</td>
 
362
      <td><code>bean:define</code> extension.</td>
 
363
    </tr>
 
364
    <tr>
 
365
      <td>nested:image</td>
 
366
      <td><code>html:image</code> extension.</td>
 
367
    </tr>
 
368
    <tr>
 
369
      <td>nested:img</td>
 
370
      <td><code>html:img</code> extension.</td>
 
371
    </tr>
 
372
    <tr>
 
373
      <td>nested:link</td>
 
374
      <td><code>html:link</code> extension.</td>
 
375
    </tr>
 
376
    <tr>
 
377
      <td>nested:message</td>
 
378
      <td><code>bean:message</code> extension.</td>
 
379
    </tr>
 
380
    <tr>
 
381
      <td>nested:multibox</td>
 
382
      <td><code>html:multibox</code> extension.</td>
 
383
    </tr>
 
384
    <tr>
 
385
      <td>nested:options</td>
 
386
      <td><code>html:options</code> extension.</td>
 
387
    </tr>
 
388
    <tr>
 
389
      <td>nested:optionsCollection</td>
 
390
      <td><code>html:optionsCollection</code> extension.</td>
 
391
    </tr>
 
392
    <tr>
 
393
      <td>nested:password</td>
 
394
      <td><code>html:password</code> extension.</td>
 
395
    </tr>
 
396
    <tr>
 
397
      <td>nested:radio</td>
 
398
      <td><code>html:radio</code> extension.</td>
 
399
    </tr>
 
400
    <tr>
 
401
      <td>nested:select</td>
 
402
      <td><code>html:select</code> extension.</td>
 
403
    </tr>
 
404
    <tr>
 
405
      <td>nested:size</td>
 
406
      <td><code>bean:size</code> extension.</td>
 
407
    </tr>
 
408
    <tr>
 
409
      <td>nested:submit</td>
 
410
      <td><code>html:submit</code> extension.</td>
 
411
    </tr>
 
412
    <tr>
 
413
      <td>nested:text</td>
 
414
      <td><code>html:text</code> extension.</td>
 
415
    </tr>
 
416
    <tr>
 
417
      <td>nested:textarea</td>
 
418
      <td><code>html:textarea</code> extension.</td>
 
419
    </tr>
 
420
    <tr>
 
421
      <td>nested:write</td>
 
422
      <td><code>bean:write</code> extension.</td>
 
423
    </tr>
 
424
  </tbody>
 
425
</table>
 
426
</p>
 
427
<hr><a name="doc.PropertyProperty"></a>
 
428
<h3>The relative references and the "property" property.</h3>
 
429
<p>Use of the "property" property is exactly the same as the original Struts
 
430
  tag    with minor addition. Appends the provided property to the nested
 
431
property  of   the tags that surround it. You can use additional nesting
 
432
(use "dot notation")   within the provided property as the current struts
 
433
system allows but there is   now a tag which can provide this in a "cleaner"
 
434
fashion.  :)</p>
 
435
<p>The one other addition to the "property" property, is the ability to step 
 
436
    backwards in the heirarchy in the familiar directory fashion;   e.g. "../../myPropertyName"</p>
 
437
<p>As expected this allows you to step backwards in the nested model to access 
 
438
    a higher level in the object tree. The implementation uses the StringTokenizer 
 
439
    working off the "/" delimiter and counts the tokens. This was going to
 
440
  be   denied, enforcing the ".." fashion, but on consideration, allowed
 
441
for   some   easier-to-read naming possibilities.</p>
 
442
<p>Consider "propertyOne.propertyTwo.propertyThree.propertyFour". With the
 
443
     current nesting level beneath "propertyFour" you can instead use   "two/three/four/anotherProperty"
 
444
  which is easier to understand than   "../../../anotherProperty". Doesn't
 
445
 sound like much, but makes life easier   when traversing large jsp pages
 
446
for tags defining your object model.</p>
 
447
<p>Also implemented is the also familiar directory fashion of a leading "/"
 
448
  to   reference from the root of the model and start over. e.g. "/propertyOne". 
 
449
    This allow a convenient way to move around a few levels as well as "forking" 
 
450
    in the object structure among other felixble approaches to structure.</p>
 
451
<p><b>Parent References...</b><br />
 
452
       "property" properties, including the relative properties described 
 
453
above,  all    end up referencing a property of a child bean. For example 
 
454
"/myProperty"  will   return an object from the "myProperty" of the root bean.
 
455
The fact that a   property is specified means that you are accessing the
 
456
result of that   property. This results in never being able to properly access
 
457
a parent object   itself within its current related context.   </p>
 
458
<p>   Take for example you simply want to print out a list of String objects.
 
459
  In a    bean you create a list of them, offer them out to the system via
 
460
 a getter, and   you markup using the nested:iterate or logic:iterate tag
 
461
(both contain the    same issues). The only way to get at the object itself
 
462
is get the iterate tag   to declare a scripting variable. With the nested
 
463
tags you can now simply   reference the object using a parent reference of
 
464
"./" or "this/". Any property   ending in the "/" will be treaded as a parent
 
465
reference. So if you use   "parent/" as your property, it will step back
 
466
one parent and use this block's   parent. The special cases to use the parent
 
467
of the current nested block are   "./" or "this/". Not just the iterate tag,
 
468
this will return the object   represented by any nested parent tag.   </p>
 
469
<p>   This allows you to be in a nested tag block and use the custom tags
 
470
  work    directly against the parent defined object, indexed or otherwise.
 
471
  So to be in    an iterate block, and to print out the String representation
 
472
  of the current    iterated object, you can now use...   </p>
 
473
<pre>eg:<br>  &lt;nested:iterate property="myItemList" &gt;<br>    &lt;html:write property="this/" &gt;&lt;br&gt;<br>  &lt;/html:iterate&gt;</pre>
 
474
<p>   or if you want to print the string value of a parent the other side
 
475
  of the    object...   </p>
 
476
<pre>eg:<br>  &lt;nested:iterate property="myBeanList" &gt;<br>    &lt;nested:iterate property="myItemList" &gt;<br>      &lt;html:write property="beanListObject/" &gt;&lt;br&gt;<br>    &lt;/html:iterate&gt;<br>  &lt;/html:iterate&gt;</pre>
 
477
<p>   The fact that it didn't use the special cases of "./" or "this/" means
 
478
  that it   steps back in the hierarchy as a typical relative reference.
 
479
This   is unlimited   the amount of steps you can take back in the hierarchy.
 
480
For   example, to go   back three parents your property would be "one/two/three/". 
 
481
    </p>
 
482
<p><b>Note:</b> The logic identifies the leading "/" and then reads the property 
 
483
    from the last index of "/".  Resulting in "/three/four/anotherProperty"
 
484
  working   the same as "/anotherProperty".</p>
 
485
<p><b>Note:</b> If you're busily nesting away, and a parent tag has a leading
 
486
  "/"   property, the  contained tags will append to this new structure.
 
487
Handy,   but   you have to keep it in mind.</p>
 
488
<p><b>Note:</b> If you try to reference beneath the level of the nesting,
 
489
  it will   simply act like as if a leading "/" property was defined.</p>
 
490
<p><b>Parent Reference Note:</b>   The only thing to keep in mind with parent
 
491
  references is that   you cannot parent reference the root bean. This is
 
492
because  the resulting   property would be an empty string. Something that
 
493
the BeanUtils/PropertyUtils    cannot handle (if this is a requirement, you
 
494
could use a "fake nested   property". A getter which simply returns the same
 
495
bean instance ("this")  and   simply add an extra <code>nested:nest</code>
 
496
  level at the start of your   hierarchy. Works just fine).   </p>
 
497
<hr><br />
 
498
<img src="doc-files/nestedUML.gif" alt="nested UML">
 
499
<a name="doc.ImplementationDetails"></a>
 
500
<h3>Implementation Details.</h3>
 
501
<b>NestedPropertyHelper</b>
 
502
<dir>
 
503
<p>This class embodies all of the logic that runs the nested tagging system.
 
504
  It   defines a static method, "setNestedProperties", which the nested tags
 
505
  pass   themselves into to have their appropriate properties set.</p>
 
506
<p>The tag extensions themselves implement options of three interfaces which 
 
507
    define functionality for the various types of nested usage. When traversing 
 
508
    the tag hierarchy back up to the root of the structure, these tags define
 
509
  the   result of the current tag.</p>
 
510
</dir>
 
511
<b>NestedTagSupport Interface...</b>
 
512
<dir>
 
513
<p>This is the base of the interfaces. Simply put, any tag that we need to
 
514
  single   out of the standard struts tags for use by the nesting system
 
515
can   implement   this or its children.</p>
 
516
</dir>
 
517
<b>NestedPropertySupport Interface...</b>
 
518
<dir>
 
519
<p>Tags that implement this interface will have the provided property attribute 
 
520
    appended to the parenting nested attribute. This is the heart of the matter.
 
521
    </p>
 
522
<p>This is the basic property, and so far all the nested tags support this 
 
523
    to have their nested properties written correctly.</p>
 
524
</dir>
 
525
<b>NestedNameSupport Interface...</b>
 
526
<dir>
 
527
<p>This interface means that the implementing tag wants to have it's name
 
528
  tag   looked after by the nesting system. This is automatic, and the name
 
529
  is written   for the tag from the root tag. If the JSP is a form, then
 
530
it   will look to the   form tag and get a hold of the bean name that is
 
531
defined   in the   struts-config.xml file for the action, otherwise, a nested:root
 
532
 tag must be   provided for this means.</p>
 
533
<p>This extends the NestedPropertySupport interface as, at time of writing, 
 
534
    all tags which used a "name" attribute, required a property attribute 
 
535
in some   way to make it useful. This could change, and it's only a small 
 
536
refactoring to   make it work for the instance if it's relevant for nesting.</p>
 
537
<p><b>Note:</b> At the moment, if the tag implements this interface, the
 
538
name   attribute will be rewritten by the system on all counts. I find it
 
539
hard to   picture a valid requirement for inter-mixing multiple object structures
 
540
  (which   distinguishable names would allow) in the one JSP page which couldn't
 
541
  be   more efficiently provided by the current nesting model working over
 
542
 the one   model. Time may prove this idea wrong.</p>
 
543
</dir>
 
544
<b>ParentTagSupport</b>
 
545
<dir>
 
546
<p>This tag identifies for the system those tags which define levels in the 
 
547
    nested heirarchy.  Namely the "getNestedProperty()" method that yields
 
548
  to   calling tags the fully qualified nested property of the parent tag.
 
549
 In the   case of a NestedIterator being the parent tag, it will also append
 
550
 the current   index reference. e.g. propertyOne.propertyTwo[5]</p>
 
551
</dir>
 
552
<br />
 
553
<br />
 
554
<br />
 
555
<br />
 
556
<P>
 
557
 
 
558
<P>
 
559
<HR>
 
560
 
 
561
<!-- ========== START OF NAVBAR ========== -->
 
562
<A NAME="navbar_bottom"><!-- --></A>
 
563
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0">
 
564
<TR>
 
565
<TD COLSPAN=3 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
 
566
<A NAME="navbar_bottom_firstrow"><!-- --></A>
 
567
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3">
 
568
  <TR ALIGN="center" VALIGN="top">
 
569
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
 
570
  <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT>&nbsp;</TD>
 
571
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <FONT CLASS="NavBarFont1">Class</FONT>&nbsp;</TD>
 
572
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
 
573
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
 
574
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
 
575
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
 
576
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
 
577
  </TR>
 
578
</TABLE>
 
579
</TD>
 
580
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
 
581
</EM>
 
582
</TD>
 
583
</TR>
 
584
 
 
585
<TR>
 
586
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
 
587
&nbsp;<A HREF="../../../../../org/apache/struts/taglib/logic/package-summary.html"><B>PREV PACKAGE</B></A>&nbsp;
 
588
&nbsp;<A HREF="../../../../../org/apache/struts/taglib/nested/bean/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD>
 
589
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
 
590
  <A HREF="../../../../../index.html" TARGET="_top"><B>FRAMES</B></A>  &nbsp;
 
591
&nbsp;<A HREF="package-summary.html" TARGET="_top"><B>NO FRAMES</B></A>  &nbsp;
 
592
&nbsp;
 
593
<SCRIPT>
 
594
  <!--
 
595
  if(window==top) {
 
596
    document.writeln('<A HREF="../../../../../allclasses-noframe.html" TARGET=""><B>All Classes</B></A>');
 
597
  }
 
598
  //-->
 
599
</SCRIPT>
 
600
<NOSCRIPT>
 
601
<A HREF="../../../../../allclasses-noframe.html" TARGET=""><B>All Classes</B></A>
 
602
</NOSCRIPT>
 
603
</FONT></TD>
 
604
</TR>
 
605
</TABLE>
 
606
<!-- =========== END OF NAVBAR =========== -->
 
607
 
 
608
<HR>
 
609
Copyright � 2000-2003 - Apache Software Foundation
 
610
</BODY>
 
611
</HTML>