= BigBlueButton on Rails
{<img src="https://secure.travis-ci.org/mconf/bigbluebutton_rails.png?branch=master" alt="Build Status" />}[https://travis-ci.org/mconf/bigbluebutton_rails]

{BigBlueButton}[http://bigbluebutton.org] integration for Ruby on Rails 3.

Features:
* Allows multiple servers and multiple conference rooms.
* Full API access using {bigbluebutton-api-ruby}[https://github.com/mconf/bigbluebutton-api-ruby].
* Easy way to join conferences: simply create a room and call the "join" action.
* Easy integration with authentication and authorization mechanisms, such as Devise and CanCan.
* Support for recordings: meetings can be recorded, the list of recordings retrieved and recordings can be played.
* Possibility to create private rooms, that require a password to join.
* Deals with visitors (users that are not logged), allowing (or forbidding) them to join rooms.
* Random meeting IDs to avoid problems with "end", timeouts and reuse of URLs.
* Server activity monitor.
* "On-the-fly" server selection when a meeting is started.

Possible future features:
* Limit the number of users per room and rooms per server.
* Server administration (modify config.xml, use bbb-conf, etc.).
* Pre-upload of slides.

== Supported versions

=== BigBlueButton

The current version of this gem supports *all* the following versions of BigBlueButton:

* 0.8: Altough not all features are supported yet, such as pre-upload of slides. See {TODO_08}[https://github.com/mconf/bigbluebutton_rails/blob/master/TODO_08].
* 0.7: Including 0.7, 0.71 and 0.71a.

=== Ruby

Tested in rubies:

* ruby-1.9.2
* ruby-1.9.3

=== Rails

To be used with *Rails 3* only (should work on 3.0, 3.1 and 3.2).
Tested mainly with Rails 3.2.

== Installation

You can install the latest version of BigbluebuttonRails using RubyGems:

  gem install bigbluebutton_rails

Or simply add the following line in your Gemfile:

  gem "bigbluebutton_rails"

After installing, you need to run the generator:

  rails generate bigbluebutton_rails:install

This generator will create the files needed to setup the gem in your application.
You should take some time to open all the files generated and analyze them.

By default the gem will use the views it provides, <b>but it is strongly recommended that you adapt them for your needs!</b>
The views provided are just an example of how they can be implemented in your application and
they depend on jQuery (use the gem <tt>jquery-rails</tt>) and on a css file provided by this gem.
You can easily generate the views and the css file in your application to later customize them with:

  rails generate bigbluebutton_rails:views

To now more about the generators see {How to: Generators}[https://github.com/mconf/bigbluebutton_rails/wiki/How-to:-Generators]

=== Routes

The routes to BigbluebuttonRails can be generated with the helper <tt>bigbluebutton_routes</tt>. See the example below:

  bigbluebutton_routes :default

It will generate the default routes. You need to call it at least once and the routes will be scoped with 'bigbluebutton'. They will look like:

  /bigbluebutton/servers
  /bigbluebutton/servers/my-server/new
  /bigbluebutton/servers/my-server/rooms
  /bigbluebutton/rooms
  /bigbluebutton/rooms/my-room/join

You can also make the routes use custom controllers:

  bigbluebutton_routes :default, :controllers => {
    :servers => 'custom_servers',
    :rooms => 'custom_rooms',
    :recordings => 'custom_recordings'
  }

To generate routes for a single controller:

  bigbluebutton_routes :default, :only => 'servers'

You may also want shorter routes to access conference rooms. For that, use the option <tt>room_matchers</tt>:

  resources :users do
    bigbluebutton_routes :room_matchers
  end

It creates routes to the actions used to access a conference room, so you can allow access to webconference rooms using URLs such as:

  http://myserver.com/my-community/room-name/join
  http://myserver.com/user-name/room-name/join

For more information see:

* {How to: Routes}[https://github.com/mconf/bigbluebutton_rails/wiki/How-to:-Routes]

=== Basic configurations

There are some basic assumptions made by BigbluebuttonRails:

* You have a method called <tt>current_user</tt> that returns the current user;
* The <tt>current_user</tt> has an attribute or method called "name" that returns
  his/her fullname and an attribute or method "id" that returns the ID.

If you don't, you can change this behaviour easily, keep reading.

BigbluebuttonRails uses the methods <tt>bigbluebutton_user</tt> and <tt>bigbluebutton_role(room)</tt> to get the current user and to get the permission that the current
user has in the <tt>room</tt>, respectively. These methods are defined in {lib/bigbluebutton_rails/controller_methods.rb}[https://github.com/mconf/bigbluebutton_rails/blob/master/lib/bigbluebutton_rails/controller_methods.rb]
and you can reimplement them in your application controller to change their behaviour as shown below.

  class ApplicationController < ActionController::Base

    # overriding bigbluebutton_rails function
    def bigbluebutton_user
      current_user && current_user.is_a?(User) ? current_user : nil
    end

    def bigbluebutton_role(room)
      ...
    end

  end


=== Updating the recordings

Since this task can consume quite some time if your server has a lot of recordings,
it is recommended to run it periodically in the background. To do that, you can use the
gem {whenever}[https://github.com/javan/whenever] (that uses {cron}[http://en.wikipedia.org/wiki/Cron]
underneath).

This gem provides a rake task to fetch the recordings from the webconference servers and
update the application database. This task can be triggered from whenever/cron to update the entire
recordings database.

The command below will fetch recordings for <b>all servers</b> and update the database
with all recordings found:

  rake bigbluebutton_rails:recordings:update

To set up whenever, first add it to your application Gemfile:

  gem 'whenever', :require => false

When you ran the generator <tt>:install</tt> previously, it created a file at
<tt>config/schedule.rb</tt> inside your application. This file is used to configure whenever.
Once this file is in place, running the following command will update your cron tab
to update the recordings periodically.

  whenever --update-crontab

Check {whenever}[https://github.com/javan/whenever] page to learn more about it.


For more information see:

* {How recordings work}[https://github.com/mconf/bigbluebutton_rails/wiki/How-Recordings-Work]

=== Example application

If you need more help to set up the gem or just want to see an example of it working,
check out the test application at <tt>spec/rails_app/</tt>!


==== See also

* {How to: Integrate with Devise}[https://github.com/mconf/bigbluebutton_rails/wiki/How-to:-Integrate-with-Devise]
* {How to: Integrate with CanCan}[https://github.com/mconf/bigbluebutton_rails/wiki/How-to:-Integrate-with-CanCan]

== Contributing/Development

Fork this repository, clone your fork and start by installing the dependencies:

  bundle install

Save <tt>spec/rails_app/features/config.yml.example</tt> as <tt>spec/rails_app/features/config.yml</tt> and edit it to set values for an existent BigBlueButton server. You will need it to run the integration tests. For more information see the page {Testing}[https://github.com/mconf/bigbluebutton_rails/wiki/Testing] in our wiki.

Prepare the rails_app used for tests:

  rake rails_app:install
  rake rails_app:db SERVER=my-server # select a server you defined in 'config.yml'
  rake rails_app:populate            # to create fake data

Run the tests:

  rake spec
  rake cucumber SERVER=my-server

Or simply:

  rake SERVER=my-server

Note: If you don't set the SERVER variable, the first server in <tt>config.yml</tt> will be used.

You can also start the test application and navigate to <tt>localhost:3000</tt> to check it:

  cd spec/rails_app/
  rails server

Develop. :)

If you want your code to be integrated in this repository, please fork it, create a branch with your modifications and submit a pull request.

=== Test Coverage

Coverage is analyzed by default when you run:

  rake spec

Run it and look at the file <tt>coverage/index.html</tt>.

=== Best Practices

We use the gem <tt>rails_best_practices</tt> to get some nice tips on how to improve the code.

Run:

  rake best_practices

And look at the file <tt>rails_best_practices_output.html</tt> to see the tips.

== License

Distributed under The MIT License (MIT). See {LICENSE}[https://github.com/mconf/bigbluebutton_rails/blob/master/LICENSE].

== Contact

This project is developed as part of Mconf (http://mconf.org). Contact:

* Mconf: A scalable opensource multiconference system for web and mobile devices
* PRAV Labs - UFRGS - Porto Alegre - Brazil
* http://www.inf.ufrgs.br/prav/gtmconf