Background processing for Governor, a Rails 3 pluggable blogging system.
Ruby JavaScript
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
app/helpers
lib
spec
.document
.gitignore
.rspec
Gemfile
Gemfile.lock
LICENSE.txt
README.rdoc
Rakefile
VERSION
governor_background.gemspec

README.rdoc

governor_background

Governor (named after Rod Blagojevich) is the pluggable blogging platform for Rails, built for people who want to build their blog into their website, not build their website into their blog.

governor_background plays nicely with Governor, allowing you to tie in additional services that might want to perform blog-related services in the background. For example, you may want to tweet a link to your article when publishing.

Dependencies

  • Governor, although this dependency might be removed. GovernorBackground is pretty independent.

  • Either Delayed_Job or Resque. If you use Resque, it's highly recommended that you use resque-status as well.

Setting up

In your Gemfile, add the following:

# gem 'delayed_job'                                # if you're using delayed_job
# gem 'resque', :require => 'resque/server'        # if you're using resque
# gem 'resque-status', :require => 'resque/status' # recommended if you're using resque

gem 'governor'
gem 'governor_background'

After that, it's highly recommended that you add some methods to your ApplicationController as follows:

class ApplicationController < ActionController::Base
  include GovernorBackground::Controllers::Methods
  # ...
end

Including GovernorBackground::Controllers::Methods will upon every request check to see if there are any finished jobs (either completed, failed, or killed) since the last request, and will both clear them out as well as enable you to report them to the user. To report them to the user, add the following to your layout:

<%= background_status %>

If there are any finished jobs, this will add a div with a 'background' class, and within that div will be one or more divs with either a 'completed', 'failed', or 'killed' class, and a message.

Usage

Background jobs happen in two stages in governor_background: first, they get registered, then they get run.

  1. register: To register a job, you give it a name and call GovernorBackground.register:

    GovernorBackground.register('twitter_post') do |content|
      Twitter.update(content)
    end

    You'll want to do this once when the application is first started.

  2. run: When you're ready to run your background task, call GovernorBackground.run:

    GovernorBackground.run('twitter_post', 'I am so awesome')

    GovernorBackground will look for a task registered as twitter_post and run its associated block, including any arguments you passed to run.

Job names have to be _globally unique_; a good practice can be to preface your job name with the name of your plugin and an underscore.

In your I18n settings, add an entry for your job name for each finished status (completed, failed, and killed). You'll have access in your entry to any message passed from the background service. For the above example, you might have the following in your config/locales/en.yml file:

en:
  governor_background:
    twitter_post_completed: 'Your article was successfully posted to Twitter.'
    twitter_post_failed: 'Unable to tweet your article: %{message}.'
    twitter_post_killed: 'Your tweet was interrupted: %{message}.'

Please see governor_twitter as an example usage of governor_background.

Contributing to governor_background

  • 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 © 2011 Liam Morley. See LICENSE.txt for further details.