Form (Core com.ccg Classes 1.1.6-SNAPSHOT API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.ccg.util
Class Form

java.lang.Object
  com.ccg.util.Form

public class Form
extends Object
extends Object

Class to help with the generation of HTML forms. This class is used to help one build HTML form output. It contains a bunch of static methods which can be used to help construct forms.

Most of the static methods come in two flavors. The appendXXX() methods are the more efficient method where HTML is constructed by appending strings to a java.lang.StringBuffer object. The formatXXX() methods are less efficient, but sometimes more convient to use. They construct a StringBuffer object, invoke the corresponding appendXXX() method and return the results as a String.

The following method sample demonstrates how one might use these methods to construct a simple HTML input form:


  static public void main(String args[]) {

    StringBuffer sb = new StringBuffer(4000);

    Form.appendStart(sb,"/servlet/Hello",true);

    sb.append("Name:");
    Form.appendTextField(sb,"name","Paul",20,40);

    sb.append("Password:");
    Form.appendPasswordField(sb,"name",null,12,12);

    Form.appendHiddenField(sb,"hide_this","toadflax");

    String[] colors = { "brown", "green", "blue", "yellow", "gray" };
    boolean[] selected = { false, true, false, true, false };

    sb.append("Eye Color:");
    Form.appendSelectSingle(sb,"eye_color",3,colors,null,-1);

    sb.append("Desired Flag Colors:");
    Form.appendSelectMultiple(sb,"stripes",3,colors,null,selected);

    sb.append("How Many:");
    Form.appendNumberField(sb,"count",null,null,6);

    sb.append("Male:");
    Form.appendBooleanField(sb,"gender",true,null);

    Form.appendSubmitButton(sb,"action","Update");
    Form.appendSubmitButton(sb,"action","Logout");
    Form.appendSubmitButton(sb,null,null);

    Form.appendResetButton(sb,null);

    Form.appendEnd(sb);

    System.out.println(sb);
  }

Since:: 1.0
Version:: $Revision: 1.1.1.1 $
Author:: $Author: pkb $
See Also:: TableFormat

Constructor Summary
`Form()`

Method Summary
`static boolean`	`addSubmitPair(StringBuffer dst, boolean first, String name, String val)` Appends a name/value pair encoded to the end of a URL.
`static void`	`appendBooleanField(StringBuffer sb, String name, boolean val)` Adds a "boolean" checkbox button to the form output.
`static void`	`appendEnd(StringBuffer sb)` Ends a HTML form.
`static void`	`appendHiddenField(StringBuffer sb, String name, String val)` Adds a hidden name/value pair entry field to the StringBuffer.
`static void`	`appendNumberField(StringBuffer sb, String name, Number val, NumberFormat nf, int vis_length)` Adds a number text field to the StringBuffer.
`static void`	`appendPasswordField(StringBuffer sb, String name, String val, int vis_length, int max_length)` Adds a password entry field to the StringBuffer.
`static void`	`appendResetButton(StringBuffer sb, String val)` Adds a "reset" button to the form output.
`static void`	`appendSelectChoice(StringBuffer sb, String name, String display, boolean selected)` Adds a choice to a selection list presented to the user.
`static void`	`appendSelectEnd(StringBuffer sb)` Adds the end of a selection list entry to the StringBuffer.
`static void`	`appendSelectMultiple(StringBuffer sb, String name, int vis_size, String[] choice_names, String[] choice_disp, boolean[] selected)` Create a HTML form selection list (for a multiple choice selection).
`static void`	`appendSelectSingle(StringBuffer sb, String name, int vis_size, String[] choice_names, String[] choice_disp, int selected)` Create a HTML form selection list (for a one choice selection).
`static void`	`appendSelectStart(StringBuffer sb, String name, int vis_size, boolean multiple_ok)` Adds the start of a selection list entry to the StringBuffer.
`static void`	`appendStart(StringBuffer sb, String url, boolean post)` Starts a HTML form.
`static void`	`appendSubmitButton(StringBuffer sb, String name, String val)` Adds a "submit" button to the form output.
`static void`	`appendTextField(StringBuffer sb, String name, String val, int vis_length, int max_length)` Adds a input text field to the StringBuffer.
`static void`	`encodeSubmitParam(StringBuffer dst, String from)` Appends the "escaped/encoded" form submission parameters to the end of a string.
`static String`	`formatBooleanField(String name, boolean val)` Create a "boolean" checkbox button to the form output.
`static String`	`formatEnd()` Ends a HTML form.
`static String`	`formatHiddenField(String name, String val)` Adds a hidden name/value pair entry field to the StringBuffer.
`static String`	`formatNumberField(String name, Number val, NumberFormat nf, int vis_length)` Get the output of `appendNumberField(java.lang.StringBuffer, java.lang.String, java.lang.Number, java.text.NumberFormat, int)` as a String.
`static String`	`formatPasswordField(String name, String val, int vis_length, int max_length)` Get a string representation of a HTML form password field.
`static String`	`formatResetButton(String val)` Adds a "reset" button to the form output.
`static String`	`formatSelectMultiple(String name, int vis_size, String[] choice_names, String[] choice_disp, boolean[] selected)` Create a HTML form selection list (for a multiple choice selection).
`static String`	`formatSelectSingle(String name, int vis_size, String[] choice_names, String[] choice_disp, int selected)` Create a HTML form selection list (for a one choice selection).
`static String`	`formatStart(String url, boolean post)` Starts a HTML form.
`static String`	`formatSubmitButton(String name, String val)` Generates a "submit" button for the form output.
`static String`	`formatTextField(String name, String val, int vis_length, int max_length)` Get a string representation of a HTML form input text field.
`static void`	`main(String[] args)` Simple Form class test.
`static boolean`	`parseBooleanField(String val)` Parse boolean value entered in a boolean input field.
`static Number`	`parseNumberField(String val, NumberFormat nf)` Parse value entered in a number input field.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

Form

public Form()

Method Detail

appendStart

public static void appendStart(StringBuffer sb,
                               String url,
                               boolean post)

Starts a HTML form. This inserts the start of a HTML form. It specifies what URL data will be submitted to if the user presses a button to submit data.

Parameters:: sb - StringBuffer to append the results to.; url - URL to invoke when/if the user presses a "Submit" button.; post - Boolean flag indicating how the form data should be sent to the server. If set to true, then the data will be posted (not in the URL). If set to false, the data will be appended to the URL.
Since:: 1.0
See Also:: formatStart(java.lang.String, boolean)

formatStart

public static String formatStart(String url,
                                 boolean post)

Starts a HTML form. This inserts the start of a HTML form. It specifies what URL data will be submitted to if the user presses a button to submit data.

Parameters:: url - URL to invoke when/if the user presses a "Submit" button.; post - Boolean flag indicating how the form data should be sent to the server. If set to true, then the data will be posted (not in the URL). If set to false, the data will be appended to the URL.
Returns:: Returns string representation to be included int HTML output.
Since:: 1.0
See Also:: appendStart(java.lang.StringBuffer, java.lang.String, boolean)

appendEnd

public static void appendEnd(StringBuffer sb)

Ends a HTML form. This inserts the end of a HTML form. It should be used exactly once following a appendStart(java.lang.StringBuffer, java.lang.String, boolean) (and one or more input fields).

Since:: 1.0
See Also:: formatEnd()

formatEnd

public static String formatEnd()

Ends a HTML form. This inserts the end of a HTML form. It should be used exactly once following a appendStart(java.lang.StringBuffer, java.lang.String, boolean) (and one or more input fields).

Parameters:: sb - StringBuffer to append the results to.
Since:: 1.0
See Also:: appendEnd(java.lang.StringBuffer)

appendResetButton

public static void appendResetButton(StringBuffer sb,
                                     String val)

Adds a "reset" button to the form output. This inserts the form HTML "reset" button. If the user presses this button, then all of the data fields on the form will revert to their original state.

Parameters:: sb - StringBuffer to append the results to.; val - Optional label to display for the reset button. If set to null - then the browser will provide one.
Since:: 1.0
See Also:: formatResetButton(java.lang.String)

formatResetButton

public static String formatResetButton(String val)

Adds a "reset" button to the form output. This generates a HTML form "reset" button. If the user presses this button, then all of the data fields on the form will revert to their original state.

Parameters:: val - Optional label to display for the reset button. If set to null - then the browser will provide one.
Returns:: Returns string representation to be included int HTML output.
Since:: 1.0
See Also:: appendResetButton(java.lang.StringBuffer, java.lang.String)

appendSubmitButton

public static void appendSubmitButton(StringBuffer sb,
                                      String name,
                                      String val)

Adds a "submit" button to the form output. This inserts a HTML submit button. If the user presses this button, then the forms action will be invoked (this is setup by appendStart(java.lang.StringBuffer, java.lang.String, boolean)). This typically involves submitting all of the forms input fields to the URL associated with the form.

Parameters:: sb - StringBuffer to append the results to.; name - Set this to a non-null value if you want your form processing back-end to be able to determine what button was pressed. The user will not see this information, but a form processor (such as a Java servlet) will be able to request a value of this name and retrieve the associated "val" to determine which submit button the user pressed.; val - Optional label to display for the button. You can leave this set to null, but if you have more than one submission button on your form, it is recommended to specify a value.
Since:: 1.0
See Also:: formatSubmitButton(java.lang.String, java.lang.String)

formatSubmitButton

public static String formatSubmitButton(String name,
                                        String val)

Generates a "submit" button for the form output. This generates a HTML form "submit" button. If the user presses this button, then the forms action will be invoked (this is setup by appendStart(java.lang.StringBuffer, java.lang.String, boolean)). This typically involves submitting all of the forms input fields to the URL associated with the form.

Parameters:: name - Set this to a non-null value if you want your form processing back-end to be able to determine what button was pressed. The user will not see this information, but a form processor (such as a Java servlet) will be able to request a value of this name and retrieve the associated "val" to determine which submit button the user pressed.; val - Optional label to display for the button. You can leave this set to null, but if you have more than one submission button on your form, it is recommended to specify a value.
Since:: 1.0
See Also:: appendSubmitButton(java.lang.StringBuffer, java.lang.String, java.lang.String)

appendTextField

public static void appendTextField(StringBuffer sb,
                                   String name,
                                   String val,
                                   int vis_length,
                                   int max_length)

Adds a input text field to the StringBuffer. This inserts the form HTML for a input text field (a single line of user edittable text). You may control the number of characters visible, and the maximum number of characters the user may enter in the field.

Parameters:: sb - StringBuffer to append the results to.; name - Name for the form field. This is not visible to the end user but is used to reference the data later (must not be null).; val - Optional initial value for the field (null is OK - in which case no defualt value will be displayed); vis_length - Number of characters visible to user using the form (set to -1 if you don't care - lets HTML decide).; max_length - Maximum length of characters user may enter (set to -1 if you don't want to specify a limit).
Since:: 1.0
See Also:: formatTextField(java.lang.String, java.lang.String, int, int)

formatTextField

public static String formatTextField(String name,
                                     String val,
                                     int vis_length,
                                     int max_length)

Get a string representation of a HTML form input text field. This inserts the form HTML for a input text field (a single line of user edittable text). You may control the number of characters visible, and the maximum number of characters the user may type for the field.

Parameters:: name - Name for the form field. This is not visible to the end user but is used to reference the data later (must not be null).; val - Optional initial value for the field (null is OK - in which case no defualt value will be displayed); vis_length - Number of characters visible to user using the form (set to -1 if you don't care - lets HTML decide).; max_length - Maximum length of characters user may enter (set to -1 if you don't want to specify a limit).
Returns:: Returns string representation to be included int HTML output.
Since:: 1.0
See Also:: appendTextField(java.lang.StringBuffer, java.lang.String, java.lang.String, int, int)

appendNumberField

public static void appendNumberField(StringBuffer sb,
                                     String name,
                                     Number val,
                                     NumberFormat nf,
                                     int vis_length)

Adds a number text field to the StringBuffer. This inserts the form HTML for a input text field which should be only be used for numeric value fields (a single line of user edittable text). You may control the number of characters visible, and wheter a value is displayed and how it will be formatted. Use the parseNumberField(java.lang.String, java.text.NumberFormat) method to extract the results of the user's edits.

Parameters:: sb - StringBuffer to append the results to.; name - Name for the form field. This is not visible to the end user but is used to reference the data later (must not be null).; val - Optional initial value for the field (null is OK - in which case no default value will be displayed); nf - NumberFormat to use for formatting the value. If it is null, then NumberFormat.getInstance() will be used for the default formatter. (note, this is only used if 'val' is non-null); vis_length - Number of characters visible to user using the form (set to -1 if you don't care - lets HTML decide).
Since:: 1.0
See Also:: formatNumberField(java.lang.String, java.lang.Number, java.text.NumberFormat, int), parseNumberField(java.lang.String, java.text.NumberFormat)

formatNumberField

public static String formatNumberField(String name,
                                       Number val,
                                       NumberFormat nf,
                                       int vis_length)

Get the output of appendNumberField(java.lang.StringBuffer, java.lang.String, java.lang.Number, java.text.NumberFormat, int) as a String. This inserts the form HTML for a input text field which should be only be used for numeric value fields (a single line of user edittable text). You may control the number of characters visible, and wheter a value is displayed and how it will be formatted. Use the parseNumberField(java.lang.String, java.text.NumberFormat) method to extract the results of the user's edits.

Parameters:: name - Name for the form field. This is not visible to the end user but is used to reference the data later (must not be null).; val - Optional initial value for the field (null is OK - in which case no default value will be displayed); nf - NumberFormat to use for formatting the value. If it is null, then NumberFormat.getInstance() will be used for the default formatter. (note, this is only used if 'val' is non-null); vis_length - Number of characters visible to user using the form (set to -1 if you don't care - lets HTML decide).
Returns:: Returns string representation to be included int HTML output.
Since:: 1.0
See Also:: appendNumberField(java.lang.StringBuffer, java.lang.String, java.lang.Number, java.text.NumberFormat, int), parseNumberField(java.lang.String, java.text.NumberFormat)

parseNumberField

public static Number parseNumberField(String val,
                                      NumberFormat nf)

Parse value entered in a number input field. This is the counterpart to the formatNumberField(java.lang.String, java.lang.Number, java.text.NumberFormat, int). It attempts to parse a users input as a standard java Number object. This method does not throw any exceptions, but will return null the "value" passed does not contain a valid number.

Parameters:: val - String object to try to parse number from (its OK to pass null - but you'll get null back).; nf - java.text.NumberFormat to use to try and extract the number.
Returns:: Number object if we were able to successfully parse a number, or null if not.
Since:: 1.0
See Also:: formatNumberField(java.lang.String, java.lang.Number, java.text.NumberFormat, int)

appendBooleanField

public static void appendBooleanField(StringBuffer sb,
                                      String name,
                                      boolean val)

Adds a "boolean" checkbox button to the form output. This inserts a HTML form checkbox. If the checkbox is checked, then the "name" value will be set to "true" when the form data is submitted (it will not be included if it is false). No text will appear on the output.

Parameters:: sb - StringBuffer to append the results to.; name - Set this to a non-null value if you want your form processing back-end to be able to determine if the checkbox was actually checked or unchecked by the user. The user will not see this information, but a form processor (such as a Java servlet) will be able to request a value of this name and retrieve the associated "val" to determine if the checkbox was checked.; val - Initial state of the checkbox. Set to true if checkbox should initially be displayed as "checked" (true state).
Since:: 1.0
See Also:: formatBooleanField(java.lang.String, boolean), parseBooleanField(java.lang.String)

formatBooleanField

public static String formatBooleanField(String name,
                                        boolean val)

Create a "boolean" checkbox button to the form output. This creates a HTML form checkbox. If the checkbox is checked, then the "name" value will be set to "true" when the form data is submitted (it will not be included if it is false). No text will appear on the output.

Parameters:: sb - StringBuffer to append the results to.; name - Set this to a non-null value if you want your form processing back-end to be able to determine if the checkbox was actually checked or unchecked by the user. The user will not see this information, but a form processor (such as a Java servlet) will be able to request a value of this name and retrieve the associated "val" to determine if the checkbox was checked.; val - Initial state of the checkbox. Set to true if checkbox should initially be displayed as "checked" (true state).
Since:: 1.0
See Also:: appendBooleanField(java.lang.StringBuffer, java.lang.String, boolean)

parseBooleanField

public static boolean parseBooleanField(String val)

Parse boolean value entered in a boolean input field. This is the counterpart to the appendBooleanField(java.lang.StringBuffer, java.lang.String, boolean). You can use it to process the users submitted data. It attempts to the submitted form data as a standard boolean.

Parameters:: val - String object to try to parse number from (its OK to pass null - this is expected if the user did not set the boolean choice to true).
Returns:: boolean indicating if user specified option or not (true indicates the user selected/set the boolean flag).
Since:: 1.0
See Also:: appendBooleanField(java.lang.StringBuffer, java.lang.String, boolean), formatBooleanField(java.lang.String, boolean)

appendPasswordField

public static void appendPasswordField(StringBuffer sb,
                                       String name,
                                       String val,
                                       int vis_length,
                                       int max_length)

Adds a password entry field to the StringBuffer. This inserts the form HTML for a password input field (a single line of user edittable text - which does NOT echo what the user types). You may control the number of password characters visible (typically astericks are displayed), and the maximum length of the field.

Parameters:: sb - StringBuffer to append the results to.; name - Name for the form field. This is not visible to the end user but is used to reference the data later (must not be null).; val - Optional initial value for the field (null is OK - in which case no defualt value will be displayed); vis_length - Number of characters visible to user using the form (set to -1 if you don't care - lets HTML decide).; max_length - Maximum length of characters user may enter (set to -1 if you don't want to specify a limit).
Since:: 1.0
See Also:: formatPasswordField(java.lang.String, java.lang.String, int, int)

formatPasswordField

public static String formatPasswordField(String name,
                                         String val,
                                         int vis_length,
                                         int max_length)

Get a string representation of a HTML form password field. This inserts the form HTML for a password entry field (a single line of text which displays a fixed character (like '*') allowing the user to enter a password). You may control the number of characters visible, and the maximum number of characters the user may type for the field.

Parameters:: name - Name for the form field. This is not visible to the end user but is used to reference the data later (must not be null).; val - Optional initial value for the field (null is OK - in which case no defualt value will be displayed); vis_length - Number of characters visible to user using the form (set to -1 if you don't care - lets HTML decide).; max_length - Maximum length of characters user may enter (set to -1 if you don't want to specify a limit).
Returns:: Returns string representation to be included int HTML output.
Since:: 1.0
See Also:: appendTextField(java.lang.StringBuffer, java.lang.String, java.lang.String, int, int)

appendHiddenField

public static void appendHiddenField(StringBuffer sb,
                                     String name,
                                     String val)

Adds a hidden name/value pair entry field to the StringBuffer. This inserts the form HTML for a hidden field. These fields are not visible to the user. These fields are used to pass values to the form processor which the user does not need to know about.

Parameters:: sb - StringBuffer to append the results to.; name - Name for the form field. This is not visible to the end user but is used to reference the data later (must not be null).; val - Value for the field. If set to null, then the value "true" will be used (indicating the field was set).
Since:: 1.0
See Also:: formatHiddenField(java.lang.String, java.lang.String)

formatHiddenField

public static String formatHiddenField(String name,
                                       String val)

Parameters:: sb - StringBuffer to append the results to.; name - Name for the form field. This is not visible to the end user but is used to reference the data later (must not be null).; val - Value for the field. If set to null, then the value "true" will be used (indicating the field was set).
Returns:: Returns string representation to be included int HTML output.
Since:: 1.0
See Also:: appendHiddenField(java.lang.StringBuffer, java.lang.String, java.lang.String)

appendSelectStart

public static void appendSelectStart(StringBuffer sb,
                                     String name,
                                     int vis_size,
                                     boolean multiple_ok)

Adds the start of a selection list entry to the StringBuffer. This inserts the form HTML for the start of a SELECT input field. These types of fields allow the user to pick from a known set of choices. You can control whether the user is allowed to pick a single choice, or more than one.

After invoking this method, the appendSelectChoice(java.lang.StringBuffer, java.lang.String, java.lang.String, boolean) should be invoked 1 or more times followed by a single invocation of appendSelectEnd(java.lang.StringBuffer).

Parameters:: sb - StringBuffer to append the results to.; name - Name for the form field. This is not visible to the end user but is used to reference the data later (must not be null).; vis_size - Controls how much is visible to the user (set to 0 to omit and go with defualt). This may control whether the browser displays a pick list button, or a scrolling window choice box of this many rows - I'm not sure.; multiple_ok - If its OK for the user to select more than one item or not.
Since:: 1.0
See Also:: appendSelectChoice(java.lang.StringBuffer, java.lang.String, java.lang.String, boolean), appendSelectEnd(java.lang.StringBuffer)

appendSelectEnd

public static void appendSelectEnd(StringBuffer sb)

Adds the end of a selection list entry to the StringBuffer. This should be invoked following after all of the SELECT choices have been added via appendSelectChoice(java.lang.StringBuffer, java.lang.String, java.lang.String, boolean) it ends the selection box.

Parameters:: sb - StringBuffer to append the results to.
Since:: 1.0
See Also:: appendSelectChoice(java.lang.StringBuffer, java.lang.String, java.lang.String, boolean), appendSelectEnd(java.lang.StringBuffer)

appendSelectChoice

public static void appendSelectChoice(StringBuffer sb,
                                      String name,
                                      String display,
                                      boolean selected)

Adds a choice to a selection list presented to the user. This inserts the form HTML for another choice presented to the user as a HTML form SELECT input field. These types of fields allow the user to pick from a known set of choices. You can set whether this choice is selected or not by setting a flag.

Parameters:: sb - StringBuffer to append the results to.; name - Name for the selection field. This is not visible to the end user but is used to reference the data later (must not be null).; display - This is what should be displayed to the user for the particular choice. You can pass null, in which case the 'name' value will be displayed.; selected - Set to true if this choice is currently selected.
Since:: 1.0
See Also:: appendSelectStart(java.lang.StringBuffer, java.lang.String, int, boolean), appendSelectEnd(java.lang.StringBuffer)

appendSelectSingle

public static void appendSelectSingle(StringBuffer sb,
                                      String name,
                                      int vis_size,
                                      String[] choice_names,
                                      String[] choice_disp,
                                      int selected)

Create a HTML form selection list (for a one choice selection). This method combines appendSelectStart(java.lang.StringBuffer, java.lang.String, int, boolean), appendSelectChoice(java.lang.StringBuffer, java.lang.String, java.lang.String, boolean) and appendSelectEnd(java.lang.StringBuffer) to build a single choice selection list. This isn't as flexible and building the parts by yourself, but it is convienent.

Parameters:: sb - StringBuffer to append the results to.; name - Name for the form field. This is not visible to the end user but is used to reference the data later (must not be null).; vis_size - Controls how much is visible to the user (set to 0 to omit and go with default). This may control whether the browser displays a pick list button, or a scrolling window choice box of this many rows - I'm not sure.; choice_names - Array of strings which identify the choice names for each of the choice items. Choice names are typically not displayed to the user, but used by the back end processor of the form when looking at what the user selected.; choice_disp - Array of strings (must be exactly the same length as choice_names, or null) which is the set of choices to be displayed to the user (this is what the user sees when making choices). If null, then choice_names will be used.; selected - Which item is currently selected. Set to -1 if you don't want anything marked as selected by default. Otherwise, make sure the value is in the range of [0,choice_names.length-1].
Since:: 1.0
See Also:: formatSelectSingle(java.lang.String, int, java.lang.String[], java.lang.String[], int), appendSelectMultiple(java.lang.StringBuffer, java.lang.String, int, java.lang.String[], java.lang.String[], boolean[])

formatSelectSingle

public static String formatSelectSingle(String name,
                                        int vis_size,
                                        String[] choice_names,
                                        String[] choice_disp,
                                        int selected)

Parameters:: name - Name for the form field. This is not visible to the end user but is used to reference the data later (must not be null).; vis_size - Controls how much is visible to the user (set to 0 to omit and go with default). This may control whether the browser displays a pick list button, or a scrolling window choice box of this many rows - I'm not sure.; choice_names - Array of strings which identify the choice names for each of the choice items. Choice names are typically not displayed to the user, but used by the back end processor of the form when looking at what the user selected.; choice_disp - Array of strings (must be exactly the same length as choice_names, or null) which is the set of choices to be displayed to the user (this is what the user sees when making choices). If null, then choice_names will be used.; selected - Which item is currently selected. Set to -1 if you don't want anything marked as selected by default. Otherwise, make sure the value is in the range of [0,choice_names.length-1].
Returns:: Returns string representation to be included int HTML output.
Since:: 1.0
See Also:: appendSelectSingle(java.lang.StringBuffer, java.lang.String, int, java.lang.String[], java.lang.String[], int), formatSelectMultiple(java.lang.String, int, java.lang.String[], java.lang.String[], boolean[])

appendSelectMultiple

public static void appendSelectMultiple(StringBuffer sb,
                                        String name,
                                        int vis_size,
                                        String[] choice_names,
                                        String[] choice_disp,
                                        boolean[] selected)

Create a HTML form selection list (for a multiple choice selection). This method combines appendSelectStart(java.lang.StringBuffer, java.lang.String, int, boolean), appendSelectChoice(java.lang.StringBuffer, java.lang.String, java.lang.String, boolean) and appendSelectEnd(java.lang.StringBuffer) to build a multiple choice selection list. This isn't as flexible and building the parts by yourself, but it is convienent.

Parameters:: sb - StringBuffer to append the results to.; name - Name for the form field. This is not visible to the end user but is used to reference the data later (must not be null).; vis_size - Controls how much is visible to the user (set to 0 to omit and go with default). This may control whether the browser displays a pick list button, or a scrolling window choice box of this many rows - I'm not sure.; choice_names - Array of strings which identify the choice names for each of the choice items. Choice names are typically not displayed to the user, but used by the back end processor of the form when looking at what the user selected.; choice_disp - Array of strings (must be exactly the same length as choice_names, or null) which is the set of choices to be displayed to the user (this is what the user sees when making choices). If null, then choice_names will be used.; selected - Array of boolean values which indicate which entries should be in the selected state. If null, then no entries will be considered selected. Make sure the value is in the range of [0,choice_names.length-1].
Since:: 1.0
See Also:: formatSelectMultiple(java.lang.String, int, java.lang.String[], java.lang.String[], boolean[]), appendSelectSingle(java.lang.StringBuffer, java.lang.String, int, java.lang.String[], java.lang.String[], int)

formatSelectMultiple

public static String formatSelectMultiple(String name,
                                          int vis_size,
                                          String[] choice_names,
                                          String[] choice_disp,
                                          boolean[] selected)

Parameters:: name - Name for the form field. This is not visible to the end user but is used to reference the data later (must not be null).; vis_size - Controls how much is visible to the user (set to 0 to omit and go with default). This may control whether the browser displays a pick list button, or a scrolling window choice box of this many rows - I'm not sure.; choice_names - Array of strings which identify the choice names for each of the choice items. Choice names are typically not displayed to the user, but used by the back end processor of the form when looking at what the user selected.; choice_disp - Array of strings (must be exactly the same length as choice_names, or null) which is the set of choices to be displayed to the user (this is what the user sees when making choices). If null, then choice_names will be used.; selected - Array of boolean values which indicate which entries should be in the selected state. If null, then no entries will be considered selected. Make sure the value is in the range of [0,choice_names.length-1].
Returns:: Returns string representation to be included int HTML output.
Since:: 1.0
See Also:: appendSelectMultiple(java.lang.StringBuffer, java.lang.String, int, java.lang.String[], java.lang.String[], boolean[]), formatSelectSingle(java.lang.String, int, java.lang.String[], java.lang.String[], int)

encodeSubmitParam

public static void encodeSubmitParam(StringBuffer dst,
                                     String from)

Appends the "escaped/encoded" form submission parameters to the end of a string.

This method is used to properly format the strings to append to a URL that indicate form values (to allow one to make links that act like forms with all of the values set). Here is the table of how characters are currently replaced:

In	Out
" " (space)	"+"
Letter/Digit	Same Character
Others [0,255]	%XX (Hex Value)

IMPORTANT:You should not pass a full URL to this method as it will trash all of your characters. You should only use this method to append the names and then values of parameters. For example, if you pass: "x=312", it will mess up the "=" sign. Instead, use two separate calls (one to pass "x" and one to pass "312").

Here is an example of how one might use this:

 public static String getMapURL(String addr, String city, String st) {
   StringBuffer url = 
     new StringBuffer("http://maps.yahoo.com/py/maps.py?addr=");

   Form.encodeSubmitParam(url,addr);
   url.append("&csz=");
   Form.encodeSubmitParam(url,city);
   url.append("%2C");
   Form.encodeSubmitParam(url,zip);
   Form.encodeSubmitParam(url,"&Get Map=Get Map");

   return url.toString();
 }

Parameters:: dst - Buffer to append the encoded results to.; src - String to interpret (can be null - nothing will be appended)
Since:: 1.0
See Also:: addSubmitPair(java.lang.StringBuffer, boolean, java.lang.String, java.lang.String)

addSubmitPair

public static boolean addSubmitPair(StringBuffer dst,
                                    boolean first,
                                    String name,
                                    String val)

Appends a name/value pair encoded to the end of a URL.

This method is used to properly adds a name/value pair to the end of a URL string being formed. For example, if you wanted to set "x" to "312" and "y" to "400" this could be a handy method.

Here is an example of how one might use this (this is a "cleaner" rewrite of the example in encodeSubmitParam(java.lang.StringBuffer, java.lang.String)):

 public static String getMapURL(String addr, String city, String st) {
   StringBuffer url = 
     new StringBuffer("http://maps.yahoo.com/py/maps.py");

   boolean needFirst = Form.addSubmitPair(url,true,"addr",addr);
   needFirst = Form.addSubmitPair(url,needFirst,"csz",city+','+zip);
   needFirst = Form.addSubmitPair(url,needFirst,"Get Map","Get Map");

   return url.toString();
 }

Parameters:: dst - Buffer to append the encoded results to.; first - Is this the first parameter to append (determines if '?' or '&' will be appended first).; name - Name of the parameter we will set the value for (if this is null, then nothing is done); value - Value of the parameter to append.
Returns:: true if nothing was done (we still need to append '?' instead of '&' before adding the next name/value pair
Since:: 1.0
See Also:: encodeSubmitParam(java.lang.StringBuffer, java.lang.String)

main

public static void main(String[] args)

Simple Form class test. This is a simple example which generates a HTML form using the methods available in this class. Invoke from the command line via:

 java com.ccg.util.Form

Parameters:: args - Array of command line arguments (which are ignored).