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

In theory.

In practice, you will be faced with a problem that is obviously a blind spot of the portlet definition (at least, the “old” JSR-186): how to communicate between portlets. The ability to mix-and-match portlets is key to a truly pluggable application formed of portlets.

To solve the communication problem, we have developed a solution much like the one developed by the folks at liferay, but a bit more tuned and optimized for a fully pluggable solution.

Portlet Services and Invokers

Our implementation follows a simple pattern: Portlets are able to promote services to a page-central instance and can include interaction elements that are used to invoke services that match certain criteria:

• the type of object the service must be able to handle
• the type of operation the service offers

Promoting a service to other portlets includes:

• specifying what type of operation (CREATE/READ/UPDATE/DELETE) is offered
• a text telling the user what happens when invoking the service
• the function that should get called on service activation

Using these simple building blocks we can offer users a list of actions that are available for a specific object:

Completely discoupled

The major advantage of our solution is that we do not hard-wire which portlets offers what to other portlets. All you have to do is insert a service invoker into the UI and the framework does the work for you. All people working on the project can work in parallel, the communication overhead is minimal. All the developers must do is offering a portlets services using the framework and give services a name that speaks.

This makes turns our product into a completely customizable platform that fits exactly our users’s needs.

Maximum flexibility

The framework makes splitting up responsibilities between portlets easy and puzzling just the right application for the job together possible. After adding a new portlet to a page, all service menus are automatically updated to offer new services that may have been added by the new portlet.

A generated service menu

Service menu for a different set of portlets

What you see in these screenshots is that depending on which portlets are available, the portlet will offer different actions for an object (for Screenshot 2, the “Ping” portlet was added). All information about which services are available is calculated client-side and for the current setup. Adding a new portlet will add its services to the actions list. The text that appears inside the menu is set by the portlet offering the service.

Invoking services is not limited to the context menus. We also use buttons for services that enable the creation of new items.

Impacts on portlet design

All this makes it easy to develop portlets that are designed to fulfill small tasks the right way. Reusability of portlets is massively increased. And on top of all this you get a consistent usage pattern that your customers will be familiar with when you are adding more functionality.

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

• Using YUI loader for your own javascript modules
  
• Portlet namespaces and javascript

In my next post in this series, i will give a little insight into how we use metadata generated by our server to make creating a fully ajax portlet a breeze. Meanwhile, check out our posts about testing our Ajax frontends using Selenium and the YUI Test framework.

The setting

Let me explain the structure of our project a bit. The main constraint we are facing when developing rich user interfaces for the web platform is that we were up to do so using Java Portlets. Using the portlets standard (JSR-168), we are able to meet our customer’s needs in a way we never could have done when developing traditional, monolithic web applications. But this flexibility comes at a price: we do not know which apps are on a page when it gets loaded; further, we want to be able to add new portlets to each page at any time. From a Javascript perspective, this means that traditional “just put script tags into the header”-style Javascript coding will lead to a very bad user experience, since every page would be bloated with stuff the user will never use and – even more important- the user experience will degrade as we are adding new features to our product, even if our customer does not need or want the new features. As explained before, adding Javascript code to HTML/JSP Parts of the Portlets were no option and would have caused massive double-loading of script code. As our platform grew, we saw the need to put together a Javascript library to support code reuse up front. We clearly needed a mechanism to load our Javascript modules as they are needed. After some experiments (including the use of unholy synchronous XHR calls… shame on me!), we tried the YUI Loader.

Meet the YUI Loader Utility

Its no secret that we are using YUI in our product. As YUI comes with a special module for loading dependencies, the YUI Loader Utility, we explored if we could use YUI for our needs. The Loader’s feature list reads like our wish-list:

• Reliable, sorted loading of dependencies
• Safe, efficient mechanism for adding new components to a page on which YUI may already be present.
• Automatic use of rolled-up files.

