Archives

A WordPress Plugin – Hello XML-RPC World

In a previous post (How Can I Modify The WordPress XML-RPC System?) I outlined how one might create a plugin that adds functionality to the WordPress XML-RPC server. I’ve had some questions from some readers arise so I wanted to take the opportunity to provide a more concrete and usable example.

WordPress Plugin

First you are going to create your plugin. This can be a single file that follows all of the regular WordPress plugin flow. I have a complete plugin example listed below.

Of course, for simplicity sake in this post I’ve eliminated comment blocks. You’ll need those in order for your plugin to be properly recognized by WordPress. Other than that this is it. The wpHelloXMLRPCWorld method is the actual method that does the work of whatever you want. This one simply returns a hello world string. The attach_new_xmlrpc method is used to do the work of registering your new XML-RPC method. And finally we just need to add the action to tell WordPress to use our attach_new_xmlrpc method to attach our new XML-RPC function.

Testing With Java

I personally like the Redstone XML-RPC library, which I’ve written on before (Would You Like To Post To WordPress From Java?). This is a very simple Java class which can test the new XML-RPC function.

Download

This is a complete example that includes:

  1. The PHP file needed for the plugin. Just upload wpHelloXMLRPC.php to your wp-content/plugins directory and activate as usual for WordPress plugins.
  2. The Java program which can run your new XML-RPC method.
  3. A bat file (dos/Windows) that will compile the Java test program.
  4. A jar file containing the required Redstone libraries

wpHelloXMLRPC.zip

How Can I Modify The WordPress XML-RPC System?

One of the great things about WordPress plugin development is the abundance of open source content to learn from. Ever see a plugin in action and wonder, “how does that work?” or “How can I modify the WordPress XML-RPC system?” Well, all you have to do is download it and see! Most plugins are licensed under the GPL license (General Public License).

One of my recent projects involves working with the WordPress XML-RPC interface. The problem is I needed the XML-RPC interface to do more than the current implementation offered. Initially I wrote a patch for the xmlrpc.php file to accomplish what I needed. It never actually occurred to me that the smart folks at WordPress would actually give you a way to write hooks into the XML-RPC interface to add more functionality. Sweet! I came to this revelation thanks to a plugin called wpLinkMentor, a plugin that allows you to manage your blog links over XML-RPC.

Logging

An important part of most applications is logging, right? This provides an insight into what is going on with your program/plugin and can be extremely helpful in debugging problems you might encounter. The following snippet allows your plugin to make log entries into the standard WordPress XML-RPC log.

Error Handling

The way to handle errors in your XML-RPC plugin is to throw an IXR_Error which is somewhat like an exception in other languages.

Making The Magic Hook!

Ok, all of that is fine and dandy, but how do I hook into the XML-RPC system? Where’s the beef!? Here it is in all of it’s simplistic glory, just like most of the WordPress architecture.

I could not have imagined it being so simple. Just write your methods to do whatever you desire and them register them as in the previous code sample. Have you written any WordPress plugins that utilize the XML-RPC interface?

WordPress Posting Via Java – Part 2

In the first part of this series titled “Would You Like To Post To WordPress From Java?” I introduced you (hopefully) to the XML-RPC mechanism that WordPress implements. I also showed how it is quite simple to post to a WordPress blog using Java and the Redstone XML-RPC API. In this installation I’d like to expand the example a bit further.

First, however I’d like to apologize for posting non-working code. 🙁 I posted the example without actually compiling and/or testing it. If you downloaded and fixed the errors to get it to compile you also probably noticed that the method would not successfully login to your blog. Doh! I’ll be fixing those errors in the next version of the file, so hopefully you will walk away with something you can actually modify to your liking… and use.

Now, how about that last example? Did you notice anything lacking in the data that we posted. If you recall the method signature looks like this:

This is actually part of the problem with the first implementation. Looking into the xmlrpc.php file, the method starts looking for the blog_ID at array index 1… not zero. So the method signature should actually be like this:

I’m not sure what emptyData is supposed to be or even why it is there, but I just posted an empty string here and everything was great. The method doesn’t actually ever use that argument… odd.

