To illustrate how we create a widget I will use the example of the session explorer screen,
as it uses a UserGrid Widget which is one of the more complex widgets. To use our architecture
for each screen you need to have an Action Bean , Form Bean and a JSP (ala Struts). It is
important to note that JAFFA, although utilizing some of the Struts Architecture, differs
from it in some important ways.
We must import the Struts Tag Library and the Jaffa Portlet tags.
<%@ tag lib uri="/WEB-INF/struts-html.tld" prefix="html" %>
<%@ tag lib uri="/WEB-INF/jaffa-portlet.tld" prefix="Portlet" %>
The header tag must be added in the head block of the JSP, look
at this code snippet for an example.
This tag is very important as many of the Widgets utilize this
for information gathering on the page and adds in the base ref,
that all the files are relative to.
The next tag that needs to be added to the JSP is the FORM tag.
This tag extends the struts form tag with a few powerful variations
(note that struts tag that it extends has been modified and simplified)
Unlike Struts JAFFA has a more powerful event handling capability.
The following hidden fields are added to every rendered JSP.
<input type="hidden" name="componentId" value="">
<input type="hidden" name="eventId" value="">
<input type="hidden" id="dateTimeStamp" value="">
The componentID keeps track of the current component, The eventID
stores the event that has been fired. For example on any given screen
we could have unlimited event handlers. The dateTimeStamp field
is used for caching the date and time that an error message
was raised on rendering the screen. This then is written
to a cookie. If the back button is pressed the datetimestamp on the screen
and the cooke are compared, if they match the error box will not be displayed
again. If a form is posted and the dateTimeStamp does not match
the one stored in the cookie .. an error screen will be displayed
(if any error messages were raised).
The final tag that is necessary is the footer tag.
This tag will write out any registerd JS files for widgets on the screen.
code for the widgets when the widgets themselves are rendered. The
reason for this is simple. If you have for example 5 edit boxes
on a screen they all require the editbox.js file to be included
on a page. If the script was written at the time of widget rendering
you would get 5 duplicate references to the embedded editbox.js
file. This would be a sloppy way to have code on your HTML page.
Then Close the form tag.
It is important to note that Form beans do NOT persist in JAFFA
by default. They are request scope only. The reason for this is
to allow reuse of the same screens. If you wish to store any persisted
values you MUST use the UserSession or a Component Controller. You
can change if you wish the scope in the struts-config.xml file to
make them persistent, but in doing so you would not have the facility
for re-use of the same screens. Jaffa also uses the struts-config.xml
file. As a rule in JAFFA we use Global Forwards, as opposed to definitions
per action. Now that we have established the basic differences between
Struts and JAFFA lets look at building a basic example.