Overview

JSP Controls Tag Library consists of five tags: Accept, Handler, Reload, Prerender and Render. A typical JSP component uses all of them in the order listed above:

<jc:accept>
  <jc:handler event="...">
    ...
  </jc:handler>
  <jc:reload/>
</jc:accept>

<jc:prerender>
  ...
</jc:prerender>

<jc:render view="...">
  ...
</jc:render>

Accept tag

Accept tag identifies the accept (or input) phase of two-phase request cycle. On accept phase the event, triggered by browser, is handled and input data is processed.

After accept phase has finished, a component can either switch to render phase by reloading itself (non-Ajax mode), or it can continue processing the page, thus entering the render phase without reloading (Ajax mode), or it can redirect to a different location.

Accept tag does not have parameters or attributes. All it does it checks if the request contains an event, or is sent with POST method. An event is a request parameter, that has a ".jspcontrols.event" suffix, like "login.jspcontrols.event".

Because event name is encoded in parameter key, it value can be any you like. You can exploit this feature to use any parameter value you like. For example, if you hook up an event to a submit button, you are free to choose any arbitrary caption for it:

<input type="submit" name="login.jspcontrols.event" value="Log In" />

If you assign an event to a regular link, do not forget to set any value, "1", "true" or "dummy", because it may be important for some browser/server combination. Accept tag does not process event's value, it is interested in the key only:

<a href="loginComponent.jsp?login.jspcontrols.event=true">Log In</a>

Handler tag

Handler tag contains code that processes a particular event. Event name is obtained from event parameter by Accept tag, in the above example event name is "login".

Handler tag has one mandatory attribute, "event". The body of Handler tag is evaluated if the value of event attribute equals to event name obtained from request:

  <jc:handler event="login">
    ...
  </jc:handler>

A Handler tag must be defined inside the body of Accept tag, otherwise it will not be evaluated.

The body of Handler tag can contain JSP scriptlet or can include another JSP or Struts action or any other resource that can process request data. If you use Struts to process input data, the execute method of action class should return null.

Reload tag

Reload tag separates HTTP request corresponding to accept phase from request corresponding to render phase. JSP Controls requires that each phase occurs in its own HTTP request, this helps to fight with Back button issues and makes possible to build simple aggregated JSP components.

Reload tag is placed within Accept tag after all Handler tags and signifies the last step of accept phase. In non-Ajax mode, Accept tag reloads component by redirecting either to the location of component itself or if "jspcontrols.location.parent" request parameter is present, to the location defined by this parameter. This value of this parameter can be set automatically when the page is rendered, if you provide the following hidden element in the form:

<input type="hidden"
       name="jspcontrols.location.parent"
       value="<%=request.getRequestURL().toString()%>" />

Prerender tag

Prerender tag must always be used for Ajax components, non-Ajax components can use regular Render tag with no attributes. This tag is evaluated on render phase. Prerender tag does not have attributes, it always evaluates its body.

This tag sets response MIME type to "text/xml" if request contains flag "jspcontrols.ajax.xhtml", signaling that request was sent asynchronously. YOu do not need to set this flag yourself, the ajaxhelper.js script does this for you.

Prerender tag is usually the place where the view name is chosen based on current application state:

<jc:render>
  <%
      pageContext.setAttribute("jspcontrolsViewSelected",
          session.getAttribute("USER") != null ? "loggedin" : "notloggedin"
      );
  %>
</jc:render>

The value of a scoped variable "jspcontrolsViewSelected" is checked by Render tags to distinguish which view to render if the component has more than one view.

Render tag

Render tag is evaluated on render phase. It always evaluates its body if it has no attributes. This tag has an optional "view" attribute. If the attribute is specified, Render tag is evaluated the value of "view" attribute is equal to value of a scoped variable "jspcontrolsViewSelected", which should be set in either page or request scope.

<jc:render view="notloggedin">
  <jsp:include page="loginComponent-viewLogin.jsp" />
</jc:render>

Render tags allow to define several views in one JSP file and to choose a proper view depending on current application state.