NOLOH has two types of events: events that run on the Server are called ServerEvents and events that run on the client are called ClientEvents.

Events enable objects to trigger actions depending on various circumstances. Events enable NOLOH applications to flow continuously between client and server. NOLOH Events do not need forms or complicated client-side code. ServerEvents enable NOLOH to deliver sophisticated Ajax-like functionality in the client without ANY client-side coding, taking care of all user view state synchronization issues.

ServerEvents

Example of a ServerEvent:

class SomePanel extends Panel
{
    function SomePanel()
    {
        parent::Panel();
        //Instantiate a button
        $button = new Button();
        //Add the button to the Controls of the Panel
        $this->Controls->Add($button );
        /*Sets the Click event of the button to a ServerEvent
        that will call the function SomeFunc when the button is clicked*/
        $button->Click = new ServerEvent($this, "SomeFunc");
    }
    function SomeFunc()
    {
        System::Alert("Triggered an Event");
    }
}

Let's break down a ServerEvent into its component parts:

new ServerEvent($this, "SomeFunc");

The first parameter ($this) is the object whose function you want to be called.

Alternatively, if the function is static, then you may pass in a class's name as a string as the first parameter, as in:

new ServerEvent("SomeClass", "SomeStaticFunc");

The second parameter is the name, as a string, of the function that you want to be called. Finally, you may pass in any number of parameters thereafter that will serve as the parameters passed into the function that is called.

Consider a small variant on the above example:

class SomePanel extends Panel
{
    function SomePanel()
    {
        parent::Panel();
        //Instantiate a button
        $button = new Button();
        //Add the button to the Controls of the Panel
        $this->Controls->Add($button);
        /*Sets the Click event of the button to a ServerEvent
        that will call the function SomeFunc when the button is clicked*/
        $tmpButton->Click = new ServerEvent($this, "SomeFunc", $button);
    }
    function SomeFunc($button)
    {
        $button->Text = "Triggered an Event";
    }
}

Note that primitive data types are passed in by value at the time of creation of the event. So if, for example, a Control's Text is passed in as a parameter, any changes made to that Control's Text thereafter will not affect the value of the parameter. If you do wish to get the current Text of a Control (for example, you want to get the text in a TextArea and parse it), pass in the Control itself as the parameter and read off its Text, as follows:

class SomePanel extends Panel
{
    function SomePanel()
    {
        parent::Panel();
        //Instantiate a button and a textarea
        $button = new Button();
        $textArea = new TextArea();
        //Add the button and the textarea to the Controls of the Panel
        $this->Controls->Add($button);
        $this->Controls->Add($textArea);
        /*Sets the Click event of the button to a ServerEvent
        that will call the function SomeFunc when the button is clicked*/
        $button->Click = new ServerEvent($this, "SomeFunc", $textArea);
    }
    function SomeFunc($textArea)
    {
        $currentText = $textArea->Text;
        System::Alert("The current text of the TextArea is: $currentText");
    }
}

ClientEvents

ClientEvents run without having to communicate back to the server. This has the advantage of creating more responsive applications as no serverclient communication is required, yet has the obvious disadvantages of exposed logic, inability to query a database, and forfeiting many of NOLOH's advantages. We carefully warn the reader to use ClientEvents only when it is necessary, and caution him or her to not write your entire application client-side. Its only parameter is a string of JavaScript code to be executed. Consider the following code sample:

$button = new Button();
$this->Controls->Add($button);
$button->Click = new ClientEvent("alert('Triggered an Event')");

At this point, you might be wondering why we even included ClientEvents in NOLOH. Well, it is because we plan to enable future NOLOH applications to parse PHP functions into browser-specific JavaScript, thus obviating the need for a developer to use Javascript at all because we believe NOLOH should be the only language a developer should have to know.

Besides, ClientEvents is one of the ways you can call your own Javascript functions.

Multiple events

Sometimes, a developer may wish to associate more than one event with a particular behavior. In that case, they may treat events completely as though they were regular arrays in PHP. This includes, for example, the use of the common square-bracket notation, the isset and unset functions, indexing by a string, and so forth.

Consider the following code sample:

$button = new Button();
$button->Click = new ServerEvent($this, "FirstFunc");
$button->Click[] = new ServerEvent($this, "SecondFunc");

When the Click event fires, first the FirstFunc will be called, followed by a call to SecondFunc. Alternatively, the developer may treat it as an array from the very beginning, as in:

$button = new Button();
$button->Click[] = new ServerEvent($this, "FirstFunc");
$button->Click[] = new ServerEvent($this, "SecondFunc");
$button->Click[] = new ServerEvent($this, "ThirdFunc");

Note that the type of the event (Server or Client) is modified to reflect the fact that multiple events have been used. A ServerEvent or ClientEvent when turned into a multiple event will become an instance of an Event class, which will have various other events inside it.

You can also add events recursively, resulting in a tree structure which is traversed preorder when launched:

$button = new Button();
$button->Click = new ServerEvent($this, "FirstFunc");
$button->Click['event'] = new ServerEvent($this, "SecondFunc");
$button->Click['event'][] = new ServerEvent($this, "ThirdFunc");

Custom events

A developer may also use events for purposes other than being assigned to handle specific Control behaviors such as Click, RightClick, etc. This is done by calling the Exec() function of an event, thus launching it. This can be helpful for advanced techniques such as the following:

class SomeLabel extends Label
{
    public $TextChange;
    //
    // Overload the setting of text of a Label
    function SetText($text)
    {
        // Checks whether the new text is different from the parameter
        if($this->Text != $text)
            // Checks whether the object has a TextChange event
            if($this->TextChange instanceof Event)
                // And launches it
                $this->TextChange->Exec();
        // Calls default SetText functionality
        parent::SetText($text);
    }
    //
}

Thus, a developer may handle the change of a Label's Text as an event, or indeed, create powerful, custom events. However, care must be taken when using multiple events together with custom events as the convenience of automatically changing types is unavailable for anything other than Control behaviors. To allow multiple custom events, a developer must first instantiate an instance of Event, and only then may the object be treated as an array:

$someLabel = new SomeLabel();
// This must be done first for multiple custom events.
$someLabel->TextChange = new Event();
// And only then can one treat TextChange as an array.
$someLabel->TextChange[] = new ServerEvent($this, "SomeFunc");
// An example of indexing events by strings.
$someLabel->TextChange['other'] = new ServerEvent($this, "OtherFunc");
// Event objects can hold Client or Server events, or mixes.
$someLabel->TextChange[] = new ClientEvent('alert("Third one")');