Movable Type User Manual: PROGRAMMATIC INTERFACES

« Table of Contents

• PROGRAMMATIC INTERFACES
  • XML-RPC API
  • Perl API
  • Plugins

PROGRAMMATIC INTERFACES

XML-RPC API

Movable Type features a full implementation of the Blogger XML-RPC API (where applicable). The only two methods that are not supported by Movable Type are getTemplate and setTemplate, due to the differences between Blogger's template system and Movable Type's template system.

Movable Type also supports the metaWeblog XML-RPC API (also where applicable).

Finally, Movable Type also adds a couple of other methods of its own for manipulating the categories assigned to your entries.

Usage of any of these XML-RPC APIs requires that your webserver have both LWP::UserAgent and SOAP::Lite installed; if yours does not, the Installation Instructions can tell you how to install them.

Following are the XML-RPC methods supported by Movable Type:

• blogger.newPost
  Description: Creates a new post, and optionally publishes it.

  Parameters: String appkey, String blogid, String username, String password, String content, boolean publish

  Return value: on success, String postid of new post; on failure, fault

• blogger.editPost
  Description: Updates the information about an existing post.

  Parameters: String appkey, String postid, String username, String password, String content, boolean publish

  Return value: on success, boolean true value; on failure, fault

• blogger.deletePost
  Description: Deletes a post.

  Parameters: String appkey, String postid, String username, String password, boolean publish

  Return value: on success, boolean true value; on failure, fault

• blogger.getRecentPosts
  Description: Returns a list of the most recent posts in the system.

  Parameters: String appkey, String blogid, String username, String password, int numberOfPosts

  Return value: on success, array of structs containing ISO.8601 dateCreated, String userid, String postid, String content; on failure, fault

  Notes: dateCreated is in the timezone of the weblog blogid

• blogger.getUsersBlogs
  Description: Returns a list of weblogs to which an author has posting privileges.

  Parameters: String appkey, String username, String password

  Return value: on success, array of structs containing String url, String blogid, String blogName; on failure, fault

• blogger.getUserInfo
  Description: Returns information about an author in the system.

  Parameters: String appkey, String username, String password

  Return value: on success, struct containing String userid, String firstname, String lastname, String nickname, String email, String url; on failure, fault

  Notes: firstname is the Movable Type username up to the first space character, and lastname is the username after the first space character.

• metaWeblog.newPost
  Description: Creates a new post, and optionally publishes it.

  Parameters: String blogid, String username, String password, struct content, boolean publish

  Return value: on success, String postid of new post; on failure, fault

  Notes: the struct content can contain the following standard keys: title, for the title of the entry; description, for the body of the entry; and dateCreated, to set the created-on date of the entry. In addition, Movable Type's implementation allows you to pass in values for five other keys: int mt_allow_comments, the value for the allow_comments field; int mt_allow_pings, the value for the allow_pings field; String mt_convert_breaks, the value for the convert_breaks field; String mt_text_more, the value for the additional entry text; String mt_excerpt, the value for the excerpt field; String mt_keywords, the value for the keywords field; and array mt_tb_ping_urls, the list of TrackBack ping URLs for this entry. If specified, dateCreated should be in ISO.8601 format.

• metaWeblog.editPost
  Description: Updates information about an existing post.

  Parameters: String postid, String username, String password, struct content, boolean publish

  Return value: on success, boolean true value; on failure, fault

  Notes: the struct content can contain the following standard keys: title, for the title of the entry; description, for the body of the entry; and dateCreated, to set the created-on date of the entry. In addition, Movable Type's implementation allows you to pass in values for five other keys: int mt_allow_comments, the value for the allow_comments field; int mt_allow_pings, the value for the allow_pings field; String mt_convert_breaks, the value for the convert_breaks field; String mt_text_more, the value for the additional entry text; String mt_excerpt, the value for the excerpt field; String mt_keywords, the value for the keywords field; and array mt_tb_ping_urls, the list of TrackBack ping URLs for this entry. If specified, dateCreated should be in ISO.8601 format.

• metaWeblog.getPost
  Description: Returns information about a specific post.

  Parameters: String postid, String username, String password

  Return value: on success, struct containing String userid, ISO.8601 dateCreated, String postid, String description, String title, String link, String permaLink, String mt_excerpt, String mt_text_more, int mt_allow_comments, int mt_allow_pings, String mt_convert_breaks, String mt_keywords; on failure, fault

  Notes: link and permaLink are both the URL pointing to the archived post. The fields prefixed with mt_ are Movable Type extensions to the metaWeblog.getPost API.

