Although the vast majority of MarsEdit users are using it to manage posts on one of the big publicly available blogging systems, there are a good number of users, especially in the tech community, who run their own custom blog or blog-like software. I’ve received several private inquiries and this public one, all asking about the steps required to get MarsEdit working with a custom piece of hosting software.
Many have suggested that it would help for MarsEdit to support some kind of plugin system whereby custom software authors could develop a script or piece of code to help MarsEdit interface with the site. This general line of thinking is the right one, but the plugin is probably more appropriate for the server than for the client.
So how do you get MarsEdit working with your custom server software? You adopt a standard API and implement it for your site, in the form of a “xmlrpc.php” type file that accepts POST requests from MarsEdit and returns the appropriate responses. This isn’t as hard as it sounds, because there are really only a few calls involved. And after all, I assume if you’ve got a custom solution already, you know your way around a bit of web programming (or you know somebody who does!).
The best part is that by adopting a standard API, you’ll be prepared to work with other clients besides just MarsEdit. I mean, you’d be crazy to not use MarsEdit, but I’d rather keep you as a happy customer than a locked-in one!
Pick An API
The first thing you’ll need to do is choose a publicly documented API to implement. The choice is yours, but if you have no clue about which to adopt, I’d probably recommend the MetaWeblog API. You’ll be in good company, since some major services such as WordPress and Microsoft Spaces use the API for their remote editing support.
Observe A Working Case
Once you’ve settled no an API, I suggest setting up a working test blog that uses the API. That is, get a free blog somewhere, set it up and throw a few test posts up. Now you have a working case to compare your custom implementation against.
MarsEdit makes it easy to examine the chit-chat that goes on between it and a given blog publishing system. From the Window menu select “RPC Console”, and you’ll see a verbose transcript of all the messages sent from and received by MarsEdit:
Now you’ve got a working case to compare everything against as you iron out the details in yoru custom script.
Write Your Custom Script
Start small. Very small. Just write a simple CGI script that accepts a HTTP POST request from MarsEdit and prints out the cargo of the request. You’ll see that it matches exactly what showed up in the RPC Console. From here I would start with a single API call, probably the “getRecentPosts” call, and build your way up from there. Once you’ve got getRecentPosts working you’ll be able to see your list of blog entries show up in MarsEdit, which will surely inspire you to finish the rest!
If you get completely stuck, the good news is there are lots of working code examples out there as well. For instance, take a stroll down Google Code Search way on the MetaWeblog term. Be mindful of the licensing of any code you find, as always.
Configure MarsEdit For Your Blog
You’ll actually do this as soon as you’ve got your first very small test-case of a script finished. Just click the + button beneath MarsEdit’s list of blogs to add a new one, and specify the name and URL. Obviously MarsEdit will fail to obtain meaningful information about the blog, so you’ll have to edit the information manually. Assuming I set up a custom blog using MetaWeblog, the settings window might look like this:
(Note: The appearance of this dialog is slightly different in 1.1.3 and earlier. Look for this new layout in MarsEdit 1.1.4 and later)
Extra Credit: Really Simple Discovery
If you want to spare yourself and future users of your software from the pain of manually entering the data into the settings dialog, you can describe your blog’s API support by embedding in the home page a “rel” tag identifying a specially-formatted file called an RSD file. This stands for Really Simple Discovery, and is a format which MarsEdit can read to automatically determine which standard API your system uses.
Any questions I didn’t cover? Feel free to ask in the comments.