blogrpc

= blogrpc

BlogRPC is a set of XML RPC server facilities which allow you to easily create a blogging XML-RPC backend in your Ruby web application. Your application can then be used with blog clients like BlogJet and MarsEdit.

== Quickly defining a blog RPC handler

Define your blog handler right in the rackup file:

rpc_endpoint = BlogRPC.generate_endpoint do | handler |
    handler.rpc "mt.publishPost", :in => [:int, :string, :string], :out => :bool do | postid, user, pw |
      login!(user, pw)
      get_entry(postid).update_attributes :draft => false
      true
    end
end

run rpc_endpoint

or as a separate class:

class MyHandler < BlogRPC::BasicHandler
  rpc "mt.publishPost", :in => [:int, :string, :string], :out => :bool do | postid, user, pw |
    login!(user, pw)
    get_entry(postid).update_attributes :draft => false
    true
  end
end

rpc_endpoint = BlogRPC::RackApp.new(MyHandler.new)
run rpc_endpoint

== More involved examples

The gem consists of two parts. The first part is a Rack application that will handle XML-RPC requests and respond to them. It's primary role is an adapter between the old Ruby's XML-RPC library that ships with Ruby and the more modern Rack infrastructure.

It handles things like wrapping exceptions properly, detecting the needed parameters and configuring all of the IO so that Ruby's XML-RPC facilities can get at it. You use it like this:

rpc_endpoint = BlogRPC::RackApp.new(MyBlogHandler.new)
rpc_endpoint.blog_url = "http://site.com"
rpc_endpoint.rpc_endpoint_url = "/secret-rpc-url.xml"
rpc_endpoint.call(env)

The BlogHandler object should be a more or less complete subclass of BlogHandler that you provide. When the RPC application receives a GET request it will respond with the RSD fragment that will auto-configure your blogging client (like MarsEdit or BlogJet).

The second part of the solution is a blog handler. The handler is responsible for saving and loading entries and images, creating pages and categories and so on. Unfortunately, you have to write this handler yourself since no two blogging systems are alike. However, we provide a SampleHandler to get you started.

IMPORTANT: It is absolutely imperative that you review the sample handler very thoroughly and rewrite and double-check it ad nauseam. We do not recommend that you inherit from the SampleHandler. Instead, make your own copy and define your methods there, and inherit your handler class from BlogRPC::BasicHandler

== Contributing to blogrpc

• Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
• Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
• Fork the project.
• Start a feature/bugfix branch.
• Commit and push until you are happy with your contribution.
• Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
• Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

== Copyright

Copyright (c) 2012 Julik Tarkhanov. See LICENSE.txt for further details.