isoTope Documentation: Mime-type handler API

This is a very simple API to handle the different mime-types allowable in the content, summary and title elements of an Atom entry.

Basically each mime-type handler must implement a means of storing the data, and returning it in the required output format, be it entity-escaped HTML, plain text, an XML representation, or a DOM representation.

The base implementation comes with a number of mime-type handlers including:

• text/plain - for plain text and/or wiki formats
• text/html - for handling HTML content
• application/x.opml+xml - for handing OPML content
• application/x.oml+xml - for handling OML content

The design criteria was to keep content within lightweight method-less value objects (containers), where the methods are implemented in the mime-type handler class.

---

Each mime-type is keyed by a mime-type key. This is a short keyword for a particular mimetype that is used as array keys and as part of a filename. For example the OML format can have the mime-type prefix of oml. The source file would then be handlerOml.php, and the class name would be OmlHandler.

Classes

Each mime-type handler is a PHP class (in a file called handler{MimeTypeKey}.php) in the format:

class {MimeTypeKey}Handler extends BaseClassHandler {

}
				

---

Variables

$container

Contains either plain text, or a reference to a content container class

$containerType

The type of container. Either "text" or "obj"

---

Functions

The following functions MUST be implemented in each mime-type handler class:

parseContent(&$domNodeReference)

This method takes a node reference from a DOM structure and extracts all the needed information, storing it within the mime-type handler class (or objects defined in it).

string getContentAsHtml()

This method returns the mime-type handler's content as a string of HTML. The details, layout and structure of the content is entirely up to the handler, as long as the returned string can be inserted into an HTML page.

The following functions SHOULD be implemented in each mime-type handler class:

insertContentInDom(&$domNodeReference)

This method takes a node reference (typically to the atom:content element) and populates the child node(s) with the content, using standard DOM methods.

The input node is the content node, so both the mode and the type can be retrieved. This can be used to determine whether to return XML, plain text or base64. This function can overwrite both the mime-type and mode of the content node.

string getContent()

This method returns the content as a string. Each handler must decide on the mode of that string - whether that string is plain text, xml or base64 encoding.

---

Registering a mime type handler

In the source file atom.config add a line in the $mimeType array. The key is the mime-type key (for example oml), the value is the actual mime-type (for example application/x.oml+xml). This array is used to determine if there is a handler available for a specific mime-type.

Further down in the source file atom.config add a line in the $mimeTypeHandler. The key is the mime-type key (oml), the value is essentially identical to the mime-type key but with a leading capital letter (e.g. Oml). This array is used to determine which handler class to use for an identified mime-type.

Further down in the atom.config add a line in the $hierXml array. The key is the mime-type key, the value is the name of the top level element of that vocabulary. For example, every HTML file starts with html as the top level element.

After that, all entries using your new mime-type format can now use your handler class.

Note-to-self: This should probably be simplified somewhat, perhaps an array per mime-type

---