Overview of Hotaru Plugins

[Nick]

Hotaru plugins can be as big as you like and do as much as you want them to do. You could build a simple plugin to show the date in the sidebar, or a complex plugin to run an online photo gallery. The documentation in this section shows you how to get started and explains some of the ways you can get the most out of Hotaru CMS.

Before you get started

You will need a basic understanding of PHP, and should understand the Hotaru Cycle and our implementation of the PEAR Coding Standards before beginning.

Preparing your files

In the /content/plugins folder, create a new folder and give it a name. In that folder, you need a .php file of the same name, i.e.

plugins
---my_plugin
------my_plugin.php

You can optionally have language, CSS and JavaScript files, too, which should be named as follows:

plugins
---my_plugin
------my_plugin.php
---languages
------my_plugin_language.php
---css
------my_plugin.css
---javascript
------my_plugin.js

Additional files can be added with names of your choice, but those first files should all match the plugin folder name.

How plugins work

Hotaru themes, some core files and other plugins, contain plugin hooks that look like this:

$h->pluginHook('hook_name') 

When PHP encounters a plugin hook, it calls a special function imaginatively titled pluginHook. That function is in /libs/PluginFunctions.php. The purpose of the pluginHook function is to determine which plugin files and functions to include and trigger at that point.

Each plugin specifies the hooks it uses in a comment block at the top of the file. Hotaru takes those hooks and stores them along with the plugin name in the database. The pluginHook function checks the database (or database cache) to see which plugins match the plugin hook encountered.

Your plugin class

The pluginHook function described above will build an instance of your class and use it to run the function intended at that hook. A function's name must match the plugin hook's name and have $h as the first parameter, e.g.

// In a plugin or template:
$h->pluginHook('plugin_hook_name');

// In the pluginHook function:
$my_plugin = new MyPlugin($h);
$my_plugin->plugin_hook_name($h); 

Therefore, the skeleton for your plugin should look something like this:

<?php
/**
 * name: My Plugin
 * description:  Does wonderful things
 * version: 0.1
 * folder: my_plugin
 * class: MyPlugin
 * hooks: plugin_hook_name
 *
 * You can type notes here
 */  

class MyPlugin
{
         public function plugin_hook_name($h)
         {
                 // do something
         }
}

?>

By passing $h to each function, we can use the dozens of functions built into Hotaru.

Now you're ready to make your first plugin!