Ok, back to the initial question… do you notice anything lacking? Sure, a lot of things are missing. Mainly and most blaring is the lack of a title. In the above and previous example all we are posting is the content. That’s no good. I would like to at a minimum be able to specify the title of my post. For that we will take advantage of the metaWeblog API calls. There is a similar function with the following signature:

First, this method does NOT contain the empty data argument. Secondly you’ll notice that instead of passing a string for content, we are passing a struct. So what type of data might this struct contain? It contains: title, link, description, author, category, comments, enclosure, guid, pubDate and source. Wow, that’s a lot more information! I won’t be covering all of these different data elements, but you can read more about them on the RSS 2.0 Specification on the Harvard Law IT Page. There are actually a few more elements than listed here which we will make use of in an upcoming post. 🙂 For now, however I am content to just have the title.

We’ll need to change the method we are calling:

We’ll need to create our content struct, which will be created using a

. Don’t worry, the Redstone serializers will convert this into the XML that we need. Nice!

Then finally there is the method call:

That’s it! Just a few simple changes to our original example (plus the bug fixes) and we now have a title. You can also play around with adding other elements such as a Category. Here is the working file if you would like to download the source.

XmlRpcPoster.java (1.68 KB)

XML-RPC Java Sample: Sorry About The Formatting

I just installed the WP-Syntax WordPress plugin for the last post. This was so I could have my sample Java code formatted and syntax highlighted in the post. Wow! I didn’t realize how bad it was going to be formatted. The plugin is nice and the syntax highlighting is good, but the code is formatted so that it runs off the page. Sorry… mah bad! This is probably due to the fact that it is in a <PRE> tag and so does not wrap any. You can still copy-n-paste the code from the blog entry to view it better.

So I figured I’d offer the code sample as a download for convenience. Again, sorry about that.

XmlRpcPoster.java (1.38 KB)

Would You Like To Post To WordPress From Java?

I use and love the WordPress platform for this and several other blogs that I maintain. One of the many cool features of WordPress is that it supports XML-RPC. What does that mean? Well XML is… XML. It’s the extensible markup language and is basically just a way of formatting data in some meaningful way. RPC stands for remote procedure call. That is making calls to methods/procedures on a remote system. Put them together and you get the idea… making method/procedure calls on remote systems using XML to bundle up the method calls and returns.

Great, now I have to write some sort of custom program to build an XML formatted message and submit it to WordPress. Then I have to have the same program be able to parse and decipher the return XML format. Well, no you don’t! There are already libraries that will do this for you. WordPress supports the Blogger API, the metaWeblog API and the MoveableType API. These are blog specific APIs that use XML-RPC to communicate. You could very easily download one of these, read the documentation and become productive with Java in no time at all. That was actually my first step. But wait… the APIs don’t support all of the same methods. Which one should I use?

I actually decided not to use any of the APIs mentioned above. Instead I went with the Redstone XML-RPC library. This API provides a layer of abstraction from all of the XML-RPC details that is nice and it also gives me the flexibility to implement any methods that I want. This will come in handy as you will see in a later post. For now though, how might I make a post using this API? Simple really. We’ll start out with the Blogger API method call. The method signature looks like this:

blogger.newPost(blog_ID, user_login, user_pass, content, publish)

The blog_ID is used for systems that maintain multiple blogs. There is actually a method we could call to get that piece of information called blogger.getUsersBlogs. Here’s a little secret though… WordPress doesn’t currently support this feature and is just hard-coded to be “1”. So for brevity sake I’ll just use that for now.

Wait a minute… there is no XML code anywhere in your example. Exactly! The Redstone API uses serializers to take the Object[] you provide and create the appropriate XML. Spiffy, eh? Not only that, but if the return type of the method call happens to be a struct, then the token will contain a Map that you can iterate over and retrieve values from.

I hope you enjoyed this little excursion into XML-RPC and Java. Stay tuned for my next post where I’ll be kicking this example up a notch to get more functionality and meta-data into our WordPress posting.