Textpattern Plugin How To

In response to many inquires I’ve seen on the Textpattern Forums I decided to put together a guide that to writing plugins in Textpattern. Although I’m still a relatively new TXP user of less than 6 months, I’ve written about 8 textpattern plugins and hacks. My learning process consisted of research and tips from both the forums and fellow TXPers sites. Keep in mind that the following is only my experience with writing plugins and is by no means the authoritative guide to writing plugins or the only way to do things. In fact, I’m pretty confident that there are many in the community that have much better PHP skills than myself. Nevertheless, this has worked for me and hopefully will be useful to aspiring plugin authors.

Compiling Your Plugin

The first thing you’ll need is a method of creating and compiling your plugin. I’d recommend getting the j|g plugin creator This plugin/hack allow you to compile plugins through the TXP web interface. All you have to do is fill out a form, paste in your code and documentation and the plugin is compiled for you. If you prefer, you can use the original Texpattern Plugin Template. There is also an improved plugin template by zem that adds a few nice conveniences.

Globals

Next you’ll want to familiarize yourself with global variables and functions that will make the job a lot easier. The first stop is some excellent writeups on global variables in Textpattern by ob1. You’ll need to use these to access global settings and preferences, page scope variables and articles level variables depending on the type of plugin you are creating. I’m also assuming you have at least some basic knowledge of PHP before attempting to write a plugin.

Hooking into Textpattern

The next stop is the Textpattern source code. If you’re in need of querying the TXP tables, read through the txplib_db.php and make use of the various helper functions. To get a good idea of a basic plugin, take a look at the taghandlers.php. Each of the built in Textpattern tags is essentially the same as a plugin. For example, you’ll find a function call that reads function linklist($atts) {...} which is the code behind the <txp:linklist /> tag. Take note of Dean’s coding conventions so that you can write clear, concise and clean code. You also might want to call some of the funtions (such as the permalink function) from your plugin to save yourself some work.

Next, take a look at the source of as many plugins as you can to see how people take advantage of the above functions and variables. Just find a few plugins, install them and click on the plugin name to view the source.

Before you decide to author a plugin, check the Textpattern Resources site and the Central Plugin List to make sure no one else beat you to it. You can also search the Textpattern forums for tips or just post your questions.

Basic Plugin Example

Now, on to an example and breakdown of a basic plugin.

function rss_hello_world($atts) {
  extract($atts);
  $name = isset($name) ? $name : "Anonymous";
  $msg = 'Hello World, my name is' . $name;
  return $msg;
}

The plugin would be called like this: <txp:rss_hello_world name="Rob" /> with the output of course reading “Hello World, my name is Rob”. The tag is both opened and closed in one call. The first thing you’ll notice is the array called $atts that contains the attributes that are passed into the tag. A basic null check is always a good idea after extracting the attributes from the array. Each attribute is then referred to by the same name as specified in the tag call. In this case, if the name is not specified, “Anonymous” will be used.

Another Plugin Example

Here’s an example of another type of plugin.

function rss_if_this($atts, $enclosed) {
  extract($atts);
  $that = isset($that) ? $that: "that";
  return ($that == "hello") ? parse($enclosed) : '';
}

The plugin would be called like this <txp:rss_if_this that="hello">Hello World</txp:rss_if_this>. The difference between this and the previous example if that if the condition in the plugin code evaluates to be true, the text or code within the plugin tags, in this case “Hello World” will be displayed. If not, nothing will be displayed.

Finishing Up

Your final step is to put this all together, create your HTML documentation and compile your plugin. Just save the base64 encoded output and there’s your plugin file.

Hopefully, this short guide will help you on your way to creating the next great Textpattern plugin.

Resource Roundup

• j|g plugin creator
• Texpattern Plugin Template
• Improved Plugin Template
• Global Variables in Textpattern
• PHP Documentation
• Textpattern source code
• txplib_db.php
• taghandlers.php
• Textpattern Resources
• Central Plugin List
• Textpattern Forum

Comments

Add a comment

You may use textile in your comment. Gravatars are enabled. Your email will not be displayed and will remain private. I reserve the right to edit or delete comments.

Name E-mail Website Remember

Message