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 and has a certain lifecycle.
A JSP fragment is a web component defined in one or more JSP files. JSP Controls Tag Library manages the lifecycle of JSP fragments. This document uses terms "fragment" and "component" interchangeably.
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 corresponding "loggedin" view displays logout form that shows user name and "Log Out" button. The button submits logout form, sending "logout" event to the component.
Username is "guest", password is "pass". This is just a demo.
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 page includes the Login Component
that is defined further in
<%@ 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 a composite page with the standard <jsp:include> action. The composite page itself does not have to conform to 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 prefix="jc" uri="http://jspcontrols.net/tags/core" %> <jc:component 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> </jc:component>
The above skeleton 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.