Current Record: XataJax_Compiler #114

Return to XataJax DISCLAIMER: This page introduces features that require Xataface 1.3 or higher. At present (Jan. 2011) only Xataface 1.2....

Current Record: XataJax_Compiler #114

Return to XataJax DISCLAIMER: This page introduces features that require Xataface 1.3 or higher. At present (Jan. 2011) only Xataface 1.2....

Introduction to the XataJax Compiler

[Permalink]

Return to XataJax

DISCLAIMER: This page introduces features that require Xataface 1.3 or higher. At present (Jan. 2011) only Xataface 1.2.6 has been released to the public.

Synopsis

The XataJax compiler is a Javascript CSS compiler and linker that comes with the XataJax module and will be a standard part of Xataface starting in version 1.3. It provides a mechanism to process and compile (or so to speak) all of the javascripts required for a page request at the time that the page is requested. This results in a more scalable, manageable javascript and CSS source base - and in improved performance for your applications.

Compiler Directives

Name Description Version
include? Includes another javascript file inside the current one in place of this directive. Sample code:
//include <myscript.js>
XataJax 0.1 Xataface 1.3
require? Includes another javscript file inside the current one only if that file hasn't already been included. Sample code:
//require <myscript.js>
XataJax 0.1 Xataface 1.3
require-css? Includes a CSS script in the CSS file. This will will search in the Dataface_CSSTool? include path for the script. Sample code:
//require-css <mystyles.css>
XataJax 0.1 Xataface 1.3
load? Loads the specified Javascript file in a separate script tag. This enables you to reference other scripts without including them in the same bundle, allowing for more effective caching. Sample code:
//load <myscript.js>
XataJax 0.1 Xataface 1.3

How it Works

The XataJax compiler works similar to a regular code compiler. It provides 4 server-side directives to allow you to express dependencies between scripts and stylesheets:

  1. include : Includes another javascript file inside the current script in place of the include'' directive.
  2. require : Includes another javascript file inside the current script (if it hasn't already been included) - i.e. if a script is included twice with a require directive, it will only actually be included once.
  3. load : Registers a dependency to another script, but doesn't include it in the same bundle. This may be used if your script requires code from another javascript, but you don't want it all to be bundled into the same javascript file. This may help with caching in certain cases.
  4. require-css''' : Registers a dependency to a CSS file. If your script depends on a CSS file, then it can be registered in this way.

Brief Example

scriptA.js:

//require <scriptB.js>
alert('You are in script A');

scriptB.js:

alert('You are in script B');

If you loaded scriptA.js, it would actually result in the following javascript being executed:

alert('You are in script B');
alert('You are in script A');

Notice that it included scriptB.js inside script A before the alert of script A. That is why script B's alert comes first. Note that this example won't work if you simply try to load scriptA.js directly in Apache. These directives are only evaluated if the scripts are served by Xataface. Here is a simple Xataface action that demonstrates how to use this in your Xataface script.

Creating a custom action

In your application directory, create an actions directory if you don't already have one. Then create a single file named hello.php with the following content:

class actions_hello {
    function handle($params){
        $jsTool = Dataface_JavascriptTool::getInstance();
        $jsTool->addPath('js', DATAFACE_SITE_URL.'/js');
        $jsTool->import('scriptA.js');
        echo '<html><head></head><body>'.$jsTool->getHtml().'</body></html>';
        exit;
    }
}

About this code:

$jsTool = Dataface_JavascriptTool::getInstance();
We start by obtaining an instance of the JavascriptTool. This is the object that does all of the magic of compiling your scripts and managing dependencies.
$jsTool->addPath('js', DATAFACE_SITE_URL.'/js');
This line adds the js directory to the tool's include path, and specifies (with the 2nd parameter) the URL to reach this directory also. The JavascriptTool works like most source code compilers. You need to give it the path where it can expect to find its libraries and scripts. Only paths that you add here will be searched for javascripts. You can add as many paths as you like. By default it will have the DATAFACE_PATH/js and the XATAJAX_PATH/js directories in the include path so you can directly reference any scripts in those directories always.
 $jsTool->import('scriptA.js');
This is where we declare that we want to use scriptA.js in the current request. This line then assumes that the scriptA.js file is located in one of the directories of the current include path. In our case we make sure that it resides in the DATAFACE_SITE_PATH/js directory.
echo '<html><head></head><body>'.$jsTool->getHtml().'</body></html>';
On this line we simply output the HTML script tags that the javascript tool generates linking to our resulting script.

Now we can test our our action by going to the page index.php?-action=hello. If everything worked correctly you should see the appropriate alert dialogs appear - first telling you you're in Script B, then telling you you're in Script A. If it doesn't work, you should check your javascript error logs to see what went wrong.

NOTE: - This simple example actually shows you the step of writing out the HTML tags explicitly with the getHtml() method. If you are using a standard Xataface template that is based on the Dataface_Main_Template.html template, then this step is unnecessary because the XataJax module will automatically include this HTML just before the closing </body> tag in your pages.

blog comments powered by Disqus
Powered by Xataface
(c) 2005-2024 All rights reserved