= Quickstart 3: Building a Form Event =

Model-Glue doesn't have "pages." Instead, it has "events." When you read "event" or "event handler," think "page." To access a given event handler (page!) in a Model-Glue application, you add ?event=''eventHandlerName'' to the URL.

Ok, so to create a new event handler (page!), we add it to !ModelGlue.xml. We're going to want to create an event handler that displays a form where the user can enter a phrase to translate.

First, we need to create a .CFM file known as a "view". To do this, follow these steps:

  1. Create a file named "frmPhrase.cfm" in /translator/views.
  1. Paste the following code into the file. We'll explain a few odd parts in just a moment.

{{{
<cfset submit = event.linkTo( event.getValue("xe.translate") ) />

<cfform action="#submit#">
    <cfinput type="text" name="phrase" required="false" value="#event.getValue("phrase")#" />
    <input type="submit" value="Ok" />
</cfform>
}}}

Ok - what's with this "event" stuff?

Whenever you're writing a .CFM view, there are two variables always available: "event" and "viewcollection." We'll get to viewcollection in a bit, but here's the rundown on event:
 Event::
  An event object contains all the variables FORM and URL scopes as well as any other values added by the framework.
The event object contains data like a query from a database or (big surprise) the translated version of the phrase that we're asking the user to enter.

To get to one of the variables, you ask the event object to "get its value" with the getValue() function.

There are a few "default" variables added to event object you need to be aware of:

  * "myself" is the URL of the current page with "?event=" added to it, such as "index.cfm?event="
  * "self" is the URL of the current page without the "?event=" bit, such as "index.cfm"
  * "event" is the name of the current event. Don't worry about this one.
  * "eventValue" is the name of the URL variable that contains the current event. Don't worry about this one much, either.

Therefore, the first line in that frmPhrase.cfm says "make me a link please, and use the value in the event object for 'xe.translate' as the name of the event."

So what's with this "xe.translate" value? "XE" stands for "eXit Event," and has emerged as a best practice in Model-Glue applications (because it's taken from a best practice in Fusebox!). It lets us reuse this view in multiple places because we determine the action page of the form at runtime, instead of hard coding it into our .CFM template.

So where does the value of xe.translate come from? It's time to learn a bit of Model-Glue XML. (Don't worry! I just wrote the entire tag reference, and it's only sixteen tags! And about five of them are just placeholders that contain other tags!)

To create the actual event handler to display the form, do the following:

Open /translator/config/!ModelGlue.xml

In the <event-handlers> block, add a new event handler tag and give it a name attribute of "translationForm". You should have this:

{{{
<event-handlers>
    <event-handler name="translationForm">
    </event-handler>

    <!-- Some other event handlers.... -->
</event-handlers>
}}}

Now, we need to add a "views" block to the event handler. This declares what .CFM templates should be included as part of this event handler. Adding the views block and an <include> tag (see, it's almost just like <cfinclude>!) to the prior XML, we have this:

{{{
<event-handlers>
    <event-handler name="translationForm">
        <views>
            <include name="body" template="frmPhrase.cfm" />
        </views>
    </event-handler>

    <!-- Some other event handlers.... -->
</event-handlers>
}}}

Now, we need to provide the value for "xe.translate." We do this with the (very aptly named!) <value> tag:

{{{
<event-handlers>
    <event-handler name="translationForm">
        <views>
            <include name="body" template="frmPhrase.cfm">
                <value name="xe.translate" value="translationFormAction" />
            </include>
        </views>
    </event-handler>

    <!-- Some other event handlers.... -->
</event-handlers>
}}}

Finally, run the page by visiting http://localhost/translator/index.cfm?event=translationForm . You should see your form. Viewing its source, you'll see that its action page is index.cfm?event=translationFormAction.

You've just learned about a quarter of the Model-Glue framework. Not too bad, eh?
----

Back [wiki:QuickStart/2:ModellingourApplication#Quickstart2:ModelingourApplication Quickstart 2: Modeling our Application]

Next [wiki:QuickStart/4:HandlingaForm#Quickstart4:HandlingaForm Quickstart 4: Handling a Form]