I’ll probably tackle the migration with my next new PHP project — check back here for updates.

Clickframes-PHP makes it easy to integrate dynamic content into your e-mails, which keeps code customization to a minimum. I think it’s easiest to lead by example, so here’s a genuine appspec snippet:

<email id="passwordReset">
	<title>Password Reset Message</title>
	<description>
		Sent to user when he requests a password reset.
	</description>
	<emailSubject>CookItLater Password Reset Request</emailSubject>
	<emailText>
<![CDATA[
Hi!

You're only moments away from getting back into to your recipe collection.

To reset your password, click this URL, or paste into your browser:

http://cookitlater.com/passwordReset/#{user.passwordResetCode}

The unique code in the URL will expire in 24 hours to prevent unauthorized access.

We've sent this e-mail to #{user.email} - if this request was sent in error, please accept our apologies for the inconvenience.

Thanks!
CookItLater
]]>
	</emailText>
	<outputs>
		<output id="user" entity="user">
			<title>User</title>
			<description>
				User who requested password reset.
			</description>
		</output>
	</outputs>
</email>

When define an output within your e-mail, its properties become available to your e-mail text using Apache Velocity syntax, e.g. #{outputId.propertyId}

You can also define other substitution variables as you please, e.g. #{myAwesomeVariable}.

Clickframes-PHP generates a library class, [appspecName]Email.class.php, that manages all your e-mails. The class contains a send method for each e-mail; a method entitled sendPasswordReset() would be generated for the example above. The generated method accepts a “from” address, a “to” address, your substitution variables, and any outputs as parameters. Review the generated code for precise details.

The generated outcome code will automatically create your e-mail and send it. If you’re using Windows, I highly recommend smtp4dev to test e-mail locally.

If you’ve thought ahead a bit, you generally won’t need to customize the generated e-mail code. Please leave comments or contact the mailing list if you have questions or suggestions for improvement.

Create your project

See Starting a new Clickframes-PHP project for how to create a basic Clickframes-PHP project, then continue below.

Install Apache, PHP, and a database

If you’re here, you probably know how to do this already. For ease, I like to use Wampserver on Windows. If you’re going to use an SQLite database, no installation is necessary.

Enable required PHP libraries

To use SQLite 3 with your Clickframes-PHP project, make sure the required extensions for PDO and SQLite are installed and enabled in php.ini

Point Apache to your project’s webapp directory

There are a few approaches to this, but here’s the quick and dirty way to get Apache to serve files directly from your development directory.

Open up Apache’s httpd.conf and set your document root to the src\main\php\webapp directory of your project.

#
# DocumentRoot: The directory out of which you will serve your
# documents. By default, all requests are taken from this directory, but
# symbolic links and aliases may be used to point to other locations.
#
DocumentRoot "d:/workspace/php-quickstart/src/main/php/webapp"

Further along in httpd.conf, configure the settings for your DocumentRoot defined above. Your preferences may be different from below; these rules are pretty secure.

<Directory "d:/workspace/php-quickstart/src/main/php/webapp">
    Options Indexes FollowSymLinks
    AllowOverride all
    Order Deny,Allow
    Deny from all
    Allow from 127.0.0.1
</Directory>

Create your database tables

After you’ve run mvn clickframes:gen, the entities in your appspec will be translated into database schemas. Look in \src\main\sql for the SQL scripts that match your database (MySQL or SQLite 3).

If you’re using SQLite, it helps to have a graphical management tool; I’ve been using the free, open-source Sqliteman.

Copy CodeIgniter system files

Download CodeIgniter 1.7.2 and copy the system directory somewhere convenient. I keep mine in d:\CodeIgniter_1.7.2\system.

To use SQLite 3, you must install a newer database driver. Download codeigniter_pdo_sqlite.zip and unzip into the system/database/drivers directory.

Customize index.php

CodeIgniter’s main index.php file lives in your project at src/main/php/webapp/. Change the $system_folder variable to point to the location of your system folder as copied above.

Customize project config files

Your application’s configuration files are found in src/main/php/webapp/application/config. To get started, you only need to change these:

• config.php
  Customize $config['base_url']
• database.php
  If you aren’t using SQLite, customize settings for your database.
• email.php
  Customize $config['smtp_host'] to use an SMTP server somewhere other than localhost.

Go!

Open a browser and visit http://localhost/. If all went well, you’ll be looking at the default page you defined in your appspec.

Try customizing your appspec and regenerating with mvn clickframes:gen — your changes will be immediately visible in your browser.

Most of the defaults are fine, but there are few key elements some folks may want to update.

Starting at the fifth line of pom.xml, you’ll see:

<groupId>php-quickstart</groupId>
<artifactId>php-quickstart</artifactId>
<packaging>pom</packaging>
<name>PHP Quickstart</name>
<version>1.0-SNAPSHOT</version>

