com.uwyn.rife.site
Interface FormBuilder

All Superinterfaces:
Cloneable
All Known Implementing Classes:
FormBuilderXhtml, FormBuilderXml

public interface FormBuilder
extends Cloneable

This interface defines the methods for bean-centric form generation.

All the fields in a form can be generated at once by using the generateForm methods, or individual fields can be generated through the generateField method. It's also possible to remove the form generation for all the fields or for one field in particular through the removeForm and removeField methods.

When generating a form of a Validated bean instance, and associated ValidationBuilder will be used to also generate the validation errors and markings.

The form building works with a Template instance that it will analyze for the presence of certain values. The names of these will be in the following format: FORM:PREFIX:name where FORM:PREFIX: identifies which type of field has to be generated and name indicates the name of the property for which the form field will be generated.

The form builder will generally use the constraints on the bean property to generate the form field with the appropriate meta data information. Many times it's appropriate to add custom information to the form fields. This can be done by providing text in between the form field value begin and end tags. For example, for the XHTML form builder you can provide custom CSS style information:

 <!--V 'FORM:INPUT:firstname'-->style="border: 1px solid black;"<!--/V-->
 
If the custom attributes are dynamic and contain value tags, then you should use a dedicated block template tag that has an ATTRIBUTES: middle part, for example:
 <!--V 'FORM:INPUT:firstname'/-->
 <!--B 'FORM:INPUT:ATTRIBUTES:firstname'-->style="border: 1px solid ${v color/};"<!--/B-->
 

By default, the generation of the form fields only includes the field itself. You can however customize this by specifying a block tag that has the same name as the value tag that will be filled in with the generated form field. This bock tag supports the following value tags: FORM:LABEL, FORM:NAME, FORM:VALUE and FORM:FIELD. If one of these is present, it will be replaced respectively with: the label of the form field, the name of the property, the current value of the property, and the generated form fields. For example:

 <!--B 'FORM:INPUT:firstname'-->
 <!--V 'FORM:NAME'/-->-<!--V 'FORM:VALUE'/--> : <!--V 'FORM:FIELD'/-->
 <!--/B-->
 
could be rendered like this with the XHTML form builder:
 firstname-John : <input type="text" name="firstname" />
 

Since:
1.0
Version:
$Revision: 3697 $
Author:
Geert Bevin (gbevin[remove] at uwyn dot com)
See Also:
Validated, ValidationBuilder

Field Summary
static String ID_FORM_FIELD
          Template value tags with the FORM:FIELD name will be replaced by the actual generated form field if they are present inside block tags that have the same name as the template value that will contain the generated form field.
static String ID_FORM_LABEL
          Template value tags with the FORM:LABEL name will be replaced by the label if they are present inside block tags that have the same name as the template value that will contain the generated form field.
static String ID_FORM_NAME
          Template value tags with the FORM:NAME name will be replaced by the field name if they are present inside block tags that have the same name as the template value that will contain the generated form field.
static String ID_FORM_VALUE
          Template value tags with the FORM:VALUE name will be replaced by the current field value if they are present inside block tags that have the same name as the template value that will contain the generated form field.
static String MIDDLE_ATTRIBUTES
          A template block with an ATTRIBUTES middle part after the standard form field prefix, allows for dynamic custom attributes specifications for the form field generation.
static String PREFIX_FORM_CHECKBOX
          Template values that start with FORM:CHECKBOX: will generate a checkbox group for the property name that follows the prefix.
static String PREFIX_FORM_DISPLAY
          Template values that start with FORM:DISPLAY: will not actually generate a form field but simply display the current value as text.
static String PREFIX_FORM_HIDDEN
          Template values that start with FORM:HIDDEN: will generate a hidden form field for the property name that follows the prefix.
static String PREFIX_FORM_INPUT
          Template values that start with FORM:INPUT: will generate a text input form field for the property name that follows the prefix.
