struts-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hus...@apache.org
Subject cvs commit: jakarta-struts/src/share/org/apache/struts/taglib/html package.html
Date Mon, 19 Feb 2001 17:20:48 GMT
husted      01/02/19 09:20:47

  Added:       src/share/org/apache/struts/taglib/html package.html
  Log:
  (Submitted by Ted Husted.) Add package.html as source to generate HTML Tag Developer's Guide.
  
  Revision  Changes    Path
  1.1                  jakarta-struts/src/share/org/apache/struts/taglib/html/package.html
  
  Index: package.html
  ===================================================================
  <html>
  <head>
  <title>Package Documentation for org.apache.struts.taglib.html Package</title>
  </head>
  <body bgcolor="white">
  <p><a name="doc.Description">The "struts-html" tag library</a> contains
JSP 
  custom tags useful in creating dynamic HTML user interfaces, including input 
  forms.</p>
  <div align="center"> 
    <p> <a href="#doc.Intro">[Introduction]</a> <a href="#doc.Form">[HTML
Form Tags]</a> 
      <a href="#doc.Form">[Other HTML Tags]</a> </p>
  </div>
  
  <hr>
  
  <h3><a name="doc.Intro">Introduction</a></h3>
  
  <p>The tags in the Struts HTML library form a bridge between a JSP view and the 
    other components of a Web application. Since a dynamic Web application often 
    depends on gathering data from a user, input forms play an important role in 
    the Struts framework. Consequently, the majority of the HTML tags involve <a href="#doc.Form">HTML</a>

    forms. Other important issues addressed by the Struts-HTML tags are <a href="#doc.Other.errors">error

    messages</a>, <a href="#doc.Other.hyperlinking">hyperlinking</a> and
<a href="#doc.Other.i18n">internationalization</a>.</p>
  
  <hr>
  <h3><a name="doc.Form">HTML "form" tags</a></h3>
  
  <ul>
      <li><a href="../../../../../../struts-html.html#button">button</a></li>
      <li><a href="../../../../../../struts-html.html#cancel">cancel</a></li>
      <li><a href="../../../../../../struts-html.html#checkbox">checkboxes</a></li>
      <li><a href="../../../../../../struts-html.html#file">file</a></li>
      <li><a href="../../../../../../struts-html.html#hidden">hidden</a></li>
      <li><a href="../../../../../../struts-html.html#image">image</a></li>
      <li><a href="../../../../../../struts-html.html#multibox">multibox</a></li>
      <li><a href="../../../../../../struts-html.html#password">password</a>
input fields</li>
      <li><a href="../../../../../../struts-html.html#radio">radio</a> buttons</li>
      <li><a href="../../../../../../struts-html.html#reset">reset</a> buttons</li>
      <li><a href="../../../../../../struts-html.html#select">select</a>
lists with embedded</li>
      <li><a href="../../../../../../struts-html.html#option">option</a></li>
      <li><a href="../../../../../../struts-html.html#options">options</a></li>
      <li><a href="../../../../../../struts-html.html#submit">submit</a>
buttons</li>
      <li><a href="../../../../../../struts-html.html#text">text</a> input
fields</li>
      <li><a href="../../../../../../struts-html.html#textarea">textareas</a></li>
  </ul>
  
  <p>Each of these tags must be nested within a &lt;html:form&gt; tag.</p>
  
  <h4><a name="doc.Form.formTag">About the form tag</a></h4>
  
  <p>The Struts <code>form</code> tag outputs a standard HTML form tag,
and also 
    links the input form with a JavaBean subclassed from the Struts ActionForm object 
    (see <a href="../../../../../../api/index.html">Javadoc</a>). Each field in

    the form should correspond to a property of the form's bean. When a field and 
    property correspond, the bean is first used to populate the form, and then to 
    store the user's input when the form is submitted to the controller servlet.</p>
  
  <p>The name of the bean and its class can be specified as a property to the form tag,
but 
  may also be omitted. If omitted, the <code>ActionMappings</code> database (loaded
from the 
  <code>struts-config.xml</code> file) is consulted. If the current page is specified
as 
  the <code>input</code> property for an <code>action</code>, the
name of the 
  <code>action</code> is used. The <code>type</code> property for
