Occasionally, it is important to execute code on the client without interacting with the server. Though the NOLOH development team is currently working on an advanced system by which all code, client and server, is written in one language, we still offer extensive support for JavaScript. The most important manifestation of this is the ClientEvent object, which really deserves its own section in the Events article that focuses on alternative ways of running JavaScript within NOLOH.

Adding Source Files

To include an existing JavaScript source file which has the definitions of various functions, one uses the AddScriptSrc function, which simply takes in the path of the source file as a parameter, like so: AddScriptSrc('MyScripts.js'); AddScriptSrc automatically keeps track of the various files that have been added so that if the same file is added twice, the scripts will still only be sent to the client once. Hence, the developer never has to worry about when and where to call AddScriptSrc, and can easily associate certain classes with certain JavaScript source files, for example, by adding the file in the constructor:

class CustomPanel extends Panel
{
    function CustomPanel($left, $top, $width, $height)
    {
        parent::Panel($left, $top, $width, $height);
        AddScriptSrc('CustomPanel.js');
    }
}

AddScript Function

The simplest way to execute JavaScripts is the AddScript function. It takes in the string of JavaScript to be executed and optionally, a priority which allows the developer some control over their order. By default, the priority is Priority::Medium. This code will be immediately sent to the client. For example:

AddScript('Foo();', Priority::Low);
AddScript('Bar();');

The above code will first execute the JavaScript function Bar(), followed by the function Foo() due to the fact that Bar has a higher priority. Note that added code behaves like a queue structure (more precisely, three queues, one for each priority): the code added first will be executed first.

QueueClientFunction

The disadvantage of AddScript is precisely the fact that the code is immediately executed. Consider the following scenario: you have a custom panel with an overloaded SetLeft() function, which executes a JavaScript function. If you were to simply AddScript this client-side function call, you may experience the problem that the custom panel may not even have been shown on the client at this point, since it is perfectly legal to set the Lefts of Panels that only become shown at some very distant point in the future. Or, it might be the case that after setting the Left, the developer has changed his mind and set it to something else, but might not wish the JavaScript function to call twice. In summary, once you AddScript, the code is immediately queued for showing, there is no delaying or taking back. The more advanced QueueClientFunction function was designed to address these problems.

QueueClientFunction takes in several parameters, outlined in the following function header:

QueueClientFunction(Component $component, $functionName, $paramsArray, $replace=true, $priority=Priority::Medium)

First, it takes in a Component object that is to be associated with the JavaScript function. The code will not be sent to the client to execute unless this Component has been shown. Second, it takes in the name of the JavaScript function to be executed, as a string. Third, it takes in an array of parameters that will be passed into the JavaScript function. Next, it optionally takes in a bool (default to true) which indicates whether future QueueClientFunction calls with the same object and function name will overwrite previous calls. And finally, an optional priority (default to Priority::Medium) is taken in, analogous to the priority of AddScript.

Let us see an example of how we can use QueueClientFunction to address the scenario given above with a custom Panel's Left:

class CustomPanel extends Panel
{
    function CustomPanel($left, $top, $width, $height)
    {
        parent::Panel($left, $top, $width, $height);
        AddScriptSrc('CustomPanel.js');
    }
    function SetLeft($left)
    {
        parent::SetLeft($left);
        QueueClientFunction($this, 'UpdateLeft', array($left));
    }
}

Now, whenever Left is set on an instance of CustomPanel, it will call a JavaScript function UpdateLeft (which should be defined in the CustomPanel.js file) and pass the left as a parameter. Furthermore, the UpdateLeft function will not be called until the instance in question has been shown, and it will not be called twice from the same interaction with the server; it will replace previous calls and only call it once with the latest left.