What you should know:

• Metadata for scaffoling your GUI (described here).

What you need to compile/run the examples:

• java1.5 or newer
• opensource framework: agimatec-validation : download agimatec-validation.jar
• optional: javax.servlet.jar (servlet-api)
• optional: opensource frameworks/tools: agimatec-tools : download annomark-dist.zip and annogen.jar

1. Create model classes

We start with a plain java class, our model, used to transport attributes from the server to the GUI. (You can use DWR for marshaling object instances between Java and JavaScript/JDOM).

Example class “Business”:

import javax.persistence.*;

public class Business {
@Id
@Column(name=”business_id”, nullable=false, unique=true)
Long businessId;
@Column(name=”name”, nullable=false, unique=true, length=200)
String name;
@Column(name=”active”, nullable=false)
boolean active;
// getters, setters follow…
}

2. Write or generate xml meta data

You can write the xml meta data manually, or – if your classes have javax.persistence.* annotations – you can generate them using agimatec-tools/annomark.jar (described here):

<bean id=”com.agimatec.Business” impl=”com.agimatec.Business”>
<feature key=”mainKey”>
<value class=”string”>businessId</value>
</feature>
<property name=”businessId”>
<feature key=”uniqueKey”>
<value class=”boolean”>true</value>
</feature>
</property>
<property name=”name” mandatory=”true” maxLength=”200″>
<feature key=”uniqueKey”>
<value class=”boolean”>true</value>
</feature>
</property>
<property name=”active” mandatory=”true”/>
</bean>

Store the file as “beaninfos-default.xml” in the classpath.

2. Access the MetaBean

This requires agimatec-validation.jar to compile:

import com.agimatec.validation.MetaBeanManagerFactory;
import com.agimatec.validation.model.MetaBean;

MetaBeanManagerFactory.getRegistry().
addResourceLoader(“beaninfos-default.xml”);

MetaBean metabean = MetaBeanManagerFactory.getFinder().findForClass(Business.class);

3. Generate JSon for metabean(s)

We want to use the meta data in the AJAX layer, to have information about the properties, their types and additional features (mandatory, max-length, …) as a JSON formatted string. agimatec-validation offers a JSONGenerator, based on a freemarker template:

import com.agimatec.validation.json.JSONGenerator;

JSONGenerator generator = new JSONGenerator();
String json = generator.toJSON(metabean);
System.out.println(json);

This prints this JSON string:

agimatec.namespace(“agimatec.metadata”);

(function(){

var metaBean0 = {
“id” : “com.agimatec.Business”,
“beanClass” : “com.agimatec.Business”,
“name” : “Business”,
“features” :{   “mainKey” : “businessId”},
“properties” :{
“active”:{
“name” : “active”,
“type” : “boolean”,
“features” : {       “mandatory” : true       }},
“businessId”:{
“name” : “businessId”,
“type” : “long”,
“features” : {       “uniqueKey” : true       }},
“name”:{
“name” : “name”,
“type” : “java.lang.String”,
“features” : {       “maxLen” : 200,       “mandatory” : true,       “uniqueKey” : true       }},
“version”:{
“name” : “version”,
“type” : “int”,
“features” : {       }}}};

agimatec.metadata.metaBeans = {“com.agimatec.Business” : metaBean0};})();

4. Write a servlet to deliver JSON for the AJAX GUI

The java code for the servlet should not be a surprise, for it consists of what we have seen so far:

public void init() throws ServletException {
super.init();
MetaBeanManagerFactory.getRegistry().addResourceLoader(“beaninfos-default.xml”);
}

public void service(HttpServletRequest servletRequest, HttpServletResponse res)
throws ServletException, IOException {
Map<String, MetaBean> metaBeans = MetaBeanManagerFactory.getFinder().findAll();
// output JSON:
res.setContentType(“text/javascript”);
PrintWriter writer = res.getWriter();
String json = new JSONGenerator().toJSON(metaBeans.values());
writer.write(json);
}

Thats basically all! With this infrastructure your AJAX GUIs have access to meta information about the model classes.

5. Enrich meta data with information for the GUI-layer

You can enrich the xml meta data with additional hints (field sequence, formats, …) – whatever your GUI needs. If hhe additional information cannot be generated automatically, you should keep them in a separate xml-file:

<bean id=”com.agimatec.Business”>
<feature key=”DESCRIPTION”>
<value class=”string”>{name}</value>
</feature>
<feature key=”SORTING”>
<value class=”list”>
<string>name</string>
<string>active</string>
</value>
</feature>
<!–Visualisation as table–>
<feature key=”TABLE_COLUMNS”>
<value class=”list”>
<string>name</string>
<string>active</string>
</value>
</feature>
</bean>

Save this as “beaninfos-gui.xml ” in the classpath and register the file in the init() method of the servlet, too:

MetaBeanManagerFactory.getRegistry().addResourceLoader(“beaninfos-gui.xml”);

You see, that the JSON code will contain the additional information as well, because the MetaBeanManager merges them.

So far, we have the infrastructure to support meta data that allows us to build generic AJAX GUIs. The JSON string can be cached, because it will never change while the application is running.

6. User-specific meta data

We can go one step further: We can also support user-specific meta data! A usual requirement in a web application is, that – depending on the role of a user that is logged in – field-level permissions must be supported:
User A is allowed to change the “active”-state of our “Business” entity, while User B has read-only access to the field and the field is hidden for User C, …

This could also be useful, when a user can customize its GUI (disable fields) by himself or when the application is used by different companies with different settings for their users….

How does it work? – Use additional xml files and merge them in the JSON servlet. (You can also generate the meta beans during runtime programmatically).

beaninfos-role1.xml:

<bean id=”com.agimatec.Business”>
<property name=”active”>
<feature key=”readonly”>
<value class=”boolean”>true</value>
</feature>
</property>
</bean>

Extension of the servlet:

String customInfos = “beaninfos-role1.xml”; // determine this from session or request dynamically!
XMLMetaBeanInfos xmlInfos =
new XMLMetaBeanURLLoader(getClass().getResource(customInfos)).load();
Map<String, MetaBean> metaBeans =
MetaBeanManagerFactory.getEnricher().enrichCopies(xmlInfos);

The statements after “// output JSON” stay the same (see previous code fragment).

More information?

We already got some more posts in German about metadata and code generation, explaining the concepts and giving examples:

• TransferObjects generieren
• agimatec-tools als OpenSource auf google.code released!
• Statt Modellieren: Annotieren und generieren
• Klassen mit Mehrwert: Validierung und Metadaten

The open-source frameworks have a WIKI and additional examples or junit testcases, that help you.

If you have questions, do not hesitate to contact us!

This is the fifth article in our mini-series about developing highly ajaxified portlets. Other articles are:

• Generate Your UI Using Metadata
• Inter Portlet Communication
• Using YUI loader for your own javascript modules
• Portlet namespaces and javascript

This is the situation we are in. And here is how we ease the pain: we are generating the user interface.

Generating a Form

To generate a form using our framework, you need to tell it :

• what should be edited
• the type of what is edited

Say we are building a form to edit a user object that contains user ip addresses:

var user = {
	name:"Sebastian Schuth",
	ipAddress:"192.168.1.33",
	active:true
}

The form fields needed are described using object literals:

var fields = [
	{
		key:'name', //name of the edited property
		label:'User name', //label to use in the form
		type: 'string',//type information
		permissioning:{denied: false, readonly: false}
	},
	{
		key:'active',
		label:'User is active',
		type: 'boolean',
		permissioning:{denied: false, readonly: false}
	},
	{
		key:'ipAddress',
		label:'IP Address',
		type: 'ipAddress',//this is a custom type
		permissioning:{denied: false,readonly: false}
	}
];

The properties needed for each field are:

• key – name of the property that gets described by the entry
• label – description shown as label inside the form
• type – the type of the data stored in the property. This information is used by the framework to choose an editor implementation
• permissioning – data about what the user is allowed to do with the entry. This reflects what the server allows the user to do.

Using this information, we can create a form using the following API:

/**
 *

Adds a form with into the given container element using the given fieldDefinitions.

 *

The structure of the form's contents depend on the editor implementation inside fieldDefinitions. This
 * function creates just a form element as container for the elements the editors return and which it adds to the DOM.

 *

A Save button is added to the form as long as the addSaveBtn
 * config option is not set to false.
 * The fnOkCallback function must takes one parameter: it gets a new object filled with the values from the
 * created form.
 * 

 *
 * @param {object} namespace                The javascript portlet namespace (used to get I18N information)
 * @param {Element} container               HTML node to which the form is added
 * @param {object[]} fieldDefinitions       The definitions of the form fields
 * @param {function} fnOkCallback           Function which is called when the form's save button is clicked
 *                                          (if no save button is added (oConfig.addSaveBtn === false),
 *                                          this function is never called!)
 * @param {object} [oConfig]                Optional configuration.
 * @config {object} [formAttributes]        Attribute definitions for the form as key/value object.
 * @config {boolean} [addSaveBtn]           If false, no save button gets added to the form. Defaults to true.
 * @config {object[]} [additionalButtons]   Array of additional buttons that should get added left of the save button
 *                                          (if a save button is added) to the form.
 *                                          The contained objects need to members:
 *

 *
label {string} Label of the button.

 *
callback {function} Function called if the button gets clicked.

 *                                          

 *                                          Note: Make sure to stop the click event inside the callback function
 *                                          to make sure that the form does not get send!
 *
 * @return {function} An error handling function that can be called to check for errors and add error messages to the
 * form as needed.
 */
