Mach-II Primer : 1 : Files vs. Events

When you see a filename in a URL, you can go to that specific file on the server to see how the content displayed on the screen is put together. In Mach-II, the only filename you'll see is "index.cfm". In order to see how the content for a given URL is put together, you'll have to look into an event.

Files vs. Events

Open the procedural version of the Contact Manager in your browser.

http://localhost/mach-ii-primer/classic/

You should see a left-hand navigation menu with links to Home, Contacts, Companies and Categories. In order to view the contents of the home page, open up the index.cfm file.

i.e. C:\Inetpub\wwwroot\mach-ii-primer\classic\index.cfm

This file contains HTML and some <cfinclude>s.

Now open up the Mach-II version of the Contact Manager in your browser.

http://localhost/mach-ii-primer/m2/

If you open up the index.cfm file located in the m2 folder, you'll find either code that affects your Mach-II configuration (when using Application.cfm and index.cfm)

or a single comment (when using Application.cfc and index.cfm, MACHII_CONFIG_PATH, etc. has been moved into Application.cfc)

In Mach-II, the file "index.cfm" is only used as a placeholder.

So how do you find out how the home page, or any "page" is put together in Mach-II? Don't look for a file, look for an event.

MVC: The Controller

The files and processes that make up an event are defined in the Controller file:

/mach-ii-primer/m2/config/mach-ii.xml

The minimal sections needed in a mach-ii.xml file are properties, page-views and event-handlers.

Properties become application scoped variables (application.{applicationRoot}.{propertyName}) and can be defined in the XML file or through the Property Manager. The Property Manager will be covered in a later step.

There are six default properties that should be defined in a Mach-II application.

One of the six main properties is "defaultEvent", currently set to "home". When no event is specified, Mach-II automatically loads the event-handler named "home". Therefore these URLs are all the same:

1. http://localhost/mach-ii-primer/m2/
2. http://localhost/mach-ii-primer/m2/index.cfm
3. http://localhost/mach-ii-primer/m2/index.cfm?event=home

In order for defaultEvent to work, you must have defined an event-handler named "home".

The event-handler defines an event. An event is an object that contains default arguments and functions as defined by Mach-II, plus arguments and data as defined in the XML.

MVC: The View

A page-view defines a reference to a piece of the presentation layer (i.e. a CFM/HTM/TXT file). This section will compile a list of all the User Interface files used in the application. The files don't have to be in the same folder as the current application and this functionality removes the need for the <cfinclude> tag.

In fact, forget about <cfinclude>. It doesn't even exist. cfinc-what? I don't know what you're talking about.

An event-handler uses the XML tag view-page to reference a defined page-view by name.

So how is the homepage put together in Mach-II?

Imagine paper files stacked one on another. In event-handlers, page-views (files) are stacked on one another in the order they are defined to create the final displayed content.

Now let's take a look at how an event-definition might be written using procedural code (pseudo code, not guaranteed to work).

The procedural version of the "exceptionEvent" definition can be thought of like this:

The "home" event could look something like this:

The Event object abstracts or masks lengthy code like this. In a few relatively simple lines of XML, we are able to define

1. The order in which functions are processed
2. When and how variables are created
3. Which (if any) presentation files are displayed and in what order.

We haven't yet talked about processing business logic and data in an event. That's just a couple of steps away. Let's get a bit more comfortable with displaying basic content with events first.

Next Step

Next up: creating and using event arguments (variables) throughout an event.