Events in Symphony are a powerful tool. Bound to pages, they give you an even greater level of control over how your site behaves. Be it a silent statistic tracker or a custom welcome message, Events add infinite depth to what you can create. They can be found in your Symphony Events folder under “/workspace” along with the data-source and text-formatter folders.

This article will step you through the process of creating your own Event, which can be included on your front-end pages.

When you create your Pages, Masters or Utilities in Blueprint, you have the option of adding events. Each Event is a small PHP class that has a condition attached. Conditions can be as simple as a page load. If the condition is met, the Event is triggered and XML is produced. This XML is available to your XSL. All event XML is wrapped in an event element.

Before we can begin, it is important to discuss the API for events. Its a very simple structure consisting of some trigger conditions and actions. The event parent class structure looks like this:

	Class Event Extends Object
		var $_parent
		var $_env
		var $_db
		__construct($args)
		about()
		load()
		trigger()

A new event must extend this class. i.e. Class eventMyEvent Extends Event

I’ll quickly explain what each function does.

* _parent, _env & _db → These are private variables that your extended class can access. _db is the most important. It is a connection to the database. _env contains environment variables such as current URL and post data. _parent is the Site container which does all the page processing.

* __construct($args) → This must be overloaded in the child class. It initialises the engine references. i.e. database wrapper. The child must also explicitly call this parent constructor after it has finished initializing its own members.

* about() → Also must be overloaded by the child class. This function returns an array containing information about the event. It is called in the Administration area. The format of this will be explained later

* load() → Again, requires to be overloaded by the child. This is the public function that gets called if the event is associated with a page. The child class implements the trigger condition in this function

* trigger() → Overloaded. Called explicitly by the load() function if the trigger condition evaluates.

Now its time to create our own custom event. In this tutorial we will create create a Random number generator.

Since this is a PHP file, you will need to wrap then entire file contents in a PHP script tag. In your file place

    <?php 
    
    ?>

Some of you are most likey thinking that is trivial point, but its actually quite important. There must be no whitespace before or after the <?php ?> tags. If you do, any page with this Event will fail to load. Similarly, within your class you must not have any print() or echo statements unless you are buffering the output.

Events in Symphony are called dynamicly when the page loads. There is no hardcoded information. Because of this there is a strict naming scheme to ensure that the Event classes can be called reliabily.

Your class declaration needs to have event before the actual name. E.G. eventLogin. It also needs to extend the Event class we saw eariler. So, in this instance we will have the following for our class declaration:

Class eventRandomNumber Extends Event

Once you have done this I suggest you save your file to get the naming correct. In this instance it will be event.randomnumber.php Notice the event prefix. This makes it easy to identify which files are Events.

Based on the API discussed earlier, this is what your class skeleton will look like

	Class eventRandomNumber Extends Event{
		var $_randomNumber;

		function __construct($args=array()){
 		}

		function about(){
 		}

 		function load(){
 		}

 		function trigger(){
 		}
	}

You will notice we have created a private variable called __randomNumber. It is not completely necessary, but it will help later on.

The constructor is where we initalize variables and do other once off things. It is also necessary to explicitly call the parent constructor. The order that this is done is important and it is advised to call parent constructor first. This is what our constructor will look like

	function __construct($args=array()){
		parent::__construct($args);
		$this->_randomNumber = 0;
	}

Any parameters passed in are sent on to the parent constructor. This is done automatically since Events are all called dynamically on page load.

The about function needs to return an associative array of details about the event. It must contain the following fields:

• name: The name of the Event as it will appear in the page configure multi-select box.
• author: An array containing ‘name’, ‘website’ and ‘email’
• version: Number denoting the version of this release. Must be in the format of Major.Minor E.G. 1.5
• description: Details about the Event. This is currently unused, but will eventually.
• release-date: Must be correctly formatted GMT date. Year-Month-Day Hour:Min:Sec E.G. 2006-01-23 14:02:33
• trigger-condition: Information about what triggers this event. NULL if there isn’t one.
• recognised-fields: An array of field names that this event makes use of. NULL if there aren’t any.

Given that guideline, our About function will look like this:

	return array(
		"name" => "Random Number Generator",
		"description" => "Places a random number in the events XML on page load.",
		"version" => "1.0",
		"author" => array("name" => "Alistair Kearney",
					"website" => "http://www.pointybeard.com",
					"email" => "alistair@pointybeard.com"),
		"trigger-condition" => 'Page Load',
		"recognised-fields" => NULL,
		"release-date" => "2006-01-23 13:05:00"
	);

This is where we will place the trigger condition. In this instance the trigger condition is simply page load, so we wont need anything fancy here. Because of this, all we need is as follows:

	return $this->trigger();

The trigger function does the processing and returns an XMLElement object. This is then used by the Site object in the page XML generation.

Here is where the work is done, should the trigger condition tested in our load() function be met. To begin with we will generate our random number, and assign it to our private variable, using PHP‘s rand() function.

	$this->_randomNumber = rand(1, 100);

Once this is done we need to set up our response XML. Each XML document is built from a set of nodes. Symphony has a class called XMLElement which is used to build up each document. Our resultant XML should look like this:

	<randomnumber>43</randomnumber>

There is a single node with a value. Creating the XML for this is very easy, and can be done with a single line.

	$result = new XMLElement("randomnumber", $this->_randomNumber);

The first parameter in the constructor is the name of the node. The second is the node’s value. A more indepth look at the XMLElement class will be covered in another article.

The final code for our trigger()function ends up looking like this:

	$this->_randomNumber = rand(1, 100);
	$result = new XMLElement("randomnumber", $this->_randomNumber);
	return $result;

The entire Event now looks like this:

	<?php

	Class eventRandomNumber Extends Event{
 		var $_randomNumber;

 		function __construct($args=array()){
    			parent::__construct($args);
    			$this->_randomNumber = 0;
 		}

 		function about(){
    		return array(
    			"name" => "Random Number Generator",
    			"description" => "Places a random number in the events XML on page load.",
    			"version" => "1.0",
    			"author" => array("name" => "Alistair Kearney",
						"website" => "http://www.pointybeard.com",
						"email" => "alistair@pointybeard.com"),
    			"trigger-condition" => "Page Load",
    			"recognised-fields" => NULL,
    			"release-date" => "2006-01-23"
    		);
 		}

 		function load(){
    			return $this->trigger();
 		}

 		function trigger(){
   			$this->_randomNumber = rand(1, 100);
   			$result = new XMLElement("randomnumber", $this->_randomNumber);
   			return $result;
 		}
	}

	?>

To begin with we will check the syntax of the Event. If the syntax is incorrect, than any Blueprint page with events on them will fail to display.

To test the file, place it into your /workspace/events/ folder . Then browse to the file. E.G. http://yoursite.com/workspace/events/event.randomnumber.php If there are problems with the file you will see error messages, and you will need to correct these errors on the line they are associated with. *Note:* The following error is OK, and means you have no Syntax errors:

    Fatal error: Class 'Event' not found in /workspace/events/event.randomnumber.php on line 3

Once you get an error message similar to the one above, meaning there are no syntax errors, you can proceed to your Blueprint page and add the file to your Index page for testing. Save the page and browse to your front-end. If you check your source you should see a commented out section detailing what is in your Events XML. It should look something like this:

	<events>
  		<randomnumber>23</randomnumber>
	</events>

If you’re feeling game, try creating a page that dynamically gives this Event a range for the rand() function. You will need to use the page url schema option and dig into the $this→_env[’url’] array.

Well, that concludes the tutorial. Hopefully you now have a better understanding of how Events in Symphony work.