usage.apt

这是AJAX的一个HTML实现！ HTML标签AJAX的实现！

Usage
~~~~~

* Base URL
~~~~~~~~~~~

  The <<<baseUrl>>> property is used by the tag to make a request to
  the serverside. The responding resource (e.g., servlet, JSP, etc.) is
  responsible for returning the response in the appropriate format 
  (plain text, HTML, XML, etc.). This take is used as a normal URL you are
  able to append parameters.

** Parameters
~~~~~~~~~~~~~

  Each tag has a common <<<parameters>>> property, composed of name-value pairs that eventually get
  passed to the URL specified in the <<<baseUrl>>> property.  You may specify multiple name-value
  pairs by separating them with commas.  Within each pair, you can also indicate that you want a
  certain form field value to be inserted at the time the request is made by surrounding the value
  with curly brackets.

  Let's look at an example.  Assume we want to pass two parameters on the URL, one indicating the
  make of our automobile and another that is a plain text constant.  The value of the make parameter
  will be inserted at request time.  In this case, we assume the makeId form field contains a value
  of "Honda".

+------------------------------------------------------------------------+
parameters="make={makeId},q=someConstantValue"
+------------------------------------------------------------------------+

  ...will be replaced at request time with...

+------------------------------------------------------------------------+
parameters="make=Honda,q=someConstantValue"
+------------------------------------------------------------------------+

*** Implicit Parameters
~~~~~~~~~~~~~~~~~~~~~~~

  The ajax:htmlContent and ajax:callout tags will accept an implicit parameter in place of the value
  of the source element.  For instance, if you want to include the value of the source element on
  the querystring when making the AJAX call, simply define the parameters attribute as follows:

+------------------------------------------------------------------------+
parameters="someId={ajaxParameter}"
+------------------------------------------------------------------------+


** Post-functions and Error Functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  If you've wondered how to either chain AJAX tags together--by having one execute after another has
  completed--then you'll like this.  The <<<postFunction>>> attribute allows you do just that. This
  attribute expects a JavaScript function name to be passed. The AJAX JavaScript will execute the
  function you define after it has finished its work.

  In addition to post-functions, you may also define functions to be executed when the AJAX request
  could not be completed (e.g., invalid URL, server exception).  You simply enter the name of the
  user-defined JavaScript function into the optional <<<errorFunction>>> tag attribute.


* ajax:anchors
~~~~~~~~~~~~~~

  The anchors tag will convert any HTML anchor tags (\<A\>) within it's area to be AJAX-enabled.
  Essentially the href is removed and its contents placed within an onclick event for the anchor,
  thus forcing the resource to be accessed through AJAX instead.  The response will then be loaded
  in any area on the page you define.

+------------------------------------------------------------------------+
<ajax:anchors target="ajaxFrame">
  <!-- Ajax this link -->
  Refresh first area <a href="${contextPath}/pagearea.jsp" class="contentLink"></a>
</ajax:anchors>

<div id="ajaxFrame"></div>
+------------------------------------------------------------------------+

*---------------------+------------------------------------------------------------+-------------*
 <<Parameter>>        | <<Description>>                                            | <<Required>>
*---------------------+------------------------------------------------------------+-------------*
 target               | The target region on the page where the AJAX response will be written, often a DIV tag | yes
*---------------------+------------------------------------------------------------+-------------*


* ajax:area
~~~~~~~~~~~

  The area tag lets you wrap a piece of the webpage and force all links and resources to be loaded
  inside of it instead of refreshing the entire page.

  If you use ajaxAnchors your content have to be xhtml conform.

+------------------------------------------------------------------------+
<ajax:area id="ajaxFrame"
  style="width:300px; min-height:100px; height:100px;"
  styleClass="textArea"
  ajaxAnchors="true">
  This is the first area and should be refreshed only when the first link or
  the link inside itself is clicked:

  It may include a link to <a href="${contextPath}/pagearea.jsp"> itself </a>
</ajax:area>
+------------------------------------------------------------------------+

*---------------------+------------------------------------------------------------+-------------*
 <<Parameter>>        | <<Description>>                                            | <<Required>>
*---------------------+------------------------------------------------------------+-------------*
 id                   | Name of ID used for enclosing DIV tag written by tag       | yes
*---------------------+------------------------------------------------------------+-------------*
 style                | Inline CSS style properties                                | no
*---------------------+------------------------------------------------------------+-------------*
 styleClass           | CSS class name to use                                      | no
*---------------------+------------------------------------------------------------+-------------*
 ajaxAnchors          | Whether to rewrite HTML anchor tags with an onclick event  | no
*---------------------+------------------------------------------------------------+-------------*


* ajax:autocomplete
~~~~~~~~~~~~~~~~~~~

  The autocomplete tag allows one to retrieve a list of probable values from a backend servlet (or
  other server-side control) and display them in a dropdown beneath an HTML text input field. The
  user may then use the cursor and ENTER keys or the mouse to make a selection from that list of
  labels, which is then populated into the text field. This JSP tag also allows for a second field
  to be populated with the value or ID of the item in the dropdown.

+------------------------------------------------------------------------+
<form>
  Make: <input id="model" name="model" type="text" size="30" class="form-autocomplete" />
  Model: <input id="make" name="make" type="text" size="30" />
</form>

<ajax:autocomplete
  baseUrl="${pageContext.request.contextPath}/GetModel.view"
  source="make"
  target="model"
  parameters="model={model}"
  className="autocomplete"
  indicator="throbbing"
  minimumCharacters="1" />
