" /> ecto: June 29, 2008 - July 5, 2008 Archives

« March 30, 2008 - April 5, 2008 | Main | August 17, 2008 - August 23, 2008 »

July 3, 2008

Writing your own formatter

Some blog systems (Drupal, MovableType, TypePad) provide a blog client (such as ecto) with a list of available text formats. This allows the user to write a post in ecto using, for example Markdown, and have ecto inform the blog system on publish that it should interpret the text as Markdown.

Markdown and Textile formatters are built into ecto, so that when you preview your post the text is correctly converted to HTML. You can, however, create custom formatters for any formats that your blog system uses but isn't handled by ecto (e.g. MathML).

To get you going, I have made the source code of the Markdown formatter available.

Once you've downloaded and unpacked the sample, rename the project. Ideally, you'd use the name of the format provided by your blog system. Let's assume your formatter will be called MathML. In the Finder, rename "Markdown.xcodeproj" to "MathML.xcodeproj". Double-click the file to open it. Make sure to use the Release build configuration. In the Groups & Files list, click on "Markdown" under the "Targets" section. Select File → Get Info. Under "Build", find the values for "Product Name" and "Prefix Header" and rename them. Under "Properties", assign a unique identifier, e.g. com.thirdparty.ecto_mathml and change the principal class to "MathML". Close the Get Info window.

Back in Groups & Files, rename any files containing "Markdown" so that they contain "MathML". You will then have to rename the class names inside those files as well. In other words, class Markdown becomes MathML, and so forth.

Do NOT rename "FormatterInterface.h" and do NOT rename the "ECTOFormatterProtocol" protocol name.

In Markdown.m, you will also need to change the code for "-(NSString*)formatterKey", "-(NSString*)formatterDescription" and "-(BOOL)willHandleFormat".

The formatter plug-in has one entry point: "- (NSString*)formatText:(NSString*)source". That's where the conversion to HTML happens. For Markdown, I used Perl scripts, which are accessed via a pipe. See the code for details.

Some blog systems, such as WordPress, do not provide a list of formatters. When you preview posts in ecto written for these blog systems, ecto uses a special built-in formatter, Generic.formatter. It analyzes the text and will format accordingly (it recognizes Markdown and Textile). You could write your own Generic.formatter and install it into ~/Library/Application Support/ecto3/formatters/ and it would override the built-in version.

If you have any questions about writing a formatter, please visit the Developer support forum.