12.7. Working With Formbuilder

The formbuilder service makes it possible for non-technical application administrators to build forms (typically HTML forms). It has an API that lets developers mount those forms in an application. The developer is responsible for the processing of the form whereas the administrator takes care of the form elements and visual appearance.

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 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-1. Static Mounting of a Persistent Form

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();

Example 12-2. Dynamic Mounting of a Persistent Form