• metaWeblog.getRecentPosts
  Description: Returns a list of the most recent posts in the system.

  Parameters: String blogid, String username, String password, int numberOfPosts

  Return value: on success, array of structs containing ISO.8601 dateCreated, String userid, String postid, String description, String title, String link, String permaLink, String mt_excerpt, String mt_text_more, int mt_allow_comments, int mt_allow_pings, String mt_convert_breaks, String mt_keywords; on failure, fault

  Notes: dateCreated is in the timezone of the weblog blogid; link and permaLink are the URL pointing to the archived post

• metaWeblog.newMediaObject
  Description: Uploads a file to your webserver.

  Parameters: String blogid, String username, String password, struct file

  Return value: URL to the uploaded file.

  Notes: the struct file should contain two keys: base64 bits (the base64-encoded contents of the file) and String name (the name of the file). The type key (media type of the file) is currently ignored.

• mt.getRecentPostTitles
  Description: Returns a bandwidth-friendly list of the most recent posts in the system.

  Parameters: String blogid, String username, String password, int numberOfPosts

  Return value: on success, array of structs containing ISO.8601 dateCreated, String userid, String postid, String title; on failure, fault

  Notes: dateCreated is in the timezone of the weblog blogid

• mt.getCategoryList
  Description: Returns a list of all categories defined in the weblog.

  Parameters: String blogid, String username, String password

  Return value: on success, an array of structs containing String categoryId and String categoryName; on failure, fault.

• mt.getPostCategories
  Description: Returns a list of all categories to which the post is assigned.

  Parameters: String postid, String username, String password

  Return value: on success, an array of structs containing String categoryName, String categoryId, and boolean isPrimary; on failure, fault.

  Notes: isPrimary denotes whether a category is the post's primary category.

• mt.setPostCategories
  Description: Sets the categories for a post.

  Parameters: String postid, String username, String password, array categories

  Return value: on success, boolean true value; on failure, fault

  Notes: the array categories is an array of structs containing String categoryId and boolean isPrimary. Using isPrimary to set the primary category is optional--in the absence of this flag, the first struct in the array will be assigned the primary category for the post.

• mt.supportedMethods
  Description: Retrieve information about the XML-RPC methods supported by the server.

  Parameters: none

  Return value: an array of method names supported by the server.

• mt.supportedTextFilters
  Description: Retrieve information about the text formatting plugins supported by the server.

  Parameters: none

  Return value: an array of structs containing String key and String label. key is the unique string identifying a text formatting plugin, and label is the readable description to be displayed to a user. key is the value that should be passed in the mt_convert_breaks parameter to newPost and editPost.

• mt.getTrackbackPings
  Description: Retrieve the list of TrackBack pings posted to a particular entry. This could be used to programmatically retrieve the list of pings for a particular entry, then iterate through each of those pings doing the same, until one has built up a graph of the web of entries referencing one another on a particular topic.

  Parameters: String postid

  Return value: an array of structs containing String pingTitle (the title of the entry sent in the ping), String pingURL (the URL of the entry), and String pingIP (the IP address of the host that sent the ping).

• mt.publishPost
  Description: Publish (rebuild) all of the static files related to an entry from your weblog. Equivalent to saving an entry in the system (but without the ping).

  Parameters: String postid, String username, String password

  Return value: on success, boolean true value; on failure, fault

NOTE: the value of appkey is ignored by Movable Type in all of the Blogger XML-RPC methods.

You can use Movable Type's XML-RPC implementation with existing tools like w.bloggar, BlogApp, BlogLet, BlogBuddy, Jericho, etc. For example, to set up BlogBuddy to post to your Movable Type weblog, follow these instructions:

1. Download BlogBuddy from http://blogbuddy.sourceforge.net/. Unpack the archive, and install the application.
2. Open the BlogBuddy application.
3. Select General Settings from the Settings menu. On the General tab, enter your Movable Type username in UserName, and your password in Password.
4. In the Remote Host tab, enter the name of the host where your version of Movable Type is installed into Host name, and the path to mt-xmlrpc.cgi into Endpoint. For example, if mt-xmlrpc.cgi is located at http://www.foo.com/bar/mt-xmlrpc.cgi, you should enter www.foo.com into Host name, and /bar/mt-xmlrpc.cgi into Endpoint. If your webserver runs on a port other than 80, you should also change the port setting.
5. In the Blogs tab, click the Update blogs button; BlogBuddy will contact Movable Type on your webserver, and ask it for a list of weblogs which you have access to (using getUsersBlogs, above).
6. You can now post to your Movable Type weblog(s) using BlogBuddy's posting interface.

