Header: StructuredBlogging.org

Resources

For developers, there are two main usages for Structured Blogging:

  1. Building Structured Blogging into your own software platform.
  2. Making new microcontent types.

We’ll outline how to use Structured Blogging in those ways, plus we’ll explain how to convert the Structured Blogging XML into other formats (like RDF).

Before you read this document

This will make a lot more sense if you first use a Structured Blogging plugin to create a piece of microcontent, then "view source" on the resulting HTML to see how it is marked up with microformats, and followed by a chunk of XML inside a <script type="application/x-subnode; charset=utf-8"> block.

code example
Code example

Using Structured Blogging in your own software

The Structured Blogging plugins incorporate microcontent editing and display libraries.

PHP developers

If you are using PHP, you can use the library inside the Wordpress plugin.

See /wp/wpsb-files/microcontent/microcontent.php, which is called from /wp/wp-admin/sb-edit-form.php.

Perl developers

If you are using Perl, you can use the Movable Type plugin's library.

See /mt/plugins/StructuredBlogging/lib/MicroContent.pm, which is called from /mt/plugins/StructuredBlogging/StructuredBlogging.pl.

How microcontent types are defined

The microcontent types are defined by the XML files inside the 'descriptions' subdirectory:

/mt/plugins/StructuredBlogging/descriptions

or

/wp/wpsb-files/microcontent/descriptions

Microcontent types and XML formats

If you are not using PHP or Perl (and can't wait for us to produce a library for you!), here are details on how to interpret the XML files. This will also tell you how to generate editing interfaces and displays for the microcontent formats.

MCD: Micro-Content Description file

Each microcontent type editable with a Structured Blogging plugin, is defined by an MCD ("micro-content description") file. We’re currently working on a tool to generate schema for the XML that you produce. For the time being, refer to the MCD files for details on the XML formats.

Each MCD file has a root element of <micro-content>, under which are two elements: <editor> and <display>.

Table: Elements of the MCD file

Elements

Description

<micro-content>

The root element

<editor>

The <editor> element is an HTML template for the editing form of the microcontent type. It can contain XHTML, plus <group> and <field> elements.

<field>

Each <field> element refers to an input field. It must have a "content" attribute, which specifies the XPath to where the data will be stored, and may also have any of the following optional attributes:

  • "type": this can be "text", "textarea", "datetime", "date", or "uploadfile".
    • "text" is the default.
    • "textarea" fields are displayed as HTML textareas. They can have "cols" and "rows" attributes, to set the size in characters, and can be defined to fill available space with the "width" attribute.
    • "datetime" fields store a date and a time.
    • "date" fields store a date (but no time).
    • "uploadfile" fields allow the user to upload a file. They can have a "filetype" attribute, which can be "image", "audio" or "video". If set to "image", a preview image will be shown in the editing form.
  • "select" field displays as pulldown lists. Specify the list options with <option> elements inside the <field>.

    For example:
    <field content="license" type="select"><option name="cc-by">Creative Commons Attribution</option><option name="cc-by-sa">Creative Commons ShareAlike</option></field>

<group>

The <group> element is used to define the default XML path of <field> elements, and to set display style for a block of elements.

For example:
<group content="/review"><field content="description" type="textarea"/></group> is equivalent to <field content="/review/description" type="textarea"/>

If you wish to have input fields arranged horizontally (rather than the default, vertically), put them inside a <group orientation="horizontal"> element.

<display>

The <display> element is used when rendering the microcontent as HTML.

As with <editor>, it can contain HTML, <group> and <field> elements. Their behaviour is generally the same, apart from the following exceptions:

  • Where <field content="/foo" type="select"> is used in <editor>, use <field-map content="/foo"><map input="option-value" output="Option Text"/></field-map>.

    The example given for "select" field types would look like: <field-map content="license"><map input="cc-by" output="Creative Commons Attribution"/><map input="cc-by-sa" output="Creative Commons ShareAlike"/></field>
  • Display images with <field type="image" content="/path/to/image/url"/>.
  • Generate links (and set attributes) like this: <a><attribute name="href"><field content="/path/to/url"/></attribute><field content="/path/to/linktext"/></a>


X-Subnode: Embedding XML in HTML

When publishing a piece of microcontent in structured XML form, a method of embedding the XML inside HTML is required. Structured Blogging uses the HTML <script/> tag.

X-Subnode is used for two main reasons:

1) We can declare a script type that will both (1) identify the content, and (2) associate it with text content in the HTML page; and

2)It's designed to be ignored by browsers if they can't process the content.

Here’s an example:

<script type="application/x-subnode; charset=utf-8">

<subnode alternate-for-id="sbentry_1">

...

</subnode>

</script>

Because the script tag is HTML, we can embed it in the blog page itself - as well as in the ‘description’ and ‘content’ elements of syndication formats.

More about the x-Subnode script type

The x-subnode script type represents the simplest possible script processing language.

It is designed to substitute the enclosed content for the node in the enclosing HTML, with the given tag ID. Most browsers will simply ignore the x-subnode script tag - following the HTML specification that if a browser doesn't have an appropriate language processor, then it can safely ignore a script tag.

However if a browser or browser plug-in had a processor for the x-subnode language, it could implement any number of applications on top of the structured content. Here are some examples:

· Comparison shopping

· Collaborative filtering

· Checking tickets

· Showtimes

· Etc...

For reference, a simple XSLT implementation of a script processor will be available for download soon.

The purpose of X-Subnode

The purpose of the x-subnode script block is to embed valid XML in the HTML content, in a way that is compatible with both HTML and XML and is not displayed or processed by browsers. It is important that the content remain valid XML, so parsing applications can recognize and process it. Therefore the contents can't be escaped or enclosed in an HTML comment.

Reference: Old Structured Blogging Schema Types

The original Structured Blogging plugin published reviews and events using the following schemas. They are retained here for reference, along with an XML schema for the <xml-structured-blog-entry/> element, which is still used.

The base type is <xml-structured-blog-entry/>. This type is an envelope or container for the structured blog types; the defined types (for the moment) are <simple-event/> and <simple-review/>.
For Developers
- Resources
- Formats & Support

Supporters:

For information about joining the initiative contact: info@structuredblogging.org