rhoconnect-rb

A ruby library for the RhoConnect App Integration Server.

Using rhoconnect-rb, your application's model data will transparently synchronize with a mobile application built on the Rhodes framework, or any of the available RhoConnect clients. This client includes built-in support for ActiveRecord and DataMapper models.

Getting started

Load the rhoconnect-rb library:

require 'rhoconnect-rb'

Note, if you are using datamapper, install the dm-serializer library and require it in your application. rhoconnect-rb depends on this utility to interact with Rhoconnect applications using JSON.

Setup the Model

Now include Rhoconnect::Resource in a model that you want to synchronize with your mobile application:

class Product < ActiveRecord::Base
  include Rhoconnect::Resource
end

Or, if you are using DataMapper:

class Product
  include DataMapper::Resource
  include Rhoconnect::Resource
end

Partitioning Datasets

Next, your models will need to declare a partition key for rhoconnect-rb. This partition key is used by rhoconnect-rb to uniquely identify the model dataset when it is stored in a rhoconnect instance. It is typically an attribute on the model or related model. rhoconnect-rb supports two types of partitions:

• :app - No unique key will be used, a shared dataset is synchronized for all users.
• lambda { some lambda } - Execute a lambda which returns the unique key string.

For example, the Product model above might have a belongs_to :user relationship. This provides us a simple way to organize the Product dataset for rhoconnect by reusing this relationship. The partition identifying a username would be declared as:

class Product < ActiveRecord::Base
  include Rhoconnect::Resource
  
  belongs_to :user

  def partition 
	lambda { self.user.username }
  end
end

Now all of the Product data synchronized by rhoconnect will organized by self.user.username. Note: You can also used a fixed key if the dataset doesn't require a dynamic value:

def partition
  :app
end

For more information about Rhoconnect partitions, please refer to the Rhoconnect docs.

Querying Datasets

rhoconnect-rb installs a /rhoconnect/query route in your application which the Rhoconnect instance invokes to query the dataset for the dataset you want to synchronize. This route is mapped to a rhoconnect_query method in your model. This method should return a collection of objects:

class Product < ActiveRecord::Base
  include Rhoconnect::Resource
  
  belongs_to :user

  def partition 
	lambda { self.user.username }
  end

  def self.rhoconnect_query(partition)
    Product.includes(:user).where("users.username = ?",partition)
  end
end

In this example, self.rhoconnect_query returns a list of products where the partition string (provided by the rhoconnect instance) matches the user_id field in the products table.

Configuration and Authentication

Running RhoConnect Manually

Configure RhoConnect in an initializer like config/initializers/rhoconnect.rb (for Rails), or directly in your application (i.e. Sinatra). Here you will setup the rhoconnect uri (the location of your RhoConnect instance), the api_token (see rhoconnect:get_token rake task), and app_endpoint (the location of your ruby app):

config.uri   = "http://myrhoconnect.com"
config.token = "secrettoken"
config.app_endpoint = "http://myapp.heroku.com"

If app_endpoint is defined, your Rhoconnect instance will be configured to query data from the endpoint using the rhoconnect_query method in your model. For example, if your app_endpoint is defined as "http://myapp.heroku.com", RhoConnect will query data with:

POST http://myapp.heroku.com/rhoconnect/query

Example:

Rhoconnect.configure do |config|
  config.uri   		  = "http://myrhoconnect-server.com"
  config.token 		  = "secrettoken"
  config.app_endpoint = "http://myapp.heroku.com"
end

Example with authentication:

rhoconnect-rb installs a /rhoconnect/authenticate route into your application which will receive credentials from the client. Add block which handles the credentials:

Rhoconnect.configure do |config|
  config.uri   = "http://myrhoconnect-server.com"
  config.token = "secrettoken"
  config.authenticate = lambda { |credentials| 
    User.authenticate(credentials[:login], credentials[:password]) 
  }
end

Using the RhoConnect Heroku Addon

If you're using the RhoConnect Heroku Addon, then you can omit the config.uri and config.token (they are managed for you):

Rhoconnect.configure do |config|
  config.authenticate = lambda { |credentials| 
    User.authenticate(credentials[:login], credentials[:password]) 
  }
end

Meta

Created and maintained by Lucas Campbell-Rossen, Vladimir Tarasov and Lars Burgess.

Released under the MIT License.