001: /*
002: * Copyright 2001-2007 Geert Bevin <gbevin[remove] at uwyn dot com>
003: * Distributed under the terms of either:
004: * - the common development and distribution license (CDDL), v1.0; or
005: * - the GNU Lesser General Public License, v2.1 or later
006: * $Id: FormBuilder.java 3697 2007-03-16 16:59:32Z gbevin $
007: */
008: package com.uwyn.rife.site;
009:
010: import java.util.Collection;
011: import java.util.Map;
012:
013: import com.uwyn.rife.template.Template;
014: import com.uwyn.rife.tools.exceptions.BeanUtilsException;
015:
016: /**
017: * This interface defines the methods for bean-centric form generation.
018: * <p>All the fields in a form can be generated at once by using the
019: * <code>generateForm</code> methods, or individual fields can be generated
020: * through the <code>generateField</code> method. It's also possible to remove
021: * the form generation for all the fields or for one field in particular
022: * through the <code>removeForm</code> and <code>removeField</code> methods.
023: * <p>When generating a form of a {@link Validated} bean instance, and
024: * associated {@link ValidationBuilder} will be used to also generate the
025: * validation errors and markings.
026: * <p>The form building works with a {@link Template} instance that it will
027: * analyze for the presence of certain values. The names of these will be in
028: * the following format: <code>FORM:PREFIX:name</code> where
029: * <code>FORM:PREFIX:</code> identifies which type of field has to be generated
030: * and <code>name</code> indicates the name of the property for which the form
031: * field will be generated.
032: * <p>The form builder will generally use the constraints on the bean property
033: * to generate the form field with the appropriate meta data information.
034: * Many times it's appropriate to add custom information to the form
035: * fields. This can be done by providing text in between the form field value
036: * begin and end tags. For example, for the XHTML form builder you can provide
037: * custom CSS style information:
038: * <pre>
039: * <!--V 'FORM:INPUT:firstname'-->style="border: 1px solid black;"<!--/V-->
040: * </pre>
041: * If the custom attributes are dynamic and contain value tags, then you should
042: * use a dedicated block template tag that has an <code>ATTRIBUTES:</code>
043: * middle part, for example:
044: * <pre>
045: * <!--V 'FORM:INPUT:firstname'/-->
046: * <!--B 'FORM:INPUT:ATTRIBUTES:firstname'-->style="border: 1px solid ${v color/};"<!--/B-->
047: * </pre>
048: * <p>By default, the generation of the form fields only includes the field
049: * itself. You can however customize this by specifying a block tag that has
050: * the same name as the value tag that will be filled in with the generated
051: * form field. This bock tag supports the following value tags:
052: * <code>FORM:LABEL</code>, <code>FORM:NAME</code>, <code>FORM:VALUE</code> and
053: * <code>FORM:FIELD</code>. If one of these is present, it will be replaced
054: * respectively with: the label of the form field, the name of the property,
055: * the current value of the property, and the generated form fields.
056: * For example:
057: * <pre>
058: * <!--B 'FORM:INPUT:firstname'-->
059: * <!--V 'FORM:NAME'/-->-<!--V 'FORM:VALUE'/--> : <!--V 'FORM:FIELD'/-->
060: * <!--/B-->
061: * </pre>
062: * could be rendered like this with the XHTML form builder:
063: * <pre>
064: * firstname-John : <input type="text" name="firstname" />
065: * </pre>
066: *
067: * @author Geert Bevin (gbevin[remove] at uwyn dot com)
068: * @version $Revision: 3697 $
069: * @see Validated
070: * @see ValidationBuilder
071: * @since 1.0
072: */
073: public interface FormBuilder extends Cloneable {
074: /**
075: * Template values that start with <code>FORM:HIDDEN:</code> will generate
076: * a hidden form field for the property name that follows the prefix.
077: * @since 1.0
078: */
079: public static final String PREFIX_FORM_HIDDEN = "FORM:HIDDEN:";
080:
081: /**
082: * Template values that start with <code>FORM:INPUT:</code> will generate
083: * a text input form field for the property name that follows the prefix.
084: * The maximum length of the allowed text will be obtained from the
085: * <code>maxLength</code> constraint.
086: * @since 1.0
087: */
088: public static final String PREFIX_FORM_INPUT = "FORM:INPUT:";
089:
090: /**
091: * Template values that start with <code>FORM:SECRET:</code> will generate
092: * a password input form field for the property name that follows the
093: * prefix. The maximum length of the allowed text will be obtained from the
094: * <code>maxLength</code> constraint.
095: * @since 1.0
096: */
097: public static final String PREFIX_FORM_SECRET = "FORM:SECRET:";
098:
099: /**
100: * Template values that start with <code>FORM:TEXTAREA:</code> will
101: * generate a multi-line text form field for the property name that follows
102: * the prefix.
103: * @since 1.0
104: */
105: public static final String PREFIX_FORM_TEXTAREA = "FORM:TEXTAREA:";
106:
107: /**
108: * Template values that start with <code>FORM:RADIO:</code> will
109: * generate a radio button group for the property name that follows the
110: * prefix. The possible radio button values will be obtain from the
111: * <code>inList</code> constraint,
112: * @since 1.0
113: */
114: public static final String PREFIX_FORM_RADIO = "FORM:RADIO:";
115:
116: /**
117: * Template values that start with <code>FORM:CHECKBOX:</code> will
118: * generate a checkbox group for the property name that follows the
119: * prefix. The possible checkbox values will be obtain from the
120: * <code>inList</code> constraint,
121: * @since 1.0
122: */
123: public static final String PREFIX_FORM_CHECKBOX = "FORM:CHECKBOX:";
124:
125: /**
126: * Template values that start with <code>FORM:SELECT:</code> will
127: * generate a select list for the property name that follows the
128: * prefix. The possible select list options will be obtain from the
129: * <code>inList</code> constraint,
130: * @since 1.0
131: */
132: public static final String PREFIX_FORM_SELECT = "FORM:SELECT:";
133:
134: /**
135: * Template values that start with <code>FORM:DISPLAY:</code> will
136: * not actually generate a form field but simply display the current value
137: * as text.
138: * @since 1.0
139: */
140: public static final String PREFIX_FORM_DISPLAY = "FORM:DISPLAY:";
141:
142: /**
143: * Template blocks that start with <code>FORM:LABEL:</code> provide a
144: * textual label for a specific value for a property name. The format after
145: * the prefix is <code>propertyname:propertyvalue</code>.
146: * <p>For example:
147: * <pre>
148: * <!--B 'FORM:LABEL:options:1'-->the first option<!--/B-->
149: * <!--B 'FORM:LABEL:options:2'-->the second option<!--/B-->
150: * </pre>
151: *
152: * @since 1.0
153: */
154: public static final String PREFIX_FORM_LABEL = "FORM:LABEL:";
155:
156: /**
157: * A template block with an <code>ATTRIBUTES</code> middle part after the
158: * standard form field prefix, allows for dynamic custom attributes
159: * specifications for the form field generation.
160: *
161: * @since 1.0
162: */
163: public static final String MIDDLE_ATTRIBUTES = "ATTRIBUTES:";
164:
165: /**
166: * Template value tags with the <code>FORM:LABEL</code> name will be
167: * replaced by the label if they are present inside block tags that have
168: * the same name as the template value that will contain the generated
169: * form field. (More information in the {@link FormBuilder} interface
170: * Javadocs)
171: * @since 1.0
172: */
173: public static final String ID_FORM_LABEL = "FORM:LABEL";
174:
175: /**
176: * Template value tags with the <code>FORM:FIELD</code> name will be
177: * replaced by the actual generated form field if they are present inside
178: * block tags that have the same name as the template value that will
179: * contain the generated form field. (More information in the
180: * {@link FormBuilder} interface Javadocs)
181: * @since 1.0
182: */
183: public static final String ID_FORM_FIELD = "FORM:FIELD";
184:
185: /**
186: * Template value tags with the <code>FORM:NAME</code> name will be
187: * replaced by the field name if they are present inside block tags that
188: * have the same name as the template value that will contain the generated
189: * form field. (More information in the {@link FormBuilder} interface
190: * Javadocs)
191: * @since 1.0
192: */
193: public static final String ID_FORM_NAME = "FORM:NAME";
194:
195: /**
196: * Template value tags with the <code>FORM:VALUE</code> name will be
197: * replaced by the current field value if they are present inside block
198: * tags that have the same name as the template value that will contain
199: * the generated form field. (More information in the {@link FormBuilder}
200: * interface Javadocs)
201: * @since 1.0
202: */
203: public static final String ID_FORM_VALUE = "FORM:VALUE";
204:
205: public static final String SUFFIX_SELECTED = ":SELECTED";
206: public static final String SUFFIX_CHECKED = ":CHECKED";
207:
208: /**
209: * The array of standard form field prefixes.
210: * @since 1.0
211: */
212: public static final String[] VALUE_PREFIXES = new String[] {
213: PREFIX_FORM_HIDDEN, PREFIX_FORM_INPUT, PREFIX_FORM_SECRET,
214: PREFIX_FORM_TEXTAREA, PREFIX_FORM_RADIO,
215: PREFIX_FORM_CHECKBOX, PREFIX_FORM_SELECT,
216: PREFIX_FORM_DISPLAY };
217:
218: /**
219: * Generates all the form fields for a bean class.
220: * <p>If content has already been filled in for any of the template values
221: * that are normally replaced with generated form fields, no generation
222: * will happen for those and the existing content will simply remain
223: * present.
224: *
225: * @param template the template instance that will be used for the form
226: * generation
227: * @param beanClass the bean class whose properties will be analyzed for
228: * the form generation
229: * @param values a map of name-value pairs that indicate the currently
230: * active context for the form that will be generated, these are typically
231: * the values that have been submitted previously through a web page. The
232: * values will be used to pre-populate the form fields with content.
233: * @param prefix the prefix of the bean property names that should be used
234: * while generating the form, this is handy to use when the several forms
235: * are present that use the same bean class or that has overlapping
236: * property names
237: * @return the collection of template value names that have been generated
238: * @throws BeanUtilsException when errors occurred during the form
239: * generation
240: * @since 1.0
241: */
242: public Collection<String> generateForm(Template template,
243: Class beanClass, Map<String, String[]> values, String prefix)
244: throws BeanUtilsException;
245:
246: /**
247: * Generates all the form fields for a bean instance.
248: * <p>If content has already been filled in for any of the template values
249: * that are normally replaced with generated form fields, no generation
250: * will happen for those and the existing content will simply remain
251: * present.
252: *
253: * @param template the template instance that will be used for the form
254: * generation
255: * @param bean the bean instance whose properties and validation errors
256: * will be analyzed for the form generation
257: * @param values a map of name-value pairs that indicate the currently
258: * active context for the form that will be generated, these are typically
259: * the values that have been submitted previously through a web page. The
260: * values will be used to pre-populate the form fields with content.
261: * @param prefix the prefix of the bean property names that should be used
262: * while generating the form, this is handy to use when the several forms
263: * are present that use the same bean class or that has overlapping
264: * property names
265: * @return the collection of template value names that have been generated
266: * @throws BeanUtilsException when errors occurred during the form
267: * generation
268: * @since 1.0
269: */
270: public Collection<String> generateForm(Template template,
271: Object bean, Map<String, String[]> values, String prefix)
272: throws BeanUtilsException;
273:
274: /**
275: * Generates a form field for one particular property.
276: * <p>If content has already been filled in for any of the template values
277: * that are normally replaced with generated form fields, no generation
278: * will happen for those and the existing content will simply remain
279: * present.
280: *
281: * @param template the template instance that will be used for the form
282: * generation
283: * @param property the constrained property that the form field will be
284: * generated for
285: * @param values the current values of the property, these are typically
286: * the values that have been submitted previously through a web page. The
287: * values will be used to pre-populate the form field with content.
288: * @param prefix the prefix of the bean property names that should be used
289: * while generating the form, this is handy to use when the several forms
290: * are present that use the same bean class or that has overlapping
291: * property names
292: * @return the collection of template value names that have been generated
293: * @since 1.0
294: */
295: public Collection<String> generateField(Template template,
296: ConstrainedProperty property, String[] values, String prefix);
297:
298: /**
299: * Generates a form field for one particular property.
300: * <p>If content has already been filled in for any of the template values
301: * that are normally replaced with generated form fields, no generation
302: * will happen for those and the existing content will simply remain
303: * present.
304: *
305: * @param template the template instance that will be used for the form
306: * generation
307: * @param propertyType the type of the property
308: * @param property the constrained property that the form field will be
309: * generated for
310: * @param values the current values of the property, these are typically
311: * the values that have been submitted previously through a web page. The
312: * values will be used to pre-populate the form field with content.
313: * @param prefix the prefix of the bean property names that should be used
314: * while generating the form, this is handy to use when the several forms
315: * are present that use the same bean class or that has overlapping
316: * property names
317: * @return the collection of template value names that have been generated
318: * @since 1.6
319: */
320: public Collection<String> generateField(Template template,
321: Class propertyType, ConstrainedProperty property,
322: String[] values, String prefix);
323:
324: /**
325: * Generates a form field for one particular property name.
326: * <p>If content has already been filled in for any of the template values
327: * that are normally replaced with generated form fields, no generation
328: * will happen for those and the existing content will simply remain
329: * present.
330: *
331: * @param template the template instance that will be used for the form
332: * generation
333: * @param name the name of the property that the form field will be
334: * generated for
335: * @param values the current values of the property, these are typically
336: * the values that have been submitted previously through a web page. The
337: * values will be used to pre-populate the form field with content.
338: * @param prefix the prefix of the bean property names that should be used
339: * while generating the form, this is handy to use when the several forms
340: * are present that use the same bean class or that has overlapping
341: * property names
342: * @return the collection of template value names that have been generated
343: * @since 1.0
344: */
345: public Collection<String> generateField(Template template,
346: String name, String[] values, String prefix);
347:
348: /**
349: * Generates a form field for one particular property name.
350: * <p>If content has already been filled in for any of the template values
351: * that are normally replaced with generated form fields, no generation
352: * will happen for those and the existing content will simply remain
353: * present.
354: *
355: * @param template the template instance that will be used for the form
356: * generation
357: * @param propertyType the type of the property
358: * @param name the name of the property that the form field will be
359: * generated for
360: * @param values the current values of the property, these are typically
361: * the values that have been submitted previously through a web page. The
362: * values will be used to pre-populate the form field with content.
363: * @param prefix the prefix of the bean property names that should be used
364: * while generating the form, this is handy to use when the several forms
365: * are present that use the same bean class or that has overlapping
366: * property names
367: * @return the collection of template value names that have been generated
368: * @since 1.6
369: */
370: public Collection<String> generateField(Template template,
371: Class propertyType, String name, String[] values,
372: String prefix);
373:
374: /**
375: * Generates a form field for one particular property and always replace
376: * the content of the template values that match the auto-generation
377: * name format.
378: * <p>This method also adds a <code>templateFieldName</code> parameter.
379: * It allows you to use another property name for the template values
380: * than the one of the actual bean property. You will typically use this
381: * when you dynamically generate a form and iterate over the generation
382: * of certain fields. So, for example, when you have properties named
383: * <code>answer1</code> and <code>answer2</code>, you can use this
384: * template snippet:
385: * <pre>
386: * <!--V 'answers'/-->
387: * <!--B 'answer'-->
388: * <!--V 'FORM:INPUT:answer'/-->
389: * <!--/B-->
390: * </pre>
391: * By using the <code>replaceField(template, "answer", property, null, null)</code>
392: * method call for each answer property and appending the
393: * <code>answer</code> block to the <code>answers</code> value, you can
394: * benefit from the automatic form field generation but still dynamically
395: * aggregate the results into one area.
396: *
397: * @param template the template instance that will be used for the form
398: * generation
399: * @param templateFieldName the name of the form field that will be used to
400: * look for supported value tags in the property template
401: * @param property the constrained property that the form field will be
402: * generated for
403: * @param values the current values of the property, these are typically
404: * the values that have been submitted previously through a web page. The
405: * values will be used to pre-populate the form field with content.
406: * @param prefix the prefix of the bean property names that should be used
407: * while generating the form, this is handy to use when the several forms
408: * are present that use the same bean class or that has overlapping
409: * property names
410: * @return the collection of template value names that have been generated
411: * @since 1.6
412: */
413: public Collection<String> replaceField(Template template,
414: String templateFieldName, ConstrainedProperty property,
415: String[] values, String prefix);
416:
417: /**
418: * Generates a form field for one particular property and always replace
419: * the content of the template values that match the auto-generation
420: * name format.
421: * <p>The documentation of the
422: * {@link #replaceField(Template, String, ConstrainedProperty, String[], String) previous replaceField method}
423: * contains more information about the functionality of this method.
424: *
425: * @param template the template instance that will be used for the form
426: * generation
427: * @param templateFieldName the name of the form field that will be used to
428: * look for supported value tags in the property template
429: * @param propertyType the type of the property
430: * @param property the constrained property that the form field will be
431: * generated for
432: * @param values the current values of the property, these are typically
433: * the values that have been submitted previously through a web page. The
434: * values will be used to pre-populate the form field with content.
435: * @param prefix the prefix of the bean property names that should be used
436: * while generating the form, this is handy to use when the several forms
437: * are present that use the same bean class or that has overlapping
438: * property names
439: * @return the collection of template value names that have been generated
440: * @since 1.6
441: */
442: public Collection<String> replaceField(Template template,
443: String templateFieldName, Class propertyType,
444: ConstrainedProperty property, String[] values, String prefix);
445:
446: /**
447: * Generates a form field for one particular property name and always
448: * replace the content of the template values that match the
449: * auto-generation name format.
450: * <p>The documentation of the
451: * {@link #replaceField(Template, String, ConstrainedProperty, String[], String) previous replaceField method}
452: * contains more information about the functionality of this method.
453: *
454: * @param template the template instance that will be used for the form
455: * generation
456: * @param templateFieldName the name of the form field that will be used to
457: * look for supported value tags in the property template
458: * @param name the name of the property that the form field will be
459: * generated for
460: * @param values the current values of the property, these are typically
461: * the values that have been submitted previously through a web page. The
462: * values will be used to pre-populate the form field with content.
463: * @param prefix the prefix of the bean property names that should be used
464: * while generating the form, this is handy to use when the several forms
465: * are present that use the same bean class or that has overlapping
466: * property names
467: * @return the collection of template value names that have been generated
468: * @see #replaceField(Template, String, ConstrainedProperty, String[], String)
469: * @since 1.6
470: */
471: public Collection<String> replaceField(Template template,
472: String templateFieldName, String name, String[] values,
473: String prefix);
474:
475: /**
476: * Generates a form field for one particular property name and always
477: * replace the content of the template values that match the
478: * auto-generation name format.
479: * <p>The documentation of the
480: * {@link #replaceField(Template, String, ConstrainedProperty, String[], String) previous replaceField method}
481: * contains more information about the functionality of this method.
482: *
483: * @param template the template instance that will be used for the form
484: * generation
485: * @param templateFieldName the name of the form field that will be used to
486: * look for supported value tags in the property template
487: * @param propertyType the type of the property
488: * @param name the name of the property that the form field will be
489: * generated for
490: * @param values the current values of the property, these are typically
491: * the values that have been submitted previously through a web page. The
492: * values will be used to pre-populate the form field with content.
493: * @param prefix the prefix of the bean property names that should be used
494: * while generating the form, this is handy to use when the several forms
495: * are present that use the same bean class or that has overlapping
496: * property names
497: * @return the collection of template value names that have been generated
498: * @see #replaceField(Template, String, ConstrainedProperty, String[], String)
499: * @since 1.6
500: */
501: public Collection<String> replaceField(Template template,
502: String templateFieldName, Class propertyType, String name,
503: String[] values, String prefix);
504:
505: /**
506: * Removes the content of all the template values that would otherwise be
507: * filled in with generated form fields through the {@link #generateForm(Template, Class, Map, String)}
508: * method.
509: *
510: * @param template the template instance whose values will be cleared
511: * @param beanClass the bean class whose properties will be analyzed for
512: * clearing the form field values
513: * @param prefix the prefix of the bean property names that should be used
514: * while clearing the form, this is handy to use when the several forms
515: * are present that use the same bean class or that has overlapping
516: * property names
517: * @throws BeanUtilsException when errors occurred during the clearing of
518: * the form
519: * @see #generateForm
520: * @since 1.0
521: */
522: public void removeForm(Template template, Class beanClass,
523: String prefix) throws BeanUtilsException;
524:
525: /**
526: * Removes the content of the template value that would otherwise be
527: * filled in with a generated form field through a {@link #generateField}
528: * method.
529: *
530: * @param template the template instance whose values will be cleared
531: * @param name the name of the property for which the template value will
532: * be cleared
533: * @param prefix the prefix of the bean property names that should be used
534: * while clearing the form, this is handy to use when the several forms
535: * are present that use the same bean class or that has overlapping
536: * property names
537: * @see #generateField
538: * @since 1.0
539: */
540: public void removeField(Template template, String name,
541: String prefix);
542:
543: /**
544: * Removes the content of the template value that would otherwise be
545: * filled in with a generated form field through a {@link #replaceField}
546: * method.
547: *
548: * @param template the template instance whose values will be cleared
549: * @param templateFieldName the that is use in the template values to
550: * identify the property that has to be cleared
551: * @see #replaceField(Template, String, ConstrainedProperty, String[], String)
552: * @since 1.6
553: */
554: public void removeField(Template template, String templateFieldName);
555:
556: /**
557: * Generates the required attributes so that an existing form field
558: * indicates its checked or selected status.
559: *
560: * @param template the template instance that will be used for the
561: * generation
562: * @param name the name of the parameter
563: * @param values the values of the parameter
564: * @return the collection of template value names that have been generated
565: */
566: public Collection<String> selectParameter(Template template,
567: String name, String[] values);
568:
569: /**
570: * Removes the generated attributes that indicate that an existing form
571: * field is checked or selected
572: *
573: * @param template the template instance that will be used for the clearing
574: * @param name the name of the parameter
575: * @param values the values of the parameter
576: */
577: public void unselectParameter(Template template, String name,
578: String[] values);
579:
580: /**
581: * Returns the <code>ValidationBuilder</code> that is used by this
582: * <code>FormBuilder</code>.
583: * @return this <code>FormBuilder</code>'s <code>ValidationBuilder</code>
584: * @since 1.0
585: */
586: public ValidationBuilder getValidationBuilder();
587:
588: public Object clone();
589: }
|