We've seen how to convert data list and data detail pages from procedural code to Mach-II events. Now we need to refactor how we build form and action pages.

Create a Company

From a data list page, we generally have the options to Add a New Item, View Item Deatils or Edit Item.

Clicking on "Add a Company", we get a new Company form.

Here's the procedural version of this page:

The link to "Add a new Company" passes COMPANY_ID=0 in the querystring, so the query qCompanies returns an emtpy record set, so the form fields are all populated with empty strings.

We've already refactored the layout HTML into Mach-II <page-view>s. All that's left are three major sections of code:

1. The query qCompanies.
2. Javascript to validate the form's contents.
3. The form itself.

Creating the showCompanyForm event

First we need a query that returns a single company record. We already have this code in the CompanyListener, which uses the Company bean and CompanyDAO.

Next we need to move the Company form and Javascript to its own CFM file.

The values of the form fields are now being populated by the contents of the Company bean.

Optionally, we can move the Javascript to an external file.

If we use an external JS file, then we need to reference it in company_form.cfm.

The event-handler for showCompanyForm

Filtering data

The showCompanyForm event will be starting point for Creating, Updating and Deleting Company records.

The form is setup to show different submit actions based on url.COMPANY_ID.

When you have multiple submit buttons in a form, whichever one you click will be the name/value pair that exists on the action page. (This is basic HTML functionality.)

Procedural version

In the procedural version, the form submits to a processing page.

A different query is run based on which submit button was used to submit the form.

Mach-II version

Now we're going to submit the form to an event instead of a page.

What is a Mach-II Event Filter?

Definition

An event filter is an object (component/CFC) that allows you to run some logic, then return true or false based on the results. Any filter that you create extends MachII.framework.EventFilter.

The required function filterEvent takes 3 arguments.

You can optionally create a configure() method to handle anything that needs to run when the Filter is created. This works the same as a Listerner's configure() method.

All Filters are created when the application loads for the first time. They are placed into the application scope, so be aware of your variable scopes.

Usage

When a filter returns true, then Mach-II continues processing the event-handler. In the event-handler processCompanyData, if the filter FilterCompanyAction returns true, then the announce command is run and we proceed to the "home" event.

When a filter returns false, Mach-II stops processing the rest of the current event-handler and goes to the next one. Usually you'll announce the next event before returning false.

In the above code, if the "addCompany" submit button was clicked, then event.getArg("addCompany") will not be an empty string, so the Filter then announces the event processCompanyCreate and copies all of the current event Args to that event. Then it returns false, telling Mach-II to stop processing the current event-handler (processCompanyData).

So far, we have replaced part of the functionlity of the procedural file "company_form_process.cfm". Now we just need to handle the database interactions.

Chaining Events

So we start off at showCompanyForm.

The form in that event submits to the event processCompanyData.

Based on the action (button) we chose in showCompanyForm, the filter FilterCompanyAction then announces the next event.

If we chose to CREATE a Company

The event processCompanyCreate notifies the Listener CompanyListener to call the method createCompany.

The method createCompany creates an instance of the CompanyDAO, then creates and populates an instance of the Company bean with the form data and finally passes the Company bean to the create() method of the DAO.

Once all of this has processed, the event showCompanies is loaded.

If we chose to UPDATE a Company

The event processCompanyUpdate notifies the Listener CompanyListener to call the method updateCompany.

The method updateCompany creates an instance of the CompanyDAO, then creates and populates an instance of the Company bean with the form data and finally passes the Company bean to the update() method of the DAO.

Once all of this has processed, the event showCompanies is loaded.

If we chose to DELETE a Company

The event processCompanyDelete notifies the Listener CompanyListener to call the method deleteCompany.

The method deleteCompany creates an instance of the CompanyDAO, then creates and populates an instance of the Company bean with the COMPANY_ID only and finally passes the Company bean to the delete() method of the DAO.

Once all of this has processed, the event showCompanies is loaded.

Ack! Carpel Tunnel!

Yes, that's a heck of a lot of code for such a small application. If this was a real world app, I'm sure I'd just create it the procedural way. However, the concepts and techniques shown so far are the building blocks used in many high traffic and mission critical applications.

You can see these changes in action by using the version 5 files.

1. Rename the version 4 mach-ii.xml file to mach-ii.04.xml
2. Rename mach-ii.05.xml to mach-ii.xml
3. Reload the application and click the Companies link in the left-hand navigation.

Next chapter

The Mach-II Primer has now caught up with the Object Oriented ColdFusion Primer. I'm working on a post for that primer which will cover a Complex DAO (working with multiple tables or data sources). After that, I'll get into the Service Object and Object Factory. Once those are done, I'll come back to the Mach-II Primer to show how to implement those objects in the sample application.

But before then: We've been converting this application to an MVC framework in an effort to reduce the amount of redundant code. You should have noticed by now that there are a lot of the same objects being created in the Listeners. They're being created every time a function is called. That's redundant code too.

Next time we'll use a Plug-in or a new feature of Mach-II 1.5 to turn some objects into Mach-II Properties.