[[TOC(heading=Quickstart Section Contents, QuickStart*)]]

= 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 event.copyToScope( variables, "xe_translate,phrase" ) />
<cfset submit = event.linkTo( xe_translate ) />

<cfform action="#submit#">
    <cfinput type="text" name="phrase" required="false" value="#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 in the 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 the event variables, you can ask the event object to copy them into the scope of your choice, typically the variables scope, with the copyToScope() function. You can also retrieve individual values (variables) from the event object by using the getValue() function, but unless you only need a single value, using copyToScope() will save you a lot of repetitive typing.

Also note the use of the linkTo() function. This is another convenience method of the event object that will create a link from a supplied event name, so calling event.linkTo( "myevent" ) will produce "index.cfm?event=myevent". If any Model-Glue configuration settings are changed at some point in the future (for example, changing "event" to "e", "index.cfm" to "page.cfm", or enabling SES URLs), the generated links will automatically change to use the new conventions.

Therefore, the first two lines in that frmPhrase.cfm say "make me a link please, using 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.

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 Quickstart 2: Modeling our Application]

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