12.7. Working With Formbuilder

12.7.1. Implementing and Registering a Process Listener

Your process listener must be a named Java class in order for it to be used by a persistent form. If your form listener needs certain parameters with specific names and data types, ensure that the listener implements the com.arsdigita.formbuilder.AttributeMetaDataProvider interface.

You register the listener by going to the formbuilder admin interface mounted under /formbuilder. On the index page, choose to add a new persistent form and supply the name of the listener that was implemented.

You may now notify any application administrator that the form is ready for editing. If the listener implements the com.arsdigita.formbuilder.AttributeMetaDataProvider interface, the formbuilder admin UI will make sure that the persistent form complies with this contract and submits the parameters that the listener needs.

12.7.2. Mounting a Persistent Form in an Application

The formbuilder admin UI represents persistent forms via the com.arsdigita.formbuilder.SimpleQuestionnaire class. You may retrieve an instance of this class via its integer id or via the admin name that you specified in the admin UI (the admin name is unique).

Once you have created the instance of SimpleQuestionnaire that you need, you have two options:

• The dynamic option involves adding a com.arsdigita.bebop.MetaForm to the page and will ensure that admin changes to the form will take immediate effect.

• The static approach involves adding a normal Bebop com.arsdigita.bebop.Form to your application page so that admin changes to the form will take effect only after server startup.

The dynamic approach is more convenient for the administrator, in that he can immediately see how the form will look in the application. However, if the page has a heavy load of users, the static approach is preferable, since it is much more efficient. This is because it does not dynamically build the component hierarchy of the form on every request.

Your decision to use static or dynamic will be based upon your usage patterns. One good method to follow is to use the dynamic approach when in heavy development of an application and it's forms, then switch to static when the pages go to the live server and are subject to public loads. It is usually preferred to keep the approach static on a non-production, site-development server. When you switch to the static approach, it is recommended to restart the server regularly (e.g. with a daily cron job) so as to capture changes made by application administrators.

Example 12-1 is an example of static mounting of a persistent form. In this case, the form is built only once upon server startup. The web server must be restarted for any changes to take effect.

Page applicationPage = new Page();
SimpleQuestionnaire questionnaire = 
 new SimpleQuestionnaire(new BigDecimal("773"));
applicationPage.add(questionnaire.createComponent());
applicationPage.lock();

Example 12-2 is an example of dynamic mounting of a persistent form. Changes to the form by the administrator will take immediate effect on the application page.

Page applicationPage = new Page();
applicationPage.add(new MetaForm() {

    public MetaForm() {
        super("application_form_name");
    }

    public Form buildForm(PageState pageState) {

        SimpleQuestionnaire questionnaire = 
         new SimpleQuesionnaire(new BigDecimal("773"));

        return questionnaire.createComponent();
    }
}
);
        
applicationPage.lock();