This section takes the reader through a detailed tutorial that constructs
a JSP with custom tag libraries to demonstrate the features (and idiosyncrasies)
of the extension. Before starting the tutorial, be sure you have followed
the installation guidelines thoroughly. The tutorial will construct
a mock message reading application using some of the custom tags from
the Struts framework. For more information on Struts visit http://jakarta.apache.org/struts/index.html.
Before using the extension, you must first place the TLD files of any
custom tag libraries you wish to use into the TLDParser/tlds directory.
For this tutorial, you'll need the 3 tlds included in the ultradev4-tutorial.war
file.
- If you have not started Tomcat since placing the ultradev4-tutorial.war
file into the TOMCAT_HOME/webapps directory, do so now to expand the
archive.
- Copy the struts.tld, struts-bean.tld and struts-logic.tld files
from TOMCAT_HOME/webapps/ultradev4-tutorial/WEB-INF/ to
TOMCAT_HOME/webapps/TLDParser/tlds
The tag libraries are now accessible to the extension. If Tomcat is
not running, start Tomcat on port 8080 (see "Configuring CTLX for
Tomcat" under Things to Watch for
information on changing the location and port where
the extension looks for Tomcat), and launch UltraDev. Once UltraDev is
running, the first step is to create a site for the tutorial.
- Select Site|Define Sites... and click the New... button
- Under the Local Info category, make only the following changes:
- Set Site Name to ultradev4-tutorial
- Set the Local Root Folder by clicking on the adjacent folder
icon and browsing to the root directory of UltraDev. Create a
new folder called ultradev4-tutorial, open the folder, and select it.
- Under the Remote Info category, make only the following changes:
- Set Access to Local/Network
- Set the Remote Folder by clicking the adjacent folder icon and
browsing to TOMCAT_HOME/webapps/ultradev4-tutorial/, and opening and
selecting it.
- Under the Application Server category, make only the following changes:
- Set Server Model to JSP 1.0
- Set Remote Folder by clicking the adjacent folder icon and browsing
to TOMCAT_HOME/webapps/ultradev4-tutorial/, and opening and selecting
it.
- Set URL Prefix to http://localhost:8080/ultradev4-tutorial/
- Hit OK, and hit Done in the Define Sites window. Allow UltraDev
to create a cache of the site for improved performance.
- In the Site window, click on the green down arrow to get the entire
site. When asked if you are sure you want to get the entire site,
click OK.
With the Site window open, double click on the ctl-message.jsp file
in the Local Folder pane to open it. Now hit ctrl-shft-R (or select
View|Live Data Mode) to enter Live Data Mode. You must be in Live Data
Mode to use the extension. If switching to Live Data Mode raises an
UltraDev error, make sure you entered in all the site information properly.
If the animated gears on the upper-right corner of the document window
stop moving without raising an error, you have successfully entered
Live Data Mode. See "Perfomance in Live Data Mode" under Things
To Watch for a note about the speed of screen refreshes in Live
Data Mode.
In order to see what the extension is doing to the HTML source as you
change the document, select View|Code and Design to split the window
so you can see the HTML source while you make changes to the document
window. You may notice that the JSP is empty except for a scriptlet
at the top of the <body> tag that initializes an ArrayList into
the JSP's PageContext. The ArrayList will be used in the tutorial, but
note that scriptlets are not necessary for successful use of the
extension or the included tag libraries. The data in the included
scriptlet could just as effectively been placed into a bean and instantiated
with a <jsp:usebean> call. The scriptlet is used in this tutorial
to reduce the mystery surrounding what the tag is doing.
Now you are ready to build the JSP. Start by clicking in the blank
document window and entering the text "Messages for ". Next,
click the Insert Table button in the objects palette and insert a table
with 1 row and 2 columns. Once inserted, click inside the left cell
and type "message". Hit tab to enter the right cell, and type
"read". These elements will serve as the skeleton for our
dynamic content, which you will now add.
Open the extension's "Use a Custom Tag Library" floater by
selecting Window|Use Custom Tags. See Using the Extension
for a summary of the role and functionality of this floater.
- Click on the "Select a Custom Tag Library" drop-down menu.
It should be populated with the 3 tlds that you copied to the TLDParser/tlds
directory: struts-bean, struts-logic and struts. Select "struts"
and hit Use Tag Library. The extension will ask you for the location
of the TLD file. The default is correct, so hit OK. You are then asked
for a prefix. Any alphanumeric prefix may be used, and the default
(which is taken from the name of the TLD file) is fine, so hit OK.
The namespace instantiation for the struts tag library is added to
the top of the HTML source, and the "Select Tag to Insert"
drop-down menu is populated with the struts custom tags.
- Put the current insertion point after the space following the
"Messages for " text in the document window. Select "parameter"
from the "Select Tag to Insert" drop-down menu and click
insert. The extension asks you enter values for all required attributes
so the server can compile the page successfully. For this tag, you
are asked for a value for the "name" attribute. The parameter
tag uses its name attribute to display the value of the http request
parameter called "name". Enter "user" and hit
OK. The extension inserts the tag into the HTML source and refreshes
the document window.
- Note the document window does not change, because the server has
been sent no "user" parameter. UltraDev provides a way to
tack request parameters onto an http request. Select View|Live Data
Settings. Click the plus (+) button in the URL Request grid and add
the "user" parameter. For the value, enter your name. Hit
OK. The document window refreshes and your name appears following
the "Messages for " text.
Take note that even though your name is really a tag, you can treat
it much like a standard HTML element. Click on your name and hit ctrl-i.
Your name becomes italicized, as if it were standard text. You can push
it around by inserting text before it, and you could even drag it around
to a new location (if you do drag it somewhere else, you will need to
hit ctrl-r to refresh the display, but save that experimentation until
the tutorial is completed).
Your document window should now look something like this:
The next step is to provide functionality for the table to display
every message for the user. You will treat the provided ArrayList as
a list of messages (imaging they were procured from a server with another
custom tag), and iterate over them with the struts "iterate"
tag, creating a new row in the table for each message in the ArrayList.
- The iterate tag is in the struts-logic tag library. Select struts-logic
from the "Select a Custom Tag Library" drop-down menu and
hit Use Tag Library. Again, the default TLD location is correct. The
prefix has been changed from "struts-logic" to "strutslogic"
since prefixes must be alphanumeric. The default is fine, but you
may make it whatever you wish. The namespace instantiation is added
to the top of the page, and the "Select Tag to Insert" drop-down
menu is populated with the struts-logic tags.
- Click inside the left table cell, and click the <tr> tag from
the tag ancestor list at the bottom left corner of the document window.
The contents of the <tr> tag in the source window should now
be selected.
- Select "iterate" from the "Select Tag to Insert"
drop-down menu. Enter "item" for the id value.
- The iterate tag is wrapped around the <tr> tag, and the document
window refreshes.
**THIS GENERATES A LIVE DATA ERROR** Hit OK. The source of
the error is a complication in the tld file for the struts-logic tag
library. The entry for "iterate" in the tld file only contains
one required attribute: "id". For the tag to compile, however,
one of either "collection" or "name" must also be
specified. Since the tag uses one of "name" or "collection"
but not both, the TLD cannot specify that both are required, so it specifies
that neither is required. The extension only asks for required attributes
on insertion, so the JSP gets sent to the server without a value for
either "name" or "collection", generating an internal
servlet error. We can add the necessary value by editing the tag.
- Open the "Edit Tag" floater by selecting Window|Edit Custom
Tags. See Using the Extension for a summary of
the role and functionality of this floater.
- Click inside the left table cell again. Now click the <strutslogic:iterate>
tag in the tag ancestor list at the bottom left corner of the document
window. The "Edit Tag" floater populates with the current
attribute/value pairs of the iterate tag (see "Selection"
under Things to Watch for details on selecting
custom tags).
- Enter "list" as the value for the "name" attribute,
and hit Apply. This change causes the tag to iterate over the ArrayList
earlier defined as "list". The single table row becomes
5 rows, one for each element in the ArrayList.
- Click inside the left table cell and click <strutslogic:iterate>
in the tag ancestor list again. Try setting the value of the "length"
attribute to 3 and hit Apply. The table now displays only the first
3 rows. Click inside the left table cell and click the <strutslogic:iterate>
in the tag ancestor list again. Delete the 3 from the value of the
"length" attribute and hit Apply to remove the length constraint.
The table now has its original 5 rows.
The row on top is a template row. You can alter it as you would a normal
row. The tan rows are locked rows. Their HTML source exists only as
a compiled JSP response from the server. You can only affect them by
changing the template row. Try boldfacing the word "message"
and hitting ctrl-r to refresh. Notice how all the locked rows now contain
the boldfaced "message" text.
The main feature of the iterate tag is not repetition of the same data,
but its ability to set a bean as the current element of a collection
on each iteration. In other words, you can set the iterate tag's "id"
attribute to a bean that writes out each member of the collection. You
already set the "id" attribute of the iterate tag to "item",
so the next step is to insert the "item" bean.
- The "write" tag is in the struts-bean tag library. Select
"struts-bean" from the "Select a Custom Tag Library"
drop-down menu and hit Use Tag Library. Again, the default TLD location
is correct. The prefix has been changed from "struts-bean"
to "strutsbean" since prefixes must be alphanumeric. The
default is fine, but you may make it whatever you wish. The namespace
instantiation is added to the top of the page, and the "Select
Tag to Insert" drop-down menu is populated with the struts-bean
tags.
- Click in the left cell of the template (topmost) table row. Select
the <td> tag from the tag ancestor list at the bottom left corner
of the document window. Select "write" from the "Select
Tag to Insert" drop-down menu and click insert. Enter "item"
as the value for the "name" attribute. The content of the
<td> tag is replaced with the "write" tag (see Insertion
in Things to Watch below for more information
on how the extension chooses its insertion scheme).
- In the document window, the "write" tag populates the
left table column with the values from the "list" ArrayList.
The content of the locked cells is manipulatable as before. Select
the text "Finish report by 6", boldface it, right justify
it (Text|Align|Right), and hit ctrl-r to refresh. Notice how the locked
cells take on the same formatting. Restore the left justification.
- Next you will replace the "read" text in the right table
column with a button for reading a message. For the tutorial, the
button will serve only cosmetic purposes. The "button" tag
is in the struts tag library. It generates a localized HTML button.
- Select "struts" from the "Select a Custom Tag Library"
drop-down menu and hit Use Tag Library. The "Select Tag to Insert"
drop-down menu populates with the tags of the struts tag library,
but the server is not pinged since the tags already exist in local
cache, and the namespace instantiation is not added to the JSP since
it is already present.
- Click inside the right template cell and select the <td> tag
from the tag ancestor list at the bottom left corner of the document
window. Select "button" from the "Select Tag to Insert"
drop-down menu and hit insert. For the "property" attribute,
enter whatever you like (the property attribute is irrelevant in this
context). The struts "button" tag replaces the content of
the template cell, and the document window updates with a button in
each cell of the right column.
- Now you will alter the value displayed on the button. Select the
button in the document window if it is not already selected. The "Edit
Tag" floater populates with the attribute/value pairs of the
"button" tag. Enter "Read Message" as the value
for the "value" attribute, and hit Apply. The document window
refreshes and the buttons now say "Read Message".
The next step will be adding an element to the page that is only visible
to certain users. In this case, we will add an "Administer Privileges"
button that is only accessible to the admin of the system. We will use
the struts-logic "ifParameterEquals" tag to test for this.
In a more involved application, we could check the value of a bean set
by a "Logon" JSP for more secure authentication, but parameter
checking well suites the scope and purpose of this tutorial.
- Click to the right of the table in the document window and hit return.
The cursor should now be under the table to the left.
- Insert another struts button, and set the "property" value
to whatever you like (again the property attribute is irrelevant in
this context). The document window refreshes and the button appears
below the table. In the Edit Tag floater, set the value of the "value"
attribute to "Administer Privileges" in the Edit Tag floater
and hit Apply. The button now reads "Administer Privileges".
- Select the "ifParameterEquals" tag from the "Select
Tag to Insert" drop-down menu and hit insert. For name, enter
"user", and for value, enter "admin". The "ifParameterEquals"
tag is wrapped around the "button" tag.
- The button disappears. The parameter "user" is
set to your name, and the "ifParameterEquals" tag only processes
its body content if "user" equals "admin", as
you just specified. To make the button show, make a change to the
URL Request parameters being sent to the server. Select View|Live
Data Settings..., change the value of "user" to "admin",
and hit OK. The button reappears.
- For fun, click the button and set the value of the "onClick"
attribute to alert('Administering Privileges'); in the "Edit
Tag" floater (being sure to use single quotes and include the
semicolon). Hit Apply. This will show a JavaScript message when the
button is clicked in a browser.
Now wrap the whole page in a form. The struts tag library provides
a custom tag for creating localized forms.
- From inside the design window, hit ctrl-a to select all the design
content.
- Select the "form" tag from the "Select Tag to Insert"
drop-down menu and hit insert.
- For the "name" attribute, you may enter whatever you wish.
For "type", enter "org.apache.struts.example.LogonForm"
(case sensitive). That's a class in the site that generates a specific
form.
- The struts "form" tag is wrapped around the selected HTML
in the source window. The document refreshes. The red dotted line
around the design content is UltraDev's indication that the content
is within a form.
The last step will be setting the title of the JSP using a custom tag
that generates a localized message. Dealing with tags like <title>
that occur before the <body> tag in UltraDev is more complicated
than those within the <body> tag (see Selecting in Things
to Watch). As a result, inserting a custom tag into the <title>
tag will require an extra step.
- Before you begin, note that the "Title:" text box at the
top of the document window says "Untitled Document". You
will insert a custom tag inside the <title> tag that uses a
bean to generate a localized title.
- Select View|Head Content, or hit ctrl-shft-w (you should already
be in "Code and Design" view mode). The Head Content icons
appear in the middle of the document window, between the source window
and the design window..
- Select the title icon, which is the leftmost of the Head Content
icons. The <title> tag becomes selected in the source window.
- You should already be using the struts custom tag library. If not,
use it. Select the "message" tag from the "Select Tag
to Insert" drop-down menu and click insert.
- For the "key" attribute, enter "prompt.username".
This is the name of a class in the web-inf folder of the site that
generates a localized message.
- The "Title:" text box now says "Username:".
Oops! That's the wrong class. You'll have to edit it with the Edit
Tag floater.
- Click inside the <title> and </title> tags in the HTML
source window. The Edit Tag floater populates with the attribute/value
pairs of the message tag. If you mis-clicked, you will need to reselect
the title icon from the Head Content icons before attempting to click
inside the <title> and </title> tags again (see the special
case in "Selecting" under Things
to Watch for an explanation).
- Change the value of the key attribute to "logon.title"
and hit Apply. The document refreshes and the "Title:" text
box now reads "MailReader Demonstration Application - Logon",
the correct title.
This concludes the construction of the JSP. Hit the F12 key on your
keyboard to preview the JSP in your primary browser. It should appear
very similar to the version you interacted with in Live Data Mode (note
the width of the table depends on the size of the browser window).
The URL Request parameters you specified in UltraDev's Live Data Mode
settings are in the URL string of your browser, so all the elements
of the page are accessible. Change the value of the "user"
parameter in your browser to your name and hit return. The page now
says "Messages for [your name]" and the "Administer Privileges"
button is not visible. Set the "user" parameter to "admin"
once again. The page reads "Messages for admin" and the button
reappears. Clicking the button should show the JavaScript alert you
previously entered. If you see a JavaScript error, make sure you entered
the value correctly in the "Tag Edit" floater.
Your browser display should look something like this:
Congratulations. This completes the tutorial.