formdef
Project home

• Generate DynaActionForm definitions based on your business objects
• Data formatting support to html form controls to contain formatted text
• Conversion methods to format and parse data between your form and business object
• Locale support to allow the same form to be used in different locales using different data formats
• Extensions to allow both form definitions and form validations to reside in one XML

1. Declare the plugin in your struts-config.xml file. Of course you'll need the formdef.jar in your WEB-INF/lib or whereever you like to keep your struts.jar.

    <plug-in className="formdef.plugin.FormDefPlugIn">
        <set-property property="pathnames"
            value="/WEB-INF/form-defs.xml"/>
    </plug-in>

2. Create a form-defs.xml in your WEB-INF folder (or whereever you wanna place it). Copy the following code there, then replace the form's name with the name you want, and specify the full class name of the business object you want a formbean for.

    <form-definition>
        <formset>
            <form name="myForm"
                beanType="com.my.dto.MyBean"/>
        </formset>
    </form-definition>

That's it for declaring your bean. You can now start using your DynaActionForm in your code. The fields of your formbean will match the fields of your business object. Utility classes provide functionality for transferring data between the form bean and business object, with support for data formatting and parsing.

How does FormDef help with Struts ActionForms?

• You have forms that are just like or close to your actual business objects.
• You want your users to be able to type in formatted data, such as $11,199.95, or formatted dates.
• You need to support multiple locales in your forms.

FormDef makes it very easy to declare forms based on your business objects. Let's say you have an Employee bean, with empNo, firstName, lastName, birth, and salary as properties. The declaration for a form bean for this would be:

    <form-bean name="employeeForm"
        type="org.apache.struts.action.DynaActionForm">
        <form-property name="empNo" type="java.lang.String"/>
        <form-property name="firstName" type="java.lang.String"/>
        <form-property name="lastName" type="java.lang.String"/>
        <form-property name="birth" type="java.lang.String"/>
        <form-property name="salary" type="java.lang.String"/>
    </form-bean>

With FormDef, the equivalent definition would be:

    <form name="employeeForm" beanType="Employee"/>

By default, FormDef defines a String field for each property in your bean, resulting in a form definition just like the full form-bean XML definition given above. Of course, the defaults can be overridden, such as the type of form (i.e. DynaValidatorForm or any DynaActionForm subclass) or the type used for any given field. Forms that have more fields than the original business object are also supported, so your form can have fields for buttons or other controls that don't have bean counterparts.

The form beans are registered in Struts the same they would be if you used struts-config.xml to declare them, and there are no differences to Struts or to your actions in the way they behave or how they are used. You can continue to use BeanUtils to convert between these and your business objects, or do the conversions by hand. The only difference would be you'd potentially have a lot less XML to write and maintain, and changes to the business object would automatically be reflected in the form bean definition.
 
You want your users to be able to type in formatted data, such as $11,199.95, or formatted dates.

FormDef has conversion tools that can be used to convert data between your business object and the forms you defined through FormDef. Yes, they are similar to BeanUtils, except these methods provide more support for formatting and parsing the form values.

In the above example, suppose we want the form to use thousand separators for the salary, always show two decimal places, and use MM/DD/YYYY format for the birth date. We can use FormUtils' conversion methods, and that would use FormDef's included data converters. To specify the formatting patterns for the converters, we would supply them in the form definition, as follows:

    <form name="employeeForm" beanType="Employee">
        <field property="birth">
            <converter param="MM/dd/yyyy"/>
        </field>
        <field property="salary">
            <converter param="###,###,##0.00"/>
        </field>
    </form>

The fields that do not need conversion parameters need not be specified.

Aside from specifying conversion parameters one field at a time, you can specify them module-wide by field name or by data type, or both. For example, you can specify that all java.util.Date fields use "MM/dd/yyyy" but all fields whose name is hireMonth be formatted using "MMM-yy".
 
You need to support multiple locales in your forms.

If you're supporting multiple locales, you may want to use different conversion parameters for some specific locales. With FormDef, you can put the format in your application resource file, then provide the key in your form configuration file. This way, each locale can potentially use a different format for specific fields, including format strings that would otherwise be invalid under the default locale.

For example, if the system's default locale is "en_US", you could be using "###,###,##0.00" for a certain double field. You may decide to use "###.###.##0,00" for the same field for a "de" locale. FormDef determines the Locale using the standard Struts' Globals.LOCALE_KEY, and uses that when creating the DecimalFormat to use on your field. This enables the "de"-specific format string to be used for your data.

Taking the earlier example, the form definition will now look like:

    <form name="employeeForm" beanType="Employee">
        <field property="birth">
            <converter key="format.date"/>
        </field>
        <field property="salary">
            <converter key="format.salary"/>
        </field>
    </form>

In your application resource file, you'll have the following entries:

    format.date=MMM dd, yyyy
    format.salary=###,###,##0.00

If you want to use a different format for the "de" locale, your resource file for that could contain the following entries:

    format.date=dd MMM yyyy
    format.salary=###.###.##0,00