Expresso Taglibs

Expresso Components Listing

Introduction

All tags are currently in the com.jcorporate.expresso.ext.taglib package.

These tags are fairly simple and work well. Give them a try. You will find that after you create one page with them, you will never go back to the old way. They make a HUGE difference!

Tag Library Descriptor

Also included is the tag library descriptor, expresso.tld, under the /WEB-INF/ directory in CVS. If you have questions about which options are required, optional, etc., just scan the expresso.tld. This expresso.tld should be placed in your WEB-INF/ directory. Then, edit your web.xml file to include this:

		<taglib>

			<taglib-uri>/expresso</taglib-uri>

			<taglib-location>/WEB-INF/expresso.tld</taglib-location>

		</taglib>

This is also done in the web.xml file in CVS.

Quick usage:

Include this at the top of the page:

<%@ taglib uri="/expresso" prefix="expresso" %>

and then the tags wherever you want them:

Important Notes

The custom tags make some assumptions about how your jsp page is defined. One important assumption is that your controller is called "controller" in the jsp page (jsp:useBean id="controller" scope="session" class="myControllerClass" /). If you have used an id in your usebean tag that is something other then "controller", then you need to specify the controller name to each of your expresso tags as an argument, like: <expresso:InputTag name="expresso.input.first_name" controller="mycontrollername" />

Expresso Tag Library Summary

The Expresso Tag Library contains a number of JSP custom tags to help build JSP pages easily, and eliminate the Java usage in JSP pages.

Example JSP code: The following JSP will try to illustrate the tags in the library:

1. <font color="red">
2.     <expresso:ErrorTag/>
3. </font>

4. <table class="jc-default" border="0" align="center">
5. <expresso:TableHead value="ID|Name|Start Date|End Date|Duration|Command"/>

6. <expresso:ElementCollection type="block">
7. <expresso:ElementIterator>
8.      <expresso:ElementCollection type="output">
9.      <expresso:ElementIterator>
10.         <expresso:OutputTag name="xxx">
11.           <tr>
12.             <td><expresso:AttributeTag name="CourseId"/> &nbsp; </td>
13.             <td><expresso:AttributeTag name="CourseName"/> &nbsp; </td>
14.             <td><expresso:AttributeTag name="CourseStartDate"/> &nbsp; </td>
15.             <td><expresso:AttributeTag name="CourseEndDate"/> &nbsp; </td>
16.             <td><expresso:AttributeTag name="CourseDuration"/> &nbsp; </td>
17.         </expresso:OutputTag>
18.     </expresso:ElementIterator>
19.     </expresso:ElementCollection>

20.     <expresso:ElementCollection type="transition">
21.     <expresso:ElementIterator>
22.         <html:form action="/training/TrainingController.do&state=promptUpdateCourse" method="POST">
23.             <td><expresso:TransitionTag name="promptUpdateCourse" /></td>
24.         </html:form>
25.     </expresso:ElementIterator>
26.     </expresso:ElementCollection>

27.           </tr>
28. </expresso:ElementIterator>
29. </expresso:ElementCollection>
30. </table>

This example will:

Display the Expresso Error Collection if it exists (Lines 1-3)
Construct and display a table header with header names ID, Name, Start Date, End Date, Duration, Command (Lines 4,5)
Iterate through all Block objects found in the ControllerResponse (Lines 6,7)
--->Iterate through all Output objects in the current Block (Lines 8,9)
-------->Use an OutputTag to help OutputAttribute tags (Line 10)
------------>Display the various attributes of the current Output object (Lines 12-16)
---->Iterate through all Transition objects found in the ControllerResponse (Lines 20,21)
-------->Display the current Transition as a submit box (Lines 22-24)

