Modules

Modules are extensions for the WordPoints plugin. They allow WordPoints to be extended in a manner very similar to how plugins extend WordPress. You can use plugins or modules to extend WordPoints — which you use is up to you. The main difference is that WordPoints modules are stored and managed separately from any WordPress plugins that you have installed.

Another thing to consider when deciding whether to build your extension as a module or a plugin is whether you will want to distribute it through the WordPress.org plugins repository. I plan to eventually create a module repository for WordPoints, but until then, you  may choose to wrap your customizations in a plugin if you wish to redistribute it in that way.

Converting a plugin to a module or vice versa is very easy, so don’t worry too much about which one you decide to do. You can always make the conversion from one to the other later if you feel the need.

Where Do Modules Reside? #

The modules installed on your website can actually be stored anywhere you like. By default they are stored in the /wp-content/wordpoints-modules/ directory. If you want to change this, you can set the WORDPOINTS_MODULES_DIR constant in wp-config.php to be the path of the folder where you want the modules stored.

Example:

It is recommended that you don’t change this to a folder within the WordPoints plugin (or any other plugin for that matter), because all of your modules would be deleted when you upgrade WordPoints. Yikes!

Organizing Your Module’s Files #

You can pretty much organize your module files however you want. They are loaded similarly to the way that WordPress plugins are loaded, and support the same sort of file structure. Modules can have a single file, or multiple files organized in a folder. If your module has multiple files, then you can organize them in a folder however you like. For example, if your module’s files were in a subdirectory of the modules directory named /my-module/, your main module file might be /my-module/my-module.php.

Module Headers #

Just like WordPress plugins, WordPoints modules are identified by a header at the top of the main module file. The module headers are similar like the plugin headers, except that ‘Plugin’ is replaced with ‘Module’:

In WordPoints 2.2.0, the Namespace module header was introduced. It is recommended that all modules include this header. It should be the prefix/namespace/slug used by your module’s code. It should be in Title_Case, and should omit WordPoints as a prefix. As you can see, in the above example we’ve used the namespace My_Module. In the future, WordPoints will use this namespace to generate the slug it uses to reference your module, and for other purposes.

To create a module, add a .php file in the /wp-content/wordpoints-modules/ directory (if it doesn’t exist you can create it). Add the module headers to the file. Now your module will appear on the WordPoints > Modules administration screen!

Activation and Deactivation #

As of WordPoints version 1.1.0, a module’s code is not executed until it is activated (for information on the pre-1.1 behavior, see here). This is the same behavior as how WordPress handles plugins.

To perform an action when your module is activated, use the wordpoints_register_module_activation_hook() function:

Similarly, to run any code you need to on deactivation, use wordpoints_register_module_deactivation_hook() to register your callback function.

A complete basic module would look something like this:

Uninstallation #

Uninstallation of a module happens when a module is being removed, before its files are deleted. Unlike activation and deactivation, when uninstallation occurs, the module is not active, and its code is not loaded. So instead of having an uninstall hook, module’s have an uninstall file, uninstall.php. If your module creates database tables or adds some options to the database on activation, you should delete those things when your module is uninstalled. In other words, if your module has an install process, it should have an uninstall process, too. The code to do that needs to go in uninstall.php in your module. This means that your module will need to be split into multiple files in a directory.

When your module is being uninstalled, only the uninstall.php file is loaded (if it is present). That means that if you need to use any of your module’s other code, you need to include it in the uninstall file.

Conclusion #

Now that you know the basic structure of a module, it’s time to make it actually do something! That’s what the rest of this code reference is for. Unfortunately it’s still a work in progress, so you’ll probably want to read the source.