the bean is also then taken 
  from the configuration, via a Form Bean definition.</p>
  
  <p>Here's a clip from the Struts Example configuration:</p>
  
  <pre>
  &lt;action-mappings&gt; 
    &lt;!-- Process a user logon --&gt;
    &lt;action path=&quot;/logon&quot;
      type=&quot;org.apache.struts.example.LogonAction&quot;
      name=&quot;logonForm&quot;
      scope=&quot;request&quot;
      input=&quot;/logon.jsp&quot;&gt;
    &lt;/action&gt;
    &lt; ... /&gt;
  &lt;/action-mappings&gt;
  &lt;form-beans&gt;
    &lt;!-- Logon form bean --&gt;
    &lt;form-bean name=&quot;logonForm&quot;
      type=&quot;org.apache.struts.example.LogonForm&quot;/&gt;
    &lt; ... /&gt;
    &lt;/form-beans&gt;
  &lt;/pre&gt;
  </pre>
  
  <p>Given this configuration, the HTML form tag for <code>input.jsp</code>
will default 
  to using "<code>logonForm</code>" as its name property and 
  "<code>org.apache.struts.example.LogonForm</code>" as the attribute's type.
This way you 
  can manage the namespace for your framework components from the configuration file.</p>
  
  <p>If the form tag does not find the form bean in any of the scopes (page, request,

  session, application), it creates one using the specified type.</p>
  
  <p>The Struts <code>ActionForm</code> class is equipped with standard
<code>reset()</code> 
    and <code>validate()</code> methods, that can be used by the controller to
enable 
    automatic data validation. See the <a href="/../../../../../../userGuide/building_view.html#form_validation">

    Users Guide</a> for more about Form Validation. An important aspect of validation

    is reporting errors to the user. This can be handled by the Struts <code>errors</code>

    tag, which is discussed <a href="#doc.Other.errors">later in this document</a>.</p>
  
  <hr>
  <h4><a name="doc.Form.attributes">Common Form Tag Attributes</a></h4>
  
  <p>The form "field" tags in the Struts-HTML tag library share a common set of 
    tag attributes that have the same meaning, no matter what field tag they are 
    used with. These properties also accept Runtime Expressions, meaning you can 
    set them with a scriptlet. The common attributes fall into four categories: 
    <a href="doc.Form.attributes.struts">Struts Common,</a> <a href="doc.Form.attributes.navigation">HTML

    Navigation</a>, <a href="doc.Form.attributes.javascript">Javascript</a>,
and 
    <a href="doc.Form.attrbutes.css">CSS</a>.</p>
  <h5><a name="doc.Form.attributes.struts">Struts Common</a></h5>
  <div align="center"> 
    <center>
      <table width=90% border="1" cellpadding="4">
        <tr> 
          <td> name </td>
          <td> The attribute name of the <code>ActionForm</code> bean whose
