JSP Controls Tag Library: Getting Started
Overview
In terms of the Library, a web component is a stateful server-side object that handles client events and input data, renders itself according to its state, has a certain lifecycle and is defined in one or more JSP files.
The HTML markup rendered by a component is called HTML fragment, because a component is usually included into larger composite page with <jsp:include> action.
A sample Login Component
This guide explains functionality of the Library by building a simple login component. The Login Component has two states: "Logged In" and "Not Logged In", two corresponding views: "loggedin" and "notloggedin", and two input events: "login" and "logout".
If a user has not logged in yet, the Login Component stays at "Not Logged In" state. The "notloggedin" view displays login form with "username" and "password" fields and "Log In" button. The button submits login form, sending "login" event to the component.
When a user logs in, the Login Component switches to "Logged In" state. The "loggedin" view displays logout form containing user name and "Log Out" button. The button submits logout form, sending "logout" event to the component.
The Composite Page
First we are going to create a composite page that aggregates the Login Component. The composite page can contain other markup and/or web components. The index.jsp page aggregating Login Component is deliberately simple, having only two paragraphs of text. It includes the Login Component defined further in loginComponent.jsp file:
<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<html>
<body>
<p>This paragraph is defined directly in the parent page
and should <strong>precede</strong> the content of login control.</p>
<div id="LoginComponent">
<jsp:include page="loginComponent.jsp"/>
</div>
<p>This paragraph is defined directly in the parent page
and should <strong>follow</strong> the content of login control.</p>
</body>
</html>
A component is included into the composite page with a standard <jsp:include> action. The composite page itself does not have to conform to a component lifecycle. Just a simple inclusion, that is all what it takes.
The <div> element surrounding the <jsp:include> action comes into play when component is activated and rendered in Ajax mode.
The Login Component
Unlike the composite page, the component has a specific lifecycle, which is controlled by the Library. A component handles input and output in two separate phases. Input phase is processed by Handler tags, render phase is processed by Prerender and Render tags, as shown in the following outline of the Login Component:
<%@ page contentType="text/html;charset=UTF-8" language="java" %> <%@ taglib uri="/WEB-INF/lib/jspcontrols.tld" prefix="jc" %> <span id="LoginComponent"> <%-- Accept phase --%> <jc:handler event="login"> ... </jc:handler> <jc:handler event="logout"> ... </jc:handler> <jc:reload/> <%-- Render phase --%> <jc:prerender> ... </jc:prerender> <jc:render view="notloggedin"> ... </jc:render> <jc:render view="loggedin"> ... </jc:render> </span>
The above outline is used throughout this guide to highlight different features of the Library. When a particular aspect of the Library is discussed, the body of appropriate tags are filled with related code.
The order of tags is important since JSP page is processed from top to bottom. Handler tags must precede Prerender tag. Prerender tag must precede Render tags. The <span> element that surrounds component code is utlized when component is activated and rendered in Ajax mode.
