CoolBrew User Guide Version 1.3
Based on CodeIgniter Version 1.5.4

Collector Class

The Collector class contains functions that permit you to collect and consolidate both JavaScript and Cascading Style Sheets (CSS).

With CoolBrew, we may want to load several tags on a single web page, and each of those tags may have CSS or JavaScript that it needs to display properly. So how do we manage that kind of data from multiple tags? If a tag you are writing needs CSS or JavaScript components, you can use this class to add that data to a central collection. That collection can then be inserted into the page all at once.

Note: This class is initialized automatically by the system so there is no need to do it manually.

Providing a Return Option

When you write a tag that adds code to the collections, you'll find that you need to design the tag to return its output rather than display it to the screen. At the very least, you'll need to add an option to return the output this way.

The reason for this will become obvious as soon as you try to use the tag: you'll need to run the tag at the top of your page so the JavaScript and/or CSS collections are complete before you finish the <HEAD> section of your document, but you'll need the tag results to display in the <BODY> section. You can see an example of this in the Collector Module section of this guide.

Note: For more information about the how collections can be accessed and used inside your website document files, see the Collector Module section in this manual.

If you are using the CodeIgniter $this->load->view() function to load a view file in your tag, returning the data is a simple process: <?php

// the bulk of your tag here.

$results = $this->load->view('whirligig', $data, TRUE);

return $results;

?>

For more information about the $this->load->view() function, see the Loader Class page in the CodeIgniter User Guide.

Adding Code from a File

You can save your JavaScript and CSS code in files inside your module folder and then add them to your collections using these functions:

$this->collector->append_js_file('file');
$this->collector->append_css_file('file');

These functions add the contents of file to the JavaScript and CSS collections respectively, where file is the filename without the .js or .css extension.

The advantage of using files to store your code instead of defining the code directly in your controller is that the CSS or JavaScript can be overridden at the document level. This is especially helpful with CSS which might need to be changed significantly for each website to match a particular design. CoolBrew will look for the requested file in three different folders and use the first one it finds. In the case of the JavaScript function:

  1. DOCPATH/js/
  2. system/js/
  3. system/MODULE_NAME/js/

And the for the CSS function:

  1. DOCPATH/css/
  2. system/css/
  3. system/MODULE_NAME/css/

Note: Generally, JavaScript or CSS code intended to be added to the collections does not include the HTML <SCRIPT> or <STYLE> tags that are used to place the code in an HTML document. This keeps the code flexible as to how it gets inserted.

Adding Code Directly

You can also add CSS and JavaScript code directly from your controller using these functions:

$this->collector->append_js_code('code');
$this->collector->append_css_code('code');

Getting the Collected Data

Once all the JavaScript and CSS code is collected, you can get the collected data in a form that is ready to be inserted into an HTML document or view file using these functions:

$this->collector->wrap_js('wrapper');
$this->collector->wrap_css('media', 'wrapper');

These functions return the JavaScript or CSS collections wrapped in HTML <SCRIPT> or <STYLE> tags respectively.

The default wrapper templates are system/js/wrapper.js and system/css/wrapper.js. These templates can be edited directly or overridden by placing copies of them in DOCPATH/js/ and DOCPATH/css/ and editing those copies. You can also specify a whole different template file in the function call, where wrapper is the template filename without the .js or .css extension.

The wrapper templates are not standard view files. They are simple files with one or two template variables that get replaced with the collection contents. The JavaScript template has the {javascript} variable, and the CSS template has the {CSS} and {media} variables.

Other Utilities

$this->collector->get_js_file('file');

Returns the contents of the javascript file.

$this->collector->get_js();

Returns the JavaScript collection without wrapping it first.

$this->collector->get_css();

Returns the CSS collection without wrapping it first.