HasRemote¶ ↑

Binds your local ActiveRecord objects to a remote ActiveResource object, which enables you to look for certain attributes remotely using a RESTful webservice.

Installation¶ ↑

Rails 3¶ ↑

Add the following to your Gemfile:

gem 'HasRemote', '~> 0.2.0', :require => 'has_remote'

And only if you require synchronization, run:

rails generate has_remote:migration
rake db:migrate

Rails 2.3¶ ↑

Add the following to environment.rb:

config.gem 'HasRemote', :version => '~> 0.1.7', :lib => 'has_remote'

And only if you require synchronization, run:

script/generate has_remote_migration
rake db:migrate

Links¶ ↑

RDoc:

rdoc.info/projects/innovationfactory/has_remote

Github:

github.com/innovationfactory/has_remote

Simple example of how HasRemote simplifies your code:

gist.github.com/176335

Simple API authentication with HasRemote:

gist.github.com/174497

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.

1. Inline synchronization

2. 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 {HasRemote::Synchronizable#updated_remotes #updated_remotes} class method on one of your synchronizable models, then note that these parameters are passed in as a hash to {HasRemote::Synchronizable#updated_remotes #updated_remotes} internally.)

Testing¶ ↑

Install Bundler and run bundle install in order to obtain RSpec and other dependencies. To run the specs, from the root folder run:

rspec spec

More information & patches¶ ↑

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

Copyright © 2009-2011 Innovation Factory.