static String PREFIX_FORM_LABEL
          Template blocks that start with FORM:LABEL: provide a textual label for a specific value for a property name.
static String PREFIX_FORM_RADIO
          Template values that start with FORM:RADIO: will generate a radio button group for the property name that follows the prefix.
static String PREFIX_FORM_SECRET
          Template values that start with FORM:SECRET: will generate a password input form field for the property name that follows the prefix.
static String PREFIX_FORM_SELECT
          Template values that start with FORM:SELECT: will generate a select list for the property name that follows the prefix.
static String PREFIX_FORM_TEXTAREA
          Template values that start with FORM:TEXTAREA: will generate a multi-line text form field for the property name that follows the prefix.
static String SUFFIX_CHECKED
           
static String SUFFIX_SELECTED
           
static String[] VALUE_PREFIXES
          The array of standard form field prefixes.
 
Method Summary
 Object clone()
           
 Collection<String> generateField(Template template, Class propertyType, ConstrainedProperty property, String[] values, String prefix)
          Generates a form field for one particular property.
 Collection<String> generateField(Template template, Class propertyType, String name, String[] values, String prefix)
          Generates a form field for one particular property name.
 Collection<String> generateField(Template template, ConstrainedProperty property, String[] values, String prefix)
          Generates a form field for one particular property.
 Collection<String> generateField(Template template, String name, String[] values, String prefix)
          Generates a form field for one particular property name.
 Collection<String> generateForm(Template template, Class beanClass, Map<String,String[]> values, String prefix)
          Generates all the form fields for a bean class.
 Collection<String> generateForm(Template template, Object bean, Map<String,String[]> values, String prefix)
          Generates all the form fields for a bean instance.
 ValidationBuilder getValidationBuilder()
          Returns the ValidationBuilder that is used by this FormBuilder.
 void removeField(Template template, String templateFieldName)
          Removes the content of the template value that would otherwise be filled in with a generated form field through a replaceField(com.uwyn.rife.template.Template, java.lang.String, com.uwyn.rife.site.ConstrainedProperty, java.lang.String[], java.lang.String) method.
 void removeField(Template template, String name, String prefix)
          Removes the content of the template value that would otherwise be filled in with a generated form field through a generateField(com.uwyn.rife.template.Template, com.uwyn.rife.site.ConstrainedProperty, java.lang.String[], java.lang.String) method.
 void removeForm(Template template, Class beanClass, String prefix)
          Removes the content of all the template values that would otherwise be filled in with generated form fields through the generateForm(Template, Class, Map, String) method.
 Collection<String> replaceField(Template template, String templateFieldName, Class propertyType, ConstrainedProperty property, String[] values, String prefix)
          Generates a form field for one particular property and always replace the content of the template values that match the auto-generation name format.
 Collection<String> replaceField(Template template, String templateFieldName, Class propertyType, String name, String[] values, String prefix)
          Generates a form field for one particular property name and always replace the content of the template values that match the auto-generation name format.
 Collection<String> replaceField(Template template, String templateFieldName, ConstrainedProperty property, String[] values, String prefix)
          Generates a form field for one particular property and always replace the content of the template values that match the auto-generation name format.
 Collection<String> replaceField(Template template, String templateFieldName, String name, String[] values, String prefix)
          Generates a form field for one particular property name and always replace the content of the template values that match the auto-generation name format.
 Collection<String> selectParameter(Template template, String name, String[] values)
          Generates the required attributes so that an existing form field indicates its checked or selected status.
 void unselectParameter(Template template, String name, String[] values)
          Removes the generated attributes that indicate that an existing form field is checked or selected
 

Field Detail

PREFIX_FORM_HIDDEN

static final String PREFIX_FORM_HIDDEN
Template values that start with FORM:HIDDEN: will generate a hidden form field for the property name that follows the prefix.

Since:
1.0
See Also:
Constant Field Values

PREFIX_FORM_INPUT

