OSIMS

I’m using Xaraya as the php backend for this project.  It’s a very robust platform to build upon with a number of great features for dealing with access control, templating and customization.

It was, unfortunately, built in the time before “AJAX” when javascript use was far more rudimentary and mostly for cosmetic purposes.  After a fairly substantial development hiatus, recent updates to Xaraya have sought to improve this situation.  They’ve recently introduced the ability to include javascript frameworks within Xaraya and have used JQuery to improve many of the administrative interfaces within Xaraya.

Unfortunately, I still see some problems with the Xaraya approach, so I’m going to create an ExtJS module for Xaraya which will make the framework’s functionality available in this project.

The Pre-Existing JS Support in Xaraya

The existing support for Javascript in Xaraya is supplied through the “base” module, which is the core module of Xaraya.  It’s the base on which everything else can be developed.  At the most basic level, Javascript files can be linked either from within the API backend by calling the “modulefile” function like this:

xarModAPIFunc('base','javascript','modulefile',array('module'=>'extjs',filename=>'ext-base.js'));

or in the page templates by including a custom Xaraya tag in a template:

<xar:base-include-javascript module="extjs" filename="ext-base.js" />

Both of the above examples do essentially the same thing.  They simply tell Xaraya to look in the ExtJS Xaraya  module and link the javascript file called ext-base.js into the current page.  This function also takes care to ensure that each javascript file is only linked once per a page regardless of how frequently the request to include it is made.

The Expanded JS Support in Xaraya 1.2.0

Just in the last couple weeks the Xaraya team released version 1.2.0 in which the primary improvement is the inclusion of JQuery and better javascript support.  This change adds several new javascript template tags:

<xar:base-js-framework name="extjs" />

<xar:base-js-plugin name="rowactions.js" style="rowactions.css" />

and

<xar:base-js-event name=”ready” code=”$code” />

These tags seek to formalize the javascript abstraction layer by loading a pre-defined “framework” and then applying its plugins.  The event tag actually uses some framework specific templates to send javascript to the browser.

The first two seem like a step in the right direction, but the last one seems a bit misguided to me.  The intent is to be able to pass the $code to the ready event of whichever framework is currently being used.  Ideally this would allow one  javascript framework to be exchanged for another, but in practice any javascript code in $code that’s being passed is unlikely to be framework agnostic.  The passed code is going to need to be specifically tailored for the toolkit being used.  So there seems little point in having the ability to pass code to javascript frameworks that likely won’t be able to understand what to do with it.  Besides, the rules about how to compose and send javascript code through this function gets really confusing.

As an additional hassle, to be able to use an existing framework in this way, the framework needs to be “Xarayaized” to fit specific layout requirements.

Avoiding the Overhead

Xaraya dictates a very strict structure for its modules.  Within each module are sections for APIs, Styles, Templates and so on.  In this structure, all javascript is to be in the ./xartemplates/includes folder.  Cascading Style Sheets (CSS) should be in the ./xarstyles folder.  Images all belong in the ./xarimages folder.  This works well when developing a stand alone module, but when building on the work of someone else, it means a lot of time is spent pulling out pieces of the package and updating the text of CSS and javascript files to point to the correct locations.  Everytime there’s an update to ExtJS I would have to search through the folders for all the images and css files, move them to the correct folders and modify the css to look in xarimages.  Even Javascript Frameworks included by the base module have to go through a similar process and end up as bits and pieces scattered around several directories.

I’m lazy.

I’d much prefer to just drop in the latest release from the ExtJs team so I’ve created a module called extjs.  Inside the module, in the ./xartemplates/includes/ folder I just upload the entire extjs package.  I’ve then created an api function called base which does the following:

xarModAPIFunc('base','javascript','modulefile',array('module'=>'extjs','filename'=>'ext/adapter/ext/ext-base.js'));
xarModAPIFunc('base','javascript','modulefile',array('module'=>'extjs','filename'=>'ext/ext-all.js'));

xarTPLAddStyleLink('extjs','../xartemplates/includes/ext/resources/css/reset-min',null,null,'all');
xarTPLAddStyleLink('extjs','../xartemplates/includes/ext/resources/css/ext-all',null,null,'all');

This function is looking at the specific locations where these files are located within the ExtJS packages distributed by the ExtJS development team.  The xarTPLAddStyleLink function creates the CSS link similar to the javascript functions.  Normally it would look for the CSS files in the xarstyles directory, but I’ve I’ve used the relative URL ../xartemplates/includes to back out of the xarstyles directory and point it in the right direction.  Now I no longer have to pick apart the the ExtJS packages, I can just drop them in and they’re ready to go.

Adding More Functionality and Convenience

To make things a bit more convenient, I’ve added a Xaraya module variable for the ExtJS version, and another to turn on/off debug mode.  By changing the module configuration through the user interface I can select which version of ExtJS to use and whether to use the smaller file to save on bandwidth.

Because I haven’t broken the ExtJS code into bits and pieces, all the distributed examples and documentation is intact, and a couple quick links can be provided directly from the module’s admin page.

Finally, the Xaraya template engline allows the creation of custom tags.  In the installation of my module I have the following line:

xarTplRegisterTag('extjs','extjs',array(),'extjs_userapi_base');

Which allows me to include the ExtJS in any template simply by including the HTML-like tag:

<xar:extjs />

I’ve made the Xaraya ExtJS Module available here:

http://osims.org/resources/extjs.zip

Filed under:
Uncategorized by Brian Bain