You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@struts.apache.org by ms...@apache.org on 2001/01/09 22:02:15 UTC

cvs commit: jakarta-struts/src/share/org/apache/struts/taglib/logic package.html

mschachter    01/01/09 13:02:14

  Added:       src/share/org/apache/struts/taglib/logic package.html
  Log:
  Unfinished rough draft of logic tag user guide, initial check-in
  
  Revision  Changes    Path
  1.1                  jakarta-struts/src/share/org/apache/struts/taglib/logic/package.html
  
  Index: package.html
  ===================================================================
  <html>
  <head>
  <title>Package Documentation for org.apache.struts.taglib.logic Package</title>
  </head>
  <body bgcolor="white">
  	
  	<p>
  		The "struts-bean" tag library contains tags that are useful in managing conditional
  		generation of output text, looping over object collections for repetitive generation
  		of output text, and application flow management
  	</p>
  	<a name="doc.Description"></a>
  	
  	<p>
  		<div align="center">
  			<a href="#doc.Intro">[Introduction]</a>
  			<a href="#doc.Functionality">[Logic Functionality]</a>
  			<a href="#doc.Properties">[Logic Properties]</a>
  			<a href="#doc.Usage">[Logic Usage]</a>
  		</div>
  	<p></p>
  	
  	<hr />
  	
  	<a name="doc.Intro"></a>
  	<h3>Introduction</h3>
  	
  	<p>
  		The Logic library supplies tags that are useful for manipulating presentation logic
  		without the use of scriptlets.
  	</p>
  	
  	<a name="doc.Functionality"></a>
  	<h3>Logic Tag Functionality</h3>
  	
  	
  <p> The functionality of the logic tag can be divided into four groups:</p>
  <p><b>Value Comparisions -</b> The purpose of these tags is to print out the body 
    of the tag if the comparision evaluates to <i>true. </i></p>
  <ul>
    <li><b><a href="/struts-logic.html#equal">equal,</a> <a href="/struts-logic.html#notEqual">notEqual</a></b> 
    </li>
    <li><b><a href="/struts-logic.html#greaterEqual">greaterEqual</a>, <a href="/struts-logic.html#lessEqual">lessEqual</a></b></li>
    <li><b><a href="/struts-logic.html#greaterThan">greaterThan</a>,<a href="/struts-logic.html#lessThan"> 
      lessThan</a></b></li>
  </ul>
  <p><b>Substring Matching -</b> The purpose of these tags is to match substrings 
    inside of other Strings</p>
  <ul>
    <li><b><a href="/struts-logic.html#match">match</a>, <a href="/struts-logic.html#notMatch">notMatch</a></b></li>
  </ul>
  <p><b>Presentation Location -</b> The purpose of these tags is to change the location 
    of the presentation page</p>
  <ul>
    <li><a href="/struts-logic.html#forward"><b>forward</b></a></li>
    <li><a href="/struts-logic.html#redirect"><b>redirect</b></a></li>
  </ul>
  <p><b>Collection Utilities -</b>The purpose of these tags is to handle Collections</p>
  <ul>
    <li><a href="/struts-logic.html#iterate"><b>iterate</b></a> </li>
  </ul>
  <h3>Logic Tag Properties</h3>
  <p>Each of the four groups of logic tags have a common set of attributes associated 
    with them. :</p>
  <blockquote> 
    <p><b>Value Comparisions</b> (equal, notEqual, greaterEqual, lessEqual, greaterThan, 
      lessThan, present, notPresent)</p>
    <p>Each of the value comparision tags takes a <i>value</i> and compares it to 
      the value of a comparision attribute. If the value given can be successfully 
      converted to a <i>float</i> or <i>double</i>, then a number comparision is 
      performed the value given and the value of the comparision attribute. Otherwise 
      a String comparision is performed. You have to specify one of the comparision 
      attributes: <i>cookie</i>, <i>header</i>, <i>parameter</i>, <i>property</i> 
      or <i>name. </i>For each of the examples, the tag &quot;<i>someComparisionTag&quot;</i>can 
      be replaced by any of the value comparision tags.</p>
    <ul>
      <li>value - the value to which this tag is going to compare, used in conjunction 
        with one of the comparision attributes: <i>cookie</i>, <i>header</i>, <i>parameter</i>, 
        <i>and property</i> and/or <i>name. </i></li>
      <li>cookie - the name of the cookie to compare to <i>value</i> 
        <ul>
          <li>example: 
            <pre>&lt;logic:<i>someComparisionTag</i> value=&quot;someUserName&quot; cookie=&quot;userName&quot;&gt;
  	User Logged In
  &lt;/logic:<i>someComparisionTag</i>&gt;
  </pre>
          </li>
        </ul>
      </li>
      <li>header - the name of the HTTP header to compare to <i>value</i> 
        <ul>
          <li>example: 
            <pre>&lt;logic:<i>someComparisionTag</i> value=&quot;en_US&quot; header=&quot;Accept-Language&quot;&gt;
  	Welcome English-speaking User*
  &lt;/logic:<i>someComparisionTag</i>&gt;
  *Note: See the section in the user's guide on <a href="building_view.html#i18n">Internationalized Messages</a> to do things like this better
  	</pre>
          </li>
        </ul>
      </li>
      <li>name - the variable to be compared to <i>value</i> is the JSP bean specified 
        by this attribute, if property is not specified, or the value of the specified 
        property of this bean, if property is specified. 
        <ul>
          <li>example: 
            <pre>&lt;%
  	String testString = &quot;pantalones&quot;;
  	pageContext.setAttribute(&quot;testString&quot;, testString, PageContext.PAGE_SCOPE);
  %&gt;
  &lt;jsp:useBean id=&quot;testString&quot; scope=&quot;page&quot; type=&quot;java.lang.String&quot; /&gt;
  
  
  &lt;logic:<i>someComparisionTag</i> name=&quot;testString&quot; value=&quot;pantalones&quot;&gt;
  	Usted tiene pantalones!
  &lt;/logic:<i>someComparision</i>&gt;</pre>
          </li>
        </ul>
      </li>
      <li>parameter - the name of the request parameter to compare to <i>value</i> 
        <ul>
          <li>example: 
            <pre>&lt;logic:<i>someComparisionTag</i> value=&quot;&quot; parameter=&quot;username&quot;&gt;
  	Error: a username must be specified
  &lt;/logic:<i>someComparisionTag</i>&gt;</pre>
          </li>
        </ul>
      </li>
      <li>property - the variable to be compared with <i>value</i> is the property 
        (of the bean specified by the name attribute) specified by this attribute. 
        The property reference can be simple, nested, and/or indexed. <i>property</i> 
        is used in conjunction with <i>name</i> to specify a property in the bean 
        specified by <i>name</i>. For the type of syntax used for property, see 
        the users guide on the Bean Tags.</li>
      <li>scope - the bean scope within which to search for the bean named by the 
        name property, or "any scope" if not specified. Possible values are &quot;page&quot;, 
        &quot;request&quot;, &quot;session&quot;, &quot;application&quot;, or &quot;any 
        scope&quot; </li>
    </ul>
    <p><b>Substring Matching</b> (match, notMatch)</p>
    <p>The substring matching tags take all the same arguments as the value comparision 
      tags. You compare the String specified by <i>value</i> to any of the comparision 
      values you give it, specified by <i>cookie</i>, <i>header</i>, <i>parameter</i>, 
      <i>property</i> or <i>name.</i> Note that in the examples, <i>matchTag</i> 
      corresponds either the <i>match </i>or <i>notMatch</i> tag. Matching tags 
      also have an additional <i>location</i> attribute added:</p>
    <ul>
      <li>location - has two possible values, &quot;start&quot; and &quot;end&quot;. 
        If &quot;start&quot;, the substring is attempted to be matched at the beginning 
        of the String, if &quot;end&quot;, then the substring is attempted to be 
        matched to the end of the String 
        <ul>
          <li>example: 
            <pre>&lt;logic:<i>matchTag</i> parameter=&quot;action&quot; value=&quot;processLogin&quot;&gt;
  	Processing Login....
  &lt;/logic:<i>matchTag</i>&gt;
  
  
  Basically, in this short example, a request parameter &quot;action&quot; 
  was compared to see if was equal to the String value &quot;processLogin&quot;.
  In this case, <i>matchTag</i> would have to be logic:match.</pre>
          </li>
        </ul>
      </li>
    </ul>
    <p><b>Presentation Location</b> (forward, redirect)</p>
    <p>The <i>redirect</i> tag is resposible for sending a re-direct to the client's 
      browser, complete with URL-rewriting if it's supported by the container. It 
      has one argument:</p>
    <ul>
      <li>href - The context-relative path to forward to</li>
    </ul>
    <p>The <i>forward</i> tag is responsible for either redirecting or forwarding 
      to a specified global action forward. To define a global ActionForward, see 
      The <a href="building_controller.html#config">Action Mappings Configuration 
      File</a>. You can specify whether the forward re-directs or forwards when 
      executed in the config file. The forward tag has one attribute:</p>
    <ul>
      <li>name - The logical name of the ActionForward to use</li>
    </ul>
    <p><b>Collection Utilities</b> (iterate)</p>
    <p>The <i>iterate</i> tag is responsible for executing it's body content once 
      for every element inside of the specified Collection. There is one required 
      attribute:</p>
    <ul>
      <li>id - The name of a page scope JSP bean that will contain the current element 
        of the collection on each iteration</li>
    </ul>
    <p>The other attributes allow for more flexibility on which Collection to iterate 
      and how to do it:</p>
    <ul>
      <li>collection - a runtime expression that evaluates to a Collection to be 
        iterated 
        <ul>
          <li>example: 
            <pre>&lt;%
  	java.util.Vector vector = new java.util.Vector();
  	vector.add(new Integer(12));
  	vector.add(new Integer(5))
   %&gt;</pre>
          </li>
        </ul>
      </li>
    </ul>
    <blockquote> 
      <blockquote> 
        <pre>&lt;bean:iterate id=&quot;myCollectionElement&quot; collection=&quot;&lt;% vector %&gt;&quot;&gt;
  <i>	Do something with myCollectionElement</i>
  &lt;/bean:iterate&gt;</pre>
      </blockquote>
    </blockquote>
    <ul>
      <li>length - The maximum number of entries (from the underlying collection) 
        to be iterated through on this page. This can be either an integer that 
        directly expresses the desired value, or the name of a JSP bean (in any 
        scope) of type java.lang.Integer that defines the desired value. If not 
        present, there will be no limit on the number of iterations performed</li>
      <li>name - The name of the JSP bean containing the collection to be iterated 
        (if property is not specified), or the JSP bean whose property getter returns 
        the collection to be iterated (if property is specified). 
        <ul>
          <li>example: 
            <pre>&lt;%<br>    java.util.ArrayList list = new java.util.ArrayList();<br>    list.add(&quot;First&quot;);<br>    list.add(&quot;Second&quot;);<br>    list.add(&quot;Third&quot;);<br>    list.add(&quot;Fourth&quot;);<br>    list.add(&quot;Fifth&quot;);<br>    pageContext.setAttribute(&quot;list&quot;, list, PageContext.PAGE_SCOPE);<br> %&gt;
  
  &lt;logic:iterate id=&quot;myCollectionElement&quot; name=&quot;list&quot;&gt;
  	<i>Do something with myCollectionElement</i>
  &lt;/logic:iterate&gt;</pre>
          </li>
        </ul>
      </li>
      <li>offset - The zero-relative index of the starting point at which entries 
        from the underlying collection will be iterated through. This can be either 
        an integer that directly expresses the desired value, or the name of a JSP 
        bean (in any scope) of type java.lang.Integer that defines the desired value. 
        If not present, zero is assumed (meaning that the collection will be iterated 
        from the beginning. </li>
      <li>property - Name of the property, of the JSP bean specified by name, whose 
        getter returns the collection to be iterated. See the user's guide for the 
        bean tag library for the syntax of the property attribute</li>
      <li>scope - The bean scope within which to search for the bean named by the 
        name property, or "any scope" if not specified. Possible values are &quot;page&quot;, 
        &quot;request&quot;, &quot;session&quot;, &quot;application&quot;, or &quot;any 
        scope&quot; </li>
      <li>type - Fully qualified Java class name of the element to be exposed through 
        the JSP bean named from the id attribute. If not present, no type conversions 
        will be performed. NOTE: The actual elements of the collection must be assignment-compatible 
        with this class, or a request time ClassCastException will occur. 
        <ul>
          <li>example: 
            <pre>&lt;%<br>    java.util.ArrayList list = new java.util.ArrayList();<br>    list.add(&quot;First&quot;);<br>    list.add(&quot;Second&quot;);<br>    list.add(&quot;Third&quot;);<br>    list.add(&quot;Fourth&quot;);<br>    list.add(&quot;Fifth&quot;);<br>    pageContext.setAttribute(&quot;list&quot;, list, PageContext.PAGE_SCOPE);<br> %&gt;
  
  &lt;logic:iterate id=&quot;myCollectionElement&quot; name=&quot;list&quot; type=&quot;java.lang.String&quot;&gt;
  	<i>Do something with myCollectionElement</i>
  &lt;/logic:iterate&gt;</pre>
          </li>
        </ul>
      </li>
    </ul>
  </blockquote>
  <p>&nbsp;</p>
  <h3>Logic Tag Usage</h3>
  <blockquote>
    <p>TODO: content for this section...</p>
    <p>&nbsp;</p>
  </blockquote>
  </body>
  </html>