static final String PREFIX_FORM_INPUT
Template values that start with FORM:INPUT: will generate a text input form field for the property name that follows the prefix. The maximum length of the allowed text will be obtained from the maxLength constraint.

Since:
1.0
See Also:
Constant Field Values

PREFIX_FORM_SECRET

static final String PREFIX_FORM_SECRET
Template values that start with FORM:SECRET: will generate a password input form field for the property name that follows the prefix. The maximum length of the allowed text will be obtained from the maxLength constraint.

Since:
1.0
See Also:
Constant Field Values

PREFIX_FORM_TEXTAREA

static final String PREFIX_FORM_TEXTAREA
Template values that start with FORM:TEXTAREA: will generate a multi-line text form field for the property name that follows the prefix.

Since:
1.0
See Also:
Constant Field Values

PREFIX_FORM_RADIO

static final String PREFIX_FORM_RADIO
Template values that start with FORM:RADIO: will generate a radio button group for the property name that follows the prefix. The possible radio button values will be obtain from the inList constraint,

Since:
1.0
See Also:
Constant Field Values

PREFIX_FORM_CHECKBOX

static final String PREFIX_FORM_CHECKBOX
Template values that start with FORM:CHECKBOX: will generate a checkbox group for the property name that follows the prefix. The possible checkbox values will be obtain from the inList constraint,

Since:
1.0
See Also:
Constant Field Values

PREFIX_FORM_SELECT

static final String PREFIX_FORM_SELECT
Template values that start with FORM:SELECT: will generate a select list for the property name that follows the prefix. The possible select list options will be obtain from the inList constraint,

Since:
1.0
See Also:
Constant Field Values

PREFIX_FORM_DISPLAY

static final String PREFIX_FORM_DISPLAY
Template values that start with FORM:DISPLAY: will not actually generate a form field but simply display the current value as text.

Since:
1.0
See Also:
Constant Field Values

PREFIX_FORM_LABEL

static final String PREFIX_FORM_LABEL
Template blocks that start with FORM:LABEL: provide a textual label for a specific value for a property name. The format after the prefix is propertyname:propertyvalue.

For example:

 <!--B 'FORM:LABEL:options:1'-->the first option<!--/B-->
 <!--B 'FORM:LABEL:options:2'-->the second option<!--/B-->
 

Since:
1.0
See Also:
Constant Field Values

MIDDLE_ATTRIBUTES

static final String MIDDLE_ATTRIBUTES
A template block with an ATTRIBUTES middle part after the standard form field prefix, allows for dynamic custom attributes specifications for the form field generation.

Since:
1.0
See Also:
Constant Field Values

ID_FORM_LABEL

static final String ID_FORM_LABEL
Template value tags with the FORM:LABEL name will be replaced by the label if they are present inside block tags that have the same name as the template value that will contain the generated form field. (More information in the FormBuilder interface Javadocs)

Since:
1.0
See Also:
Constant Field Values

ID_FORM_FIELD

static final String ID_FORM_FIELD
Template value tags with the FORM:FIELD name will be replaced by the actual generated form field if they are present inside block tags that have the same name as the template value that will contain the generated form field. (More information in the FormBuilder interface Javadocs)

Since:
1.0
See Also:
Constant Field Values

ID_FORM_NAME

static final String ID_FORM_NAME
Template value tags with the FORM:NAME name will be replaced by the field name if they are present inside block tags that have the same name as the template value that will contain the generated form field. (More information in the FormBuilder interface Javadocs)

Since:
1.0
See Also:
Constant Field Values

ID_FORM_VALUE

static final String ID_FORM_VALUE
Template value tags with the FORM:VALUE name will be replaced by the current field value if they are present inside block tags that have the same name as the template value that will contain the generated form field. (More information in the FormBuilder interface Javadocs)

Since:
1.0
See Also:
Constant Field Values

SUFFIX_SELECTED

