You are viewing a plain text version of this content. The canonical link for it is here.
Posted to taglibs-dev@jakarta.apache.org by sh...@apache.org on 2001/07/30 17:24:54 UTC
cvs commit: jakarta-taglibs/input/xml input.xml
shawn 01/07/30 08:24:53
Added: input/doc/web input.html
input/xml input.xml
Log:
Submitted by: Lance Lavandowska
Reviewed by: Shawn Bayern
(I thought these files had been committed previously.)
Revision Changes Path
1.1 jakarta-taglibs/input/doc/web/input.html
Index: input.html
===================================================================
<!-- Author: Shawn Bayern (shawn.bayern@oooo.com) -->
<html>
<body bgcolor="#ffffff">
<h1>The "Input" Tag Library</h1>
<h2>What is the "Input" tag library?</h2>
<p>
The "input" tag extension library lets you present HTML <code><form>
</code>elements
that are tied to the ServletRequest that caused the current JSP page to
run. That is, using this library, you can easily prepopulate form
elements with prior values that the user has chosen -- or with default
values for the first time a user hits a web page. This is useful when you
need to present the same page to the user several times (e.g., for
server-side validation).
</p>
<p>
You can also automatically build up <code><select></code> boxes,
making it easier to
build data-driven forms. And even if you don't present the same page
multiple times, you may want form elements that have default values;
this library lets you do that without writing excessive logic.
</p>
<h3><a href="usage.html">Using the "Input" tag library...</a></h3>
<h2>Rationale</h2>
<p>
Most web-based, server-side logic is accessed by users of HTML forms.
Since for many applications, input validation is best done on the server
side (for reasons of security, removal of business logic from the
presentation layer, and so on), a typical process of input entry involves
the following cycle (represented as pseudo-code because I'm in a lazy
mood and don't need to describe it better):
</p>
<pre>
browser requests form
do {
web server displays form
user enters information and clicks "submit"
browser POSTs information to web server
} while (server determines that information is incomplete or invalid)
server displays response to successful and complete input
</pre>
<p>
With each presentation of the form, It generally makes sense to display
the user's prior response in order to facilitate the explanation of why
it's invalid. For example, it's considerably more helpful to a user to
show something like:
</p>
<pre>
Problems encountered:
* Invalid email address!
(Email addresses are of the form user@host.domain)
------------------------------
Name: Shawn Bayern
** Email: bayern@incomplete
Sex: Male
[etc.]
</pre>
<p>
than simply to say "invalid email address" and present an empty spot on
the form next to "Email."
</p>
<p>
The problem that authors of systems of this type face is that there's no
strong binding between HTML and data; it's therefore tedious to construct
an HTML form that contains the user's prior response. To give you an
idea, here's a section of HTML and Java from a JSP project I just finished
(quoted approximately):
</p>
<pre>
<select ...>
<% for (int i = 1; i <= x; i++) { %>
<option <%= !firstRunThrough
? sel(Integer.toString(i), prior)
: sel(i,now.get(default)) %>
><%= i %></option>
<% } %>
</select>
</pre>
<p>
And it's only that "clean" because I abstracted away two different <code>
sel()</code> functions, one that takes <code>int</code>s and one that
takes <code>String</code>s, both of which return the String "selected" if
their arguments match. These functions are included at the top of every
page that needs them.
</p>
<p>
This sort of application cries out for some sort of macro- or
meta-language, and tag libraries for JSP fit in quite nicely. This sort
of problem is a clear-cut case where repetitive work can be cut down
through the use of something that acts as the moral equivalent of a macro
language.
</p>
<p>
I've therefore decided to write and provide contribute to the Jakarta
project -- hoping to make web-application developers' lives a little
easier -- a custom tag library called "input" that presents HTML form
elements that are prepopulated with default input. The developer selects
the default input and uses Maps and other objects as necessary to
communicate between the page and the tag library in cases where input
benefits from (to the point where it's almost accurate to say "requires")
something more structured than Strings (which are the default and usual
mediator). The tag library is designed with ease-of-use and ease of
reading code that uses it in mind.
</p>
<h2>Miscellaneous notes</h2>
<p>
To make the library more useful, I've taken care to make sure that it
quotes appropriate HTML entities correctly, itself, in attribute values
and textboxes so that users can input characters like & and ", and your
application can do the right thing automatically. You don't have to worry
about whether the user has entered a " in a web form, which would
screw up the HTML you output back to the user unless handled:
</p>
<pre>
<input type="text" name="blah"
value="you typed a "quoted" string the last time" />
</pre>
<p>
Instead of the tag above, the library will output
</p>
<pre>
<input type="text" name="blah"
value="you typed a &quot;quoted&quot; string the last time" />
</pre>
<p>
This library differs from similar ones in a number of ways. It attempts
to be more general than the similar tags that JRun's tag library supports;
this one is open-source, first of all, which I don't believe JRun's is,
and it isn't tied to HTML 4.0 attributes. Since you pass in an
"attributes" map, you can include whatever attribute/value pairs you'd
like.
</p>
<p>
Joseph Ottinger's <a href="http://adjacency.org/formtags.jsp"
/>Form Taglib</a> is thorough and reasonably similar to mine in
terms of what it can do. I've optimized mine for a special case -- tying
data to the ServletRequest object -- and tried to make it particularly
easy to use regardless of how your application structures its data. That
is, you don't have to use JavaBeans or create any new classes at all to
use this library. You might find that Ottinger's fits your needs better
or works more generally with your data, and his library provides support
for building up an entire <code><form></code>, JavaScript validation,
and so on -- stuff I've stayed away from for reasons entirely related to
personal opinions and nothing more. (I personally use server-side validation
more than client-side validation for just about everything.) His library
seems great, overall; pick whichever one seems to make your life easier at the
time you're deciding.
</p>
<hr />
<address>
Shawn Bayern <br />
shawn.bayern@oooo.com
</address>
1.1 jakarta-taglibs/input/xml/input.xml
Index: input.xml
===================================================================
<?xml version="1.0" ?>
<!-- Change all instances of input with the jakarta-taglib
name for this tag library.
Change all instances of Input with the name to use
for things such as titles in the tag library documentation.
Change all instances of Shawn Bayern with your name for
for things such as author name in the tag library documentation.
Change <prefix>foo</prefix> below to a short prefix for this
tag library.
-->
<document url="./input.xml">
<!-- More properties can be added. Good place to stick loose
data needed elsewhere. -->
<properties>
<!-- The title here overrides the title generated by the
stylesheet for the documentation HTML <title> tag
<title>Jakarta Project: Input JSP Tag Library</title>
-->
<!-- The name here is used in the HTML <meta name="author"...> tag -->
<author>Shawn Bayern</author>
</properties>
<!-- The following defines elements uses both to create the taglib
documentation and the tag library descriptor .tld file. The
elements used are those from the JSP 1.2 TLD DTD and special
elements used when creating the tagib documentation. Although
the JSP1.2 TLD DTD is used, this document can be used to
generate both a JSP 1.1 and a JSP 1.2 TLD.
-->
<taglib>
<!-- The following elements are from the JSP 1.2 TLD DTD -->
<!-- Version number of this tagib -->
<tlib-version>1.0</tlib-version>
<!-- Minimum version of JSP spec required -->
<jsp-version>1.1</jsp-version>
<!-- jakarta-taglib name of this tag library -->
<short-name>input</short-name>
<!-- URI of taglib -->
<uri>http://jakarta.apache.org/taglibs/input-1.0</uri>
<!-- The name to use in titles, etc. for the taglib -->
<display-name>Input Tag library</display-name>
<!-- JSP 1.2 tag library DTD only, not used for generating
documentation.
<small-icon></small-icon>
<large-icon></large-icon>
-->
<!-- Used for generating Overview section of HTML documentation
and for the description element for a JSP 1.2 TLD.
Enter information here as straight XHTML paragraphs. Inside the
paragraphs regular XHTML can be used (but an external CSS is
encouraged). The information is copied into the generated HTML doc,
and the <p> elements are essential for that. -->
<description>
<p>The "input" tag extension library lets you present HTML <form>
elements that are tied to the ServletRequest that caused the current
JSP page to run. That is, using this library, you can easily
prepopulate form elements with prior values that the user has chosen
-- or with default values for the first time a user hits a web page.
This is useful when you need to present the same page to the user
several times (e.g., for server-side validation).</p>
<p>You can also automatically build up <select> boxes, making it easier
to build data-driven forms. And even if you don't present the same
page multiple times, you may want form elements that have default
values; this library lets you do that without writing excessive logic.</p>
<p>What is the "Input" tag library? <a href="input.html">Read more.</a></p>
</description>
<!-- The following elements are for JSP 1.2 tag libraries only,
and are not used for generating documentation yet.
<validator>
<validator-class></validator-class>
<init-param>
<param-name></param-name>
<param-value></param-value>
<description></description>
</init-param>
<description></description>
</validator>
<listener>
<listener-class></listener-class>
</listener>
-->
<!-- The taglib-location is used to fill in the web.xml configuration
information in the HTML doc. -->
<taglib-location>/WEB-INF/input.tld</taglib-location>
<!-- The prefix is used to fill in the taglib directive
configuration information in the HTML doc. -->
<prefix>input</prefix>
<!-- This element must be straight text and is copied right into
the "Requirements" section of the HTML doc. -->
<requirements-info>
This custom tag library requires no software other than a servlet container
that supports the JavaServer Pages Specification, version 1.1 or higher.
Plus any requirements for additional API packages.
</requirements-info>
<!-- The toc element allows the addition of document sections to
the Table of Contents list after the Tag Reference entry.
0 .. N sections can be added to the Table of Contents.
<toc href="test" name="Testing">
<p>This is a test of a TOC.</p>
</toc>
-->
<!-- The tagtoc element provides the ability to categorize the
tags in the tag library. There must be at least one tagtoc.
1 .. N tags can be nested within a tagtoc.
-->
<tagtoc name="Input Tags">
<!-- text tag -->
<tag>
<name>text</name>
<tag-class>org.apache.taglibs.input.Text</tag-class>
<!-- Optional TEI class
<tei-class>org.apache.taglibs.foo.fooTEI</tei-class>
-->
<body-content>empty</body-content>
<!-- JSP 1.2, display name of tag -->
<display-name>text</display-name>
<!-- JSP 1.2 tag library DTD only, not used for generating
documentation.
<small-icon></small-icon>
<large-icon></large-icon>
-->
<!-- Complete description of this tag. Used for JSP 1.2 TLD
and for generating HTML documentation. -->
<description>Displays a one-line text-entry box. See <a href="usage.html#text">Usage</a> page.</description>
<!-- The next three non-standard elements are used to inform the relevant
sections of the HTML doc. See, for example, the Regexp
taglib docs for examples of the output. -->
<!-- One line summary of what tag does for Tag Summary section -->
<summary>Displays a one-line text-entry box</summary>
<!-- Version of taglib when this tag became available,
deprecated is a possible value. -->
<availability>1.0</availability>
<!-- Any restrictions on use of the tag -->
<restrictions>None</restrictions>
<attribute>
<name>name</name>
<required>true</required>
<rtexprvalue>true</rtexprvalue>
<!-- Optional attribute type for JSP 1.2 rtexprvalue
<type>java.lang.String</type>
-->
<!-- Used for JSP 1.2 TLD and generating HTML docs -->
<description>text box name</description>
<!-- Used for the HTML documentation only.
Version of taglib when this attribute became available,
deprecated is a possible value. -->
<availability>1.0</availability>
</attribute>
<attribute>
<name>default</name>
<required>false</required>
<rtexprvalue>true</rtexprvalue>
<!-- Optional attribute type for JSP 1.2 rtexprvalue
<type>java.lang.String</type>
-->
<!-- Used for JSP 1.2 TLD and generating HTML docs -->
<description>text box default value</description>
<!-- Used for the HTML documentation only.
Version of taglib when this attribute became available,
deprecated is a possible value. -->
<availability>1.0</availability>
</attribute>
<attribute>
<name>attributes</name>
<required>false</required>
<rtexprvalue>true</rtexprvalue>
<!-- Optional attribute type for JSP 1.2 rtexprvalue
<type>java.util.Map</type>
-->
<!-- Used for JSP 1.2 TLD and generating HTML docs -->
<description>extra text box attributes</description>
<!-- Used for the HTML documentation only.
Version of taglib when this attribute became available,
deprecated is a possible value. -->
<availability>1.0</availability>
</attribute>
</tag>
<!-- textarea tag -->
<tag>
<name>textarea</name>
<tag-class>org.apache.taglibs.input.TextArea</tag-class>
<!-- Optional TEI class
<tei-class>org.apache.taglibs.foo.fooTEI</tei-class>
-->
<body-content>empty</body-content>
<!-- JSP 1.2, display name of tag -->
<display-name>textarea</display-name>
<!-- JSP 1.2 tag library DTD only, not used for generating
documentation.
<small-icon></small-icon>
<large-icon></large-icon>
-->
<!-- Complete description of this tag. Used for JSP 1.2 TLD
and for generating HTML documentation. -->
<description>Displays a one-line text-entry box. See <a href="usage.html#textarea">Usage</a> page.</description>
<!-- The next three non-standard elements are used to inform the relevant
sections of the HTML doc. See, for example, the Regexp
taglib docs for examples of the output. -->
<!-- One line summary of what tag does for Tag Summary section -->
<summary>Displays a multiline textarea</summary>
<!-- Version of taglib when this tag became available,
deprecated is a possible value. -->
<availability>1.0</availability>
<!-- Any restrictions on use of the tag -->
<restrictions>None</restrictions>
<attribute>
<name>name</name>
<required>true</required>
<rtexprvalue>true</rtexprvalue>
<!-- Optional attribute type for JSP 1.2 rtexprvalue
<type>java.lang.String</type>
-->
<!-- Used for JSP 1.2 TLD and generating HTML docs -->
<description>textarea name</description>
<!-- Used for the HTML documentation only.
Version of taglib when this attribute became available,
deprecated is a possible value. -->
<availability>1.0</availability>
</attribute>
<attribute>
<name>default</name>
<required>false</required>
<rtexprvalue>true</rtexprvalue>
<!-- Optional attribute type for JSP 1.2 rtexprvalue
<type>java.lang.String</type>
-->
<!-- Used for JSP 1.2 TLD and generating HTML docs -->
<description>textarea default value</description>
<!-- Used for the HTML documentation only.
Version of taglib when this attribute became available,
deprecated is a possible value. -->
<availability>1.0</availability>
</attribute>
<attribute>
<name>attributes</name>
<required>false</required>
<rtexprvalue>true</rtexprvalue>
<!-- Optional attribute type for JSP 1.2 rtexprvalue
<type>java.util.Map</type>
-->
<!-- Used for JSP 1.2 TLD and generating HTML docs -->
<description>extra textarea attributes</description>
<!-- Used for the HTML documentation only.
Version of taglib when this attribute became available,
deprecated is a possible value. -->
<availability>1.0</availability>
</attribute>
</tag>
<!-- select tag -->
<tag>
<name>select</name>
<tag-class>org.apache.taglibs.input.Select</tag-class>
<!-- Optional TEI class
<tei-class>org.apache.taglibs.foo.fooTEI</tei-class>
-->
<body-content>empty</body-content>
<!-- JSP 1.2, display name of tag -->
<display-name>select</display-name>
<!-- JSP 1.2 tag library DTD only, not used for generating
documentation.
<small-icon></small-icon>
<large-icon></large-icon>
-->
<!-- Complete description of this tag. Used for JSP 1.2 TLD
and for generating HTML documentation. -->
<description>Displays a select list. See <a href="usage.html#select">Usage</a> page.</description>
<!-- The next three non-standard elements are used to inform the relevant
sections of the HTML doc. See, for example, the Regexp
taglib docs for examples of the output. -->
<!-- One line summary of what tag does for Tag Summary section -->
<summary>Displays a select list</summary>
<!-- Version of taglib when this tag became available,
deprecated is a possible value. -->
<availability>1.0</availability>
<!-- Any restrictions on use of the tag -->
<restrictions>None</restrictions>
<attribute>
<name>name</name>
<required>true</required>
<rtexprvalue>true</rtexprvalue>
<!-- Optional attribute type for JSP 1.2 rtexprvalue
<type>java.lang.String</type>
-->
<!-- Used for JSP 1.2 TLD and generating HTML docs -->
<description>select name</description>
<!-- Used for the HTML documentation only.
Version of taglib when this attribute became available,
deprecated is a possible value. -->
<availability>1.0</availability>
</attribute>
<attribute>
<name>default</name>
<required>false</required>
<rtexprvalue>true</rtexprvalue>
<!-- Optional attribute type for JSP 1.2 rtexprvalue
<type>java.lang.String</type>
-->
<!-- Used for JSP 1.2 TLD and generating HTML docs -->
<description>select default value</description>
<!-- Used for the HTML documentation only.
Version of taglib when this attribute became available,
deprecated is a possible value. -->
<availability>1.0</availability>
</attribute>
<attribute>
<name>attributes</name>
<required>false</required>
<rtexprvalue>true</rtexprvalue>
<!-- Optional attribute type for JSP 1.2 rtexprvalue
<type>java.util.Map</type>
-->
<!-- Used for JSP 1.2 TLD and generating HTML docs -->
<description>extra select attributes</description>
<!-- Used for the HTML documentation only.
Version of taglib when this attribute became available,
deprecated is a possible value. -->
<availability>1.0</availability>
</attribute>
<attribute>
<name>options</name>
<required>true</required>
<rtexprvalue>true</rtexprvalue>
<type>java.lang.Hashtable</type>
<description>options list for select</description>
<availability>1.0</availability>
</attribute>
</tag>
<!-- radio tag -->
<tag>
<name>radio</name>
<tag-class>org.apache.taglibs.input.Radio</tag-class>
<!-- Optional TEI class
<tei-class>org.apache.taglibs.foo.fooTEI</tei-class>
-->
<body-content>empty</body-content>
<!-- JSP 1.2, display name of tag -->
<display-name>radio</display-name>
<!-- JSP 1.2 tag library DTD only, not used for generating
documentation.
<small-icon></small-icon>
<large-icon></large-icon>
-->
<!-- Complete description of this tag. Used for JSP 1.2 TLD
and for generating HTML documentation. -->
<description>Displays a radio button. See <a href="usage.html#radio">Usage</a> page.</description>
<!-- The next three non-standard elements are used to inform the relevant
sections of the HTML doc. See, for example, the Regexp
taglib docs for examples of the output. -->
<!-- One line summary of what tag does for Tag Summary section -->
<summary>Displays a radio button</summary>
<!-- Version of taglib when this tag became available,
deprecated is a possible value. -->
<availability>1.0</availability>
<!-- Any restrictions on use of the tag -->
<restrictions>None</restrictions>
<attribute>
<name>name</name>
<required>true</required>
<rtexprvalue>true</rtexprvalue>
<!-- Optional attribute type for JSP 1.2 rtexprvalue
<type>java.lang.String</type>
-->
<!-- Used for JSP 1.2 TLD and generating HTML docs -->
<description>radio button name</description>
<!-- Used for the HTML documentation only.
Version of taglib when this attribute became available,
deprecated is a possible value. -->
<availability>1.0</availability>
</attribute>
<attribute>
<name>default</name>
<required>false</required>
<rtexprvalue>true</rtexprvalue>
<!-- Optional attribute type for JSP 1.2 rtexprvalue
<type>java.lang.String</type>
-->
<!-- Used for JSP 1.2 TLD and generating HTML docs -->
<description>radio button default value.</description>
<!-- Used for the HTML documentation only.
Version of taglib when this attribute became available,
deprecated is a possible value. -->
<availability>1.0</availability>
</attribute>
<attribute>
<name>value</name>
<required>true</required>
<rtexprvalue>true</rtexprvalue>
<type>java.lang.String</type>
<description>value can be empty, but it must be present</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>attributes</name>
<required>false</required>
<rtexprvalue>true</rtexprvalue>
<!-- Optional attribute type for JSP 1.2 rtexprvalue
<type>java.util.Map</type>
-->
<!-- Used for JSP 1.2 TLD and generating HTML docs -->
<description>extra radio button attributes</description>
<!-- Used for the HTML documentation only.
Version of taglib when this attribute became available,
deprecated is a possible value. -->
<availability>1.0</availability>
</attribute>
</tag>
<!-- checkbox tag -->
<tag>
<name>checkbox</name>
<tag-class>org.apache.taglibs.input.Checkbox</tag-class>
<!-- Optional TEI class
<tei-class>org.apache.taglibs.foo.fooTEI</tei-class>
-->
<body-content>empty</body-content>
<!-- JSP 1.2, display name of tag -->
<display-name>checkbox</display-name>
<!-- JSP 1.2 tag library DTD only, not used for generating
documentation.
<small-icon></small-icon>
<large-icon></large-icon>
-->
<!-- Complete description of this tag. Used for JSP 1.2 TLD
and for generating HTML documentation. -->
<description>Displays a checkbox. See <a href="usage.html#checkbox">Usage</a> page.</description>
<!-- The next three non-standard elements are used to inform the relevant
sections of the HTML doc. See, for example, the Regexp
taglib docs for examples of the output. -->
<!-- One line summary of what tag does for Tag Summary section -->
<summary>Displays a checkbox</summary>
<!-- Version of taglib when this tag became available,
deprecated is a possible value. -->
<availability>1.0</availability>
<!-- Any restrictions on use of the tag -->
<restrictions>None</restrictions>
<attribute>
<name>name</name>
<required>true</required>
<rtexprvalue>true</rtexprvalue>
<!-- Optional attribute type for JSP 1.2 rtexprvalue
<type>java.lang.String</type>
-->
<!-- Used for JSP 1.2 TLD and generating HTML docs -->
<description>checkbox name</description>
<!-- Used for the HTML documentation only.
Version of taglib when this attribute became available,
deprecated is a possible value. -->
<availability>1.0</availability>
</attribute>
<attribute>
<name>default</name>
<required>false</required>
<rtexprvalue>true</rtexprvalue>
<!-- Optional attribute type for JSP 1.2 rtexprvalue
<type>java.lang.String</type>
-->
<!-- Used for JSP 1.2 TLD and generating HTML docs -->
<description>The two "defaults" for checkbox are concatenated together to form
an array of size (defaults.length + 1), or 1 if defaults.length
is null or isn't present</description>
<!-- Used for the HTML documentation only.
Version of taglib when this attribute became available,
deprecated is a possible value. -->
<availability>1.0</availability>
</attribute>
<attribute>
<name>defaults</name>
<required>false</required>
<rtexprvalue>true</rtexprvalue>
<!-- Optional attribute type for JSP 1.2 rtexprvalue
<type>java.lang.String[]</type>
-->
<!-- Used for JSP 1.2 TLD and generating HTML docs -->
<description>The two "defaults" for checkbox are concatenated together to form
an array of size (defaults.length + 1), or 1 if defaults.length
is null or isn't present</description>
<!-- Used for the HTML documentation only.
Version of taglib when this attribute became available,
deprecated is a possible value. -->
<availability>1.0</availability>
</attribute>
<attribute>
<name>value</name>
<required>true</required>
<rtexprvalue>true</rtexprvalue>
<type>java.lang.String</type>
<description>value can be explicitly empty, or it can be absent, in which
case it defaults to "on"</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>attributes</name>
<required>false</required>
<rtexprvalue>true</rtexprvalue>
<!-- Optional attribute type for JSP 1.2 rtexprvalue
<type>java.util.Map</type>
-->
<!-- Used for JSP 1.2 TLD and generating HTML docs -->
<description>extra checkbox attributes</description>
<!-- Used for the HTML documentation only.
Version of taglib when this attribute became available,
deprecated is a possible value. -->
<availability>1.0</availability>
</attribute>
</tag>
</tagtoc>
</taglib>
<!-- The following is used to generate the tag library revision history
changes.html file. There can be 0 .. N revisions. Each revision
can have 0 .. N sections, each section can have 0 .. N items.
<revision release="{release-name}" date="MM/DD/YYYY">
<description>
Description of release.
<description>
<section name="New Features">
<item>
Added the Foo tag.
</item>
</section>
<section name="Bugs Fixed">
<item>
Fixed the Bar tag.
</item>
</section>
<section name="Deprecated">
<item>
The Test tag has been replaced by the Foo tag.
The Test tag will be removed in a later release.
</item>
</section>
</revision>
-->
<revision release="Development" date="MM/DD/YYYY">
<description>
The Input tag library is in development,
changes are fast and furious.
</description>
</revision>
</document>