properties 
            are consulted when rendering the current value of this input field. 
            If not specified, the bean associated with the form tag we are nested 
            within is utilized. </td>
        </tr>
        <tr> 
          <td> property </td>
          <td> Name of the request parameter that will be included with this submission,

            set to the specified value. </td>
        </tr>
        <tr> 
          <td> value </td>
          <td> Value of the label to be used with this element. This value will 
            also be submitted as the value of the specified request parameter. [Body 
            of this tag (if any), or "Click"]&nbsp; </td>
        </tr>
      </table>
    </center>
  </div>
  <p>&nbsp;</p>
  <p>Like <a href="../bean/package-summary.html#doc.Properties">Struts-Bean</a>

    tags, the property attribute for the Struts-HTML tags accept simple, nested, 
    and indexed expressions. For example, this tag:</p>
  <pre>
    &lt;html:text property="mailingAddress.street"/&gt;
  </pre>
  <p>corresponds to:</p>
  <pre>
    getMailingAddress().getStreet()
  </pre>
  <p>For more about using simple, nested, and indexed expressions with Struts, see 
    the <a href="../bean/package-summary.html#doc.Properties">Struts-Bean Developers

    Guide.</a> </p>
  <h5><a name="doc.Form.attributes.javascript">Javascript Event Handlers</a></h5>
  <div align="center"> 
    <center>
      <table width=90% border="1" cellpadding="4">
        <tr> 
          <td> onblur </td>
          <td> Executed when this element loses input focus. </td>
        </tr>
        <tr> 
          <td> onchange </td>
          <td> Executed when this element loses input focus and its value has changed.

          </td>
        </tr>
        <tr> 
          <td> onclick </td>
          <td> Executed when this element receives a mouse click. </td>
        </tr>
        <tr> 
          <td> ondblclick </td>
          <td> Executed when this element receives a mouse - double click. </td>
        </tr>
        <tr> 
          <td> onfocus </td>
          <td> Executed when this element receives input focus. </td>
        </tr>
        <tr> 
          <td> onkeydown </td>
          <td> Executed when this element has focus and a key is depressed.&nbsp;

          </td>
        </tr>
        <tr> 
          <td> onkeypress </td>
          <td> Executed when this element has focus and a key is depressed and released

          </td>
        </tr>
        <tr> 
          <td> onkeyup </td>
          <td> Executed when this element has focus and a key is released </td>
        </tr>
        <tr> 
          <td> onmousedown </td>
          <td> Executed when this element is under the mouse pointer and a mouse 
            button is depressed. </td>
        </tr>
        <tr> 
          <td> onmousemove </td>
          <td> Executed when this element is under the mouse pointer and the pointer

            is moved. </td>
        </tr>
        <tr> 
          <td> onmouseout </td>
          <td> Executed when this element was under the mouse pointer but the pointer

            was moved outside the element. </td>
        </tr>
        <tr> 
          <td> onmouseover </td>
          <td> Executed when this element was not under the mouse pointer but the 
            pointer is moved inside the element. </td>
        </tr>
        <tr> 
          <td> onmouseup </td>
          <td> Executed when this element is under the mouse pointer and a mouse 
            button is released.&nbsp; </td>
        </tr>
        <tr> 
          <td>&nbsp; </td>
          <td> <b>&quot;parent&quot; form tag only</b> </td>
        </tr>
        <tr> 
          <td> onreset </td>
          <td> Executed if the form is reset. </td>
        </tr>
        <tr> 
          <td> onsubmit </td>
          <td> Executed if the form is submitted.&nbsp; </td>
        </tr>
      </table>
    </center>
  </div>
  <h5>&nbsp;</h5>
  <h5><a name="doc.Form.navigation">HTML Navigation Attributes</a></h5>
  <div align="center"> 
    <center>
      <table width=90% border="1" cellpadding="4">
        <tr> 
          <td> accesskey </td>
          <td> The keyboard character used to move focus immediately to this element.

          </td>
        </tr>
        <tr> 
          <td> tabindex </td>
          <td> The tab order (ascending positive integers) for this element. </td>
        </tr>
      </table>
    </center>
  </div>
  <h5>&nbsp;</h5>
  <h5><a name="doc.Form.css">CSS Attributes</a></h5>
  <div align="center">
    <center>
      <table width=90% border="1" cellpadding="4">
        <tr> 
          <td> style </td>
          <td> CSS styles to be applied to this HTML element. </td>
        </tr>
        <tr> 
          <td> styleClass </td>
          <td> CSS stylesheet class to be applied to this HTML element. </td>
        </tr>
      </table>
    </center>
  </div>
  <p>&nbsp;</p>
  <p>See the <a href="../../../../../../struts-html.html">HTML Tags Reference</a>

    for detailed information about the available tags in this tag library, and the 
    complete list of valid attributes for each tag.</p>
  <hr>
  <h3><a name="doc.Other">Other HTML tags</a></h3>
  <p>Aside from form processing, the Struts-HTML offers several other tags or tag 
    properties to help with displaying error messages, maintaining hyperlinks, and 
    with internationalizing your application.</p>
  <h4><a name="doc.Other.errors">Displaying Error Messages</a></h4>
  <p>Error handling is an important part of any application, and curing an error 
    often involves getting the user's help. Struts provides a generalized method 
    for communicating runtime messages to users, based on the same technology used 
    to provide internationalization. </p>
  <p>In a Web application, it is common to reuse the input page to display error 
    messages. The Struts error message tag can be placed wherever you would like 
    the messages to display. If no messages are pending, nothing is printed.</p>
  <p>By default, the errors tag will print all pending messages. You can also specify

    a property when queuing a message, and then refer to that property in the errors 
    tag. In that case, only the message for that property will be displayed. This 
    is helpful when you would like to place the message for a field next to the 
    actual field.</p>
  <p>Error messages are often queued in the ActionForm validate method. Here's a 
    snippet from the Struts Example application:</p>
  <pre>  ActionErrors errors = new ActionErrors();
    if ((username == null) || (username.length() < 1))
        errors.add("username", <br>        new ActionError("error.username.required"));
    if ((password == null) || (password.length() < 1))
        errors.add("password", 
          new ActionError("error.password.required"));
  </pre>
  <p>This queues two error messages, one for the "username" field and another for 
    the "password" field. To print all the messages together, simply place the error 
    tag anywhere in your JSP.</p>
  <pre>
    &lt;body bgcolor="white"&gt;
    &lt;html:errors/&gt;
  </pre>
  <p>Or, you can place specific error messages at different locations</p>
  <pre>
    &lt;td align="left"&gt;
      &lt;html:text property="username" size="16" maxlength="16"/&gt;
      &lt;html:errors property="username"&gt;
    &lt;/td&gt;
    &lt;/tr&gt;&lt;tr&gt;
    &lt;td align="left"&gt;
      &lt;html:text property="password" size="16" maxlength="16"/&gt;
      &lt;html:errors property="password"&gt;
    &lt;/td&gt;
  </pre>
  <p>By default, the actual error message is retrieved from the application's standard

    message resource. This gives you a master list of the error messages used by 
    your application, and provides for internationalization. In the code snippet, 
    the message corresponding to "error.username.required" would be retrieved and 
    displayed to the user at runtime. </p>
  <pre>
    error.username.required=&lt;li&gt;Username is required&lt;/li&gt;
  </pre>
  <p>Most often, error messages are displayed in a particular way. To make it easy 
    to format your messages, you can also specific an <code>errors.header</code>

    and <code>errors.footer</code> string in your message resource. Typically,