static final String SUFFIX_SELECTED
See Also:
Constant Field Values

SUFFIX_CHECKED

static final String SUFFIX_CHECKED
See Also:
Constant Field Values

VALUE_PREFIXES

static final String[] VALUE_PREFIXES
The array of standard form field prefixes.

Since:
1.0
Method Detail

generateForm

Collection<String> generateForm(Template template,
                                Class beanClass,
                                Map<String,String[]> values,
                                String prefix)
                                throws BeanUtilsException
Generates all the form fields for a bean class.

If content has already been filled in for any of the template values that are normally replaced with generated form fields, no generation will happen for those and the existing content will simply remain present.

Parameters:
template - the template instance that will be used for the form generation
beanClass - the bean class whose properties will be analyzed for the form generation
values - a map of name-value pairs that indicate the currently active context for the form that will be generated, these are typically the values that have been submitted previously through a web page. The values will be used to pre-populate the form fields with content.
prefix - the prefix of the bean property names that should be used while generating the form, this is handy to use when the several forms are present that use the same bean class or that has overlapping property names
Returns:
the collection of template value names that have been generated
Throws:
BeanUtilsException - when errors occurred during the form generation
Since:
1.0

generateForm

Collection<String> generateForm(Template template,
                                Object bean,
                                Map<String,String[]> values,
                                String prefix)
                                throws BeanUtilsException
Generates all the form fields for a bean instance.

If content has already been filled in for any of the template values that are normally replaced with generated form fields, no generation will happen for those and the existing content will simply remain present.

Parameters:
template - the template instance that will be used for the form generation
bean - the bean instance whose properties and validation errors will be analyzed for the form generation
values - a map of name-value pairs that indicate the currently active context for the form that will be generated, these are typically the values that have been submitted previously through a web page. The values will be used to pre-populate the form fields with content.
prefix - the prefix of the bean property names that should be used while generating the form, this is handy to use when the several forms are present that use the same bean class or that has overlapping property names
Returns:
the collection of template value names that have been generated
Throws:
BeanUtilsException - when errors occurred during the form generation
Since:
1.0

generateField

Collection<String> generateField(Template template,
                                 ConstrainedProperty property,
                                 String[] values,
                                 String prefix)
Generates a form field for one particular property.

If content has already been filled in for any of the template values that are normally replaced with generated form fields, no generation will happen for those and the existing content will simply remain present.

Parameters:
template - the template instance that will be used for the form generation
property - the constrained property that the form field will be generated for
values - the current values of the property, these are typically the values that have been submitted previously through a web page. The values will be used to pre-populate the form field with content.
prefix - the prefix of the bean property names that should be used while generating the form, this is handy to use when the several forms are present that use the same bean class or that has overlapping property names
Returns:
the collection of template value names that have been generated
Since:
1.0

generateField

Collection<String> generateField(Template template,
                                 Class propertyType,
                                 ConstrainedProperty property,
                                 String[] values,
                                 String prefix)
Generates a form field for one particular property.

If content has already been filled in for any of the template values that are normally replaced with generated form fields, no generation will happen for those and the existing content will simply remain present.

Parameters:
template - the template instance that will be used for the form generation
propertyType - the type of the property
property - the constrained property that the form field will be generated for
values - the current values of the property, these are typically the values that have been submitted previously through a web page. The values will be used to pre-populate the form field with content.
prefix - the prefix of the bean property names that should be used while generating the form, this is handy to use when the several forms are present that use the same bean class or that has overlapping property names
Returns:
the collection of template value names that have been generated
Since:
1.6

generateField

Collection<String> generateField(Template template,
                                 String name,
                                 String[] values,
                                 String prefix)
Generates a form field for one particular property name.

If content has already been filled in for any of the template values that are normally replaced with generated form fields, no generation will happen for those and the existing content will simply remain present.