Tag Name	Description
ActionTag	Renders an Expresso action, and associated hidden fields
AttributeTag	A tag to display an Attribute from an Expresso Input or Output tag.
Back	Displays a "Back" button or image to go back to a page
Block	A tag to act as a container for child InputTag, OutputTag, TransitionTag and Block tags. Directly related to the Expresso Block controller element.
config	Defines a scripting variable out of the ConfigManager object
ContentTag	A tag to display an Expresso Output Element's Contents Field.
Context	A tag to insert the web-app context, optionally including the expresso-dir and the path to an application's files
DBDescription	A tag to display the description text for the current DB context
DBMaint	A tag to include a row with calls to DBMaint for a dbobject
ElementCollection	A tag that retrieves a collection of a controller elements that can later be iterated through using the ElementIterator tag
ElementIterator	A tag to iterate through each controller element inside a parent ControllerCollection tag
ErrorMessages	A tag to display error messages based on their key's in the MessageBundle.properties
ErrorTag	A tag to display an Expresso Error Collection as a Unordered List (UL)
IfElementExists	A tag to check if a particular controller element exists as part of the parent: controller-response, block or element-iterator tags.
IfErrorExists	A tag to check if the controller generated errors and stored it in the page context.
IfLoggedIn	A tag to check if a session is established and a valid user is logged in.
IfMemberOfGroup	This tag checks the currently logged in user for membership into a specified security group.
InputTag	A tag to display an Expresso Input Object
LabelTag	A tag to print the label of a controller element
Login	Tries to make the user log in
output	Defines a scripting variable out of an Output object
OutputTag	A tag to display an Expresso Output Element.
RestrictAccess	A tag to allow quick and dirty restriction of access to jsp pages.
session	Defines a scripting variable out of the current session.
setup	Defines a scripting variable out of the Setup object
TransitionTag	A tag to display an Expresso Transition Button
TransitionParamsTag	A tag to display the parameters with an Expresso Transition
TableHead	A tag to display a pipe-delimited string as a table header
UserName	A tag to display the logged in user-name

<expresso:ActionTag name="refreshCompany" /> - renders the expresso action button with that name. This tag also takes care of the hidden form field that action tags rely on to pass parameters. This action tag allows seamless changes between GET and POST form actions.

All three tags have no body (no closing tag). These simplest examples will work for most all cases, but there are many options you can set to override the default behaviors.

Sufficient code and info has been included here to cover three out of four common expresso cases (Output is missing...this is easy in its simple case, but the nested cases may be a little tricky to create as tags).

.

The AttributeTag can be used to display attributes from Input or Output objects. These attributes are the ones that you put in Input or Output objects by out1.setAttribute(String attrName, String value) in your States.
The AttributeTag can either be used stand-alone, in which case all the arguments are required, or nested within an OutputTag or InputTag, in which case only the attribute name must be specified.

If no valid Input or Output objects can be found, a JspTagException will be thrown, saying "A controllerElement was not specified for this attribute tag, or a parent tag did not supply a controllerElement."

Examples:

1) <expresso:AttributeTag controllerElement="product" name="product_desc" type="OUTPUT" />

Will display the value of the "product_desc" attribute, contained in the "product" Output object.

2) <expresso:OutputTag name="product">
<expresso:AttributeTag name="product_desc"/>
</expresso:OutputTag>

This one does the same thing as the 1st example but this time the OutputTag must be enclosed in a Block or ElementIterator tag

