Phillip Pearson - web + electronics notes

For the last couple of months, we (along with XML expert Kimbro Staken and Movable Type consultant Chad Everett) have been working on extending the Structured Blogging plugin for Wordpress to publish a bunch of new microcontent types, support microformats and other standards like Media RSS, and leave the door open for translating the structured data into other formats like OPML (when a standard for that emerges) and RDF (which Danny Ayers is hacking on already), and building a whole new plugin for Movable Type to do the same thing.

Today I'm talking about how the Wordpress plugin is structured - and explaining what the files do. This isn't the final version, so there's still some cruft in there that we'll get rid over the coming days/weeks, but it's close enough for me to be able to explain it as-is and hopefully not have to totally rewrite the explanation a month later. Fingers crossed!

The files:

First, we've got some docs and status info:

SB-LICENSE.txt
SB-README.txt
SB-VERSION.txt

- - -

Then there's the plugin itself:

wp-content/plugins/structuredblogging.php

This:

• Adds some new items to the Wordpress 'Write' menu.
• Adds a filter at the start and another at the end of the the_content filter chain, to insert a chunk of XML into the content and make sure it doesn't get mangled by other filters.
• Insert a stylesheet into the display pages.
• Redirect the user into our own editing pages if they edit a post with structured content.
• Insert extra elements into RSS feeds.

- - -

Now we have the aforementioned editing pages:

wp-admin/sb-post.php
wp-admin/sb-post-common.php
wp-admin/sb-post-thing.php
wp-admin/sb-edit-form.php

These are used for the new microcontent types, so as you go across the 'Write' menu you see the usual Write Post and Write Page, which go to the usual places (post.php and page-new.php), followed by the following additions, which are all handled by sb-post.php:

• Review (takes you to a list of review types that you can create; clicking on one takes you to its own posting form)
• Event (takes you to a list of event types, linked in the same way)
• List (takes you to a list of list types - blogrolls etc)
• Audio (takes you straight to the post form for the 'audio' media type)
• Video (takes you straight to the post form for the 'video' media type)
• People Showcase (takes you straight to the 'people showcase' post form)
• Group Showcase (takes you straight to the 'group showcase' post form)
• Other microcontent (takes you to a full menu of all the microcontent you can create with the plugin)

- - -

... which use the core of the system, the microcontent editing and rendering library. This interprets XML files to generate editing forms and XML + XHTML + RSS that stores the microcontent in human- and machine-readable form.

wpsb-files/microcontent/microcontent.php
wpsb-files/microcontent/mc_renderers.php

This makes the system extremely flexible. Supporting microformats, for example, is being done on the output end by adding class attributes in the appropriate places in the display XHTML templates. There's another section (code going in tonight with any luck...) that lets you add elements into the RSS feed (we haven't done Atom or RDF yet, but we will if we can find a microcontent type that would benefit from it).

The microcontent is stored internally as a chunk of XML, and manipulated using an XPath library. We also output this XML in the post content and the feed, so (in future - not implemented yet) it can be picked up and edited / republished by another blog running a Structured Blogging plugin. The plugin also lets you send copies of your posts via a redirector service and the metaWeblog API or Atom API to other blogs, which should bootstrap this sort of activity.

- - -

Here are the XML files - one for each type of microcontent, plus a few extra 'testing' ones that don't display in the system but are useful to show aspects of the microcontent library and might be useful in future.

Each XML file (we call them MCDs - microcontent descriptions) contains an editing template (kind of like in XForms) and at least one display template (greatly simplified XSLT). So with this system, anyone can create their own microcontent type for publication via Wordpress or Movable Type just by making an MCD and copying it into the right directory.

wpsb-files/microcontent/descriptions/index.php
wpsb-files/microcontent/descriptions/showcase-person.xml
wpsb-files/microcontent/descriptions/review-event.xml
wpsb-files/microcontent/descriptions/media-video.xml
wpsb-files/microcontent/descriptions/event.xml
wpsb-files/microcontent/descriptions/event-conference.xml
wpsb-files/microcontent/descriptions/review-club.xml
wpsb-files/microcontent/descriptions/list.xml
wpsb-files/microcontent/descriptions/review-restaurant.xml
wpsb-files/microcontent/descriptions/list-xspf-playlist.xml
wpsb-files/microcontent/descriptions/review-book.xml
wpsb-files/microcontent/descriptions/list-links.xml
wpsb-files/microcontent/descriptions/review-software.xml
wpsb-files/microcontent/descriptions/review-magazine.xml
wpsb-files/microcontent/descriptions/review-cafe.xml
wpsb-files/microcontent/descriptions/review-album.xml
wpsb-files/microcontent/descriptions/media-image.xml
wpsb-files/microcontent/descriptions/review-website.xml
wpsb-files/microcontent/descriptions/review-song.xml
wpsb-files/microcontent/descriptions/showcase-group.xml
wpsb-files/microcontent/descriptions/review-hotel.xml
wpsb-files/microcontent/descriptions/review-localservice.xml
wpsb-files/microcontent/descriptions/list-songlist-detail.xml
wpsb-files/microcontent/descriptions/list-songlist.xml
wpsb-files/microcontent/descriptions/event-concert.xml
wpsb-files/microcontent/descriptions/media-audio.xml
wpsb-files/microcontent/descriptions/review-movie.xml

- - -

We have the script.aculo.us and Prototype Javascript libraries, and code to look up books etc on Amazon, and other things from various other places:

wpsb-files/prototype.js
wpsb-files/sb-lookup.js
wpsb-files/sb-lookup.xsl
wp-admin/sb-get.php
wpsb-files/effects.js
wpsb-files/slider.js
wpsb-files/builder.js
wpsb-files/quicktags.js
wpsb-files/scriptaculous.js
wpsb-files/dragdrop.js
wpsb-files/controls.js

This is pretty cool. You can enter the name of a book, movie or cd (among other things - Kimbro did this code so I'm not intimate with it) and click 'Lookup'. A window slides open and lists the results of a search on the most appropriate service for the product type, and lets you extract various details (images, ISBN numbers, etc) for your post.

- - -

Now some miscellaneous stuff: an options page, code to read entries created with the original (v0.5) Structured Blogging plugin, an XML-RPC library, and an XPath library:

wp-admin/sb-options.php
wp-admin/sb-post-event.php
wp-admin/sb-post-review.php
wpsb-files/microcontent/IXR_Library.inc.php
wpsb-files/microcontent/XPath.class.php

- - -

And finally, two stylesheets and a bunch of images for rendering ratings and some content types:

wpsb-files/wpsb-admin.css
wpsb-files/wpsb-style.css
wpsb-files/empty-star.gif
wpsb-files/full-star.gif
wpsb-files/book.gif
wpsb-files/calendar.gif
wpsb-files/cd.gif
wpsb-files/clock.gif
wpsb-files/movie.gif

- - -

Now, we've been told that this plugin forks Wordpress. Obviously that's a Bad Thing, and we definitely don't want to do that... the only problem is, I can't see what about what we've done could seriously count as a fork. We only add files, never replacing anything from WP, we use the plugin API, and bend over backwards with Javascript and output buffering hacks to avoid having to change core files.

The only thing I can think of that might look like that is the way we copied/modified post.php as sb-post-common.php to avoid yet more output buffering hackery. If this is not kosher, we could attempt to do all this by filtering the output from post.php, but it doesn't seem like such a big deal to me. If it were possible to add more plugin hooks into post.php so we could do it without any special hacking, that would be nice, but it's not something we can do with the current version of Wordpress. (We'd love to get it going in future, though).

Opinions?

Update: Cool - this just hit memeorandum ...