How do I...Integrate Deki with WordPress?

Get the plug-in

The plugin is attached below, and is available from SVN: https://svn.mindtouch.com/source/pub...ools/wordpress

Introduction

You have, in your hands, a WordPress plugin which will keep all your WordPress (WP) posts synchronized with a MindTouch Deki install. New WP posts will be created into a configurable location in your Deki, and subsequent updates to the WP entries will also keep the Deki pages synchronized. Moving your WP post (by changing the URL) will also move the Deki page, and deletions in WP are also respected by Deki.

The goal of this plugin is to allow a couple use cases:

1. deeper collaboration on individual blog posts that are not afforded by WP, but are a logical part of any wiki engine
2. content federation from scattered WordPress wikis into a single Deki instance - this allows you to get a better broad overview of all posts being created in your multiple WP installs and allows for innate Deki features like searching
3. lays the groundwork for when Deki supports publishing hooks - once Deki can effectively publish back to the WP installation that pushed

Requirements

You need a WordPress installation as well as a MindTouch Deki installation running PHP 5.

Testing has only been done on Wordpress 2.5.1, but it should work as far back as WordPress 2.01. You will need a Deki instance running at least 8.05; earlier versions of Deki had a search bug which prohibits full usage of this plug-in (content creation will work, but subsequent synchronization fails).

Installation

To install this plug-in, unzip the "mindtouch_deki" folder into the /wp-content/plugins/ folder of your WordPress installation. You will need to
edit the mindtouch_deki.php file with your Deki information:

DEKIHOST is the host name of your Deki's installation. If you've gotten a Wik.is account, input something like:
mindtouch.wik.is

DEKIUSERNAME/DEKIPASSWORD are the Deki account credentials used  to post content - I suggest you create a new user for this purpose. It is *not* the WordPress account credentials!

DEKIPATH is the location in Deki that all WordPress posts should be stored. This can be overriden on a post-by-post basis.

The WordPress server should be able to "see" the Deki installation - if the plug-in fails, check that first. You should be able to do a wget on http://{deki-host-name}/@api/deki/@about and receive a page which looks similar to http://wiki.developer.mindtouch.com/@api/deki/@about

Usage

If your installation was successful, the next time you publish publicly a WP post, the Deki should automatically pick up those changes. Subsequent edits
and deletes will also synchronize, as well as URL changes.

All categories and tags from a WP entry are collapsed into a single tag list for Deki; the plug-in will also respect custom tags which have been added to the page inside Deki.

The Deki page will receive a few custom tags:

wp-id:{int} is the Wordpress entry id; this is used to keep the Deki entry associated with WordPress entry; if you ever wanted to "freeze" the Deki page, simply remove this tag.

wp-from:{string} is the URL of the WordPress install. In the case that you have multiple WP blogs pointing to the same Deki, there will be WP id collisions; this allows the plug-in to know which page to affect. Being a tag also allows you to identify inside Deki all the blog posts from a given WordPress entry.

wp-author:{string} is the author name of the WordPress entry. Unless you are running an account synchronization tool between WP and Deki, it's nearly impossible to attribute Deki entries accurately. This data is here so that later on, we can possibly merge them. If anything, it's usable metadata.

If you want to re-target any individual WordPress entry to a different location in your Deki, use the "dekipath:{path as string}" tag in WP - this will override the DEKIPATH you set in your initial install. Note that if you attempt to target a location which already exists, and is not your WP entry, the save will fail. 

Caveats

Tags, when added in Deki, take up to 60 seconds to get into the search index, which is heavily used in this plug-in. This means that AFTER YOU CREATE A POST, SUBSEQUENT ACTIONS UNDERTAKEN BEFORE THE DEKI SEARCH INDEX CATCHES UP WILL CAUSE THE FAILURE OF THIS PLUG-IN.

Be *sure* you wait for Deki to have successfully made the association or you'll end up with all sorts of problems.

This should be resolved in future versions of Deki, where we'll update the tagging interface to be real-time instead of being delayed.

Credits

This plug-in makes use of the Plug class, which Steve Bjorg ported over from C# and has been heavily bastardized by me (Roy Kim). The Result object wrapper comes from Guerric Sloan.

Todos

Here's a laundry list of things to do:

1. Add hooks for WordPress' "Pages" as well (should be trivial)
2. Add better explicit error messages for failed states - is there a way to do this cleanly in WordPress? (and appropriate i18n of the msgs)
3. Also read and send attachments to posts as file attachments to Deki
4. Account synchronization (!)
5. Add support for WordPress drafts - it should create a page, but use Deki's permissions to set to "Private" (this will probably require #5)

(if you'd like to help, email royk@mindtouch.com)