Writing a 3rd Party Component in MODx Revolution, Pt. II

Okay, so now that we've got our table, our schema, and some classes and maps, let's make a snippet that grabs some Doodles!

i18n Language Support

This is only needed in Revo-alpha-3 and earlier. In alpha-4 and beyond, you'll actually do this via the Lexicon Management panel, by creating your namespace, focus and entries in there, then having Package Builder auto-package them in in the build process.

First, though, we'll want to create our language support. Go ahead and create an 'en/' directory in the assets/lexicon directory, and place a 'default.inc.php' file in there.

In the file, all you need for now is this:

<?php
$_lang['top_downloaded_doodles'] = 'Top Downloaded Doodles';

This is the translation for the key 'top_downloaded_doodles', which can be accessed via the lexicon now.

Creating the Snippet

Go ahead and create a file in assets/elements/snippets called 'doodles.snippet.php'. The code will go like so:

<?php
// grab the main eventual path of the snippet
$doodles_path = MODX_ASSETS_PATH.'/snippets/doodles/';

// add the Doodles package into MODx
// this loads the Doodles classes and maps into MODx that we generated earlier
$modx->addPackage('doodles',$doodles_path.'model/');

// load the custom lexicon path
// the first parameter for addDirectory is the path, the 2nd is a namespace for those strings
$modx->lexicon->addDirectory($doodles_path.'lexicon/','doodles');

// now, load the 'default' lang foci, which is default.inc.php.
// note how the colon separates the namespace from the foci name.
$modx->lexicon->load('doodles:default');

// create a query to filter results to top five downloads
$c = $modx->newQuery('Doodle');
$c->sortby('downloads','DESC');
$c->limit(5);
$doodles = $modx->getCollection('Doodle',$c);

// store the output to a variable, looping through the results
$output = '<h2>'.$modx->lexicon('top_downloaded_doodles').'</h2>';
foreach ($doodles as $doodle) {
     $output .= $doodle->name.': '.$doodle->downloads.' <br />';
}

// return output for proper outputting from the snippet
return $output;
?>

Now, load up your MODx install, and create a snippet called 'Doodles', and paste this code into the code box.

Building the package

Alright! The fun part. From here on out, you'll be working solely in MODx. Go ahead and go to the Package Builder (in Tools -> Package Builder). Let's specify a name of 'doodles', a version '1', and a release 'alpha'. Click next.

From here, click on 'Add Vehicle'. First, let's explain what Vehicles are. They are basically any element, resource and other MODx objects that are connected to a record in the database. (We're working on a non-DB based vehicle called modFileVehicle that is only attached to files for Revolution-beta.) So, go ahead and select the class key modSnippet, and the Object ID combobox should populate to your available snippets. Select 'Doodles'.

Now we need to add some resolvers. Resolvers are either PHP scripts to execute during installation, or files/directories to transport when compiling the package. We want the latter option, since we have some files to transport. Go ahead and click the 'Add Resolver' link to bring up the resolver creation window. Mimic the settings shown in the photo below.

Make sure to change the Source field to reflect the proper path to your Doodles assets directory. Also make sure there is no trailing slash. Click save.

Click save again, and then Next, then 'Build'. This will have built the package. Congrats! Your package is built, and stored in core/packages.

Installation of the Package

Go to the Workspaces utility. Click 'Add New Package'. Check the 'Search Locally for Packages' option, which should make Doodles show up in the grid. Right-click on the row, and click 'Install'.

And you're done. The files should have all been installed to modx/assets/snippets/doodles/. Easy, huh?

Now to test a run, simply add [[Doodles]] to any page, plus add some default data into your modx_doodles table (you'll have to do it manually for now) and watch the magic happen!