governor_background

Governor[http://carpeliam.github.com/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

First, install Governor. Then, in your Gemfile, add the following:

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.

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.
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.

governor_background

Dependencies

Setting up

Usage

Contributing to governor_background

Copyright