Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/afcapel/alondra

Push server and framework that adds real time capabilities to your rails apps
https://github.com/afcapel/alondra

Last synced: about 2 months ago
JSON representation

Push server and framework that adds real time capabilities to your rails apps

Awesome Lists containing this project

README 

        
# Alondra



Alondra is a push server and framework that adds real time capabilities to

your rails applications.



## What can I do with Alondra?



### Subscribe clients to channels



Alondra allows browsers to subscribe to channels. Any Ruby process that loads

your Rails environment will be able to push messages to those channels.



To subscribe to a channel you can use the built in helper:



```

  <%= alondra_client @chat %>

```



Alondra uses [conventions to map records and classes to channel names](https://github.com/afcapel/alondra/wiki/Event-conventions).

The last example will subscribe the browser to a channel named '/chats/:chat_id'.

Then, the Alondra client will render any message pushed to that channel.



If you don't want to use Alondra conventions, you can always provide your own

channel names:



```

  <%= alondra_client ['my custom channel', 'another channel'] %>

```



### Sending push notifications



Since Alondra is all Ruby and integrates with your Rails environment, you can

use your Rails models and views to render push messages. For example, sending

a push notification from your controller action is as simple as this:



```ruby

  def create

    @chat = Chat.find(params[:chat_id])

    @message = @chat.messages.build(params[:message])



    if @message.save

      push '/messages/create', :to => @chat

    end



    respond_with @message

  end

```



This will render the '/messages/create' view and send the results to all

clients subscribed to the chat channel.



You can send push notifications from any process that loads your Rails

environment and from any class that includes the Alondra::Pushing module.

When rendering a push message the local context (that is, the instance

variables of the caller object) will be available in the view.



### Listening to events



Alondra comes bundled with an EventListener class that allows you to react to

events such as when a client subscribes to a channel.



```ruby

  # A ChatListener will by default listen to events

  # sent to any channel whose name begins with '/chat'

  class ChatListener < Alondra::EventListener



    # If you want to listen to other channels than the default ones

    # you can specify other patterns with the listen_to method, like

    #

    # listen_to  /tion$/

    #

    # That would make your listener receive events from any channel whose

    # name ends in 'ion'



    # This will be fired any time a client subscribes to

    # any of the observed channels

    on :subscribed, :to => :member do



      # If you use Cookie Based Session Store,

      # you can access the Rails session from the listener

      @user = User.find(session[:user_id])



      # Push notifications from listener

      push '/users/user', :to => channel_name

    end

  end

```



You can also listen to :unsubscribe, :created, :updated, :destroyed or any

custom event in the observed channels.



### Push record changes to the client



Sometimes you are just interested in pushing record updates to subscribed

clients. You can do that annotating your model:



```ruby

  class Presence < ActiveRecord::Base

    belongs_to :user

    belongs_to :chat



    push :changes, :to => :chat

  end

```



This will push an event (:created, :upated or :destroyed)  to the chat channel

each time a Message instance changes.



In the client you can listen to these events using the JavaScript API:



```javascript



  var alondraClient = new AlondraClient('localhost', 12345, ['/chat_rooms/1']);



  // render user name when presence is created



  $(alondraClient).bind("created.Presence", function(event, resource){

    if( $('#user_'+resource.user_id).length == 0 ){

      $('#users').append("
  • " + resource.username + "
    • ");

        }

      });
    


      // remove user name when presence is destroyed
    


      $(alondraClient).bind("destroyed.Presence", function(event, resource){

        $('#user_'+resource.user_id).remove();

      });
    


    ```
    


    This technique is especially useful if you use something like Backbone.js

    to render your app frontend.
    


    ## Example application
    


    You can check the [example application](http://github.com/afcapel/alondra-example)

    to see how some of the features are used.
    


    ## Installation
    


    Currently Alondra depends on Rails 3.1 and Ruby 1.9. It also uses ZeroMQ for

    interprocess communication, so you need to install the library first. If

    you are using Homebrew on Mac OS X, just type
    



      brew install zeromq

    


    When ZeroMQ is installed, add the Alondra gem to your Gemfile.
    



      gem "alondra"

    


    You also will need to install the server initialization script into your app.

    In the shell execute the generator.
    



      $ rails g alondra install

    


    To run the Alondra server, just call the provided executable in your project directory
    



      $ bundle exec alondra

    


    In development mode you can also run the Alondra server in its own thread.

    See the [initializer in the example application](https://github.com/afcapel/alondra-example/blob/master/config/initializers/alondra_server.rb)

    for how to do it.
    


    ## Contributors
    


    - [Ryan LeCompte](http://github.com/ryanlecompte)

    - [Jaime Iniesta](http://github.com/jaimeiniesta)