Clickframes is a Code Generation framework written in Java designed specifically to generate (Java) web applications.

Philosophy behind Clickframes

There are 2 aspects to a web application:

1. What the application does.
2. How it does it.

The key idea behind Clickframes is separation of these two concerns.

What the application can be defined by focusing on end user experience – what the end user sees, what the user clicks and so on. When users open a webapp in a browser they see a page, links, forms, inputs, content. They don’t see how the page was produced, which technology, framework or database was used on the back end. Defining what an application does boils does to defining a web page, after all a web application is most part is a collection of web pages linked to each other via links and form actions.

On the other hand, how an application is implemented consists of every little detail that happens “behind the scenes”. Which technology, platform and database is used, all the choices which result in a working application – but are never directly seen by the end user directly.

Clickframes separates these two aspects of the application by defining an application model called Appspec. Appspec is a rich data structure which represents the application behavior. The business analyst defines the application behavior using the Appspec model. The developer writes code generators to implement a generic Appspec and then runs them for the specific Appspec written by the business analyst. Appspec becomes a contract and a way of communication between the analyst and the developer. In the meantime QA takes the Appspec and writes tests against it. Appspec becomes a way of communication and the single source of truth for the various members of the team.

To give you a concrete sense of what I am talking about, let’s say that the Appspec has a page called “home”. The developer may choose to implement this using a simple jsp file “home.jsp”. The developer then generalizes this implementation and creates a code generator to produce a file called [page id].jsp for every page in the Appspec. Again, the philosophy being “if I can figure out how to implement one page, I can apply the same approach for all pages”. This approach implemented via a set of code generators applied against the application definition (or Appspec) is the key idea of the Clickframes approach. The result is an automatically generated application for a given target platform/technology (e.g. “jsp” in the previous example) which produces consistent code for the entire application. This code is produced using code generators at minute zero of your project, i.e. even before you start working on your project. You can then take the generated code and start customizing it. This is a great productivity boost as you can use the same code generators from one project to another as they are not specific to any particular application, but are written for the generic Appspec model for the given target technology/platform. Such code generators usually exists are code generation templates and are referred to as Clickframes Plugin.

Terminology

To recap the terminology:

Appspec (Application Specification) – Appspec is what the web application does, from an end user’s perspective. It essentially captures the behavior of the application. How many pages does the application have, how many forms does each page have. How many input fields on each page. What type of input fields (e.g. text, textarea, radio, dropdown). Are there any validation rules on the input fields (e.g. must be 8-12 characters, or must be a zipcode, must be a valid email format). What is the next page when the user submits a form on a page. How many links on the page, do the links point to another page in the application or an external link. The list goes on, but you get the idea.

Clickframes Plugin – Clickframes Plugin is a code generator, usually implemented by creating a set of templates, which inputs an Appspec and generates code. A plugin is usually a zip file consisting of dozens of templates written in plain text or velocity. Plugins can also be written or extended in Java using the Clickframes Plugin API.

Clickframes Plugin Authors – (Usually) Senior or Experienced developers who have a good understanding of the target technology create a plugin to implement the Appspec. Note that this activity needs to be done only once per technology. For example, once I have created a Seam2 plugin, you can generate any number of applications by simply writing an Appspec for your application and generate Seam code by using the plugin.

Target language/platform – Clickframes is a Code Generation framework that you use before you even start your project. It generates code that you then compile and run. Target platform refers to the platform on which the generate code runs. Example target platforms are Java/Tomcat, Java/Seam/JBoss, JSF/Tomcat, PHP. If you are willing to write your own code generation templates, you can generate code for any language/target platform.

Why Clickframes?

One advantage of Clickframes is that it acts as a medium of communication between the various members of the team.

However, the most powerful feature of Clickframes is the Clickframes Code Generation Plugins. Once you write a plugin for a technology or platform, you can instantly generate a full working application by simply writing the Appspec for that application and running the Clickframes Plugin on this Appspec . Writing an Appspec should be much easier than implementing the application itself.

Hello, World example

Let say an application has one page which has the text “Hello, World”. You can create the Appspec by either using the Java API or XML format.

Creating appspec via XML

<appspec>
  <pages>
    <page id="home">
     <contents>
      <content id="message1">Hello, world</content>
     </contents>
    </page>
  </pages>
</appspec>

Creating appspec via Java

Appspec appspec = new Appspec();
Page home = new Page();
Content message1 = new Content();
message1.setId("message1");
message1.setText("Hello, World");
home.getContents().add(message1);
appspec.getPages().addPage(home);

Clickframes sample JSP Plugin

Now lets build a simple JSP code generator. This code generator is just for the purpose of illustration and is not intended to be a real production quality plugin.

Create a file called ${page.id}.jsp. Since the file name consists of the variable ${page} this file will automatically be applied to all pages in the application.

Contents of ${page.id}.jsp below. All templates are written in Apache Velocity.

The ${page} variable passed to the template represents the Java object defined above.

<html>
 <body>
#foreach ($content in $page.contents)
  <div id="${content.id}">${content.text}</div>
#end
 </body>
</html>

Running this plugin against the above model will produce one file called “home.jsp” with the following content.

<html>
 <body>
  <div id="message1">Hello, World</div>
 </body>
</html>

You can now add a dozen pages to your application and reuse the same code generation template.

A more comprehensive demo

The above example is good to give you a quick sense of how the code generation works. However, real applications contains forms, links, inputs, actions, entities, databases and so on. The following example uses a JSF Seam2 plugin which is used to generate a simple Issue Tracker Application.

The best way to jump in and get your feet wet is by seeing and running the code. I have created a JSF Seam2 plugin which generates JSF2 and Seam based web applications.

Here’s the Appspec for the application and you can browse the generated code here. There is a hosted version of running demo at http://demo.clickframes.org/tracker/

Checkout the project code:

svn checkout http://clickframes-seam-issuetracker-demo.googlecode.com/svn/trunk/ clickframes-seam-issuetracker-demo

Run it:

cd clickframes-seam-issuetracker-demo
mvn glassfish:run

See the application run at http://localhost:8080/issuetracker/
You can type any login/password to login. The login module implemented by default does passes any input. In the future I plan modify the plugin to properly implement login.

Key demo features:

• Security: pages with login-required=”true” will automatically prompt you for login.
• AJAX input validation: inputs with validation will prompt you with an error as you type if the validation fails
• Built-in CRUD implementation using in-memory database: actions marked with “update” or “create” will actually create an entity and store it in an in memory database

Note that this application is 100% generated directly from the Appspec. What is means is that you can modify the application behavior by modifying the Appspec and regenerate the application.

Regenerate:

mvn clickframes:generate

Can you really model every single thing about a web application?

No. Clickframes focuses on things which can be easily modeled. Even if you are able to capture 50% of the application features in the Appspec, you can generate a working application which implements 50% of requirement without writing a single line of code. That’s quite a jump in productivity. You can then hand code the remaining application the usual way.

Case for Clickframes

Clickframes is not for all web applications. If the Clickframes model fits your application model then I urge you to give Clickframes a try. With Clickframes you can produce consistent code for your entire application. You can bake the best practices right into the code generation templates. Moreover, you can use these templates from one project to another.

References and Links

• Clickframes official website: www.clickframes.org
• Follow Clickframes on Twitter: http://twitter.com/clickframes