The groupId is an identifier that’s typically unique within your organization, and usually follows a Java package structure. All official Clickframes components use the groupId org.clickframes. If your company has its website at mycompany.com, your groupId could be com.mycompany.

The artifactId is the unique identifier for your project, within the context of the above groupId. It has no spaces, and words are usually separated by hyphens. An issue tracker application might have an artifactId of issue-tracker.

The packaging element specifies what Maven should generate when you build your project. For our purposes, pom is just right.

The name element is a descriptive, properly spaced and capitalized name for your project, e.g. Crazy Al's Discount Issue Tracker.

Finally, the version element indicates the current version of your project. Maven traditionally uses the SNAPSHOT designation to indicate versions that are under development. For example, you might start your project as 1.0-SNAPSHOT When you’re ready to release, you’d change it to 1.0 and check it in to your source control with a special “version 1.0″ tag. Then, you’d change the version to 1.1-SNAPSHOT to work on the next minor release, or to 2.0-SNAPSHOT if for a more major release. Maven can automate this process for you using the release plugin.

Java 1.6 is required for using Clickframes. Check the version of Java installed on your computer:

java -version

If you don’t have Java installed, you can get Java 1.6 from http://www.java.com/en/download.

Clickframes uses Maven to build projects. If you don’t have Maven installed, you can download it from http://maven.apache.org/download.html and follow the installation instructions toward the bottom of that page—it’s usually as simple as unzipping the download into a directory and adding Maven’s bin directory to your PATH environment variable.

After installing Maven, you should be able to run the following command:

$ mvn -version
Maven version: 2.0.9
Java version: 1.6.0_10
OS name: "linux" version: "2.6.23.15-137.fc8" arch: "i386" Family: "unix"


Download Quickstart Package

The PHP Quickstart download contains a fully operational Maven project, ready to customize and run. The provided appspec describe an “Issue Tracker” application. This demo app is a good way to kick the tires, and a good template for creating your own appspecs.

1. Download the latest Quickstart ZIP package from the Google Code downloads page.
2. Unzip it somewhere. By default, the contents appear in a subdirectory called php-quickstart.
3. Open your command line, go to the php-quickstart directory, and run mvn clickframes:gen

Next steps

• Get your newly generated app set up and running in Apache: see Configuring your Clickframes-PHP application.
• To understand the file structure of your generated Clickframes-PHP project, read Clickframes-PHP Project Structure
• Customize your Maven project settings: see Configuring Clickframes-PHP Maven settings.
• To learn about packaging your Clickframes-PHP project for deployment, read Deploying your Clickframes-PHP project.
• For help with your appspec and Clickframes XML, see the Core documentation.

Thank you, Clickframes!

I quickly found this PDO SQLite3 driver on the CodeIgniter wiki, and then found these fixes in the forum.

I’ve combined the two, cleaned up the code a little, improved the log messages, and posted it on the Clickframes-PHP Google Code site.

Here’s how to set up CodeIgniter to use SQLite3 with Clickframes-PHP, assuming your core CodeIgniter files are installed at BASEPATH (your “system” folder), and your application is installed at APPPATH.

1. Download the driver ZIP and expand it into BASEPATH/database/drivers. This will create a subdirectory called pdo_sqlite.
2. Make sure PHP has SQLite3 PDO support enabled. Open php.ini and uncomment the line with extension=php_pdo_sqlite.dll and restart your web server.
3. The database configuration file generated by Clickframes-PHP at APPPATH/config/database.php enables the pdo_sqlite database driver by default, and expects your database file to live at APPPATH/db/database.sqlite. Change the file path if you prefer your database file elsewhere.

Use the database creation script generated by Clickframes-PHP in src/main/sql/sqlite to create/recreate your database. Sqliteman is a decent (and free) database management GUI tool for running the scripts.

The major accomplishment has been upgrading the plugin’s auto-generated model to fully support entities, just like our Java plugins. An app built with Clickframes-PHP will now perform CRUD out of the box, with real databases (MySQL or SQLite). It will also generate “create” and “drop” scripts for both database platforms, and a foreign-key creation script for MySQL.

With that hurdle overcome, the plugin is quite useful, but considerable work remains. Here are the known tasks:

• output
  Needs file display support
• outputList
  Needs action support
  Needs file display support
• form/input
  Needs basic multiple-property support
  Needs client side validation
  Needs full test of all input types
  Needs action type=”update” support
  Needs file upload support
• content
  Needs to be migrated to language file with non-verbatim support
• entity
  Needs default update support in model
• email
  Not yet refactored
• fact
  Need to display in comments throughout code
• authentication
  Not yet refactored.

If you’d like to follow in detail, check out the updates section on our Google Code project.

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