Parameters:
template - the template instance that will be used for the form generation
name - the name of the property that the form field will be generated for
values - the current values of the property, these are typically the values that have been submitted previously through a web page. The values will be used to pre-populate the form field with content.
prefix - the prefix of the bean property names that should be used while generating the form, this is handy to use when the several forms are present that use the same bean class or that has overlapping property names
Returns:
the collection of template value names that have been generated
Since:
1.0

generateField

Collection<String> generateField(Template template,
                                 Class propertyType,
                                 String name,
                                 String[] values,
                                 String prefix)
Generates a form field for one particular property name.

If content has already been filled in for any of the template values that are normally replaced with generated form fields, no generation will happen for those and the existing content will simply remain present.

Parameters:
template - the template instance that will be used for the form generation
propertyType - the type of the property
name - the name of the property that the form field will be generated for
values - the current values of the property, these are typically the values that have been submitted previously through a web page. The values will be used to pre-populate the form field with content.
prefix - the prefix of the bean property names that should be used while generating the form, this is handy to use when the several forms are present that use the same bean class or that has overlapping property names
Returns:
the collection of template value names that have been generated
Since:
1.6

replaceField

Collection<String> replaceField(Template template,
                                String templateFieldName,
                                ConstrainedProperty property,
                                String[] values,
                                String prefix)
Generates a form field for one particular property and always replace the content of the template values that match the auto-generation name format.

This method also adds a templateFieldName parameter. It allows you to use another property name for the template values than the one of the actual bean property. You will typically use this when you dynamically generate a form and iterate over the generation of certain fields. So, for example, when you have properties named answer1 and answer2, you can use this template snippet:

 <!--V 'answers'/-->
 <!--B 'answer'-->
 <!--V 'FORM:INPUT:answer'/-->
 <!--/B-->
 
By using the replaceField(template, "answer", property, null, null) method call for each answer property and appending the answer block to the answers value, you can benefit from the automatic form field generation but still dynamically aggregate the results into one area.

Parameters:
template - the template instance that will be used for the form generation
templateFieldName - the name of the form field that will be used to look for supported value tags in the property template
property - the constrained property that the form field will be generated for
values - the current values of the property, these are typically the values that have been submitted previously through a web page. The values will be used to pre-populate the form field with content.
prefix - the prefix of the bean property names that should be used while generating the form, this is handy to use when the several forms are present that use the same bean class or that has overlapping property names
Returns:
the collection of template value names that have been generated
Since:
1.6

replaceField

Collection<String> replaceField(Template template,
                                String templateFieldName,
                                Class propertyType,
                                ConstrainedProperty property,
                                String[] values,
                                String prefix)
Generates a form field for one particular property and always replace the content of the template values that match the auto-generation name format.

The documentation of the previous replaceField method contains more information about the functionality of this method.

Parameters:
template - the template instance that will be used for the form generation
templateFieldName - the name of the form field that will be used to look for supported value tags in the property template
propertyType - the type of the property
property - the constrained property that the form field will be generated for
values - the current values of the property, these are typically the values that have been submitted previously through a web page. The values will be used to pre-populate the form field with content.
prefix - the prefix of the bean property names that should be used while generating the form, this is handy to use when the several forms are present that use the same bean class or that has overlapping property names
Returns:
the collection of template value names that have been generated
Since:
1.6

replaceField

Collection<String> replaceField(Template template,
                                String templateFieldName,
                                String name,
                                String[] values,
                                String prefix)
Generates a form field for one particular property name and always replace the content of the template values that match the auto-generation name format.

The documentation of the previous replaceField method contains more information about the functionality of this method.

Parameters:
template - the template instance that will be used for the form generation
templateFieldName - the name of the form field that will be used to look for supported value tags in the property template
name - the name of the property that the form field will be generated for
values - the current values of the property, these are typically the values that have been submitted previously through a web page. The values will be used to pre-populate the form field with content.
prefix - the prefix of the bean property names that should be used while generating the form, this is handy to use when the several forms are present that use the same bean class or that has overlapping property names
Returns:
the collection of template value names that have been generated
Since:
1.6
See Also:
replaceField(Template, String, ConstrainedProperty, String[], String)

