Home

Foreign Office is a client push library for Rails. It allows you to have side effects on your client while keeping all business logic on your servers.

Broadcasters and Listeners Foreign Office consists of broadcasters, usually service models that you create to broadcast state from models on the server, and listeners, which allow you to receive content or execute common behaviors on the client based on the state that is broadcast by the server.

Use It

Let's say you add friendships via an ajax call, and the ajax response uses the Thin Man pattern of a single representation of the object, which is inserted into the friendship list. In order to maintain that simplicity, Foreign Office handles the side effect of updating the friendship counter.

In your model

class User < ActiveRecord::Base
  has_many :friendships

  def serialize
    self.attributes.merge friend_count: self.friendships.count
  end
end

In a service object, called from your controller

class AddFriend
  def init(initiator,new_friend)
    @initiator, @new_friend = initiator, new_friend
  end

  def call
    @friendship = Friendship.create(initiator: @initiator, friend: @new_friend)
    @recipient.broadcast_change
    @new_friend.broadcast_change
    @friendship
  end
end

In your view

You have <span <%= listener_attrs(@user, :friend_count) %> >
  <%= @user.friendships.count %></span> friendships

<section id="friendship_list">
  <%= render partial: '/friendships/show_wrapper', collection: @user.friendships %>
</section>

Configure It

Server Publishing configuration

Add a message bus to your gemfile:

gem 'pubnub'

Pusher is also an option. Integrating your own message bus is fairly straightforward, you need a class that responds to publish and config, then you pass is as the klass as in the config example below. Other keys in the bus config will be passed to your classes config method. Contact us if you have questions or want to add another SaaS message bus as a default option in Foreign Office.

Here's an example of connecting a Pubnub account to Foreign Office. You can put this in config/initializers:

ForeignOffice.config({
  bus: {
    klass: ForeignOffice::Busses::PubnubBus,
    publish_key:   ENV['PUBNUB_PUBLISH_KEY'],
    subscribe_key: ENV['PUBNUB_SUBSCRIBE_KEY'],
    secret_key:    ENV['PUBNUB_SECRET_KEY']
  }
})

Naturally you must set the keys in your environment for this to work.

Configure Client Subscriptions

Connect the Foreign Office javascript in your application.js:

//= require foreign_office
$(document).ready(function(){
  pubnub_publish_key = $("[data-pubnub-publish-key]").data('pubnub-publish-key')
  pubnub_subscribe_key = $("[data-pubnub-subscribe-key]").data('pubnub-subscribe-key')
  foreign_office.config({
    bus_name: 'PubnubBus',
    publish_key: pubnub_publish_key,
    subscribe_key: pubnub_subscribe_key,
    ssl: true,
    disconnect_alert: 'You seem to have lost the server connection. Please check your internet connection. Thanks, -The Foreign Office.',
    reconnect_alert: 'Your connection to the site has been restored. All site info should now be available. Thanks, -The Foreign Office.'
  });
  foreign_office.bind_listeners()

})

And in your document

tag:

  <%= javascript_include_tag '//cdn.pubnub.com/pubnub-3.16.4.min.js' %>
  <meta name="foreign_office:config" data-pubnub-publish-key="<%= ENV['PUBNUB_PUBLISH_KEY']%>" data-pubnub-subscribe-key="<%= ENV['PUBNUB_SUBSCRIBE_KEY']%>">

You should use the latest pubnub javascript available from the Pubnub CDN, the above is merely for example.