Good Form Developer Docs

How it works

Good Form is an engine that takes a form specification DSL and creates a form definition. It uses the form definition in conjunction with a set of business rules to determine which of the specified questions to ask the user. The decision is made in a Rules Engine (One Ring) by checking the form data (facts) against a rule set.

Along the way Good Form validates the field data and fetches references to information you may already have stored in a database or other system. The reference information becomes part of the form data.

A form instance is stored in the database along with the form data. Importantly, the form data is treated as a document, or a Hash Map of Questions with answers. You can recover all entered form data just from this document (however the form definition may provide some extra context). The form data is stored as JSON text.

When the form is finally submitted the form instance is processed by your application. You may process the data into other systems via an Enterprise Bus, translate it into a Domain Model, or just store the data and mine it later, for example using MongoDB.

good form structure diagram

Structure diagram (.svg)

You can see a short video of the Good Form process on Youtube (note set the quality to HD to read the text).

Form Validation

Good Form currently provides two basic forms of validation, field and form data.

Field validation is provided per field on the form and is not aware of the intent of the data or it's relationship to other fields. Field validators know basic information such as if the field is a phone number or just a number. You can supply a validator for a field that better understands the data type, such as a post(zip) code, and can validate it. Because field validators are limited to that fields data, a post code validator can't check that the post code is valid against the suburb provided in another field.

Form data validation is done in the One Ring rules engine while deciding what the next set of questions should be. All the data so far is supplied to the rule set so it can cross check entered information and validate it against business rules.

Custom field validators

You can add custom field validators to Good Form by adding a validation closure to the formValidationService. This can be done in the BootStrap of the application or at any point you have access to the formValidationService. e.g.

formValidationService.addCustomValidator("postcode", {FormElement formElement, String fieldValue ->
def error = false
if (!(fieldValue?.isNumber())) {
formElement.attr.error += "Postcodes can only be numbers round these parts."
error = true
return error

Autocomplete suggestions

The Simple Suggestions plugin provides the ability to add autocompletion to form elements, simply add the attribute suggest to the form definition (GoodForm DSL) in the element you want to provide autocomplete suggestions, and supply a corresponding text file in a 'suggestions' sub-folder within your grails projectr.

You can also pre-fill parts of the form via the rules engine and the reference service.

The Reference Service

The reference service lets you look up data referred to in the form. For example you may have a customer reference number. The reference service can look up the customer reference data and place that information in the form data Map. Once the data is in the Map the rules engine has access to it and can do something with it, like pre-fill some form data or affect the flow of the form to ask relevant questions.

Handling the submitted form data

Once the user has navigated their way through your form and supplied all the required documents they can submit the completed form. To get the data to process you can override the submit action in the FormController where you get the form id being submitted. Here you can mark the FormInstance as read only and pass it to your processing service where the data can be massaged into whatever domain model you use or passed to another service as JSON data.

If you are simply collecting data you may just like to store the data for later mining.

Back to the Good Form documentation

Copyright © nerdErg Pty Ltd 2012 ABN 20 159 294 989