you 
    might want to render the messages in a different color, or set them up them 
    to appear in an unordered list. Using the <code>errors.header</code> and <code>errors.footer</code>

    strings keeps the setup codes out of your JSP until a message actually prints.</p>
  <pre>
    errors.header=&lt;h3&gt;&lt;font color="red"&gt;Validation Error&lt;/font&gt;&lt;/h3&gt;
      You must correct the following error(s) before proceeding:&lt;UL&gt;
    errors.footer=&lt;/ul&gt;&lt;hr&gt; 
  </pre>
  <h4><a name="doc.Other.hyperlinking">Maintaining Hyperlinks</a></h4>
  <ul>
    <li><a href="../../../../../../struts-html.html#base">base</a></li>
  </ul>
  <p>When implementing a Web application, it is usually a good idea to use relative

    references to other files in the same application. But in a dynamic application, 
    the controller servlet often returns a completely different file than the one 
    requested. (Often, the requested "file" doesn't actually exist, but represents 
    an action for the controller to interpret.) Since relative references are resolved 
    by the browser, they often won't work in a dynamic application.</p>
  <p>To accommodate this, the Struts-HTML taglib provides a <code>&lt;base&gt;</code>

    tag that renders an HTML 
    <base>
    element with an href attribute pointing to the absolute location of its page. 
  </p>
  <p>As a rule, you should place the Struts-HTML base tag in the &lt;head&gt;
section 
    of any JSP that uses relative references to other files.</p>
  <pre>
    &lt;head&gt;
      &lt;html:base/&gt;
    &lt;/head&gt;
  </pre>
  <h4><a name="doc.Other.sessions">Session Tracking</a></h4>
  <p>The Java Servlet framework has built-in support for tracking a client through 
    a session. Sessions are a useful way to compensate for the stateless nature 
    of HTTP. Tracking a client can be done with either cookies or URL rewriting, 
    cookies being preferred when available. Struts offers three tags that make it 
    easy to write "session-aware" hyperlink references:</p>
  <ul>
    <li><a href="../../../../../../struts-html.html#link">link</a> - Renders
an 
      HTML anchor or hyperlink.</li>
    <li><a href="../../../../../../struts-html.html#rewrite">rewrite</a>
- Renders 
      a request URI, but without creating the &lt;a&gt; hyperlink. This tag is useful

      when you want to generate a string constant for use by a JavaScript procedure.</li>
    <li><a href="../../../../../../struts-html.html#img">img</a> - Renders
