RubyDoc.info: File: README – Documentation for josevalim-auth_helpers (0.5.1)

AuthHelpers License: MIT Version: 0.4.1

You can also read this README in pretty html at the GitHub project Wiki page:

http://wiki.github.com/josevalim/auth_helpers

Description

AuthHelpers is a collection of modules to improve your Authlogic models. It mainly exposes some convenience methods to help on confirmation and passwords management, it also deals automatically with associations and notifications.

Authlogic also include some controllers to deal with the modules added. For example, if you add Recoverable to your model, you can have all password management for free, if you inherit from the Recoverable controller:

class AccountPasswordsController < AuthHelpers::Controller::Recoverable
end

This functionality is powered by InheritedResources, which is available at:

http://github.com/josevalim/inherited_resources

You can see an example at:

http://github.com/josevalim/starter

Installation

Install AuthHelpers is very easy. It is stored in GitHub, so just run the following:

gem sources -a http://gems.github.com
sudo gem install josevalim-auth_helpers

If you want it as plugin, just do:

script/plugin install git://github.com/josevalim/auth_helpers.git

Example app

http://github.com/josevalim/starter

Modules

class Account < ActiveRecord::Base
  acts_as_authentic do |a|
    a.validations_scope = :accountable_type
    a.require_password_confirmation = false
  end

  include AuthHelpers::Model::Confirmable
  include AuthHelpers::Model::Recoverable
  include AuthHelpers::Model::Updatable
end

Confirmable

Adds the confirmation handling. It sends an e-mail to the user on account creation, and adds find_and_confirm, find_and_resend_confirmation_instructions as class methods plus confirmed? and confirm! as instance methods.

When used with Updatable, also sends an e-mail the user changes his e-mail address.

Recoverable

Adds the reset password code handling. Adds find_and_resend_confirmation_instructions and find_and_reset_password class methods plus reset_password instance method.

Updatable

It adds email and password confirmations and hack into update_attributes to ensure the another confirmation instruction is sent when the user changes the e-mail.

Authlogic already supports password confirmation, but it’s coupled with the validates_length_of :password_confirmation, which is unecessary. So in order to use this module, is advisable to disable require_password_confirmation from Authlogic.

acts_as_authentic do |a|
  a.require_password_confirmation = false
end

Specs

All modules come with specs, that’s why the library does not have tests per se. So if you want to test the Account model declared above, just do:

describe Account do
  include AuthHelpers::Spec::Confirmable
  include AuthHelpers::Spec::Recoverable
  include AuthHelpers::Spec::Updatable

  before(:each) do
    @valid_attributes = {
      :email                 => "[email protected]",
      :email_confirmation    => "[email protected]",
      :password              => "abcdef",
      :password_confirmation => "abcdef"
    }
  end

  it "should create a new instance given valid attributes" do
    Account.create!(@valid_attributes)
  end
end

The only requirement you have for the tests is to have a @valid_attributes instance variable set with a hash of valid attributes.

Notifications

AuthHelpers also comes with default notification files. At some point you will want to prettify your notification views, so you just need to do:

AuthHelpers::Notifier.sender = %("José Valim" <[email protected]>)
AuthHelpers::Notifier.template_root = "#{RAILS_ROOT}/app/views"

Then make a copy of the plugin views folder to your app/views and start to work on them.

Notification has some basic specs which fail if you don’t include the perishable token in your emails. Just put a file in spec/models/auth_helpers/notifier.rb with the following contents:

require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')

module AuthHelpers
  describe Notifier do
    include AuthHelpers::Spec::Notifier
  end
end

I18n

Those helpers rely on I18n. Assuming the account model below, you need to configure the following messages:

activerecord:
  errors:
    models:
      account:
        already_confirmed: was already confirmed
        not_found: could not be found. Are you sure you gave the right e-mail address?
        perishable_token:
          invalid_confirmation: is invalid. Are you sure you copied the right link from your e-mail?
          invalid_reset_password: is invalid. Are you sure you copied the right link from your e-mail?

Need more?

Right now, this plugin contains the modules that I needed so far. If you are building an invitation system on top of your authlogic models, you could fork the project and add the Invitable module. Uou will never have to write it again in your next projects and it shouldn’t be harder than inheriting a few modules and few controllers.

Bugs and Feedback

If you discover any bugs, please send an e-mail to [email protected]