Extensions

Note: In versions prior to 2.4.0 extensions were called “modules”, and this was reflected in the names of the file headers, etc. (Module Name instead of Extension Name).


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

Another thing to consider when deciding whether to build your project as an extension or a plugin is whether you will want to distribute it through the WordPress.org plugins directory. WordPoints.org may offer its own extensions directory in the future, 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 an extension and 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 Extensions Reside? #

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

Example:

In general, we don’t recommend that you change the path to the extensions folder. And you should never change this to be a folder within the WordPoints plugin (or any other plugin for that matter), because all of your extensions would be deleted when you upgrade WordPoints. Yikes!

Organizing Your Extension’s Files #

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

Extension Headers #

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

In WordPoints 2.2.0, the Namespace extension header was introduced. It is recommended that all extensions include this header. It should be the prefix/namespace/slug used by your extension’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_Extension. In the future, WordPoints will use this namespace to generate the slug it uses to reference your extension, and for other purposes.

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

Activation and Deactivation #

As of WordPoints version 1.1.0, an extension’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 extension 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 extension would look something like this:

Uninstallation #

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

When your extension 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 extension’s other code, you need to include it in the uninstall file.

Conclusion #

Now that you know the basic structure of an extension, 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.