HasRemote

Gives your local ActiveRecord model an ActiveResource equivalent, which enables you to look for certain attributes remotely using a RESTful webservice.

Installation

As a gem; Add the following to config/environment.rb:

config.gem 'HasRemote', :lib => 'has_remote', :version => ">= 0.1.1"

Require the rake tasks from your application’s Rakefile (only if installed as a gem):

require 'has_remote/tasks'

As a plugin; Run:

script/plugin install git://github.com/innovationfactory/has_remote.git

And only if you require synchronization, run:

script/generate has_remote_migration

rake db:migrate

Examples

First make sure your records have a reference to a remote resource:

add_column :users, :remote_id, :integer

The default key is ‘remote_id’, but this can be changed, see options for has_remote.

class User < ActiveRecord::Base
  has_remote :site => 'http://people.local'
end

User.remote_class
# => User::Remote (subclass of ActiveResource::Base)

@user.remote
# => #<User::Remote:...>

@user.remote.username
# => "User name from remote server"

has_remote optionally takes a block which can be used to specify remote attributes:

class User < ActiveRecord::Base
  has_remote :site => '...' do |remote|
    remote.attribute :username
  end
end

@user.username
# => "User name from remote server"

Note that the current version of HasRemote only offers read-only support for remote attributes.

The :through option enables you to specify your own ActiveResource class:

class RemoteUser < ActiveResource::Base
  self.site = "people.local"
  self.element_name = "person"
end

class User < ActiveRecord::Base
  has_remote :through => "RemoteUser"
end

See documentation for has_remote for a description of all options.

Caching attributes locally

In case certain attributes are used a lot and performance is getting bad, or in case you need to do database operations on remote attributes, like sorting, you can tell has_remote to locally cache specific attributes in the following manner:

class User < ActiveRecord::Base
  has_remote :site => '...' do |remote|
    remote.attribute :username, :local_cache => true
    remote.attribute :email_address, :as => :email, :local_cache => true
  end
end

This assumes you also have a ‘username’ and ‘email’ column in the local ‘users’ table. Note that when using the :as option the local column is assumed to be named after this value.

Synchronization of cached attributes

There are two ways of keeping the locally cached attributes in sync with their remote values.

Inline synchronization
Rake task hr:sync

Inline synchronization

Synchronize a single record’s attributes:

@user.update_cached_attributes

Tip! It is often useful to trigger this method by means of a callback in order to initialize remote attributes when the record is created:

before_create :update_cached_attributes

Appending an exclamation mark will also save the record:

@user.update_cached_attributes!

Synchronize all records of one specific model:

User.synchronize!

The latter automatically requests all remote resources that have been changed (including new and deleted records) since the last successful synchronization for this particular model. You may need to override the updated_remotes class method in your model to match your host’s REST API.

See HasRemote::Synchronizable for more information.

Rake hr:sync

The rake task hr:sync is provided to allow easy synchronization from the command line. You could set up a cron tab that runs this task regularly to keep the data in sync.

By default hr:sync updates all records of each model that has remotes. You can limit this to certain models by using the MODELS variable:

rake hr:sync MODELS=Contact,Company

To specify additional parameters to send with the request that fetches updated resources use the PARAMS variable:

rake hr:sync PARAMS="since=01-01-2010&limit=25"

(If you’ve overridden the updated_remotes class method on one of your synchronizable models, then note that these parameters are passed in as a hash to updated_remotes internally.)

Documentation

To generate RDocs for this plugin, from the has_remote directory run:

rake rdoc

or from your application’s root directory, run:

rake doc:plugins:has_remote

Testing

To run the specs of the plugin, from the has_remote directory run:

rake spec

(This requires you to have both RSpec and Shoulda installed.)

More information & patches

Simple example of how HasRemote simplifies your code: gist.github.com/176335
Simple API authentication with HasRemote: gist.github.com/174497

Questions, requests and patches can be directed to sjoerd.andringa[AT]innovationfactorynl.