RhoConnect Plugins in Ruby

This the first of three articles on how RhoConnect can be combined with various platforms such as Ruby on Rails, Java, and .NET.

The Rho platform was developed as a cross-platform solution that offers powerful tools for uniting enterprise data with mobile devices.  One key part of that strategy is the RhoConnect sync server platform.  RhoConnect offers an easy-to-implement way of keeping the data on the mobile device and your back end storage synchronized.

As Motorola states:

RhoConnect is the first of a new category of “mobile app integration” servers. Using RhoConnect drastically simplifies the development of connectivity to an enterprise backend app. The RhoConnect server and built-in RhoConnect client in the smartphone app perform all the work to get data down to the device. This eliminates 50 to 80 percent of the development effort in enterprise smartphone apps: performing the backend application integration.

-- http://docs.rhomobile.com/en/5.0.0/rhoconnect/introduction

There are several ways to interface your back end systems to RhoConnect (and indirectly your mobile devices).  It's up to you, as the developer, to choose the best method suited to your needs:

1. RhoConnect REST API

RhoConnect has a REST API that allows direct and custom services to be developed with it as the platform.  The API allows you to tie in complicated back end systems by giving you direct control of the RhoConnect service.  This means your solution can be as simple or as complicated as you wish it to be.

2. RhoConnect Source Adapters

A RhoConnect source adapter gives you a framework that encapsulates the RhoConnect API, but gives you the leeway to include your own business logic through models and controllers.  The source adapter is a good choice if you wish to have a framework to automate the actual communication with RhoConnect, yet maintain the ability to inject custom business logic into the process.

3. RhoConnect Plugins

From Motorola:

Rhoconnect Plugins allow you to connect your backend apps seamlessly with rhoconnect. You can write the source (query, create, update and delete operations) into a backend application, and use a RhoConnect plugin in the language that matchs your backend application, such as Java or .NET."

A Rhoconnect plugin  encapsulates the integration of your back end solution and RhoConnect in a library that handles the communication seamlessly.  You simply implement your application's models and through the plugin RhoConnect will automatically synchronize your data across your mobile devices.

-

