Thursday, August 27, 2009

JSON Forms

Forms in a WEB applications are always a need and as they get complicated frameworks come to your rescue. Sometimes though, you have not a framework to rely on.

JSON gives a clean solution that actually works with any language out there as it is a standard Object notation supported by APIs in all modern languages used in WEB programming. After all building a JSON parser is not that hard.

Here are simple steps to come up with your own JSON Form API:
1. Create a JSON Form Array per WEB Form listing the necessary form fields. Below is a prepopulated Person JSON Form:

[{"name":"first_name","minlength":"6","maxlength":"50","mandatory":true,"editable":true,"translation":"First Name","value":"","selected":"Foo"},{"name":"last_name","minlength":"6","maxlength":"50","mandatory":true,"editable":true,"translation":"Last Name","value":"","selected":"Bar"},{"name":"email","minlength":"6","maxlength":"50","mandatory":true,"editable":true,"translation":"Email","value":"","selected":""},{"name":"phone","minlength":"7","maxlength":"16","mandatory":true,"editable":true,"translation":"Phone","value":"","selected":"+01 305-222-4444"},
{"name":"address1","minlength":"1","maxlength":"100","mandatory":true,"editable":true,"translation":"Address 1","value":"","selected":"1509 Alton Road"},{"name":"address2","minlength":"1","maxlength":"100","mandatory":false,"editable":true,"translation":"Address 2","value":"","selected":"Suite 302"},{"name":"city","minlength":"3","maxlength":"50","mandatory":true,"editable":true,"translation":"City","value":"","selected":"Miami Beach"},{"name":"state","minlength":"1","maxlength":"50","mandatory":true,"editable":true,"translation":"State","value":"","selected":"FL"},{"name":"zip","minlength":"3","maxlength":"20","mandatory":true,"editable":true,"translation":"Zip","value":"","selected":"33139"},{"name":"country","minlength":"3","maxlength":"3","mandatory":true,"editable":false,"translation":"Country","value":["USA", "Canada"],"selected":"USA"},{"name":"age","minlength":"1","maxlength":"3","mandatory":true,"editable":true,"translation":"Product","value":"","type":"int","selected":"33","min":"21","max":"100"},{"name":"graduation_date","minlength":"6","maxlength":"10","mandatory":true,"editable":true,"translation":"Graduation Date","value":"","type":"date","selected":"1999-09-05","format":"yyyy-MM-dd"},{"name":"comments","minlength":"0","maxlength":"255","mandatory":false,"editable":true,"translation":"Comments","value":"","selected":""}]

2. First time the form could be rendered with data using the "selected" field, others the form will come empty meaning "selected" will have no value. We can use "value" for a list of possible options, "mutex" to decide if we will accept multiple values, "format" for date types (we could actually change the format with the locale of the user), and so on.

3. When the form is submitted, pass the parameters to a Factory Form class that will append a validation error field (Array of errors) to the JSON Object. Things like "incorrect_length", "incorrect_type", "bigger number needed", "mandatory" are typical. On the other hand following conventions if the name of the field contains "email" then use regex to match if the email should be accepted or just use a library (Jakarta Commons Validator for Java offers an extensive amount of special data types). The same applies to zip codes and phones for example but commonly those follow special rules per country.

4. If special values are to be inserted from specific business rules do so in the JSON Object.

5. If there are validation errors render back the JSON Form explaining what the errors are (JQuery is great for this especially when using existing form plugins). Notice that with the same JSON Object you can provide both front end and middle tear validation. Ideally you should have a script that runs everytime the involved Database metadata changes, so the JSON Object is actually regenerated from time to time. That keeps the third tear (Backend) synchronized as well.

5. If there are no errors, proceed to persist the JSON Form Data in the Database. Again the persistence logic could be optionally provided on the fly using ORM techniques or even including a pre-populated by script Class that changes every time the model changes as well.