Before a frame call an event method, it will always call the setup method. You can use it to check if an user is authorized to access this event, or to initialize objects used in all the events of the frame.

If an user do not have authorized access to a frame or an event, you can throw an UnauthorizedAccessException. The frame will catch it and call the method unauthorizedAccess where you can handle the problem, redirect the user or create and send a new event. Note that you are not required to define this method. By default it will stop execution and output an error message.

Both setup, the event methods and the unauthorizedAccess method receive an $aEvent parameter containing all the event information. It is recommended to access the GET and POST data from the event array instead of using $_GET, $_POST or $_REQUEST, as you can later need to send events to other frames from your code and specify GET or POST data.

Following is an example of access control. Assuming the session variable is_admin identifies an administrator, the code will prevent non-administrators to access events on this frame, and will redirect them to the login page:

<?php

class myFrame extends weeFrame {
	protected function defaultEvent($aEvent)
	{
		// Event stuff here
	}

	protected function setup($aEvent)
	{
		weeApp()->session['is_admin'] or burn('UnauthorizedAccessException',
			_T('You are not permitted to access this page.'));
	}

	protected function unauthorizedAccess($aEvent)
	{
		header('Location: http://example.org/login');
		exit;
	}
}

The event methods usually handle three tasks: they perform an action depending on the event received (example: create an user account); they retrieve data from your persistent storage solution; and they send this data to the templates for output. The frame is responsible for the creation of the template and its subsequent output; note however that the template will be created automatically without you needing to write any code. To send data to the template, you must use the method set. For example, the following code will create a variable $nickname in the template, containing the string 'essen':

<?php

class myFrame extends weeFrame {
	protected function defaultEvent($aEvent)
	{
		$this->set('nickname', 'essen');

		// You can also do this:
		$this->set(array(
			'title' => 'My Frame',
			'description' => 'This is an example frame.',
		));
	}
}

By default, the template file used corresponds to the name of the class for the frame. For example, the myFrame template will use the file app/tpl/myFrame.tpl by default. You can customize this behavior by defining the $sBaseTemplate property. For example, the following frame will use the template file app/tpl/example.tpl.

<?php

class myFrame extends weeFrame {
	protected $sBaseTemplate = 'example';

	protected function defaultEvent($aEvent)
	{
		// Event stuff here
	}
}

Another property can be used to change the template file. The $sBaseTemplatePrefix property will append a prefix to the $sBaseTemplate property. This allows you to define a folder under which all templates are to be found for all events of this frame and/or for all childrens. This is especially useful when you define a base class for a type of frames (for example, administration panel frames) and decide to put all the templates for these frames under an admin folder. To do this you simply have to define the prefix in the base class once and then inherit it, like this:

<?php

class myBaseFrame extends weeFrame {
	protected $sBaseTemplatePrefix = 'admin/';
}

class myAdminIndexFrame extends myBaseFrame {
	protected $sBaseTemplate = 'index'; // will use the app/tpl/admin/index.tpl file
}

class myAdminUsersFrame extends myBaseFrame {
	protected $sBaseTemplate = 'users'; // will use the app/tpl/admin/users.tpl file
}

You can trigger other events easily, whether they're in the same frame or a different one. While you can use this to forward the event to the correct method, you shouldn't use it instead of a Location HTTP header.

There is two different ways to trigger an event in the same frame as the current event. You can either call it directly, or using the sendEvent method. Calling it directly will bypass the authorization check and the call to setup. When calling it using sendEvent, if the authorization fails an IllegalStateException is thrown. You can see the two different ways to trigger an event from the same frame in this example:

<?php

class myFrame extends weeFrame {
	protected function defaultEvent($aEvent)
	{
		// Send the event to this frame's test event
		$this->sendEvent(array('name' => 'test') + $aEvent);

		// Same, but bypassing the authorization test
		// Changing 'name' in $aEvent is not mandatory in this case
		$this->eventTest($aEvent);
	}

	protected function eventTest($aEvent)
	{
		// Event stuff here
	}
}

You can trigger an event from another frame using sendEvent. The new frame will replace the current frame in the application, unless the event is given a noframeschange parameter. Here is an example of its usage:

<?php

class frameA extends weeFrame {
	protected function defaultEvent($aEvent)
	{
		// Send the event to frameB
		$this->sendEvent(array('frame' => 'frameB', 'noframeschange' => 1) + $aEvent);
	}
}

class frameB extends weeFrame {
	protected function defaultEvent($aEvent)
	{
		// Event stuff here
	}
}