com.perdues.web
Class HTForm

java.lang.Object
  |
  +--com.perdues.web.HTForm

Direct Known Subclasses:

Form

public class HTForm

extends java.lang.Object

This class is sort of modeled after Perl's CGI.pm. It gives you a bunch of methods that render HTML form elements with the state maintained. In addition you can set the state of a field, which you can't do easily with HttpServletRequest itself.

HTForm has a HttpServletRequest object, and consults that when rendering a form element. So you can use it in any case you would have used HttpServletRequest.getParameterValues()

The database operations use extended database schema information from the com.perdues.db.Schema class.

Constructor Summary

HTForm()
Construct an empty Form.

HTForm(HTForm form)
Construct a copy of an existing HTForm.

HTForm(javax.servlet.http.HttpServletRequest request)
A form gets its initial state from the parameters in the request.

Method Summary

void	addValue(java.lang.String fieldname, java.lang.String value) Adds the given value to the list of values for the given field name if not already in the list.
java.lang.String	getCheckbox(java.lang.String fieldname) Renders a single checkbox with the given field name and the value "y" when checked.
java.lang.String	getCheckbox(java.lang.String fieldname, java.lang.String value) Renders a single checkbox with the given field name and value when checked.
java.lang.String	getCheckboxes(java.lang.String fieldname, java.lang.String[] values) Renders a list of checkboxes, all with the same field name, with the values and labels the same, as if with an empty hash table in the variant with a hash table argument.
java.lang.String	getCheckboxes(java.lang.String field, java.lang.String[] values, java.util.Hashtable labels) Renders a list of checkboxes, all with the same field name, one for each value in the list.
java.lang.String	getChoice(java.lang.String fieldname, java.lang.String[] values) Render a choice (dropdown list) for the named field with the listed values.
java.lang.String	getChoice(java.lang.String fieldname, java.lang.String[] values, java.util.Hashtable labels) Render a choice (dropdown list) for the named field with the listed values.
java.util.Date	getDate(java.lang.String fieldname) Reconstructs a date from the three shadow fields.
java.lang.String	getDateField(java.lang.String fieldname, int start_year, int stop_year)
java.lang.String	getHidden(java.lang.String fieldname) Returns a set of <input type="hidden"> HTML form fields with the values properly set.
int	getInt(java.lang.String fieldname) Returns the value of the given field as an integer, throwing a NumberFormatException if the value does not represent an integer, as determined by Integer.parseInt.
int	getInt(java.lang.String fieldname, int dfault) Returns the value of the given field as an integer, returning the given defaultvalue if the value does not represent an intger as determined by Integer.parseInt.
java.lang.String	getList(java.lang.String fieldname, int size, boolean allowMultiple, java.lang.String[] values) Render a scrolling list for the named field and values, with the specified size in rows, and allowing multiple selection if allowMultiple is true.
java.lang.String	getList(java.lang.String fieldname, int size, boolean allowMultiple, java.lang.String[] values, java.util.Hashtable labels) Render a scrolling list for the named field and values, with the specified size in rows, and allowing multiple selection if allowMultiple is true.
java.lang.String	getOptions(java.lang.String fieldname, java.lang.String[] values, java.util.Hashtable labels) Return a list of option tags for an HTML select.
java.lang.String	getPassword(java.lang.String fieldname, int size, int maxlength) Returns a <input type="password"> HTML form element with the state maintained
java.lang.String	getRadios(java.lang.String fieldname, java.lang.String[] values, java.util.Hashtable labels) Renders a list of radio buttons, all with the same field name, one for each value in the list.
java.lang.String	getText(java.lang.String text) Returns the same value, escaped for HTML, and suitably escaped to be inside an HTML attribute (quotes escaped).
java.lang.String	getTextarea(java.lang.String fieldname, int rows, int cols) calls getTextarea() with "none" as the wrap attribute.
java.lang.String	getTextarea(java.lang.String fieldname, int rows, int cols, java.lang.String wrap) Returns a <textarea> HTML form element with the state maintained.
java.lang.String	getTextfield(java.lang.String fieldname, int size, int maxlength) Returns a <input type="text"> HTML form element with the state maintained
java.lang.String	getValue(java.lang.String fieldname) A shorthand version of getValue(string, boolean) that passes in true as the returnNull parameter.
java.lang.String	getValue(java.lang.String fieldname, boolean returnNull) Returns the value of a given field.
java.lang.String	getValue(java.lang.String fieldname, java.lang.String defaultValue) Returns the value of a given field.
java.lang.String[]	getValues(java.lang.String fieldname) Returns the list of values for the given fieldname.
boolean	has(java.lang.String fieldname) Returns true iff getValue(fieldname) would return a string with at least one character in it.
boolean	hasValue(java.lang.String fieldname, java.lang.String value) True iff the given field of the form has a value equal to the one given.
java.util.Enumeration	keys() Returns an enumeration of all the field names in this HTForm.
void	mergeForm(HTForm form, boolean overwrite) Copies the contents of form into this form.
void	mergePathInfo(boolean overwrite) Treats PATH_INFO like another QUERY_STRING and folds those values into the form.
java.lang.Object	removeValue(java.lang.String key) Removes the value with the specified key.
void	removeValue(java.lang.String fieldname, java.lang.String value) Removes any occurrences of the given value from the list of values for fieldname.
void	setDate(java.lang.String fieldname, java.util.Date date) Sets a SQL-style string and three shadow variables for the date.
void	setDefault(java.lang.String fieldname, java.lang.String value) Sets the given value if there is none yet for the given field name.
void	setValue(java.lang.String fieldname, java.lang.String value) Sets value in the given slot fieldname.
void	setValues(java.lang.String fieldname, java.lang.String[] values) Same as form.setValue() except it sets multiple values from an array of values instead of taking a single value.
java.lang.String[]	splitString(java.lang.String str) Splits "str" into an array of Strings using \r\n as the delimitter.
java.lang.String	toQueryString() Create and return an HTTP query string (without the "?") representing the same field information contained in this HTForm.
java.lang.String	toString() Overridden method from class Object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

HTForm

public HTForm(javax.servlet.http.HttpServletRequest request)

A form gets its initial state from the parameters in the request.

HTForm

public HTForm()

Construct an empty Form.

HTForm

public HTForm(HTForm form)

Construct a copy of an existing HTForm.

Method Detail

getValue

public java.lang.String getValue(java.lang.String fieldname)

A shorthand version of getValue(string, boolean) that passes in true as the returnNull parameter.

getValue

public java.lang.String getValue(java.lang.String fieldname,
                                 java.lang.String defaultValue)

Returns the value of a given field. If the field has more than one value, it returns the first value on the list. If the field has no values, it returns the default, which may be null.

getInt

public int getInt(java.lang.String fieldname)

Returns the value of the given field as an integer, throwing a NumberFormatException if the value does not represent an integer, as determined by Integer.parseInt.

getInt

public int getInt(java.lang.String fieldname,
                  int dfault)

Returns the value of the given field as an integer, returning the given defaultvalue if the value does not represent an intger as determined by Integer.parseInt.

getValue

public java.lang.String getValue(java.lang.String fieldname,
                                 boolean returnNull)

Returns the value of a given field. If the field has more than one value, it returns the first value on the list. If the field has no values and returnNull is true, it returns null. Otherwise it returns an empty string.

has

public boolean has(java.lang.String fieldname)

Returns true iff getValue(fieldname) would return a string with at least one character in it.

hasValue

public boolean hasValue(java.lang.String fieldname,
                        java.lang.String value)

True iff the given field of the form has a value equal to the one given.

getValues

public java.lang.String[] getValues(java.lang.String fieldname)

Returns the list of values for the given fieldname. If there is only one value, this will be a single element array, just like in HttpServletRequest.getParameterValues().

The only difference between this method and the one in HttpServletRequest is that this will consult a local hash of values first that can be modified by adding, changing, or removing values.

getDate

public java.util.Date getDate(java.lang.String fieldname)

Reconstructs a date from the three shadow fields. If the shadow fields are not all there, reconstructs it from a standard SQL date string in the given field. Returns null if it cannot construct a Date from these.

splitString

public java.lang.String[] splitString(java.lang.String str)

Splits "str" into an array of Strings using \r\n as the delimitter. Useful for getting each line of a textarea back as a separate String

setValue

public void setValue(java.lang.String fieldname,
                     java.lang.String value)

Sets value in the given slot fieldname. Note that this will *not* change the value returned by HttpServletRequest, but it will be returned by form.getValues() or form.getValue(). Setting to null removes any existing values. After setting to null, getValue will return null.

setValues

public void setValues(java.lang.String fieldname,
                      java.lang.String[] values)

Same as form.setValue() except it sets multiple values from an array of values instead of taking a single value. The new values replace any existing values.

addValue

public void addValue(java.lang.String fieldname,
                     java.lang.String value)

Adds the given value to the list of values for the given field name if not already in the list.

setDefault

public void setDefault(java.lang.String fieldname,
                       java.lang.String value)

Sets the given value if there is none yet for the given field name.

removeValue

public void removeValue(java.lang.String fieldname,
                        java.lang.String value)

Removes any occurrences of the given value from the list of values for fieldname.

setDate

public void setDate(java.lang.String fieldname,
                    java.util.Date date)

Sets a SQL-style string and three shadow variables for the date. This lets special "Date widgets" pick up the right values, and also allows straightforward programmatic access and hidden fields that use this fieldname.

toQueryString

public java.lang.String toQueryString()

Create and return an HTTP query string (without the "?") representing the same field information contained in this HTForm.

mergeForm

public void mergeForm(HTForm form,
                      boolean overwrite)

Copies the contents of form into this form. If overwrite is true, then any values set in both forms will be replaced with the contents of the passed in form. Otherwise the old value in the current form will be retained.

mergePathInfo

public void mergePathInfo(boolean overwrite)

Treats PATH_INFO like another QUERY_STRING and folds those values into the form. This is useful if you want to pass dynamic information around, but still want search engines to index your pages. Most of them ignore pages with ? in the URL

