CodeBehind Event Handlers

Overview

Event Handlers are methods within CodeBehind pages that allow you to perform tasks on page refresh based on user actions.

For example, an Event Handler would be used to handle a form submittal, such as a mailing list signup, parsing out the data and saving it into a database. An Event Handler might also be used to perform a special action when a user clicks a link.

It is important to note that Event Handlers are called before View Handlers. Any actions that your Event Handlers do take place before the next page rendering.

To create trigger an event handler, all you need to do is set the variable "event" to the name of the event handler you wish to call on page refresh. This can either be set in a hidden form field, or in your query string.

Example

A quick example shows this best:



Directory Structure:
================================
EventTest.php
|--bin
   |--templates
      |--EventTest.tmpl.php

EventTest.php (CodeBehind Page)
================================
<?php
class pageEventTest extends page {
    var $layout = "Columns1";
    /* AREA 2 - Center Page */
    function area2(){
        $this->title = "Event Test Example";
        $this->border = 1;
        return $this->fetch("EventTest.tmpl.php");
    }
    /* EVENT - Signs up user to mailing list */
    function eventSignupEmail(){
        //get the email address
        $email = util::getData("email"); //Same as $mail = $_POST["email"]

        //perform some actions here, such as saving the email
        //to the database
    }
}
?>

EventTest.tmpl.php (Template)
================================
Signup for our mailing list!
<form action="<?=$PHP_SELF?>" method="post">
<input type="hidden" name="event" value="SignupEmail">
Email: <input type="text" name="email">
<input type="submit" value="Signup!">
</form>

This would be rendered as:

This example shows a simple mailing list sign up page. Whenever a user visits the page the View Handler for Area2 loads a simple template EventTest.tmpl.php that displays a sign up form.
The sign up form contains a hidden element <input type="hidden" name="event" value="SignupEmail"> that links it to the Event Handler eventSignupEmail(). Whenever the form it submitted, the event handler will automatically be called.

EventHandler Results

Often you'll want your event handlers to return a result of some type. For example, was the the user signed up to the mailling list correctly? Was an error encountered while handling the event?

You have two options for returning results from your events:

Use the built in $this->setEventResult($bool, $text); function
Set a value to a member variable of your class, such as $this->myResult = true;

The built in $this->setEventResult() is a handy method that allows you quickly set whether your event was successful or not, along with a bit of text. These values are automatically stored in the member variables $this->eventResult and $this->eventMessage.

They will also be automatically passed to any template you call under the variable names: $eventResult, $eventMessage, and $eventResultString ($eventResult converted to a string "1" or "0").

Heres the above example, this time with both types of EventHandler results added in.



EventTest.php (CodeBehind Page)
================================
<?php
class pageEventTest extends page {
    var $layout = "Columns1";
    /* AREA 2 - Center Page */
    function area2(){
        $this->title = "Event Test Example";
        $this->border = 1;

        //Member variable event result - pass to template
        $this->set("firstEmailDate",$this->firstEmailDate);

        return $this->fetch("EventTest.tmpl.php");
    }
    /* EVENT - Signs up user to mailing list */
    function eventSignupEmail(){
        //get the email address
        $email = util::getData("email"); //Same as $mail = $_POST["email"]

        //perform some actions here, such as saving the email
        //to the database

        //Set event result:
        //Regular way:
        $this->setEventResult(true, "Welcome to the Mailing List!");
        //Using a member variable to carry data:
        $this->firstEmailDate = "March 5th";
    }
}
?>

EventTest.tmpl.php (Template)
================================
<?php if(isset($eventResult)){ ?>

Welcome to the mailing list! Your first email should arrive on <b><?=$firstEmailDate?></b>.

<?php } else { ?>

Signup for our mailing list!
<form action="<?=$PHP_SELF?>" method="post">
<input type="hidden" name="event" value="SignupEmail">
Email: <input type="text" name="email">
<input type="submit" value="Signup!">
</form>

<?php } ?>

Now when we submit the form, we'll see something like this: