Compiling a plugin

The plugin template zip file also includes an example plugin, zem_example.php. We’ll start by compiling that, then installing and running it to make sure everything is working.

To compile, you need two files: the plugin itself — zem_example.php in this case — and the compiler, zem_tpl.php. Place both of these in the same directory (safely away from your Textpattern installation, if you’re compiling on your web server). We’ll call the directory txpexample for now.

If you’re using the command line:

$ cd path/to/txpexample/
$ php zem_example.php > zem_example-0.1.txt

Assuming everything worked correctly, zem_example-0.1.txt now contains your compiled plugin.

If you’re using a web server, load http://example.com/txpexample/zem_example.php in your web browser (replace example.com with your server URL, of course). The page should contain your compiled plugin, so save it as a text file, zem_example-0.1.txt.

In order to use Textile in the plugin help text, you’ll also need to place a copy of classTextile.php in the same directory.

However you compile it, zem_example-0.1.txt should resemble the base64 example above (under The Basics). If it doesn’t, or if you see some kind of error message, check that PHP is installed correctly, and that both zem_example.php and zem_tpl.php are accessible and in the correct directory.

If you’d prefer to keep the compiler separate from your plugin source, you can place zem_tpl.php and classTextile.php in another directory, and add that directory to your your include_path setting in PHP.ini.

Installing a compiled plugin

Now that you’ve successfully compiled the example plugin, you can install it.

Open the compiled plugin file you produced in the last step, zem_example-0.1.txt, in a text editor, and copy its contents to the clipboard (usually Ctrl-A, Ctrl-C on Windows, Cmd-A, Cmd-C on a Mac). You don’t have to limit the clipboard selection to the base64 encoded part; Textpattern is smart enough to ignore the comments at the top.

Next, open your Textpattern administration panel and go to textpattern > admin > plugins. Paste the clipboard contents into the Install plugin: text area, and click Upload.

Textpattern will display a preview of the plugin source code for verification. Click Install to confirm.

The plugin is now installed but not yet active. Find zem_example in the list. Under the Active column, you should see a link that says No. Click this to activate.

The process for installing a new version of an existing plugin is almost the same. You don’t have to uninstall or deactivate the old one first; just upload and install the new copy, and Textpattern will overwrite the old one. You will have to re-activate the plugin after installing the new copy, however.

Testing our example code

Now that our example plugin is installed and activated, let’s test it out.

zem_example includes three new tags. The simplest is txp:zem_hello_world. Put the tag in one of your page templates, preferably on a test server or section away from public view:

<txp:zem_hello_world />

You should see the output Hello, Alice on your page:

Hello, Alice

The tag accepts a name attribute, so this:

<txp:zem_hello_world name="Bob" />

..should display a greeting to Bob:

Hello, Bob