Perl API

The Movable Type code is written in an object-oriented style and contains a well-documented Perl API that you can use in your own Perl programs. The documentation itself is in POD format and is contained within the .pm files. You can read this documentation from the shell using the perldoc command. For example:

% cd /lib
% perldoc MT

Plugins

Movable Type's plugin framework makes it easy to add new tags to the system. In the future, more callback functionality will be added.

Plugin files are Perl scripts placed in a special directory; when Movable Type is initalized, it loads all of the plugins, which can modify the Movable Type code and system at runtime. Only files with .pl extensions are considered plugins and loaded automatically.

Your plugins directory should be placed in the same directory as mt.cgi.

To create that directory, connect to your FTP server, and open the directory where you installed Movable Type. Create a new directory called plugins.

• Variable Tags
  Here is a sample plugin that you can use to test whether your plugins directory is set up properly.
  1. Save the following in a file called load.pl:

     use MT::Template::Context;
     MT::Template::Context->add_tag(ServerUptime => sub { `uptime` });
     1;
     

  2. Upload load.pl into your plugins directory.
  3. In one of your Movable Type templates, add the following:

     Uptime: <$MTServerUptime$>
     

  4. Rebuild that template, then look at it on your browser. It should include the output from your system's uptime command.

  This is just a very simple example of a new tag that you can add. The plugin framework is not limited to adding tags that call system commands.

• Container Tags
  Here's an example of a plugin that creates a container tag:

  MT::Template::Context->add_container_tag(Loop => sub {
      my $ctx = shift;
      my $res = '';
      my $builder = $ctx->stash('builder');
      my $tokens = $ctx->stash('tokens');
      for my $i (1..5) {
          $ctx->stash('i_value', $i);
          defined(my $out = $builder->build($ctx, $tokens))
              or return $ctx->error($ctx->errstr);
          $res .= $out;
      }
      $res;
  });
  MT::Template::Context->add_tag(LoopIValue => sub {
      my $ctx = shift;
      $ctx->stash('i_value');
  });
  

  It can be used like this in a template:

  
  The value of I is: <$MTLoopIValue$>
  
  

  And it will display:

  The value of I is: 1
  The value of I is: 2
  The value of I is: 3
  The value of I is: 4
  The value of I is: 5
  

• Conditional Tags
  Conditional tags are technically just container tags, but in order to make it very easy to write conditional tags, you can use the add_conditional_tag method. This method takes two arguments: the name of the tag, and a reference to a subroutine which should return true if the condition is true, and false otherwise.

  For example, the following will add 3 tags: , which always displays its contents; , which never displays its contents; and , which must be used in entry context, and which only displays its contents if the entry has a title.

  use MT::Template::Context;
  MT::Template::Context->add_conditional_tag(IfYes => sub { 1 });
  MT::Template::Context->add_conditional_tag(IfNo => sub { 0 });
  MT::Template::Context->add_conditional_tag(EntryIfTitle => sub {
      my $e = $_[0]->stash('entry') or return;
      defined($e->title) && $e->title ne '';
  });
  

  These tags can be used like this:

  Yes, this appears.
  No, this doesn't appear.
  
  
  This entry has a title: <$MTEntryTitle$>
  
  
  

• Global Filters
  You can use the add_global_filter method to add a global tag attribute. For example:

  MT::Template::Context->add_global_filter(rot13 => sub {
      (my $s = shift) =~ tr/a-zA-Z/n-za-mN-ZA-M/;
      $s;
  });
  

  Which can be used like this:

  <$MTEntryTitle rot13="1"$>
  

  The anonymous subroutine is passed three arguments: the scalar value of the tag to be filtered, the value of the argument supplied to the attribute, and the MT::Template::Context object. As an example of the second argument, if we invented a filter called foo, and called it like this:

  <$MTCommentAuthor foo="5"$>
  

  the second argument to the callback routine would be 5.

Plugin tags could be written to display RSS feeds, display server status information, implement a hit counter, etc. You can download plugins from http://www.movabletype.org/resources.shtml.