It has been a bit since I have talked about SnowCMS, so I thought I should make a post to keep things going.

In order to allow developers to see all of what goes on in SnowCMS in a more orderly fashion, such as API’s available, the SnowCMS SVN includes documentation which is compiled every now and again (by antimatter15, not me…), which is available here. We know that a system can be great, but that system isn’t useful if no one knows how to use what the system has to offer, so developers take advantage of what SnowCMS has to offer. Currently we have a few available classes and such to aid developers create plugins much faster, and without requiring plugins to have code that multiple plugins might end up having to include themselves, which is unnecessary. So I thought that I would, over the next week or more, make some posts about how to use the various API’s and classes available to future developers.

API

The name is pretty self explanatory, but as you can see, there are many available methods which can be used by plugins, and of course, this will no doubt be the most used by plugins.

Adding a hook

A plugin can add a hook via the $api, to modify the behavior of the system, or just do some action at the time of the hooks execution. Here is an example:

/* ... */

/* ... */
# Now somewhere in SnowCMS's code, a hook is ran, and if you registered a callback on that hook,
# your callback, is, erm, called
$text = "Hi...";
$api->run_hook('the_hooks_name', array(&$text));
echo $text;

Now once all that was ran, “Hi…” would not be seen on the screen, but “I HOOKED YOU!” would be because the function my_hook had $str be a reference parameter, and when run_hook was called, $text was defined as a reference as well, allowing any function that hooked into this hook to change what $text contained. Of course, just changing text won’t be the only thing available through hooks, but there will be a lot more, but that depends upon the hook itself. Right now there is a small list available at Google Code of currently available hooks in the system, but as time progresses, the list will grow

Adding an action

When SnowCMS refers to an action, we mean an action in the URL. With the API, plugins can register actions to add some major, or possibly not so major, but still important, features to the system. Like say if there was a forum plugin and they wanted the forums index page to be accessible through index.php?action=forum, well, you can do that, and quite easily, I might add.

Adding that accessible page is done like this:

/* ... */
$api->add_action('forum', 'forum_index', 'location\of\the\forum_index.php');
/* ... */

Now when index.php?action=forum is accessed in a browser, the file “location\of\the\forum_index.php” is loaded and the function forum_index is called on. You can also leave the third parameter blank (the location of the function) and forum_index would just be called on. Through this method plugins can add pretty significant features to the system, like forums, pages, blogs, news, directories, or anything, really. Pretty slick, huh?

Adding a sub action

Along with adding an action, you can also add a sub action, the difference is that the action must implement the usage of sub actions. Such as the forum plugin (there isn’t really one, yet, I am just using it as an example ) it must use the API (which larger plugins really ought to, but don’t have to, use the API system to allow any other possible plugins to enhance the plugin itself…) to see if there are any sub actions which are registered (More on that later).

So now say you wanted to add a feature or something of the like to the forum plugin (index.php?action=forum) such as a statistics page. You would do this:

/* ... */
$api->add_subaction('forum', 'stats', 'stats_page', 'location\of\the\stats_page.php');
/* ... */

When you would access index.php?action=forum&sa=stats “location\of\the\stats_page.php” would be loaded and stats_page would be called upon, but of course, just as with add_action, the location of the function can be left empty.

Adding a group

Since we wanted to keep SnowCMS simple, we thought by default the system would only have 2 groups, an administrative group (administrator) and a member group (member, of course! But there is also a group called guest which you can’t assign yourself ). Why? Well, think about it. Most operating systems have 2 groups, administrators, which can really do everything, then there are members, which just plain get the privilege of using the computer So there are only those two groups. However, plugins are likely to add features which members shouldn’t be always allowed to use, nor should administrators be the only group allowed to use it either. So to make that work, plugins can register groups, which administrators can assign to members, which therefore elevate the abilities of that member.

First things first, a plugin needs to register the group, otherwise an administrator can’t assign (or at least, easily) the group to a member.

/* ... */
$api->add_group('forum_moderator', l('Forum Moderator'));
/* ... */

The first parameter is the groups identifier, which is the string stored inside the database, the second parameter is the human readable name of the group, in this case, Forum Moderator (I bet you are wondering what the l() function call is for, that is for language support, but more on that later ).

Now, when you want to see if the current member is allowed to perform the tasks restricted only to forum moderators, you would do a little something like this:

/* ... */

if($member->is_a(‘forum_moderator’))
{
/* They are a forum moderator, proceed */
}
else
{
/* They aren’t a forum moderator, yell at them! */
}

/* … */

There you have it… And of course you don’t need to worry about the checking of administrator’s, if the member is an administrator, any call to the method is_a is automatically returned as true.

So there you have it… A insight on how to use SnowCMS’s API class, that is all for the time being, but come back soon and I will be posting about other tools available in the SnowCMS which developers will be able to take advantage of.