Attribute Name	Description
name	Specifies the name of the attribute whose value will be displayed (If the attribute is not found, "ATTRIBUTE NOT FOUND" is displayed.. [Required] [RT Expr]
controllerElement	If supplied, specifies the name of the ControllerElement object holding the attribute. If not supplied, the tag will try to use the enclosing InputTag or OutputTag, if there is any. [RT Expr]
type	If supplied, specifies the type of the ControllerElement (Must be "INPUT or "OUTPUT"). If not supplied, the tag will put the correct value according to the enclosing InputTag or OutputTag, if there is any. [RT Expr]

Constructs an anchor to go to a specified URL, to go to the previous page, or to refresh the current page.

Attribute Name	Description
page	Specifies the page to go to. If null, a hyperlink to go back to the previous page is constructed. If "current", a hyperlink to refresh the current page is constructed, if something else, a hyperlink to go to the desired URL is constructed. [RT Expr]
image	Defaults to expresso-images-dir/FingerLeft.gif [RT Expr]
key	Title will be read from the locale file if supplied. [RT Expr]
title	Title to be displayed. [RT Expr]

The Block tag is used to provide a container tag for other tags. Just like a Block object being a container for ControllerElement objects. If there is a container for a Block tag, it must either be an ElementIterator tag, or another Block tag.

Examples:

<expresso:Block name="courseDataInput"> <tr>
<td> <expresso:InputTag name="CourseName" />
</tr>
<td><expresso:InputTag name="CourseDuration" /></td>
</tr>
</expresso:Block>

The Block tag helps the InputTag tags to retrieve the Block object and then execute Block.getInput()

Attribute Name	Description
name	The name of the block that we want to act as a container for child tags. [Required] [RT Expr]

This tag puts the specified value to the desired scope.

If "value" is not supplied, gets the value as ConfigManager.getProperty(). If "value" is supplied, this is used to be placed in the desired scope.

Attribute Name	Description
id	Specifies the name of the scripting variable that will be made available. [Required] [RT Expr]
property	Specifies which property to get from ConfigManager. [Required][RT Expr]
db	If supplied, specifies the database definition to get configuration parameter from. [RT Expr]
toScope	One of "page" (default if not supplied), "request", "session", "application". [RT Expr]
type	? [RT Expr]
value	If supplied, this will be placed in the desired scope. [RT Expr]

ContentTag must be nested within an OutputTag tag. The ContentTag has no body, and simply displays the content from the parent OutputTag (Output.getContent()).

Examples:

<expresso:OutputTag name="product">
<expresso:ContentTag /></br>
</expresso:OutputTag>

Gets the Output object from the OutputTag tag, and then displays Output.getContent().

Attribute Name	Description
	No attributes needed.

Writes the context path and/or the "expresso" directory. Optionally figures out context paths for specific schema's as well.

Examples:

<expresso:Context>

Writes: /expresso/expresso/components/training for example

Attribute Name	Description
schema	The specific schema whose context path we want to get. [RT Expr]

Retrieves the CurrentLogin object(if any) from the pageContext object, and displays ConfigManager.getContext(currentLogin.getDBName()).getDescription(). If there is no CurrentLogin, "default" is used for the dbName.

Examples:

<expresso:DBDescription>

Displays "Oracle Database", for example.

Attribute Name	Description
	No attribute needed

Provides a row for a table that contains links to the DBMaint controller providing add/update/delete functionality for a specific DB object

Attribute Name	Description
dbobj	The DBObject class. [Required] [RT Expr]
label	Label to be displayed. [RT Expr]
help	The URL for a help file about this DBObject. [RT Expr]

This tag provides an Enumeration object to an ElementIterator tag, providing access to the desired ControllerElements. The ElementIterator may iterate through all the elements found in the ElementCollection.

Attribute Name	Description
type	What type of objects do we want to get? Type should be one of "block", "input", "output", "transition". If something else is supplied, the tag will do nothing. [Required] [RT Expr]

This tag can only be used nested in an ElementCollection tag. It will iterate through all the elements found in the ElementCollection, and provide each element to the nested tags.

Attribute Name	Description
	No attribute required.

This tag is a lot like the ErrorTag in that it looks for an Expresso ErrorCollection in the page request. If an errorCollection is found, the tag iterates through the errors and displays them as an unordered (bulleted) list, however this tag goes one step further, it will display the text from the Message Bundle This is done by adding the Message Bundle key for the string that is associated with that error.

Examples: In your JSP

<expresso:ErrorMessages />

Now in the java code you simple put

    ErrorCollection errors = new ErrorCollection();
    errors.addError( "error.username.required" );
                                  

Then make sure that this maps to the MessageBundle associated with controller (done in the Schema class)

    error.username.required=<li>Username is required

Attribute Name	Description
name	Name of the ErrorCollection object. If not supplied, defaults to ErrorCollection.ERRORCOLLECTIONKEY [RT Expr]
property	If supplied, the tag will display the set of error messages related to a specific property, if not supplied, the tag will display all error messages. [RT Expr]

This tag looks for an Expresso ErrorCollection in the page request. If an errorCollection is found, the tag iterates through the errors and displays them as an unordered (bulleted) list. An errorCollection object is generally inserted into the page request by calling controller.saveErrors(errorCollection), which saves the errorCollection under the proper parameter name. If no errorCollection is found in the page request, this tag does nothing, so it is safe to include this on all of your jsp pages if desired.

The ErrorTag renders an Expresso ErrorCollection on a page. The error list is rendered as an html unordered (bulleted) list. The errors are displayed in the order they where saved to the ErrorCollection.

Examples:

<expresso:ErrorTag />

<expresso:ErrorTag name="myErrors" property="validationErrors" />

Attribute Name	Description
name	Name of the ErrorCollection object. If not supplied, defaults to ErrorCollection.ERRORCOLLECTIONKEY [RT Expr]
property	If supplied, the tag will display the set of error messages related to a specific property, if not supplied, the tag will display all error messages. [RT Expr]

Tries to find the named element in the current ControllerResponse, ElementIterator or Block, whichever is appropriate. If finds, the body of the tag will be processed.

"inverse" attribute can be used to mean "If Element Does Not Exist"

Attribute Name	Description
name	Name of the element to be checked. [Required] [RT Expr]
type	The type of the element to be checked (Must be "block", "input", "output", or "transition") [Required] [RT Expr]
inverse	If "true", the tag will mean "IfElementDoesNotExist" [RT Expr]

If finds the Expresso ErrorCollection in the page context, then the body of the tag will be processed.

Attribute Name	Description
	No attribute required.

If there is a valid user logged in, the body of the tag will be processed. "inverse" attribute can be used to to something if there is no valid login.

Attribute Name	Description
inverse	If this attribute is set to true, the tag will mean "IfNotLoggedIn" [RT Expr]

Tag checks to see if the user in the specified groupname is apart of that security group.

Attribute Name	Description
Groupname	This is the groupname which you are checking to see logged in user is apart of. [RT Expr]
inverse	If this attribute is set to true, the tag will mean if the user is in the specified group return true [RT Expr]

Displays the specified element's label (with element.getLabel()).

Attribute Name	Description
name	Name of the element whose label will be displayed. [Required] [RT Expr]
type	Type of the element ("input", "output", "transition" or "block") [RT Expr]

Tag to transition between database contexts, either logging the user into a new context (if possible with cookies, etc), or taking them to the login screen if it is not possible.

Attribute Name	Description
db	If supplied, tries to log in to this database context [RT Expr]
forward	If "false", tries to to logInAsNone(request,db) [RT Expr]

This tag puts the specified value to the desired scope. Must be nested within an OutputTag tag.

If "value" is not supplied, gets the value as getContent() from the enclosing OutputTag. If "value" is supplied, this is used to be placed in the desired scope.

Attribute Name	Description
id	Specifies the name of the scripting variable that will be made available. [Required] [RT Expr]
toScope	One of "page" (default if not supplied), "request", "session", "application". [RT Expr]
type	? [RT Expr]
value	If supplied, this will be placed in the desired scope. [RT Expr]

OutputTag is a tag that by itself does not display anything. The OutputTag must have a start and end tag. Between these tags, the ContentTag can be used to place the content from the Output, and the AttributeTag can be used to place attributes of the Output. The OutputTag can also be used to fetch out nested outputs, if one OutputTag is nested within another one.

Attribute Name	Description
name	Name of the element to be used in the nested ContentTag and AttributeTag tags. Will be automatically set if nested in an ElementIterator tag. [Required] [RT Expr]

Provides an easy way to restrict access to particular pages. If the user is not found to be allowed to access this page, s/he will be forwarded to a specified page, or a JspTagException saying "Access to this page is denied". This tag allows quick access restriction to a jsp page.

Example Usage:

<expresso:RestrictAccess allowedUsers='Admin,scann'
   allowedGroups='Admin,Everyone
/> 

or

<expresso:RestrictAccess denyURL='join.jsp'/>

or

<expresso:RestrictAccess/>

.

Attribute Name	Description
allowedUsers	A comma delimited list of user names that are allowed to access this page (Case Sensitive). [RT Expr]
allowedGroups	AComma delimited list of groups that are allowed to access to this page, also case sensitive. [Note that you can have BOTH allowedUsers and allowedGroups] [RT Expr]
denyURL	URL to forward to, if the user is not allowed to access this page. The URL to forward to if access is denied If this attribute is not supplied, then a JspTagException is thrown with the message 'Access to this page is denied'. If no allowedUsers or allowedGroups are given, then as long as the person is logged in as ANYTHING other than NONE, they'll be given access to the page. [RT Expr]

This tag puts the specified value to the desired scope.

If "value" is not supplied, gets the value as pageContext.getRequest().getAttribute(property). If "value" is supplied, this is used to be placed in the desired scope. (TODO: should be getSession??)

Attribute Name	Description
id	Specifies the name of the scripting variable that will be made available. [Required] [RT Expr]
property	Specifies which property to get from session scope. [Required][RT Expr]
toScope	One of "page" (default if not supplied), "request", "session", "application". [RT Expr]
type	? [RT Expr]
value	If supplied, this will be placed in the desired scope. [RT Expr]

This tag puts the specified value to the desired scope.

If "value" is not supplied, gets the value as Setup.getValueRequired(). If "value" is supplied, this is used to be placed in the desired scope.

Attribute Name	Description
id	Specifies the name of the scripting variable that will be made available. [Required] [RT Expr]
property	Specifies which property to get from Setup. [Required][RT Expr]
db	If supplied, specifies the database definition to get setup parameter from. [RT Expr]
toScope	One of "page" (default if not supplied), "request", "session", "application". [RT Expr]
type	? [RT Expr]
value	If supplied, this will be placed in the desired scope. [RT Expr]

Parses apart a pipe-delimited string into a table heading row. The pipe-delimited string is a convenience used by a number of Expresso controllers to pass the table headings required for various tables to the view.

If the keys attribute is used instead of "value", the headers will be read from the appropriate MessagesBundle.properties file.

Attribute Name	Description
value	Values separated by a pipe - these don't get "translated. [Required] [RT Expr]
keys	Keys into the language file - these are translated for display. [RT Expr]

Displays a submit button with the information contained in the current Transition element. If "value" is not supplied, the label of the button will come from element.getLabel().

Attribute Name	Description
name	Name of the Transition element to be displayed. [Required] [RT Expr]
ClassValue	If supplied, will be used to render the class value for the button if you use Cascading Style Sheets. [RT Expr]
OnClick	If supplied, will be used to render the onclick parameter for javascript submit box. [RT Expr]

Writes: element.getParamString(). This tag does not construct the submit button therefore makes for a great tag for creating hrefs.

<a href="/Login.do?<expresso:TransitionParamsTag name="promptFirstTime" />">I don't have a Username</a>

Attribute Name	Description
name	Name of the Transition element whose parameters are to be displayed. [Required] [RT Expr]
value	? [RT Expr]

If there is a valid login, displays the username. If not, displays "Not Logged In".

Attribute Name	Description
	No attribute required.

Conclusion

For additional technical information about how to use taglibs, please refer to any of the below resources:

• Expresso Developers Guide (EDG)
• Javadocs
• Extended Struts Tag Usage with Expresso.