On Sunday evening I got my first chance to look inside the Structured Blogging plug-in, and so I started to poke around. In this kind of situation my technique is usually task-based. I start by thinking about something that I would like to do (some feature that I would like to add, remove or change, for example) and then see if I can figure out what needs to be done to accomplish this.

In this case the process was made easy because there were at least three features that I really did want to change from the moment I installed the plug-in. These were:

1. The look of the page that is generated. I wanted the book cover and the book details to be next to each other in two columns.
2. The use of excerpts. The plug-in insists on using the entire review (including the illustration) as the excerpt for an entry, which simply doesn’t fit in with my theme. I wanted a proper excerpt, which meant adding an excerpt field to the administration page and then hooking it into the dataflow.
3. The need to write html. In WordPress 2.1.2 there is no wysiwyg console or menu bar on the plug-in editing page. I want one.

In the three evenings I spent playing with this I have managed to fix the first two items, leaving the third one to skulk around my to-do list for a while. I now understand something about the way the plug-in works, and how the xml and html are parsed and reconstructed. I also think I understand some of the theoretical concerns driving its development.

I think there are still problems that need to be ironed out before the plug-in will achieve widespread adoption. The apparent need to write html is one. The in-built tagging system is another.

I use Ultimate Tag Warrior and, for the moment, I have simply suppressed the display of the internal tags. However, the next major upgrade of WordPress is supposed to be going to have its own internal tagging system. If this turns out to be true then the whole question of how to include tags in the structured data will need to be readdressed.

I have spoken to Johnny Bistrom about all this, and we are going to consider if (and how) we can contribute to the development of the structured blogging project. Hopefully we will, at the least, be able to conrtibute to the effort to keep the WordPress plug-in up to date.

What follows are notes describing what I have done to the plug-in so far. They are partly to help me remember, and partly to inform the Broadband Mechanics, and anyone else who is interested. If (or when) I resolve the third issue then I will consider submitting the revisions as a possible official upgrade.

Restyling the page

Looking at the page source for a book review page made it clear that restyling the page was going to require more than a few alterations to the css style sheet. Some of the divs had no classes and the information was in the “wrong” order. The book title came before the illustration, whereas I needed it to come afterwards.

I therefore changed the way that the html was created. This was done in the display element in \wpsb-files\microcontent\ descriptions\ review-book.xml by adding div elements at the right place inside the xml. I created new divs (all with named classes) in order to be able to display the product image and product details in two columns.

I then added four new styles to the style sheet. I suspect that the final one #product-details-text may be superfluous. I may well look at the layout again and rethink it slightly.

Adding an Excerpt

The fields that are displayed in the administration page are determined not by a php file but by the xml description of each type of page. I therefore added a line to both the display and editor elements in \wpsb-files\microcontent\ descriptions\ review-book.xml

In the display element the line is <if content="excerpt"><p></p></if> which suppresses the display of the excerpt as part of the display of the content. (I altered the line below to similarly suppress the display of tags.)

In the editor element the line sits between the lines for description and tags, and is <field label="Excerpt" content="/review/excerpt" type="excerpt" cols="95" width="97%"/>

This in turn requires the addition of a new function in \wpsb-files\microcontent\mc_renderers.php I duplicated the MCTextarea function that is used to create the description field, renamed it MCExcerpt, and altered the height.

As a result of this the excerpt field was created, and any text entered there was stored as part of the structured information. When the edit page was opened again this text was placed correctly into the excerpt field.

Next I went to \wp-admin\sb-post-common.php and wp-admin\sb-post-review.php and removed any references to the $excerpt variable. This stopped the plug-in from filling the WordPress post_excerpt database field with the main content.

Experiment showed that if I entered some text by hand into the post_excerpt field in the database then WordPress showed it as normal. The final stage, therefore, was to work out how to duplicate the information in the excerpt field and have it entered into the database properly.

This required two steps. The first step altered what was returned from MCExcerpt. I amended the last two lines of the function so that they looked like this:

$excerpt_field_name = $this->_encodeFieldName($contentPath);

return '<textarea name="' .$excerpt_field_name. '" cols="'.$cols.'"'.$width.' rows="5">' . $dataValue . '</textarea><br /><input type="hidden" name="excerpt-field-name" id="excerpt-field-name" value="'.$excerpt_field_name.'" />';


This created a hidden field with a value that was the name of the excerpt field (which may change according to what kind of page is being written).

Finally I used this to grab the content of the field and post it. This required an addition to \wp-admin\sb-post-common.php at about line 415, like this:

$excerpt_to_go_field = $_POST['excerpt-field-name'];
$excerpt_to_go = $_POST[$excerpt_to_go_field];

$result = $wpdb->query("
UPDATE $wpdb->posts SET
post_content = '$content',
post_excerpt = '$excerpt_to_go',
...and so on

Then, late last night, it all worked.

Conclusion

Whether this is the way that the alterations should have been done is a matter for conjecture. Since I was not party to the original design decisions it is impossible for me to say.

I am aware that the original design may have left out the ability to create an excerpt for specific conceptual or philosophical reasons. Or it may simply be that the original authors didn’t use excerpts and so felt no need to add them.

I am also aware that my modified div structure may be as unsatisfactory to some people as the original was to me. I suspect that, with a bit more effort, it would be possible to produce a truly flexible structure that would allow for many different configurations.

For the moment, though, I am just glad that the pages here work approximately the way I want them to.