Engage!

Engage! is a Rails gem that adds a user support forum to your Rails application.

Installation

1. Add Engage! to the application's Gemfile: gem 'engagecsm'.

2. Install it: bundle install.

3. Run the generator: rails generate engage User.

4. Run the migrations: rake db:migrate.

The engage generator takes a model name as its argument, so just substitute User with you model name: rails generate engage YourModel

If the model exists, Engage! hooks into it assuming there's already an authentication mechanism in place. If it doesn't exist, the generator additionally creates a devise based authentication system.

Configuration

The following options can be set up in config/initializers/engage.rb:

• layout (string) - a layout used when displaying the engine's views. config.layout = 'application' means that app/views/layouts/application.html.erb will be used.

• mailer_sender (string) - an email address to use when sending engine-related messages; example: config.mailer_sender = 'engage@domain.com'.

• login_link (hash) - a path symbol and options used for generating login link. The default value when using the internal authentication looks like this: { :path => :new_user_session_path, :opts => { :remote => true } }.

  Login links are needed when a user that is not yet logged in attempts to perform an unauthorized action like for example creating a topic. The user is then redirected to the login page. The intended action is remembered by the engine, so after a successful login you may want to redirect users to the path exposed by the engage_intended_action method.

• internal_authentication (boolean) - whether the engine should use its own authentication mechanism: config.internal_authentication = true.

• user_model (string) - a model that the engine plugs into: config.user_model = 'User'.

• current_user_method (Proc) - a method returning the logged in user. Assuming current_user_method is set to Proc.new { current_user }, here are some methods that should work:

  class ApplicationController < ActionController::Base
    helper_method :current_user
  
    protected
  
    # return logged in user or nil when no one's logged in
    def current_user
      # Devise and Clearance automatically provide this method,
      # so there's no need to redefine it
  
      # for Authlogic, it could look like this:
      (user_session = UserSession.find) && user_session.user
  
      # when using OmniAuth, use something similar to:
      auth_hash = session['auth_hash']
      authorization = Authorization.find_by_provider_and_uid(auth_hash["provider"], auth_hash["uid"])
      authorization && authorization.user
    end
  end
  

• username_method (Proc) - a method called on a logged in user object used for getting his or her username. Assuming that we need to call a username method on a user, set this to config.username_method = Proc.new { username }. It can also be set to nil - the engine will then prompt users for the missing data it needs at the moment.

• email_method (Proc) - as above, but for email: config.email_method = Proc.new { email }. The trick with nil also works.

• image_url_method (Proc) - a method used for retrieving a URL of a user image, also called on a logged in user object, for example: config.image_url_method = Proc.new { avatar_url }. If not set, the engine will download a Gravatar image mathing user's email.

Managing users

Any user can be given admin privileges, initially by running something like: user.engage_user_profile.update_attribute(:admin, true). After that, a link "Manage users" is being displayed for the logged in user.

Customization

You can easily customize colors and other styles Engage! uses by editing .scss files that are generated in app/assets/stylesheets/engage.

If you'd like to modify the views Engage! uses for its internal authentication, run rails generate engage:devise_views and take a look at app/views/devise.

More

If you need to modify how the engine works, you can use a supplied test suite to help you ensure that you didn't break anything. Please note that due to the various possible usages of the engine's generator there is a need to separately test a few different setups. The engine's test suite uses customized dummy apps to achieve this and runs only relevant RSpec examples. To create a new test app variant, take a look at the dummy app template (spec/dummyapptemplate), think about what you would like to do with it (including running the Engage! generator), and describe it in a new file in the spec/appvariants directory. deviseuser.rb file is a good example of such a file - it prepares a standard devise user authentication setup and plugs the engine right into it.

To mark a RSpec block as relevant to the devise_user app variant, tag it like this:

describe Engage::Comment, :devise_user do
  ...
end

You can tag it and context blocks as well. There is also one special tag, :universal, to make an example or group of them run every time, regardless of current app variant.

Finally, to run the specs, use one of the following:

APP_VARIANT=devise_user guard # will run Guard with devise_user app variant active
APP_VARIANT=devise_user rspec spec # will run all relevant examples once  
rake spec # will run all examples for all app variants

By default, the dummy app isn't regenerated with each test run. To force such behaviour, pass REGENERATE_DUMMY_APP environment variable like this:

REGENERATE_DUMMY_APP=true APP_VARIANT=devise_user guard