Calling Javascript with Xaraya
There are times in modules where you need to add a javascript to the module output. That is simple enough to do when you are adding the javascript within the body, but what happens when you need to add the javascript within the html header? As developers, we do not have the ability to override anything outside of the our space, or do we?
Actually, we do. Within the Xaraya Core, there is a function that allows us some control over the html header to add javascript. It was placed in the core with the .9.7.0 release, and was not documented except in the release notes. The idea is simple, every theme in Xaraya should have a call to a variable:
<xar:base-render-javascript position="head" />
What this tag does in the theme is look to see if there is any Javascript defined to display on this page instance, and if so, display it. It's very simple for use in themes. When there is not any Javascript, then the tag returns false and does not display anything within the theme itself. There is also another tag that should be in every theme which allows the insertion of javascript within the html body:
<xar:base-render-javascript position="body" />
This tag does the exact same thing, but the position that we place the script is different. The HTML fundementals remain the same. We want to load the Javascript in the header, when the script is needed to be processed before the body loads. Likewise if we are not processing a script before the the body loads, then we just load it into the body.
Calling the Function
The Xaraya function itself is just a normal API call:
xarModAPIfunc('base', 'javascript', 'modulefile',
array('module'=>'base', 'filename'=>'confirmlink.js'));
Obviously, the first three variables load the function that we are calling. In this case, "base, javascript, modulefile" which in PHP speak equates to calling the base_javascriptapi_modulefile function with the array as the input parameters. The input parameters here are:
array('module'=>'base', 'filename'=>'confirmlink.js')
Which is saying, at the time that this page is loaded, go to the base module, and include the "confirmlink.js" script. By default the function will load the javascript to the header of the html file. If we wanted to load the script into the body, then all we would need to do is call an extra parameter:
array('position' => 'body', 'module'=>'base', 'filename'=>'confirmlink.js')
and our Javascript will now load to the body
Where to put our finished file
We have now included our javascript, but Xaraya is merely throwing out a dynamic script link to the file. Xaraya does not know if that file is there, but the browser is going to look in the xartemplates/includes folder within your module for the file. That is where you need to drop the script that you are wanting to include. For designers, the override function is also in effect. Xaraya will look to your theme first to see if there is a module override for the script. If no override exists, then it will include the path to the module.
Simple functionality in essance, but it does quite a bit to expand the design capabilities for the developers and designers alike. The idea was implemented by Jason Judge from the Xaraya Team. Should you have any questions or praise, the development list of Xaraya would be a good place to post them.