Creating WED page

An event is defined by creating object of type Web_Event_Simple or Web_Event_Simple_Int. A simple event represents one GET / POST / PI parameter. For example: following URL has one GET parameter (number) and will trigger simple event: http://somedomain123.com/index.php?number=21.

class Web_Event_Simple {
__constructor ( string $name, unsigned integer $type, string $capture )
}

Note: Most of the time values of parameter name and parameter capture are the same. That is not a mandatory requirement. It is made just for developer's convenience.

Web_Event_Simple_Int is created the same way. The difference between Web_Event_Simple and Web_Event_Simple_Int is that Web_Event_Simple_Int accepts only integer values (and throws exception if non-integer value is detected). Web_Event_Simple_Int is convenient way to protect yourself from SQL injection and other URL manipulation attacks.

In order event to be "operational" you have to add it to WED. Each WED page has its own WED in its $this->wed property (which is created transparently for you when page constructor is executed). Adding an event is done by calling WED's method add_wed_event_action_pair.

When WED detects trigger condition of given event it calls target method which have to be defined in the page class. Such methods have to be with "protected" access type and to accept one parameter.

Let's create WED page called my_wed_page that accepts single GET parameter "number" (using POST and PI parameters is basically the same).

You will have to create following files:

Open your new page in your browser and try it. If your don't pass GET parameter it will behave like "simple page" and the output will be No incomming parameter!. If you pass GET parameter for example tft.myhost/my_wed_page.php?number=42 output will be Incomming GET parameter number = 42

Note: Plase note that these "strange" tags in the TPL file that are enclosed in figure brackets are not feature of the Tangra framework itself. They are feature of » Smarty template engine. You will have to reat its documentation in order to learn how to use them.

In many cases given page is ment to work properly only if some parameter is passed. For example if you have page show_user_details.php and you defined in init() that you are expecting user_id parameter it is not good idea to leave default_event() with default code because this page cannot properly work without user_id. In such cases it is recommended to declare explicitly that there is no default behaviour like this:

That way you not only may help yourself during the development (i.e. exception will be thrown if something is messed up and page does not receive expected set of parameters) but also you are making your site more secure because you are making it immune to hacker attepts of messing manualy with GET parameters.

Creating WED page with multiple parameters is vary similar to creating WED page with one parameter. For definining multiple parameters Web_Event_Composite class is used. Composite events are just aggregators of simple events.

Lets create a WED page that accepts GET parameters "number" and "user", i.e. handles request like: http://somedomain123.com/my_wedm_page.php?number=21&user=4.

You will have to create following files:

Point your browser to your new page using tft.myhost/my_wedm_page.php?number=21&user=4. You should see:

Number: 21
User: 4
                    
                

Sometimes web pages accept different set of parameters. For example: we may have page that need to handle both single parameter like number=21 and two parameters like number=21&user=4. To handle such case we have to use something like this: public function init() {
        parent::init();

        $v = new Site_Web_Page_View($this);
        $this->add_view($v);

        // defining simple events
        $number_event = new Web_Event_Simple_Int('number', Tangra_Parameter_Method::GET, 'number'); 
        $user_event = new Web_Event_Simple_Int('user', Tangra_Parameter_Method::GET, 'user');
        
        // adding number_event to WED
        $this->wed->add_wed_event_action_pair($number_event, 'number_event');

        $comp_event = new Web_Event_Composite('my_composite'); //defining composite event
        
        // adding simple events to composite
        $comp_event->add_web_event_simple($number_event); 
        $comp_event->add_web_event_simple($user_event);

        // adding composite event to WED
        $this->wed->add_wed_event_action_pair($comp_event, 'my_composite_event');
    }

Here we see overlaping condition (GET parameter "number") and question arises: which event handling method will be called if we have request like: http://somedomain123.com/my_wedm_page.php?number=21&user=4? Conditions for both events are satisfied and it seems that result is undefined. To resolve such situation we can use third parameter of WED's add_wed_event_action_pair $order:

public function init() {
        parent::init();

        $v = new Site_Web_Page_View($this);
        $this->add_view($v);

        // defining simple events
        $number_event = new Web_Event_Simple_Int('number', Tangra_Parameter_Method::GET, 'number'); 
        $user_event = new Web_Event_Simple_Int('user', Tangra_Parameter_Method::GET, 'user');
        
        // adding number_event to WED with order value
        $this->wed->add_wed_event_action_pair($number_event, 'number_event', 20);

        $comp_event = new Web_Event_Composite('my_composite'); //defining composite event
        
        // adding simple events to composite
        $comp_event->add_web_event_simple($number_event); 
        $comp_event->add_web_event_simple($user_event);

        // adding composite event to WED with order value = 10, i.e. smaller than order value of number_event
        $this->wed->add_wed_event_action_pair($comp_event, 'my_composite_event', 10);
    }

$order parameter defines order of checking the events for match. WED sorts all events in ascending order based on their $order value and checks them one by one until firts match is found. That way in above example where we have parameters number=21&user=4 first my_composite will be checked (because it has lower $order value) and because its contition is satisfied event handling method my_composite_event will be called. Please note that after a match is found WED does NOT check the remaining events.

In future it is possible that WED will be made smart enough to detect overlaping conditions and to handle them automatically but until then it is your resposibility to order events properly, i.e. more general events to be checked after more specific events.