removeValue

public java.lang.Object removeValue(java.lang.String key)

Removes the value with the specified key. Returns the object that was in that slot, or null if no value exists with that key.

keys

public java.util.Enumeration keys()

Returns an enumeration of all the field names in this HTForm.

getText

public java.lang.String getText(java.lang.String text)

Returns the same value, escaped for HTML, and suitably escaped to be inside an HTML attribute (quotes escaped). Use this to define text inside quotes in the value of an input field.

getTextfield

public java.lang.String getTextfield(java.lang.String fieldname,
                                     int size,
                                     int maxlength)

Returns a <input type="text"> HTML form element with the state maintained

getPassword

public java.lang.String getPassword(java.lang.String fieldname,
                                    int size,
                                    int maxlength)

Returns a <input type="password"> HTML form element with the state maintained

getTextarea

public java.lang.String getTextarea(java.lang.String fieldname,
                                    int rows,
                                    int cols,
                                    java.lang.String wrap)

Returns a <textarea> HTML form element with the state maintained.

Parameters:

fieldname - name of textarea to create

rows - number of rows in textarea

cols - number of columns in textarea

wrap - string to place in wrap="" attribute. valid values are "none", "virtual", "physical"

getTextarea

public java.lang.String getTextarea(java.lang.String fieldname,
                                    int rows,
                                    int cols)

calls getTextarea() with "none" as the wrap attribute.

getChoice

public java.lang.String getChoice(java.lang.String fieldname,
                                  java.lang.String[] values)

Render a choice (dropdown list) for the named field with the listed values. This renders options as with getOptions.

getChoice

public java.lang.String getChoice(java.lang.String fieldname,
                                  java.lang.String[] values,
                                  java.util.Hashtable labels)

Render a choice (dropdown list) for the named field with the listed values. This renders options as with getOptions.

getList

public java.lang.String getList(java.lang.String fieldname,
                                int size,
                                boolean allowMultiple,
                                java.lang.String[] values)

Render a scrolling list for the named field and values, with the specified size in rows, and allowing multiple selection if allowMultiple is true. This renders options as with getOptions.

getList

public java.lang.String getList(java.lang.String fieldname,
                                int size,
                                boolean allowMultiple,
                                java.lang.String[] values,
                                java.util.Hashtable labels)

Render a scrolling list for the named field and values, with the specified size in rows, and allowing multiple selection if allowMultiple is true. This renders options as with getOptions.

getOptions

public java.lang.String getOptions(java.lang.String fieldname,
                                   java.lang.String[] values,
                                   java.util.Hashtable labels)

Return a list of option tags for an HTML select. The values determine the values of the options. Any value that maps to a value in the labels hash table will display as the value from the hash table. Any value that appears in the HTML data of the form as a value of the field name is rendered as selected. It will be selected more than once if it appears in the form data more than once.

getCheckbox

public java.lang.String getCheckbox(java.lang.String fieldname,
                                    java.lang.String value)

Renders a single checkbox with the given field name and value when checked. Render your own label. If this Form object's has the given value for the fieldname, render the checkbox as checked.

getCheckbox

public java.lang.String getCheckbox(java.lang.String fieldname)

Renders a single checkbox with the given field name and the value "y" when checked. Render your own label. If this Form object's has the given value for the fieldname, render the checkbox as checked.

getCheckboxes

public java.lang.String getCheckboxes(java.lang.String fieldname,
                                      java.lang.String[] values)

Renders a list of checkboxes, all with the same field name, with the values and labels the same, as if with an empty hash table in the variant with a hash table argument.

getCheckboxes

public java.lang.String getCheckboxes(java.lang.String field,
                                      java.lang.String[] values,
                                      java.util.Hashtable labels)

Renders a list of checkboxes, all with the same field name, one for each value in the list. Each checkbox is labeled with the HTML associated in the hash table with the value in the list. If no label is associated with the value, renders no HTML label onto the page.

Renders checkboxes checked based on the value or values for the given field in this Form object. Renders each box with a checkmark if its values is equal to some value for the given field in this Form.

getRadios

public java.lang.String getRadios(java.lang.String fieldname,
                                  java.lang.String[] values,
                                  java.util.Hashtable labels)

Renders a list of radio buttons, all with the same field name, one for each value in the list. Each radio button is labeled with the HTML associated in the hash table with the value in the list. If no label is associated with the value, renders no HTML label onto the page.

Renders radio buttons checked based on the value for the given field in this Form object. Renders a box with a checkmark if its values is equal to the value for the given field in this Form.

getHidden

public java.lang.String getHidden(java.lang.String fieldname)

Returns a set of <input type="hidden"> HTML form fields with the values properly set. This is useful for maintaining a value or values posted to the page from another form. If the field has just one value, this returns exactly one hidden field tag.

getDateField

public java.lang.String getDateField(java.lang.String fieldname,
                                     int start_year,
                                     int stop_year)

toString

public java.lang.String toString()

Overridden method from class Object.

Overrides:

toString in class java.lang.Object