So we’ve developed our own solution on top of the YUI loader for our Framework. It consists of two components: A Compile-time dependency analyzer and a configuration file generated by the dependency analyzer that tells YUI how to load our modules.

Analyzing JS dependencies

First of all, every JS module file starts with a set of comments telling the dependency analyzer how the current module is called and what modules are required by the declared module:

// @@module agimatec.topic
// @@requires event, agimatec.datatypes

// Module code goes here
// ...
// ...
// ...
// ...
// ...

// Tell the loader that this module has been loaded
YAHOO.register("agimatec.topic", agimatec.topic, {version:'1.0',build:'000'});

The analyzer (which is current implemented as stand-alone groovy script that is run by maven – we have plans to implement it as maven Mojo) parses the dependency information in the module files and generates a Javascript configuration file for the YUI loader from it:

// ******************************
// Generated Code - DO NOT EDIT
// ******************************
/*
  This script adds all AJF module definitions to the YUI Loader utility as noted by
  '// @@' - style comments inside the *.js files.
  If the global variable 'agimatec_config' is not defined, it is defined by this script.
*/
(function(){
    var arrModules =[

            //...

            {
             name:'agimatec.scaffolding',
             type:'js',
             skinnable:false,
             path: '../../agimatec/scaffolding-2.1.11-SNAPSHOT-min.js',
             requires:["yahoo","event","calendar","tabview","agimatec.topic","agimatec.util","agimatec.util.table","agimatec.util.element","agimatec.util.minibrowser","agimatec.util.datePicker","agimatec.util.hintedText","agimatec.validator","agimatec.metadata"]},

            {
             name:'agimatec.topic',
             type:'js',
             skinnable:false,
             path: '../../agimatec/topic-2.1.11-SNAPSHOT-min.js',
             requires:["event","agimatec.datatypes"]},

            {
             name:'agimatec.util.browser',
             type:'js',
             skinnable:false,
             path: '../../agimatec/util/browser-2.1.11-SNAPSHOT-min.js',
             requires:["yahoo","dom","event","animation","datatable","agimatec.topic","agimatec.util","agimatec.util.yui","agimatec.util.lucene","agimatec.util.element","agimatec.preferences"]},

            {
             name:'agimatec.util.connector',
             type:'js',
             skinnable:false,
             path: '../../agimatec/util/connector-2.1.11-SNAPSHOT-min.js',
             requires:["yahoo","dom","event","container","datatable","agimatec.util","agimatec.metadata","agimatec.util.table","agimatec.portletservice","agimatec.util.minibrowser"]},

            {
             name:'agimatec.util.context',
             type:'js',
             skinnable:false,
             path: '../../agimatec/util/context-2.1.11-SNAPSHOT-min.js',
             requires:["agimatec.metadata","agimatec.util"]},

            {
             name:'agimatec.util.datePicker',
             type:'js',
             skinnable:false,
             path: '../../agimatec/util/datePicker-2.1.11-SNAPSHOT-min.js',
             requires:["yahoo","dom","event","agimatec.util","agimatec.util.hintedText"]},

		 // ...
    ];

    agimatec_config = agimatec_config || {};
    agimatec_config._modules = arrModules;
    agimatec_config.getLoader = function(){
        var modulesLength=agimatec_config._modules.length, i;
        var configObject = {};
        configObject.base = agimatec_config.yuiBasePath;
        if(agimatec_config.moduleFilter){
            configObject.filter=agimatec_config.moduleFilter;
        }
        if(undefined !== agimatec_config.allowRollup){
            configObject.allowRollup = agimatec_config.allowRollup;
        }
        // configure the default skin
        configObject.skin = {
            'defaultSkin':agimatec_config.defaultSkinName,
            'base': 'assets/skins/',
            'path': 'skin.css',
            'rollup': 3
        };
        var loader = new YAHOO.util.YUILoader(configObject);
        for(i=0; i

This file is included inside the header of every portlet page. You see that thanks to the YUI Loader, we can mix YUI modules with our own ones without hassle, making development of a comprehensive Javascript Library much easier. (If your wondering why we add version numbers to the referenced module names, see this article)

Loading a module is as easy as:

// ...

var loader = agimatec_config.getLoader()
loader.require("agimatec.topic");
loader.insert(function(){
	// use agimatec.topic and ALL of its dependencies here !!!!
});

You see that using modules is very easy. All you have to do is to tell the loader what you need and provide a function that should get executed as soon as the dependencies are resolved by adding the noted Javascript files.
This solution served us very well in the last months, in fact our complete webapp development depends on this loading mechanism. It made growing a stable and feature-rich javascript library possible for us without destroying the user experience.

This post just scratches the features of our Javascript module tooling. We have also added support for a module description file format that allows us to describe Javascript modules using XML and generate the loading and dependency management code, along with support for “rollup” JS modules that allow us to reduce the number of requests needed to load portal pages.

If you are interested in this component, just tell us so in the comments and we will see how fast we can get this utility out of the door as Open Source.

This is part two of an article series about Ajax Portlet development. In my next post, i will tell you about how we handle inter-portlet communication in our framework and how our approach makes our application extremely flexible without hardcoding dependencies between portlets.

The easy way

When consulting the portlet books on the market or Sun’s own tips, you’ gonna find one easy solution to the problem: using the portlet namespace for your Javascript. The portlet namespace is a portlet-instance specific string that is suitable to identify assets of a portlet instance. So the easy way out is to use it as prefix or post fix for the functions you write:

<!-- Example: JSP page -->
<%@ taglib uri="http://java.sun.com/portlet" prefix="portlet" %>

Wow, that was easy. But there are some drawback when doing this:

• you have to stick to define your Javascript inside the portlets – no external Javascript files!
• being unable to define external Javascript files, there is no easy way of sharing Javascript code between portlets, which is not DRY
• Debugging gets even more painful with function names like “show_<insert some lengthy string here>()”

So, if your are up to make heavy use of Javascript and Ajax-based rich user interfaces, this is a no-go.

Using external Javascript files

So, loading Javascript form external file is the way to go. So here is our approach to the problem:

Use Javascript namespaces

We are putting all our stuff into one global variable, called “agimatec” (at the time we chose the name, we were not aware of Douglas Crockford‘s advice on making globals uppercase – otherwise we would haven named it “AGIMATEC”). This ensures that we’re leaving all third party scripts on the page untouched. Each portlet has its own (sub-)namespace inside this global.

Use a convention to locate the script files

We’re putting our javascript files into a java-like folder structure that reflects our namespace structure, so the portlet “Clientis Edit User” is put into the namespace “agimatec.portlet” and the corresponding file can be found under “agimatec/portlet/clientisEditUser.js”

Use a common initialization method for all portlets

All our portlet scripts must define the function “getPortlet()”, which returns a “raw” version of the portlet script.

Let a library create portlet script objects

Last but definitely not least we have written our own library to create portlet instances. The library contains a function that takes the portlet namespace string, along with the name of the portlet Javascript object, creates a new instance by calling “getPortlet()” on the Portlet object and puts the instance into its own namespace which is created using the portlet namespace:

/**
* Create a portlet namespace instance.
* @param {object} portletObject           A raw portlet namespace
* @param {string} portletNamespace    The Portlet ID as given by the portlet container
*/
agimatec.createPortletInstance(portletObject, portletNamespaceId){
    var rawNamespace = portletObject.getPortlet();
    portletObject[portletNamespaceId] = rawNamespace;
}

Using this technique, we are able to write clean, fully namespace-wrapped portlet scripts that have no problems with colliding function names and can co-exist even in multiple instances on one page without problems. As bonus, two instances of the same portlet on one page only load the external Javascript file once.

One major thing is not mentioned of this post: how to load the portlet scripts. We are using the YUI Loader for loading the portlet scripts, amoung other things. I’ll cover this in another post in the next weeks, so stay tuned.