Package javawebparts.ajaxparts.taglib

The AjaxParts Taglib (APT).

See:
          Description

Class Summary
AjaxEnableTag This class is a custom tag (AjaxEnableTag) that must be placed on a page AFTER all other Ajax-enabled tags.
AjaxEventTag This class is a custom tag (AjaxEventTag) that emits the small script element following an element to be Ajax-enabled.
AjaxInit This class is responsible for all configuration tasks to prepare for Ajax functionality.
AjaxManualTag This class is a custom tag (AjaxManualTag) that emits the script necessary to set up a manual AJAX event.
AjaxTimerTag This class is a custom tag (AjaxTimerTag) that emits the script necessary to set up a timed AJAX event.
AjaxUtils This class contains utility functions used throughout the taglib.
 

Package javawebparts.ajaxparts.taglib Description

The AjaxParts Taglib (APT).

Table Of Contents

Introduction To APT
Using APT
Basic APT Concepts
Configuring APT
Referencing Configurations
Tag reference
Standard Handlers
Writing Custom Handlers
General Notes
JSON-P Support


-- Introduction To APT --

APT is a JSP taglib for attaching AJAX events to any element on an HTML page, allowing you to use AJAX techniques (Asynchronous Javascript with XML) in response to any user interface event (or as a result of a timer, or manually called from your own code) without having to write any code (at least, none you don't choose to write). APT is XML configuration file driven and consists of only four custom tags, and only two are used on a regular basis, the others less frequently. It is useful for adding AJAX to existing applications as it requires NO changes to your existing pages, just a few simple additions in the form of a new taglib declaration and adding the APT tags in the appropriate places, plus an addition to web.xml. For new apps it is of course ideal too because it will save you from having to write all the client-side AJAX code yourself.

Note that APT says NOTHING about what happens on the server-side of the interaction. It is strictly concerned with the client-side of the AJAX equation. There may be some other parts in Java Web Parts that helps with the server-side though!

APT began its life as an enhanced version of the Struts HTML taglib, but was subsequently modified to be framework-agnostic. You should be able to use APT with any application framework, or with no framework at all, the choice is entirely yours!


-- Using APT --

Before anything else, let's look at the steps you will go through to use APT in your own application.

  1. Add the javawebparts-ajaxparts-xxxx.jar and the javawebparts-core-xxxx.jar to your application, usually in the WEB-INF/lib directory, where xxxx is the version you are deploying.


  2. Add a context parameter to your web.xml file that will point to your ajax-config.xml file(s) like so:

    <context-param>
      <param-name>AjaxPartsTaglibConfig</param-name>
      <param-value>/WEB-INF/ajax-config.xml </param-value>
    </context-param>

    This is a context-relative path, which can of course be whatever you like, as can the name of the file itself. However, you may want to stick with the location and name shown here as they are the recommended values (and also what will be used throughout this documentation).

    Building this configuration file is covered in the Configuring APT section. Building that file is in fact a required step here as well though!

    OPTIONAL: In some environments and under certain circumstances, there can be a problem with DTD validation of the configuration file. This can be avoided by setting another context paramete:

    <context-param>
      <param-name>AjaxPartsTaglibValidateConfig</param-name>
      <param-value>false </param-value>
    </context-param>

    Setting this parameter to "false" disabled validation of the configuration file. Setting it to "true", or not setting it at all, leaves validation turned on, which is the default action.


  3. Add the taglib declaration to any JSP that will use APT, like so:

    <%@ taglib prefix="ajax" uri="javawebparts/ajaxparts/taglib" %>

    The prefix can be whatever you like of course, although "ajax" is recommended. Note that the TLD is contained in the javaweparts-ajaxparts-xxx.jar file, so you don't need to worry about it.


  4. For any page element you wish to attach an AJAX event to, add the following tag after it:

    <ajax:event ajaxRef="xxxx/yyyy" attachTo="xxxx/yyyy"/>

    There are two ways you can do this. First, the original way, is that this tag MUST come IMMEDIATELY after the element to attach to. Note that IMMEDIATELY means IMMEDIATELY!! There can be NOTHING between the tag you wish to AJAX-enable and this tag, NOT EVEN WHITESPACE!! The only exception to this rule is elements like checkboxes and radios where you normally follow them with some text. This is OK, the emitted Javascript will handle these cases. In this case, you SHOULD NOT include the attachTo attribute.

    The alternative new method, which is the recommended method, is to use the attachTo attribute. The value of this attribute is the DOM ID of the element to attach the event to. When you use this approach, the event tag can come anywhere on the page, it does not need to follow the element to be AJAX-enabled, although it is recommended that you in fact do keep them near each other.

    The meaning of ajaxRef is covered in the "Referencing Configurations" section, but suffice it for now to say that it links the element you are attaching an AJAX event to with the appropriate configuration in ajax-config.xml.


  5. AFTER all <ajax:event> tags on the page, add the following tag:

    <ajax:enable/>

    It is VERY important that this come AFTER all AJAX tags on the page. The recommended location is right before the closing </body> tag.


  6. -- Basic APT Concepts --

    APT works by hooking a UI event like onClick or onMouseOver, and firing an AJAX request in response. It can also fire AJAX events in response to a timer, as well as expose Javascript functions for you to manually call to fire an AJAX request.

    APT works by defining an event in the ajax-config.xml file, and then attaching it to a given element on the page by placing the <ajax:event/> tag after it. For each event configured, a request handler and a response handler (or multiple response handlers) is defined. A request handler is a Javascript function that forms some sort of request, be it an XML document, a simple query string, or something else entirely, and sends it to a defined URI. A response handler is what takes the response from the remote system and does something with it, be it updating a <div>, populating a <select> or something else. APT comes packaged with a number of very common and powerful handlers, but you can also write your own to suite your needs. We have found that a majority of the time, the packaged handlers (calls standard handlers) suffice for most peoples' needs.


    -- Configuring APT --

    As mentioned previously, APT is a declarative approach to AJAX, which means all you need to do is write an XML configuration file to drive it, no mucking around with Javascript (usually). The following is a basic outline of the configuration file.

    <ajaxConfig>
      <handler name="" type="">
        <function></function>
        <location></location>
      </handler>
      <group ajaxRef="" async="" method="" form="" preProc="" postProc="">
        <errroHandler code="" type="" />    
        <element ajaxRef="" async="" method="" form="" preProc="" postProc="">
          <errroHandler code="" type="" />
           <event type="" async="" method="" form="" preProc="" postProc="">
            <errroHandler code="" type="" />
             <requestHandler type="" target="" jsonp="">
               <parameter></parameter>
            </requestHandler>
            <responseHandler type="" matchPattern="">
              <parameter> </parameter>
            </responseHandler>
          </event>
        </element>
      </group>
    </ajaxConfig>

    The following table summarizes each element.

    ajaxConfig This is simply the root element of the document.

    Attributes: None.
    ajaxConfig/handler This element is used to define a custom handler (request, response or error). This is entirely optional!

    Attributes:
    • name (required)- Gives a name to the handler that you will reference later in the config file


    • type (required)- Is one of three values, "request", "response" or "error", which defines whether this is a request handler, a response handler or an error handler (must be lower-case).
    ajaxConfig/handler/function This names the Javascript function that implements this handler. Note that this function must adhere to a specific signature, which is described later in the "Creating Custom Handlers" section.

    Attributes: None.
    ajaxConfig/handler/location This defines where the function can be found. It can be one of two things, either the value "local", which means that you are taking full responsibility for ensuring the function is on the page (however you wish to accomplish that) or a URL to an external file. In the later case, a <script> tag will be rendered with the src attribute set to the value you provide here, so it can be any value that would normally be valid in a <script> tag. Note that if the value "local" is used, you must take care to ensure that the handler code appears before the <ajax:enable> tag!

    Attributes: None.
    ajaxConfig/group This element defines a group of AJAX-enabled elements. A group will most usually represent a single JSP page, but this is NOT a requirement! You can create arbitrary groups as you see fit.

    Attributes:
    • ajaxRef (required)- For each <group> in your ajax-config.xml file, you need to specify a unique ajaxRef value for it. It can be anything you like. Note that this value IS case-sensitive!


    • async (optional)- This attribute takes one of two values: "true" or "false" (must be lower-case). You will almost always want this to be "true", and that is the default value at group-level (see comments following this table for what the different scope levels mean). If this is set to false, then no Javascript on the client will execute until the response has been received by the client. Defaults to "true".


    • method (optional)- This attribute takes one of the following values: "head", "get", "post", "put", "delete", "trace", "options", "connect" (must be lower-case). Defaults to "post".


    • form (optional)- This attribute gives the name of an HTML form that the request handler will use, if the choosen request handler works with a form at all. You can use the special value "parent" here to indicate the handler should use the parent form of the element that fired the AJAX event. However, the "parent" value IS NOT VALID for events of type "manual" or "timer". Note that this value IS case-sensitive! Defaults to "parent".


    • preProc (optional)- This attribute names a Javascript function that will be called before the AJAX request is made to the server. Returning true from this Javascript function will cause the AJAX request to be canceled. Note that this value IS case-sensitive!


    • postProc (optional)- This attribute names a Javascript function that will be called after the AJAX request returns from the server, and also after the response handler(s) have finished, and after all <script> blocks in the server's response have been executed. Note that this value IS case-sensitive!
    ajaxConfig/group/errorHandler This element defines a handler that will deal with a specific HTTP response code for all elements within the group. You can define as many as you like per group, or none at all, but you must only define one per HTTP response code!

    Attributes:
    • code (required)- This is the HTTP respone code this handler will handle. Can be any HTTP response code, i.e., 404, 500, etc.


    • type (required)- This is the type of handler to use. This can be either the "name" attribute of a custom handler defined in the ajax-config.xml file, or a value that begins with "std:", for instance "std:AlertErrorHandler". This means it is one of the built-in "standard" APT handlers.
    ajaxConfig/group/element This element represents an element on the page you will attach an AJAX event to.

    Attributes:
    • ajaxRef (required)- For each <element> in your ajax-config.xml file, you need to specify a unique ajaxRef value for it. It can be anything you like. Note that this value IS case-sensitive!


    • async (optional)- This attribute takes one of two values: "true" or "false" (must be lower-case). You will almost always want this to be "true", and that is the default value at group-level (see comments following this table for what the different scope levels mean). If this is set to false, then no Javascript on the client will execute until the response has been received by the client. Defaults to "true".


    • method (optional)- This attribute takes one of the following values: "head", "get", "post", "put", "delete", "trace", "options", "connect" (must be lower-case). Defaults to "post".


    • form (optional)- This attribute gives the name of an HTML form that the request handler will use, if the choosen request handler works with a form at all. You can use the special value "parent" here to indicate the handler should use the parent form of the element that fired the AJAX event. However, the "parent" value IS NOT VALID for events of type "manual" or "timer". Note that this value IS case-sensitive! Defaults to "parent".


    • preProc (optional)- This attribute names a Javascript function that will be called before the AJAX request is made to the server. Returning true from this Javascript function will cause the AJAX request to be canceled. Note that this value IS case-sensitive!


    • postProc (optional)- This attribute names a Javascript function that will be called after the AJAX request returns from the server, and also after the response handler(s) have finished, and after all <script> blocks in the server's response have been executed. Note that this value IS case-sensitive!
    ajaxConfig/group/element/errorHandler This element defines a handler that will deal with a specific HTTP response code for all events within the element. You can define as many as you like per element, or none at all, but you must only define one per HTTP response code! Note that if you define a handler here that handles the same code as a handler defiend at the group level, this handler definition will override those definitions.

    Attributes:
    • code (required)- This is the HTTP respone code this handler will handle. Can be any HTTP response code, i.e., 404, 500, etc.


    • type (required)- This is the type of handler to use. This can be either the "name" attribute of a custom handler defined in the ajax-config.xml file, or a value that begins with "std:", for instance "std:AlertErrorHandler". This means it is one of the built-in "standard" APT handlers.
    ajaxConfig/group/element/event This element defines an event that will fire an AJAX request on the parent element.

    Attributes:
    • type (required)- This can be any of the following standard Javascript UI events: onblur, onfocus, onchange, onclick, oncontextmenu, onkeydown, onkeypress, onkeyup, onmousemove, onmouseout, onmouseover, onmouseup, onmousedown, onresize, onscroll, onselect. This value MUST be lower-case. It can also be one of two special values, "manual", which means this will fire in response to a developer calling a rendered Javascript function manually, and "timer", which means this will fire in response to a timer. Note that only a single event of type "manual" or "timer" should be defined per element! In fact, logically, any element that has one of hese types of events should have no other events defined for it. This would be considered a misconfiguration, and would yield undefined behavior!


    • async (optional)- This attribute takes one of two values: "true" or "false" (must be lower-case). You will almost always want this to be "true", and that is the default value at group-level (see comments following this table for what the different scope levels mean). If this is set to false, then no Javascript on the client will execute until the response has been received by the client. Defaults to "true".

    • method (optional)- This attribute takes one of the following values: "head", "get", "post", "put", "delete", "trace", "options", "connect" (must be lower-case). Defaults to "post".


    • form (optional)- This attribute gives the name of an HTML form that the request handler will use, if the choosen request handler works with a form at all. You can use the special value "parent" here to indicate the handler should use the parent form of the element that fired the AJAX event. However, the "parent" value IS NOT VALID for events of type "manual" or "timer". Note that this value IS case-sensitive! Defaults to "parent".


    • preProc (optional)- This attribute names a Javascript function that will be called before the AJAX request is made to the server. Returning true from this Javascript function will cause the AJAX request to be canceled. Note that this value IS case-sensitive!


    • postProc (optional)- This attribute names a Javascript function that will be called after the AJAX request returns from the server, and also after the response handler(s) have finished, and after all <script> blocks in the server's response have been executed. Note that this value IS case-sensitive!
    ajaxConfig/group/element/event/errorHandler This element defines a handler that will deal with a specific HTTP response code for this event. You can define as many as you like per event, or none at all, but you must only define one per HTTP response code! Note that if you define a handler here that handles the same code as a handler defiend at the element or group level, this handler definition will override those definitions.

    Attributes:
    • code (required)- This is the HTTP respone code this handler will handle. Can be any HTTP response code, i.e., 404, 500, etc.


    • type (required)- This is the type of handler to use. This can be either the "name" attribute of a custom handler defined in the ajax-config.xml file, or a value that begins with "std:", for instance "std:AlertErrorHandler". This means it is one of the built-in "standard" APT handlers.
    ajaxConfig/group/element/event/requestHandler This defines what request handler will be used to service this event. You must specify one and only one of these per event.

    Attributes:
    • type (required)- This is the type of handler to use. This can be either the "name" attribute of a custom handler defined in the ajax-config.xml file, or a value that begins with "std:", for instance "std:QueryString". This means it is one of the built-in "standard" APT handlers.


    • target (required)- This attribute names the URI to submit the request to. This can be context-relative or absolute. For the former, begin with a forward-slash, which will cause the URL rendered in the Javascript to start with the current context path, and then this target will be appended. For the later, begin with anything other than a forward-slash, in which case this target will be rendered in the Javascript exactly as it appears in the ajax-config.xml file. Note that URL rewriting is performed on this target, so if cookies are disabled, jsessionid will be appended.

    • jsonp (optional)- This can have a value of "true" or "false", and it will default to false if not present. This enabled JSON-P support (see the JSON-P Support for details).
    ajaxConfig/group/element/event/requestHandler/parameter The meaning of this element is specific to the handler being used. See the "Standard Request/Response Handlers" section below. Note that even if the handler does not use this, the element must still be present! It is in that case perfectly valid to have <parameter/>.

    Attributes: None.
    ajaxConfig/group/element/event/responseHandler This defines what response handler will be used to service this event. You can specify multiple response handlers per event, but at least one must be defined per event.

    Attributes:
    • type (required)- This is the type of handler to use. This can be either the "name" attribute of a custom handler defined in the ajax-config.xml file, or a value that begins with "std:", for instance "std:QueryString". This means it is one of the built-in "standard" APT handlers.


    • matchPattern (optional)- This attribute is a regex expression that is used to examine the response from the server. If the response matches this pattern, only then will the response handler fire. Because you can have multiple response handlers per event, this allows you the possibility of only having certain ones execute, depending on the returned response.
    ajaxConfig/group/element/event/responseHandler/parameter The meaning of this element is specific to the handler being used. See the "Standard Request/Response Handlers" section below. Note that even if the handler does not use this, the element must still be present! It is in that case perfectly valid to have <parameter/>.

    Attributes: None.

    A word about scope levels...

    The "form", "async" and "method" attributes mentioned above can be defined in three "scopes", or levels: group, element and event. The values defined at higher levels can be overriden by those at lower levels. So, for instance, if you have the method on a <group> element set to "get", and you then have the method attribute on an <event> element set to "post", then for that event, the method used to make the request will be "post", but for any other events in that group, "get" will be used.

    This also applies to the <errorHandler> elements. So, if you have an <errorHandler> defined as a child of <group> element to handle 404 status codes that uses a particular error handler, you can use a different error handler for that 404 code for a specific event, or for a specific element (i.e., all events under that element would then use the new error handler, while any other elements in the group still use the handler defined for the group).

    TO BE DONE!!! As an example, let's examine an APT configuration file in detail:

    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

    EXPLANATION!!!!!!!!!!!!!!!!!!!!!!!!!!!



    -- Referencing Configurations --

    With the information in the "Configuring APT" section, you should be able to write a AJAX ajax-config.xml file. One question remains: how do you tie those configuration entries to elements on the page? The answer is it all revolves around the ajaxRef values.

    When you put an <ajax:event> after an element on a page, that tag accepts a single ajaxRef attribute. This attribute always has a value in the form xxxx/yyyy, where xxxx is the ajaxRef of a <group> in the ajax-config.xml file, and yyyy is the ajaxRef of an <element> in the ajax-config.xml file. The groups and elements form a hierarchy, and the ajaxRef of the tag is a path through that hierarchy to a specified <element> configuration.

    Please note that ajaxREFs are ALWAYS case-sensitive!


    -- Tag reference --

    This section contains details on all the custom tags contained in APT.

    <ajax:event/> This is the tag you place IMMEDIATELY after an element on the page you wish to attach an AJAX event to (it only has to be immediately after it if you don't use the attachTo attribute).

    Attributes:
    • ajaxRef (required)- This is the ajaxRef of the <element> in the ajax-config.xml file to apply to this page element, in the form xxxx/yyyy (see the "Referencing Configurations" section for explanation)


    • attachTo (optional)- This is the DOM ID of the element on the page to attach the AJAX event to. When you use this attribute, the event tag does NOT need to come immediately after the element to AJAX-enable, which it does if you don't use this attribute. Using this attribute is the new method, and it is the recommended method of using APT.
    <ajax:enable/> This is the tag that MUST be placed AFTER all <ajax:event/> tags on the page.

    Attributes:
    • debug (optional, default: "error")- This sets the level of debugging that will occur on the client-side. The possible values are "trace", "debug", "info", "error", "fatal". Each value, in that order, will result in less debug messages (i.e., the setting "trace" will result in the most verbose logging, and "fatal" will result in the least.


    • logger (optional, default: "JWPAlertLogger")- This sets the logger that will be used to deal with logging messages. Two loggers a built in: "JWPAlertLogger", which just dislays logging messages with a Javascript alert(), and "JWPWindowLogger" which opens a new window and writes logging messages to it.


    • suppress (optional, default: "false")- This determines whether the logger and main Javascript object that really is the heart of AjaxParts Taglib on the client is rendered. This is meant to be set to "true" when you are generating a response to an AJAX request with a JSP, and you want to use AjaxParts Taglib in that JSP. In that case, since most of the required Javascript is already present on the client, you would not want to render it again as part of the JSP response (and it would likely cause problems if you did). So, in those situations, you will want to suppress the rendering of that code. This attribute allows you to do that.
    <ajax:timer/> This tag sets up a repeating AJAX event on a timer. Think of things like periodically refreshing a status update, etc. Note that when you write the configuration for a timer event, it must always be part of a virtual form. Also note that if the request handler you declare needs a reference to an HTML form, the std;QueryString handler for example, then you MAY NOT use the special value "parent" here! Note that the default value of the form attribute is in fact "parent", so an error will occur if you do not override this value with the name or ID of a real form.

    This tag will render two Javascript functions named startXXXX() and stopXXXX(), where XXXX is the ajaxRef, with the slash replaced with an underscore. For example, for ajaxRef "MyPage/MyButton", the functions rendered would be startMyPage_MyButton() and stopMyPage_MyButton(). As their names imply, these allow you to manually start and stop the timed event. Note that if the stop function is called while an AJAX request is in progress, that event will complete, but no further events will fire unless you call the start function.

    Attributes:
    • ajaxRef (required)- This is the ajaxRef of the <element> in the ajax-config.xml file, in the form xxxx/yyyy (see the "Referencing Configurations" section for explanation) that contains the <event> of type "timer" that defines the AJAX event the timer will fire.


    • frequency (required)- This is the amount of time, in milliseconds, between event firings. Note that when the timer is started, it will always wait this amount of time before the first firing takes place, even if startOnLoad is "true"


    • startOnLoad (optional)- This determines whether a timer will be started automatically when the page loads (when set to "true"), or whether you will take full responsibility for starting the timer (when set to "false"). The later is good if you want to start the timed event after something else on the page happens, like only start updating a status display after the user clicks a "Start" button for instance. In this case, you will need to set call the function that starts the timer yourself.
    <ajax:manual/> This tag is used when you just want the AJAX code rendered on the page but do not want to attach it to any given element. This is good if you want to do a lot of complex processing around the event, but would rather not have to write the actual AJAX code and also still keep the configuration of the event in the ajax-config.xml file. Also note that if the request handler you declare needs a reference to an HTML form, the std;QueryString handler for example, then you MAY NOT use the special value "parent" here! Note that the default value of the form attribute is in fact "parent", so an error will occur if you do not override this value with the name or ID of a real form.

    Attributes:
    • ajaxRef (required)- This is the ajaxRef of the <element> in the ajax-config.xml file to apply to this manual function, in the form xxxx/yyyy (see the "Referencing Configurations" section for explanation)


    • function (required)- This is the name of the Javascript function that will be created for you to call. You can then call this function at any time to fire the configured AJAX event.



    -- Standard Handlers --

    APT ships with a number of handlers built-in, which are termed "standard" handlers. They are split into the following groups:


    The following tables detail these standard handlers. Some general notes:


    Request Handlers

    std:QueryString Constructs a query string and sends it to the specified target.

    Requires form reference: Yes

    Parameter:

    A comma-separated list of name-value pairs. The name is the parameter that will be submitted, the value is the form element to get the value from. For example: "text1V=text1,text2V=text2" will result in the parameters "text1V" and "text2V" being submitted, with the values of the "text1" and "text2" form fields as their values, respectively.
    std:SendById Constructs a query string (or POST body) based on explicit elements based on DOM ID and sends it to the specified target.

    Requires form reference: No

    Parameter:

    A comma-separated list. The first element MUST be the type of request to make, either the value "xml" or "querystring". If the value is "xml", then this element must also contain the root node name. In other words, if you want to send XML and you want the root element to be "person", then the first element of this CSV list should be "xml.person". After that, the elements are in the form X.Y, where X is the DOM ID of the element to get the value from, and Y is the property of that element to read. So, you can do "myDiv.innerHTML", or "myDiv.innerText" or "myTextbox.value", or any other accessible property of the element.
    std:SimpleRequest Simply submits a request to the server with no data passed along with the request.

    Requires form reference: No

    Parameter:

    None.
    std:SimpleXML Constructs a simple XML document and sends it to the specified target as a POST body.

    Requires form reference: Yes

    Parameter:

    A comma-separated list of name-value pairs, where the first item is the name of the root element. For example: "Person,firstName=text1,lastName=test2" will result in the following XML being constructed:

    <Person>
      <firstName>??</firstName>
      <lastName>??</lastName>
    </Person>

    ...where the ?? value of the <firstName> will be the value of the "text1" form field and the ?? value of the <lastName> will be the value of the "text2" form field.
    std:Poster Submits values as the POST body of the request. This will obviously only have meaning if the HTTP method is POST.

    Requires form reference: Yes

    Parameter:

    A comma-separated list of name-value pairs. The name is the parameter that will be submitted, the value is the form element to get the value from. For example: "text1V=text1,text2V=text2" will result in the parameters "text1V" and "text2V" being submitted, with the values of the "text1" and "text2" form fields as their values, respectively.
    std:FormSender Submits the contents of a form via either POST or GET, as simple request parameters, JSON or XML. When you send the form contents as JSON or XML, the HTTP method must be POST... GET will not work! For plain parameters, either GET or POST will work.

    Requires form reference: Yes

    Parameter:

    One of three values: "parameters", "json" or "xml". The value "parameters" will send the contents of the form as plain old request parameters. "json" will send the contents of the form as JSON, when the base object name is the name of the form. "xml" will send the contents of the form as XML, where the root node is the name of the form. Note that <select> elements that do no have a value selected will not be transmitted. This is true for radio elements as well.

    Response Handlers

    std:Alerter Pops a Javascript alert() box with the body content of the response.

    Parameter:

    None.
    std:CodeExecuter This handler assumes the response from the server is a Javascript snippet and executes it. Note that the response should NOT be wrapped in <script> tags.

    Parameter:

    None.
    std:IFrameDisplay This handler takes the response from the server and writes it to the document in a named iFrame. This is essentially the same thing as the std:InnerHTML handler, except that it works with iFrames specifically.

    Parameter:

    The name of an iFrame on the page. Note that this is the value of the iFrame's name attribute, NOT it's DOM ID attribute! This can be a comma-separated list of names, in which case all the iFrames will be populated with the same result.
    std:InnerHTML Sets the innerHTML property of a named element to what the server returns.

    Parameter:

    The DOM ID of an element on the page to update. This can be a comma-separated list of IDs, in which case all the elements will have their innerHTML properties populated with the same result.
    std:DoNothing This may seem like a pointless handler, but it really is not, and here's why... any response received by the server, regardless of what response handler(s) you use, will be examined for <script> blocks. Any that are found will be eval()'d. This is useful because it is typical to return Javascript as an AJAX response and have it executed on the client. However, because you must always define at least one response handler per event, if all you want to do is execute returned Javascript, you still need a response handler for the event, but in effect you don't want it to do anything. That's exactly what this is for! Note that this and the std;CodeExecuter are very similar, but the primary difference is that std:CodeExecuter assumes the response from the server is Javascript, and executes it, whereas this handler can be used if the response may or may not be Javascript (or the response may or may not include Javascript). The other difference is that std:CodeExecuter does not require the Javascript to be surrounded by <script> tags, whereas this one would.

    Parameter:

    None.
    std:Redirector This handlers assumes the response from the server is a URL, and redirects the client to it. Alternatively, you can hard-code a URL in the config file, in which case the response is essentially irrelevent, although you still may want to use the matchPattern attribute to conditionally fire this. This handlers is especially useful for things like session timesouts... You can have a filter that detects a timed out session and returns the URL to redirect to in that case. Then, for any AJAX event, configure this as the first response handlers in the response handler chain, and set a matchPattern that will cause it to only execute in response to a redirect event (perhaps if the response begins with "http" for example), or alternatively, hardcoded the URL to redirect to in the config file, and return some status messages when the session is timed out that matchPattern looks for.

    Parameter:

    None, or, the URL to redirect to. If no value is specified, then the response from the server is assumed to be the URL to redirect to.
    std:Selectbox This handler populates a <select> element with data returns by the server. The server process, which you are responsible for, must return XML in the following form:

    <list>
      <option value="??">????</option>
    </list>

    In this structure, ?? is the value attribute of a given <option> element within the <select>, and ???? is the text to go along with the option.

    Parameter:

    The DOM ID (or "name", both work) of the <select> element to populate. This can be a comma-separated list of IDs or names, in which case all the <select>'s will be all populated with the same result.
    std:TextboxArea Sets the text in a textbox or textarea element.

    Parameter:

    The "name" attribute of the form element to set text for. Note that only elements in the SAME form as the element that fired the event can be set!
    std:WindowOpener This handler opens the response from the server in a new window.

    Parameter:

    The parameter is composed of two elements, separated by a tilde (~) character. The first element is the title of the new window. The second element is a comma-separated list of window options. Please Google for the window.open() method to see the options available.
    std:XSLT This handler is capable of transforming XML returned by the server to HTML, or another XML form, or anything else you can do with XSLT. Note that this handler requires use of the Sarissa library available at http://sarissa.sourceforget.net

    Parameter:

    A comma-separated list where the first element is the DOM ID of an element on the page where output will be displayed (by setting innerHTML), and the second element is the path of the XML file for the XSL Transform.
    std:FormManipulator This handler populates one or more fields in a form. Also, it is capable of manipulating the properties of the form and the elements within it. The server process, which you are responsible for, must return XML in the following form:

    <form name="AA">
      <formproperty name="BB" value="CC"/>
      <element name="DD" value="EE">
        <property name="FF" value="GG"/>
      </element>
    </form>

    ...where AA must be the name of the form, BB is the name of the form property (e.g., action) and CC it's new value. DD must be the name of the element and EE the value you wish to assign to it. FF is like BB but then for the element's property (e.g., disabled or style.width) and GG the new value for the property. As you can see it is possible to connect properties with a dot as long as it is possible in Javascript to retrieve them with element[prop1][prop2]!

    Parameter:

    None.

    Error Handlers

    std:AlertErrorHandler Pops a Javascript alert() displaying a message formed by taking the response text and status code from the XMLHttpRequest object that processed the event.



    -- Writing Custom Handlers --

    Although APT tries to provide the majority of functionality that you might require with its standard handlers, we recognize that they will not always be sufficient. With this in mind, the ability to write custom handlers is available to you.

    -- General Notes --

    -- JSON-P Support --



    Copyright 2005 Frank W. Zammetti