an HTML 
      &lt;img&gt; element with the image at the specified URL.</li>
  </ul>
  <p>Each of these tags will automatically apply URL rewriting, to maintain session

    state in the absence of cookies. The content displayed for the hyperlink will 
    be taken from the body of the tag. The base URL for the hyperlink is calculated 
    based on properties given with the tag.</p>
  <p>Normally, the hyperlink or URI you specify is left unchanged. If you would 
    like to include dynamic parameters to the hyperlink or URI, you can pass those 
    to the tags via a JavaBean. If there may be naming conflicts, you can also specify 
    the scope that the tag searches (request, page, session, application). </p>
  <p>To pass a single dynamic parameter, specify the parameter's name using the 
    <code>paramId</code> attribute. You can then specify the name of the JavaBean

    holding the value using the <code>paramName</code> attribute, and a particular

    property using <code>paramProperty</code>. </p>
  <p>So, a tag like</p>
  <pre>   &lt;html:link paramID=&quot;target&quot; 
       paramName=&quot;linkParams&quot; <br>     paramProperty=&quot;target&quot;
       paramScope=&quot;request&quot;<br>   &gt;detail.html&lt;/html:link&gt;</pre>
  <p>would correspond to something like</p>
  <pre>  &lt;A HREF=&quot;detail.html?&lt;%= <br>    request.getParameter(&quot;linkParams&quot;).getTarget()

    %&gt;&quot;&gt;&lt;/A&gt;
  </pre>
  <p>To search all scopes (request, page, session, and application), omit <code>paramScope</code>.

  </p>
  <p>The <code>paramProperty</code> attribute may also be omitted, so long
as the 
    named bean identifies a value that can be converted to a String. 
  <p>To pass multiple dynamic parameters, you can store them in a <code><a
href="http://java.sun.com/j2se/1.3/docs/api/java/util/Map.html">java.util.Map</a></code>,

    and use the name of the map for the <code>paramName</code>. The map must then

    contain one or more <code>paramIDs</code> and their corresponding values.
As 
    the Map is processed, the keys are assumed to be the names of query parameters 
    to be appended. The value associated with each key must be either a String or 
    a String array representing the parameter value(s). If a String array is specified, 
    more than one value for the same query parameter name will be created.
  <p>The HTML session tracking tags use several common attributes, that can be organized

    into three groups, as follows. All of these attributes are not used by all three 
    tags (<code>link</code>, <code>rewrite</code>, and <code>img</code>),