+------------------------------------------------------------------------+

  <<Note: Tag must appear AFTER the web form.>>

*---------------------+------------------------------------------------------------+-------------*
 <<Parameter>>        | <<Description>>                                            | <<Required>>
*---------------------+------------------------------------------------------------+-------------*
 var                  | Name of the JavaScript object created                      | no
*---------------------+------------------------------------------------------------+-------------*
 attachTo             | Name of the JavaScript object to which autocompleter will attach.  You must define 'var' for this to work. | no
*---------------------+------------------------------------------------------------+-------------*
 baseUrl              | URL of server-side action or servlet that processes search and returns list of values used in autocomplete dropdown; expression language (EL) is supported for this field | yes
*---------------------+------------------------------------------------------------+-------------*
 source               | Text field where label of autocomplete selection will be populated; also the field in which the user types out the search string | yes
*---------------------+------------------------------------------------------------+-------------*
 target               | Text field where value of autocomplete selection will be populated; you may set this to the same value as the source field | yes
*---------------------+------------------------------------------------------------+-------------*
 parameters           | A comma-separated list of parameters to pass to the server-side action or servlet | yes
*---------------------+------------------------------------------------------------+-------------*
 className            | CSS class name to apply to the popup autocomplete dropdown | yes
*---------------------+------------------------------------------------------------+-------------*
 indicator            | ID of indicator region that will show during Ajax request call | no
*---------------------+------------------------------------------------------------+-------------*
 minimumCharacters    | Minimum number of characters needed before autocomplete is executed | no
*---------------------+------------------------------------------------------------+-------------*
 appendSeparator      | The separator to use for the target field when values are appended [default=space]. If appendValue is not set or is set to "false", this parameter has no effect. | no
*---------------------+------------------------------------------------------------+-------------*
 preFunction          | Function to execute before Ajax is begun                   | no
*---------------------+------------------------------------------------------------+-------------*
 postFunction         | Function to execute after Ajax is finished, allowing for a chain of additional functions to execute | no
*---------------------+------------------------------------------------------------+-------------*
 errorFunction        | Function to execute if there is a server exception (non-200 HTTP response) | no
*---------------------+------------------------------------------------------------+-------------*
 parser               | The response parser to implement [default=ResponseHtmlParser] | no
*---------------------+------------------------------------------------------------+-------------*


* ajax:callout
~~~~~~~~~~~~~~

  The callout tag is an easy way to attach a callout or popup balloon to any HTML element supporting
  an onclick event.  The style of this callout is fairly flexible, but generally has a header/title,
  a close link ('X'), and the content itself, of course.  All of this (since AjaxTags 1.2) is
  handled by the OverLIBMWS JavaScript library.  See {{http://www.macridesweb.com/oltest/}} for
  complete instructions on using OverLIBMWS.

+------------------------------------------------------------------------+
<div>
  <p>
    The Hitchhiker's Guide to the Galaxy is a science fiction series written by Douglas Adams
    (1952?2001).  The series follows the adventures of
    <a href="#" class="definition">Arthur Dent</a>, a hapless
    <a href="#" class="definition">Englishman</a> who escapes the destruction of Earth by an alien
    race called the <a href="javascript://nop/" class="definition">Vogons</a> with his friend
    <a href="#" class="definition">Ford Prefect</a>, an alien from a small planet somewhere in the
    vicinity of <a href="#" class="definition">Betelgeuse</a> and researcher for the eponymous
    guide.
  </p>
</div>

<ajax:callout
  baseUrl="${pageContext.request.contextPath}/GetInfo.view"
  sourceClass="definition"
  parameters="q={ajaxCallout}"
  title="Definition"
  overlib="STICKY,CLOSECLICK,DELAY,250,TIMEOUT,5000,VAUTO,WRAPMAX,240" />
+------------------------------------------------------------------------+

  <<Note: Tag must appear AFTER the web form.>>

*---------------------+------------------------------------------------------------+-------------*
 <<Parameter>>        | <<Description>>                                            | <<Required>>
*---------------------+------------------------------------------------------------+-------------*
 var                  | Name of the JavaScript object created                      | no
*---------------------+------------------------------------------------------------+-------------*
 attachTo             | Name of the JavaScript object to which callout will attach.  You must define 'var' for this to work. | no
*---------------------+------------------------------------------------------------+-------------*
 baseUrl              | URL of server-side action or servlet that processes a simple command | yes
*---------------------+------------------------------------------------------------+-------------*
 source               | ID of the element to which the callout will be attached    | either source or sourceClass must be defined
*---------------------+------------------------------------------------------------+-------------*
 sourceClass          | CSS class name of the elements to which the callout will be attached | either source or sourceClass must be defined
*---------------------+------------------------------------------------------------+-------------*
 parameters           | A comma-separated list of parameters to pass to the server-side action or servlet | yes
*---------------------+------------------------------------------------------------+-------------*
 title                | Title for callout's box header. If <<<useTitleBar==false>>> and no title is specified, then the <<<value>>> attribute of the returned XML will be used as the title. | no
*---------------------+------------------------------------------------------------+-------------*
 overlib              | Options for OverLib                                        | no
*---------------------+------------------------------------------------------------+-------------*
 preFunction          | Function to execute before Ajax is begun                   | no
*---------------------+------------------------------------------------------------+-------------*
 postFunction         | Function to execute after Ajax is finished, allowing for a chain of additional functions to execute | no
*---------------------+------------------------------------------------------------+-------------*
 errorFunction        | Function to execute if there is a server exception (non-200 HTTP response) | no
*---------------------+------------------------------------------------------------+-------------*