Writing a Plugin

This part of the handbook will document Hook’s API and how to use it to write plugins for eduTrac SIS as well as show you how to override default behavior without hacking the core. Following the codex tree below, there is important information you must read through first with regards to creating a plugin or dropin.

Plugin File Name

Your plugin must have the extension .plugin.php. This is how eduTrac SIS recognizes it is a plugin and this is the same file where you will add the needed header, which will go into more detail in a later section. Your plugin file can either go into the plugins directory or into its own directory. So, for example, if you plugin file name is tally.plugin.php, and you want to put it into its own directory, then the directory name should be tally.

Hooks: Actions and Filters

There are two types of hooks that eduTrac SIS uses. One are action hooks will the other are filter hooks. Action hooks allow you to extend or change the way eduTrac SIS functions, while filters allow you to change or manipulate content during run time. There are several action hooks spread throughout the system that you can tap into. An action hook must exist in order to use it. If it doesn’t exist and you need to create one, use do_action().

If you need certain code to run during activation or deactivation of your plugin, check out register_activation_hook() and register_deactivation_hook().

When  creating a plugin, a header must exist in the main plugin file which should include the extension .plugin.php. The header lets the system know that it is plugin and also lets the system know which file to load.

Below is what’s needed in your plugin’s header.

  • Plugin Name: The name of your plugin which will also be displayed in the plugin list.
  • Plugin URI: This is the homepage of the plugin and let’s people know where they can go to check if there is an update to the plugin. This url is also displayed in the plugin listing.
  • Version: This is the current version of the plugin and will be displayed in the plugin list.
  • Description: This is a brief and detailed description of the plugin and it’s functionality.
  • Author: This is the creator/author of the plugin.
  • Author URI: This may be the author’s personal site, blog or business site.
  • Plugin Slug: This is the same of the plugin and should be the same as the plugin file name before the extension .plugin.php.

A valid plugin header would look like the example below.

/*
Plugin Name: Tally
Plugin URI: http://plugins.edutracsis.com/package/tally/
Version: 1.0.0
Description: This is an example plugin.
Author: John Doe
Author URI: http://www.johndoe.net/
Plugin Slug: tally
*/

License

The license that eduTrac SIS uses is GPLv3 and any code, whether free or commercial must use this license and fall within the guidelines. When creating a plugin for the plugin repository, you should include the GPLv3 license in the header of your plugin. Below is an example of what an extended header would look like for a plugin. Make sure to replace {Plugin Name} and {License URI} respectively.

/*
Plugin Name: Tally
Plugin URI: http://plugins.edutracsis.com/package/tally/
Version: 1.0.0
Description: This is an example plugin.
Author: John Doe
Author URI: http://www.johndoe.net/
Plugin Slug: tally
License: GPLv3

{Plugin Name} is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
any later version.

{Plugin Name} is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with {Plugin Name}. If not, see {License URI}.
*/

Activation / Deactivation Hook

Activation and deactivation hooks allows your plugin to run or perform certain actions upon activation or deactivation.

When some sort of action needs to run during plugin activation, use the register_activation_hook() method of the Plugin class.

register_activation_hook(__FILE__, 'function_to_run');

When some sort of action needs to run during plugin deactivation, use the register_deactivation_hook() method of the Plugin class.

register_deactivation_hook(__FILE__, 'function_to_run');

For both hooks, the first parameter refers to the plugin file with the .plugin.php extension. In this file is where you will place these hooks as well as the plugin’s Header. The second parameter refers to the function that is called or acted upon.