and so 
    the tags using each attribute is given. 
  <p>&nbsp; 
  <table width=90% border="1" cellpadding="4">
    <tr> 
      <th colspan="2">forward, href, and page</th>
    </tr>
    <tr> 
      <td> forward </td>
      <td> [ link rewrite ] - Logical name of a global ActionForward that contains 
        the actual content-relative URI of the destination of this transfer. This 
        hyperlink may be dynamically modified by the inclusion of query parameters, 
        as described in the tag description. You must specify exactly one of the 
        forward attribute, the href attribute, the linkName attribute, or the page 
        attribute </td>
    </tr>
    <tr> 
      <td> href </td>
      <td> [ link rewrite ] - The URL to which this hyperlink will transfer control

        if activated. This hyperlink may be dynamically modified by the inclusion 
        of query parameters, as described in the tag description. You must specify 
        exactly one of the forward attribute, the href attribute, the linkName attribute,

        or the page attribute. </td>
    </tr>
    <tr> 
      <td> page </td>
      <td> [ link rewrite ] - The context-relative path, starting with a slash, 
        of the image to be displayed by this tag. The rendered URL for this image 
        will automatically prepend the context path of this web application (in 
        the same manner as the page attribute on the link tag works), in addition 
        to any necessary URL rewriting. You must specify either the page attribute 
        or the src attribute. </td>
    </tr>
  </table>
  <p>&nbsp; 
  <table width=90% border="1" cellpadding="4">
    <tr> 
      <th colspan="2">linkName, Target , and src</th>
    </tr>
    <tr> 
      <td> linkName </td>
      <td> 
        <p>[ link ] - The anchor name to be defined within this page, so that you 
          can reference it with intra-page hyperlinks. In other words, the value 
          specified here will render a "name" element in the generated anchor tag. 
        </p>
      </td>
    </tr>
    <tr> 
      <td> target </td>
      <td> [ link img ] - The window target in which the resource requested by this

        hyperlink will be displayed, for example in a framed presentation. </td>
    </tr>
    <tr> 
      <td> src </td>
      <td> [ img ] - The URL to which this image will be transferred from This image

        may be dynamically modified by the inclusion of query parameters, as described 
        in the tag description. This value will be used unmodified (other than potential 
        URL rewriting) as the value of the "src" attribute in the rendered tag. 
        You must specify either the page attribute or the the src attribute. </td>
    </tr>
  </table>
  <p>&nbsp; 
  <table width=90% border="1" cellpadding="4">
    <tr> 
      <th colspan="2">paramId, paramName, paramProperty, paramScope </th>
    </tr>
    <tr> 
      <td> paramId </td>
      <td> [ link img ] - The name of the request parameter that will be dynamically

        added to the generated src URL. The corresponding value is defined by the 
        paramName and (optional) paramProperty attributes, optionally scoped by 
        the paramScope attribute</td>
    </tr>
    <tr> 
      <td> paramName </td>
      <td> [ link img ] - The name of a JSP bean that is a String containing the 
        value for the request parameter named by paramId (if paramProperty is not 
        specified), or a JSP bean whose property getter is called to return a String 
        (if paramProperty is specified). The JSP bean is constrained to the bean 
        scope specified by the paramScope property, if it is specified. </td>
    </tr>
    <tr> 
      <td> paramProperty </td>
      <td> [ link img ] - The name of a property of the bean specified by the paramName

        attribute, whose return value must be a String containing the value of the 
        request parameter (named by the paramId attribute) that will be dynamically 
        added to this hyperlink or src URL</td>
    </tr>
    <tr> 
      <td> paramScope </td>
      <td> [ link img ] - The scope within which to search for the bean specified 
        by the paramName attribute. If not specified, all scopes are searched. </td>
    </tr>
  </table>
  <p>&nbsp; 
  <table width=90% border="1" cellpadding="4">
    <tr> 
      <th colspan="2"> 
        <p>name, property, scope 
      </th>
    </tr>
    <tr> 
      <td> name </td>
      <td> [ link rewrite img ] - The name of a JSP bean that contains a <code><a
href="http://java.sun.com/j2se/1.3/docs/api/java/util/Map.html">Map</a></code>

        representing the query parameters (if <code>property</code> is not specified),

        or a JSP bean whose property getter is called to return a <code>Map</code>

        (if <code>property</code> is specified). </td>
    </tr>
    <tr> 
      <td> property </td>
      <td>[ link rewrite img ] - The name of a property of the bean specified by 
        the name attribute, whose return value must be a <code><a href="http://java.sun.com/j2se/1.3/docs/api/java/util/Map.html">Map</a></code>

        containing the query parameters to be added to the src URL. You <b>must</b>

        specify the name attribute if you specify this attribute </td>
    </tr>
    <tr> 
      <td> scope </td>
      <td> [ link rewrite img ] - The scope within which to search for the bean 
        specified by the name attribute. If not specified, all scopes are searched. 
      </td>
    </tr>
  </table>
  <p>See the <a href="../../../../../../struts-html.html">HTML Tags Reference</a>

    for the complete list of valid attributes for each tag.. 
  <h4><a name="doc.Other.i18n">Internationalization</a></h4>
  <p>Internationalization is automatically supported by the HTML tags where appropriate.

  </p>
  <p><a href="../../../../../../struts-html.html#errors">Errors</a> - By
default, 
    the text for your messages will be returned by the default message resource, 
    which will select the appropriate language for the user. You may also specify 
    another message resource using the <code>bundle</code> attribute.</p>
  <p><a href="../../../../../../struts-html.html#html">HTML</a> - Renders
an HTML 
    element with language attributes extracted from the user's current Locale object, 
    if there is one. </p>
  <p>See the <a href="../../../../../../userGuide/building_view.html#i18n">Users

    Guide</a> for more on how Struts helps you internationalize your applications.</p>
  <p>&nbsp;</p>
  </body>
  </html>
  
  
  

Mime
View raw message