Ryan Florence Online

• Articles
• Projects
• Contact

MooTools Packager

By Ryan Florence, published 2010-10-14

Part of the issue MooTools 1.3.

Because MooTools is modular, manually including all the different files you need, along with their dependencies, is a pain in the neck. Kamicane’s Packager to the rescue! Packager is a PHP class and command-line tool used to build JavaScript files from components. Before you write your first line, or next line, of MooTools JavaScript, you have to get packager running.

Get it from github.

During Development – Packager PHP

I keep a server running on my machine that acts like a JavaScript CDN for me. All I have to do is add this tag to my files to include whatever JavaScript I need:

<script src="http://localhost/build.php?scripts=Core/Fx.Tween"></script>
<script src="page.js"></script>

This is part of my github repository mootools-template. The file build.php lives next to a directory named javascripts that contains clones of all the git repositories I’ve ever used in a project, including my own plugins. This is lovely because it forces me to write plugins with a mindset outside of the current application. When I discover a plugin needs some extra functionality, or I find a bug, I fix it here and then push it up to github. When others update their plugins, I can just pull and get the most up-to-date stuff.

Here’s what build.php looks like:

include(dirname(__FILE__) . "/lib/packager/packager.php");
header('Content-type: text/javascript');

$packages = array();
$dir = "javascripts";
// build up an array of packages
if ($dh = opendir($dir)) {
    while (($file = readdir($dh)) !== false) {
        if ($file != "." && $file != "..") $packages[] = $dir . '/' . $file;
    }
    closedir($dh);
}

// create the Packager instance
$pkg = new Packager($packages);
if (isset($_GET['path'])) {
    // write a file to disk
    $pkg->write_from_components($_GET['path'], explode(',', $_GET['scripts']));
    echo "// built file to " . $_GET['path'];
} else {
    // echo out the JavaScript
    echo $pkg->build_from_components(explode(',', $_GET['scripts']));
}

Pretty straightforward PHP. It first builds up an array of sub-directories in javascripts. Then it creates a Packager instance, and passes it the array of directories. Next it decides if the url indicates to write the file, or just echo it out by checking for a path key. Finally, it calls either write_from_components and writes a file or build_from_components and echos out the full JavaScript file.

Here’s a less dynamic example:

$pkg = new Packager(array(
    "javascripts/mootools-core", 
    "javascripts/mootools-more"
));

$pkg->write_from_components("javascripts/build.js", array(
    'Core/DOMReady',
    'Core/Fx.Morph'
));

Packager CLI

Building files from the command line is straightforward.

# register each package
./packager register ../../javascripts/mootools-core
./packager register ../../javascripts/mootools-more

# build the file (with dependencies, this command pulls in 35 files)
./packager build Core/DOMReady More/Fx.Move > ~/path/to/site/build.js

First you register your package, next you build. Easy enough

Making your stuff work with Packager

Packager is not very picky. It only requires two things: a package.yml manifest in the root directory, and a YAML header in your script file. Here is a bare bones example, containing only the information Packager needs.

Directory structure

my-plugin/
    package.yml
    Source/
        MyPlugin.js
        MyPlugin.Extended.js

package.yml

name: MyPlugin

sources:
  - Source/MyPlugin.js
  - Source/MyPlugin.Extended.js

MyPlugin.Extended.js

/*
---
requires:
  - Core/Fx
  - ExternalPackage/Script
  - /MyPlugin.Extended

provides: [MyPlugin.Extended]

...
*/

// ... some code

All you need to do:

1. Put package.yml in the root directory
2. Give the package a name
3. Point to the sources
4. Declare what a script requires, note that way local and scripts are required vs. external (beginning /)
5. Declare what a script provides, doesn’t have to match the file name or anything, it’s just a name.

On a recent project I was using jQuery. I went ahead and made every jQuery UI script work with Packager, and it was fabulous. Yes, that’s right, it has nothing to do with MooTools, Packager works with any files that follow these simple conventions.

Go back to the previous article in this issue: MooTools Element 1.3.