Writing Plugins for Tarski

Writing your own WordPress plugins to interface with Tarski’s theme hooks system isn’t particularly difficult, and can be done even if you’re not particularly familiar with PHP (although obviously it helps).

WordPress plugins overview

The first stop for all prospective plugin authors should be the WordPress Codex, WP‘s primary documentation site. The Developer Documentation page is a good overview of WordPress development, including plugin development. Two other vital pages are Writing a Plugin and the Plugin API. Once you’ve read those two pages, everything in the Tarski hooks reference should make a lot more sense.

Actions & filters

Plugins can extend WordPress in a number of ways, but here we’ll mostly be concerned with using actions and filters to change WordPress’ and Tarski’s behaviour. Filter vs. Action explains the difference between actions and filters pretty well, and we can easily supplement that article with a couple of examples.

Built into WordPress is the wp_head action hook. WordPress extensions—plugins, and themes like Tarski—can add actions to this hook, like hanging a series of coats on a peg. Tarski adds its stylesheets via wp_head hook. Here’s the code it uses:

add_action('wp_head', 'tarski_stylesheets');

As you can see, it’s really simple to add actions. The first argument specifies the wp_head hook, while the second calls the tarski_stylesheets function (which prints the appropriate HTML).

Filters are just as simple. Here’s an example using a filter specific to Tarski, tarski_sidebar. This piece of code hides the sidebar content on the archives page, because that page has its own sidebar content.

add_filter('tarski_sidebar', 'hide_sidebar_for_archives');

Example plugin templates

Included in WordPress is the ‘Hello Dolly’ plugin, which mostly functions as an example plugin. You can see the code here. When writing a plugin, make sure you fill out the plugin info (in the comment at the top of the plugin file) properly.

A number of Tarski-specific example plugins are available. From their names and descriptions it should be obvious what they do.

Output other plugin functions

Many plugins provide template functions which need to be hacked into a theme’s template files to make them work. Tarski’s extension of the WordPress API should, in general, make this unnecessary: you can simply write a second plugin as a ‘bridge’ between Tarski and the first plugin.

Here’s an example: you download a plugin from the WordPress plugins repository, which provides a template function named really_cool_function. This prints something really cool, which you want to add it at the end of each of your posts and pages. You could just add it to the template files, but you’d have to do it several times, and when a new version of Tarski came out you’d have to port your changes over, which is a pain. Better to write a bridge plugin to do all the hard work.

add_action('th_postend', 'really_cool_function');

That’s all there is to it. To see what other people have done, check out the Tarski-specific plugins thread on the forum.

Removing Tarski’s actions and filters

Because plugin code is loaded prior to theme code, if you add actions or filters to Tarski’s hooks they will be executed correctly, but if you attempt to remove Tarski’s default actions or filters through a plugin it will have no effect: WordPress will attempt to remove those actions or filters before they are added.

The most elegant workaround for this problem is to wrap your action and filter removal calls in a function and attach it as an action to the init hook. For example, to remove Tarski’s header image you might write some code like the following:

function remove_tarski_header() {
    remove_action('th_header', 'tarski_headerimage');
}

add_action('init', 'remove_tarski_header');

For more on the init hook read its entry in the WP hooks directory.