agimatec.scaffolding.createForm = function(namespace, container, fieldDefinitions, fnOkCallback, oConfig){
	// ...
}

(as you can see, we are using JSdoc toolkit to generate our API docs)

So, let’s create a form:

agimatec.scaffolding.createForm(this, formContainer, fields, null);

This call does two things: it creates a form inside formContainer and adds editor objects (read on to learn more about them!) to the field description objects given to it.

Now, we need to fill the form:

agimatec.scaffolding.fillFields(user, fields);

Now, we can see what we have constructed:

Form generated by the example code

Reading the values from the form is as easy as:

var objectFromForm = {};
agimatec.scaffolding.readValues(objectFromForm, fields, callbackWhenDone);

After this call, objectFromForm contains all data as edited by the user.

About Editors

Inside the framework, editor objects are used to create the form parts needed to edit object properties. All an editor does is create a fieldset which is added to the form created by agimatec.scaffolding.createForm(), which itself gets added to the DOM.
This means that if a special kind of data entry is needed, you will need to implement a special editor, which has to provide the following functions:

• getReadWriteElement() – returns the DOM element used to edit entries
• getReadElement() - returns the DOM element used to display
• setValue() – this is called by the framework when using agimatec.scaffolding.fillFields()

We have put together some editors (current count: 21), including ones to connect objects to other objects, upload files, entering IP addresses, weekdays, dates, times and so on. This makes maintaining our webapp much easier and guarantees the consistency our customers appreciate.

Now entering the stage: Metadata

Well, as easy defining fields using object literals is, this does not solve the issue of additions and changes to existing objects. This is where we added metadata to the mix. The metadata we get from the server tells us enough to create the field definitions we need to generate the forms!

So here we go:

	/**
	 * Gets the field definitions for a dynamic form element (@see scaffolding.js).
	 * This function returns the sorted field definitions for a specified object. These describe which
	 * editor is used and adds further information like key and label to it.
	 * If we have an enum type, it adds also the options to an feature object.
	 * Features:
	 *

	 *
sorting of field definitions using a bean's SORTING feature

	 *
AJF type matching for root type and all related beans (depends if the feature "include" is set)

	 *
adding type of modelObject AJF type as feature "refBeanId"

	 * 

	 *
	 * @param {object} namespace    The javascript portlet namespace (used to get I18N information)
	 * @param {string} beanInfoId   The bean info id (e.g. 'com.agimatec.connecta.model.XFireTemplate')
	 *
	 * @return {object[]} Field definitions for the given beanInfoId.
	 */
	agimatec.metadata.getFieldDefinitions = function(namespace, beanInfoId) {/*...*/};

All you need to pass is which kind of object you want to display, the rest is handled by the framework.

Whats next

In this post, i explained how our framework makes creating forms for data entry easy and how we use metadata to make things even more “magic”. But this is not the end of the story. Our metadata is generated in a multi-step process, which will be described in a future post. To wet you appetite: we are generating metadata from multiple sources: Java Beans and XML descriptors and are able to merge multiple descriptors and user-based permissions.

Of course, generated UIs always need to be highly configurable to meet your user’s needs. Our framework offers a lot of options for this, up to defining rules that can manipulate the form reflecting what the user entered (and it looks like: formManager.when("lifecycleStatus").isSetTo("ACTIVE").changeForm(/*...actions...*/)). This makes the forms more friendly to use and prevents the user from doing things that make no sense. If you are interested, i would like to hear from you, just leave a comment.

Another theme i did not mention in the example is client-side validation. This is built in, too. And it is not hard to use, but explaining it would have made this article even longer. Again: if you are interested, leave a comment. If there is interest, i will blog about it.

This is the fourth article in my mini-series about developing highly ajaxified portlets. In this blog, you can also find articles about: