Elgg 1.8: Including CSS and JavaScript
Update: we've made some changes to the functions in this blog post. We wanted to make it easier for one plugin to include a JavaScript library and another to use it. The post has been updated.
Development on Elgg 1.8 is moving along at a good clip. One of the new features that I have appreciated as I update the plugins are the new functions for including JavaScript and CSS files. In Elgg 1.0-1.7 including an external CSS file is done through extending themetatags view. Not exactly intuitive! It also means that if I have two plugins including the same file, the file is included twice in the HTML <head>. This all changes with Elgg 1.8.
Including CSS
The new functions including CSS are elgg_register_css() and elgg_load_css(). The register function takes three parameters: the identifier for the CSS file, the URL of the CSS file, and an optional priority. This function lets Elgg know about the existence of the CSS file. It should normally be called in a plugin's initialization function. Last chance to use it is just before elgg_view_page() is called at the end of a page handler.
The load function tells Elgg to include the CSS file in the html <head>. It's only parameter is the identifier used in the register function.
If I wanted to include a CSS file on every page, I can register the file in my plugin's initialization function and also call load:
$css_url = 'mod/myplugin/vendor/special.css';
elgg_register_css('special', $css_url);
elgg_load_css('special');
You may have noticed that the URL for the CSS file is a relative URL. We can do that because the core functions automatically add the base site url to links in Elgg 1.8.
Including JavaScript
A problem without a good solution in Elgg 1.7 is what to do with a JavaScript file that you want to include only when it is needed. One technique was to use a global variable in the view that uses that JavaScript (think TinyMCE plugin) and then include the script reference directly in the view the first time it is called based on the value of the global. In Elgg 1.8, you will be able to register the script with elgg_register_js() in your plugin's init function and then do this in the view:
elgg_load_js('jquery.rating');
It doesn't matter if the view is called one hundred times. Elgg will only insert the script a single time. Further, you get to choose between having the script in the HTML <head> section or in the footer in when registering the script.
If you want to include a different version of jQuery on your site, you don't have to override the head view anymore (fewer headaches with upgrades!). Instead, just override the core's registration in your plugin's init function:
elgg_register_js($google_cdn_jquery_url, 'jquery');
You can do the same thing with other plugins if you needed a newer version or want to switch to using a CDN rather than locally serving the JavaScript file.
Conclusion
Paraphrasing jQuery's slogan, including CSS and JavaScript in Elgg 1.8 requires less code with more functionality. You'll be hearing more in the coming days about other new features for developers coming in Elgg 1.8.