Writing Your Own Simple MVC Framework in ColdFusion

There are a few ColdFusion frameworks around but unfortunately it may not always be possible to use them – such as in a shared hosting environment. See my previous post about ColdFusion mappings which discusses why.

The following notes describe how a simple event driven framework might be written. This is intended to be a bare bones framework to hopefully keep everything as simple as possible.

Credit

I did have a brief look at the Model-Glue before writing this up, so any good ideas that you see here can be credited to Joe Reinhart and Model-Glue. All of the bad ideas are completely mine.

What is a Model View Controller?

Perhaps the first place to start is to understand what is a Model View Controller?

The Model represents the group of your ColdFusion components that manage the current state of your application, the business logic, and the data storage (i.e. 'data persistence').

The View represents the group of components and .cfm files that handle the display of all information in the browser. The View displays the page layouts and sets up the colours and fonts etc. as well as displaying the hyperlinks, buttons and forms to capture input from the users of your application.

The Controller ties together the Model and the View. Specifically, a click of a link or button in the browser window (i.e. the View) causes a message to be sent to the Controller (via an HTTP request). The Controller then interacts with the Model to do some processing then sends a message back to the view indicating what to display next.

Components of our simple framework

There are not many components that make up this simple framework. The key components that we will be discussing are:

Event - the event coming from the browser, which is an instruction of what to do next.

Controller – the component that knows how to handle the event.

EventResult – a component that contains the outcome of the event.

ViewState – a component that contains data that may be displayed within the browser (i.e. within a View).

Events

We will use the term 'event' to represent an HTTP request. Specifically an event occurs when a hyperlink or a form button is clicked.

So what does an event look like? Well, an event is something that has a name and associated data. I will call this data the 'event attributes'.

For example, suppose you have a form that simply collects a person's first name and last name. When submitted it displays the words "Hello" followed by the persons name. The form may look something like this:

Notice the hidden field in the form named "event". If this form was submitted with the first name "Davy" and last name "Jones", it will create an event with the name "SayHello" and the attributes firstName="Davy" and lastName="Jones".

Our event component may look something like the following.

So how does our SayHello form data get converted into an event? Well the 'event' parameter is set as the event name, and all of the form fields are set as the event attributes. This can be done quite easily in the init() method on the Event component. Here is a code snippet (I have left out validation and some other bits to keep it simple for now):

This could be extended to support URL data as well by simply adding a second argument holding the URL variables, and add them in the same way to the set of event attributes.

Lastly, how do we use our event component? This event needs to be created at the top of your index.cfm file ready for use by the rest of the application. You would likely create a default event in case the event parameter was not passed in from the form.

The Controller

Once we have our event ready, we need to pass it to the controller; it is the controller's responsibility to handle all events that occur within the system. In a large system the controller may be broken into multiple smaller controllers each handling a different part of the system.

So our Controller is going to process our event and then return to us an EventResult object to let us know what happened.

So what sort of results can we expect after processing an event? In this example, we will assume the only result is to display some output.

So back to our controller:

The controller will have a handleEvent() function that takes the event we created above as a parameter. This handle event function will then pass the event onto another function that has the same name as the event itself.

So in our example above that has an event called SayHello, we will need a function in the controller also called sayHello() to handle that particular event.

Determining if a function exists in a component

I think a quick note might be useful here to discuss about a very nice feature in ColdFusion that allows you to discover if a particular function exists in a component.

Suppose you have defined a function as follows:

You can check for the existence of this function as follows:

Or, using a variable

Calling ColdFusion functions

Usually when calling a function, you would use syntax such as

However, ColdFusion supports an alternate syntax using the tag. This alternate syntax lets you call a function based on a variable value:

Back to the Controller

So now we can look at how the handleEvent() function will work. First it checks if a function exists that has the same name as the event, and if so it executes that function then returns the resulting EventResult.

The EventResult

What does an event result look like? As mentioned above, to keep things simple our event will simply provide some output that needs to be displayed in the browser.

How does the Event Result get created?

The event result is created back in our Controller in the function called by handleEvent(). In our example this is the sayHello() function:

So within the controller, the handleEvent() function calls the SayHello() function, which returns an eventResult all the way back to the original .cfm page.

How is the output displayed in the browser?

Back in out index.cfm file we can now complete the code to display the generated output:

View Templates and View State

You will need to display more than just simple text in the browser. Following is a technique that you can use to display views based on a template page.

A View is made up of two things (1) a normal ColdFusion .cfm template that contains the page layout and display related code, and (2) a View State which is simply data that can be displayed.

The template simply gets data out of the view state and displays it however it chooses. The view state does not contain any HTML, it only contains the raw data to be displayed, such as text to display or a structure of data appropriate for the page (such as a set of Products that needs to be listed).

The view state is a set of name and value pairs. The value can be anything such as a string value or some kind of structured data such as a query result. The component may look something like:

In our SayHello example, the view state will contains the two bits of data submitted in the form; FirstName with the value "Davy" and LastName with the value "Jones"

What does a template look like? Well, heres a template 'sayhello.cfm' that could be used for our SayHello event:

Displaying the View Templates

So how do we get our template and view state data to appear within the browser?

First we need to define a location for to store our view templates. For this example we will place them in a /views directory in the root of our website.

We now change our sayHello() function to take into account the view template:

Notice that we make use of the tag to process the template page and save the results in a variable which gets stored in the event result object.

At the moment this template processing is taking place in the Controller. Not sure if that is the best place for it but it seems to work.

Where's the Model?

The Model is the place where all of your business logic and database access is placed. A framework really shouldn't know anything about your Model, that way the framework can be reused across any application you put together.

Wrapping Up

This entry is my current thoughts on creating a simple custom framework. I have left out quite a bit of code and have kept it as simple as possible to hopefully keep the focus on the main idea.

A couple of extra thoughts:

* I didn’t use any .cfcs to display output – they simply build up a string of text which is ultimately passed to a .cfm for display. To display output the .cfc functions need to have the output="true" set all the way down to the point of the display. This just doesn’t seem a very tidy approach.

* Here we create a new controller on each page request, when really only one instance is really needed, so perhaps the controller should be kept in an application variable.

* I have omitted virtually all code related to error handling and inheritance to try keep the code simple.