replaceField

Collection<String> replaceField(Template template,
                                String templateFieldName,
                                Class propertyType,
                                String name,
                                String[] values,
                                String prefix)
Generates a form field for one particular property name and always replace the content of the template values that match the auto-generation name format.

The documentation of the previous replaceField method contains more information about the functionality of this method.

Parameters:
template - the template instance that will be used for the form generation
templateFieldName - the name of the form field that will be used to look for supported value tags in the property template
propertyType - the type of the property
name - the name of the property that the form field will be generated for
values - the current values of the property, these are typically the values that have been submitted previously through a web page. The values will be used to pre-populate the form field with content.
prefix - the prefix of the bean property names that should be used while generating the form, this is handy to use when the several forms are present that use the same bean class or that has overlapping property names
Returns:
the collection of template value names that have been generated
Since:
1.6
See Also:
replaceField(Template, String, ConstrainedProperty, String[], String)

removeForm

void removeForm(Template template,
                Class beanClass,
                String prefix)
                throws BeanUtilsException
Removes the content of all the template values that would otherwise be filled in with generated form fields through the generateForm(Template, Class, Map, String) method.

Parameters:
template - the template instance whose values will be cleared
beanClass - the bean class whose properties will be analyzed for clearing the form field values
prefix - the prefix of the bean property names that should be used while clearing the form, this is handy to use when the several forms are present that use the same bean class or that has overlapping property names
Throws:
BeanUtilsException - when errors occurred during the clearing of the form
Since:
1.0
See Also:
generateForm(com.uwyn.rife.template.Template, java.lang.Class, java.util.Map, java.lang.String)

removeField

void removeField(Template template,
                 String name,
                 String prefix)
Removes the content of the template value that would otherwise be filled in with a generated form field through a generateField(com.uwyn.rife.template.Template, com.uwyn.rife.site.ConstrainedProperty, java.lang.String[], java.lang.String) method.

Parameters:
template - the template instance whose values will be cleared
name - the name of the property for which the template value will be cleared
prefix - the prefix of the bean property names that should be used while clearing the form, this is handy to use when the several forms are present that use the same bean class or that has overlapping property names
Since:
1.0
See Also:
generateField(com.uwyn.rife.template.Template, com.uwyn.rife.site.ConstrainedProperty, java.lang.String[], java.lang.String)

removeField

void removeField(Template template,
                 String templateFieldName)
Removes the content of the template value that would otherwise be filled in with a generated form field through a replaceField(com.uwyn.rife.template.Template, java.lang.String, com.uwyn.rife.site.ConstrainedProperty, java.lang.String[], java.lang.String) method.

Parameters:
template - the template instance whose values will be cleared
templateFieldName - the that is use in the template values to identify the property that has to be cleared
Since:
1.6
See Also:
replaceField(Template, String, ConstrainedProperty, String[], String)

selectParameter

Collection<String> selectParameter(Template template,
                                   String name,
                                   String[] values)
Generates the required attributes so that an existing form field indicates its checked or selected status.

Parameters:
template - the template instance that will be used for the generation
name - the name of the parameter
values - the values of the parameter
Returns:
the collection of template value names that have been generated

unselectParameter

void unselectParameter(Template template,
                       String name,
                       String[] values)
Removes the generated attributes that indicate that an existing form field is checked or selected

Parameters:
template - the template instance that will be used for the clearing
name - the name of the parameter
values - the values of the parameter

getValidationBuilder

ValidationBuilder getValidationBuilder()
Returns the ValidationBuilder that is used by this FormBuilder.

Returns:
this FormBuilder's ValidationBuilder
Since:
1.0

clone

Object clone()


Copyright © 2001-2007 Uwyn sprl/bvba. All Rights Reserved.