Difference between revisions of "Scripts Class"

Latest revision as of 13:58, 21 April 2013

Introduction

As of version 1.8.0, Geeklog introduced the Scripts class. The Scripts Class has been designed to allow themes and plugins to easily add JavaScript, JavaScript files and CSS files to the header and/or footer of a page. It also allows plugins and themes to enable the use of jQuery and the jQuery UI plugin. By default Geeklog will place all JavaScript in the footer unless told otherwise.

In previous versions of Geeklog, JavaScript and the CSS files were handled solely by the plugin usually by including the functions plugin_getheadercode_foo or plugin_getfootercode_foo.

The advantages of using the Scripts class over having a plugin or theme manage things are many. You have easy access to jQuery and the jQuery UI plugin, no more inline scripting, and you can setup things to have files only load when needed. Plus, in the future it will automatically support caching and compression of the CSS and JavaScript files.

Usage

The Scripts class is set near the beginning of lib-common.php as $_SCRIPTS. It uses the template variable plg_headercode (which is set in the function COM_SiteHeader) to put information in the header and the template variable plg_footercode (which is set in the function COM_SiteFooter) to put JavaScript in the footer. All of your JavaScript code and CSS files for the header needs to be set in the class before COM_SiteHeader is run or, for plugins, in your plugin_getheadercode_xxxx function, and themes, in the functions.php file. All JavaScript for the footer must be set by the time you call COM_SiteFooter (this shouldn't be a problem since this is one of the last functions you should be calling anyways on a page).

All JavaScript in the footer will also have access to the GeeklogConfig object. This object contains commonly used attributes taken right from Geeklogs configuration array ($_CONF) and uses the same keys.

Setting a CSS File

To set a CSS file for your plugin you would point the Scripts class to the file like so:

global $_SCRIPTS;
    
$_SCRIPTS->setCSSFile('polls', '/polls/style.css');

This tells the Scripts class to include the style sheet called polls. It is also telling the class that you plan to always include this CSS file. The reason you want to tell Geeklog that you plan to always include this CSS file is that it will then be marked for caching and compressing (future feature). If you plan to only include this CSS file on pages that the plugin displays you may want to include an extra parameter in the call to the class:

global $_SCRIPTS;
    
$_SCRIPTS->setCSSFile('polls', '/polls/style.css', false);

As stated before this needs to be done before you run the function COM_SiteHeader or in your plugins plugin_getheadercode_foo function. If your plugin has a block or uses Autotags that need the CSS file then you should always make sure it is included since Geeklog has no way of knowing if a block or Autotag will be displayed before the header is written.

Setting JavaScript

To set JavaScript for your plugin or theme you would do the following:

global $_SCRIPTS;
    
$js = 'some JavaScript';
$_SCRIPTS->setJavaScript($js, true);

This will automatically wrap the code in the html script tag. If you want to include your own script tag then just remove the "true" from the function call. There are several other attributes to this function that you may need to use from time to time (i.e. specifying the JavaScript to appear in the header and if it is constant). For more information on these take a look at the Scripts class found in the "/system/classes/" directory of your Geeklog install.

Setting a JavaScript File

To set a JavaScript file for your plugin or theme you would do the following:

global $_SCRIPTS;
    
$_SCRIPTS->setJavaScriptFile('pluginname', '/pluginname/javascript/yourfile.js');

The first attribute of the function is the internal name of the file. Make sure this is unique as you can overwrite previous entries. To standardize this, the name should be your plugin name (for themes use "theme.themename"). If you have more than one JavaScript file then you could use a name like "pluginname.subname". The second attribute of the function is obviously the location and file name of your JavaScript file. The backslash needs to be included at the beginning of this and you only include the part of the path after the public_html directory.

Setting a JavaScript Library

To load the jQuery libray included with Geeklog all you need to do is add the following code:

global $_SCRIPTS;
$_SCRIPTS->setJavaScriptLibrary('jquery');

To load a jQuery UI widget all you need to do add the following code:

global $_SCRIPTS;
$_SCRIPTS->setJavaScriptLibrary('jquery.ui.tabs');

To load a jQuery UI effect all you need to do add the following code:

global $_SCRIPTS;
$_SCRIPTS->setJavaScriptLibrary('jquery.ui.effects-highlight');

When loading an effect or widget you do not need to load the jQuery library first. When loading an effect or widget all the required files will be automatically set to load.

If a jQuery file is missing then the Google CDN-hosted copy will be substituted. There is also an option in the Geeklog Configuration under the Site tab to always use a CDN-hosted version of jQuery.

When loading one of the widgets or effects for jQuery UI you need to make sure to set it before COM_SiteHeader is executed or in your plugins plugin_getheadercode_foo function. The reason for this is the css files are set in COM_SiteHeader and we need to make sure that the CSS files for the UI plugin get set.