- image source Motorola: (http://docs.rhomobile.com/en/4.1.0/rhoconnect/plugin-intro)

In this article we're going to examine how to implement a RhoConnect plugin using Ruby on Rails as the back end application.  Ruby on Rails provides an excellent framework for rapidly developing applications that can communicate with a variety of database platforms, including MySQL, PostgreSQL, and MS SQL Server.  The RhoConnect plugin will connect our Rails application data to a Rhodes mobile application transparently.

To demonstrate RhoConnect plugins we're going to use three different apps:

• A RhoConnect server
• A Rails 4 app with the Rhoconnect-rb gem
• A Rhodes mobile app (using the iOS simulator)

We're using a Mac as the development platform in this excersize but Windows is also supported.  Install the RhoMobile Suite to get the toolchain you need to follow this post.

For our example we're going to set up a very simple address book.  It will allow the end user to view a set of addresses, along with names and email addresses associated with those addresses.  We will be able to update this list of names from both the mobile device and the Rails back end.  Let's get started!

The Setup

We're going to emulate the Internet on our local computer, meaning our applications will all be on localhost.  In a production or staging environment your RhoConnect and Rails app will be hosted on an application server, while your Rhodes app will reside on a mobile device such as an iPhone or Android device.  Let's create a root directory and create all of our applications as subdirectories from this root.

mkdir plugins

cd plugins

The first application we're going to configure is the RhoConnect service itself.  You can install it by using the command:

gem install rhoconnect

This will install the RhoConnect service gem on our computer.  Next we need to install redis:

rhoconnect redis-install

rhoconnect dtach-install  --- install this as well on a Mac

Finally we can create our RhoConnect app:

rhoconnect app address_server

cd address_server

In the settings/settings.yml add the :sources: section and add the adapter_url line to the development section:

:development:

  :licensefile: settings/license.key

  :redis: localhost:6379

  :syncserver: http://localhost:9292

  :push_server: http://someappname@localhost:8675/

  :api_token: my-rhoconnect-token

  :adapter_url: http://localhost:3000

The adapter_url line will point to our Rails app.  In development Rails apps by default use port 3000 on localhost.  This line allows our RhoConnect app to know where the data resides when synchronizing with mobile apps.

Note the api_token is set to my-rhoconnect-token.  This token will be used with the Rails app to create a shared token between the apps.  In a production environment you'll want to use a more secure token.

Note also that the sync server is running on localhost at port 9292.  This is the URL and port of your RhoConnect server.  In production this would point to the IP on the Internet where your application is installed.

Create the Ruby on Rails back end app using the RhoConnect Plugin

Next we'll create our Rails back end application.  Here we're using Rails 4, as it's the latest version of the framework available.  Rails 3 will also work; as a matter of fact it's the version that the plugin supports by default.

rails new address_book cd address_book

The official gem doesn't support Rails 4 yet, so I had to fork it to add support for that version of Rails.

Edit the Gemfile and add:

gem 'rhoconnect-rb', github: 'chronosafe/rhoconnect-rb'

If you're using Rails 3 instead, use:

gem 'rhoconnect-rb'

This gem is the actual plugin and provides the glue between the app and RhoConnect.  Behind the scenes it builds controllers and routes to your app to support communication with your RhoConnect app transparently.

Next we need to add the model for the address book:

rails g scaffold Address name address email

This creates the store for our addresses.  Note that we're using SQLite3 for our data store as it is the default for Rails and requires no configuration.

Run the rake task to process the migration:

rake db:migrate

This will create our database for us.

Next we need to add an initializer to the config/initializers directory.  This will allow us to configure our communication with RhoConnect.  Create a file in config/initializers named rhoconnect.rb and add the following:

Rhoconnectrb.configure do |config|

  config.uri    = "http://localhost:9292"

  config.token  = "my-rhoconnect-token"

  config.app_endpoint = "http://localhost:3000"

  config.authenticate = lambda { |credentials|

    # User.authenticate(credentials[:login], credentials[:password])

    true

  }

end

The config.uri line points to our RhoConnect application.  The config.app_endpoint strangely enough points back to the Rails app itself.

Notice the config.token line.  This token matches the token we created in our RhoConnect app.  We can create an authentication system for our application here as well.  RhoConnect will pass the user that is attempting to access the back end.  We can authenticate this user using normal Rails authentication.  I've commented this out for our simple example and just return true, meaning everyone is authenticated.

Next we need to make some changes to the app/models/address.rb file to add the support for RhoConnect:

class Address ActiveRecord::Base

  include Rhoconnectrb::Resource

  # RhoConnect partition

  def partition

    :app

  end

  def self.rhoconnect_query(partition, options={})

    all

  end

end

The include statement adds the RhoConnect plugin as a module to our model's class. This module includes all the functionality to enable this model to be updated (and to update) RhoConnect through the plugin.

Each model that supports the plugin must also implement two functions.  The first function is named partition and allows us to uniquely identify the scope of the data to be queried.  For example, you could define the partition to be the username used by the requesting mobile app.  In our case we're simply going to use :app, which means a global scope.

Next we must define a class method named rhoconnect_query.  This method is used by the plugin to actually query the database for a recordset when it needs to retrieve data.  Notice you're passed in the partition to use as a scope, as well a s a hash of options that can further refine the query.  For our example we're going to return all, which means the entire list of addresses.

With these modifications our Rails app is ready to communicate with RhoConnect.

Create a Rhodes App

In order to test our architecture based on the plugin we're going to create a simple Rhodes app to display and update the list of addresses.  From our /plugins root directory do:

rhodes app addresses

cd addresses

Add an Address model:

rhodes model address name,address,email

Be sure not to add spaces between the fields.  This will create the files we need to support our Address model.

Edit the app/Address/address.rb to enable sync:

Rhom::RhomObject

# You can add more methods here

class Address

  include Rhom::PropertyBag

  # Uncomment the following line to enable sync with Address.

  enable :sync

  #add model specific code here

end

Edit the rhomobile.txt to point to the sync (RhoConnect) server:

syncserver = 'http://localhost:9292'

Also change the start path for the app to display our list of addresses:

start_path = '/app/Address'

And we're done!

Testing the Apps

In order to test the app's ability to talk to each other we'll launch them all in separate shell (or command) windows.

Start up the services:

Start redis:

cd address_server

rhoconnect redis-start

Open a new shell and start Rhoconnect from the same folder:

cd address_server

rhoconnect start

Start the Rails app in another shell window:

cd address_book rails server

Start the Rhodes app in the simulator (iPhone simulator):

If using the iPhone simulator you'll need to update the version in the sdk in the build.yml file (it defaults to iOS 6):

iphone:

  configuration: Release

  sdk: iphonesimulator7.0

Run the simulator:

cd contacts

rake run:iphone

Enter any username you wish and tap go to login.

Testing the synchronization

Open a new shell and go to the Rails app:

cd address_book rails console

This will open the rails console for the app.  Add a record to the database:

> Address.create(name: 'Abraham Lincoln', address: '1600 Pennsylvania Ave.', email: 'alincoln@whitehouse.gov')

> Address.all.count

The mobile device should show 1 entry.

On the mobile app enter:

Name: Winston Churchill

Address: 10 Downing St.

Email: wchurhill@gov.uk

You should now see 2 listings on the mobile app.

Press the sync button and return to the Rails app console:

> Address.all.count

Should now return 2.

A quick scaffold shows the data on the Rails side at http://localhost:3000:

That's it! Your Rails Address model is exposed to the Rhodes app for synchronization.  Data will automatically be updated on both ends whenever it changes on either end.

Conclusion

RhoConnect plugins are a fast way to enable a back end to hook into the RhoMobile framework.  In this example we used Ruby on Rails as the back end platform, but it could have been any other platform that is supported by the plugin architecture.

The next time you need to tie in a Rails app to your RhoMobile application take a look at the RhoConnect plugin system.  It could be the perfect fit for your solution.

Want to try it yourself?  The code from the article is available at the Github repo: richard-kutir/rhoconnect-plugin · GitHub

About the Author

Richard Brown is a Senior Developer and Architect at Kutir Mobility.  His specialties include iOS, Ruby on Rails, and RhoMobile development.

About Us

Facing challenges with your RhoMobile implementation? Kutir Mobility, a Motorola Certified partner, can help you get your app done on time. Get in touch with us today at info@kutirtech.com , no strings attached.