AuthHelpers
License: MIT
Version: 0.3.0

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

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::Associatable
    include AuthHelpers::Model::Confirmable
    include AuthHelpers::Model::Recoverable
    include AuthHelpers::Model::Updatable
  end

== Associatable

This module automatically creates a belongs_to association for the first *_id
in the table. This module exists because, whenever it's possible, I follow the
pattern of having an account model and then all accountable objects uses this
model (it autodetects polymorphic associations too).

== 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::Associatable
    include AuthHelpers::Spec::Confirmable
    include AuthHelpers::Spec::Recoverable
    include AuthHelpers::Spec::Updatable

    before(:each) do
      @valid_attributes = {
        :email                 => "is.valid@email.com",
        :email_confirmation    => "is.valid@email.com",
        :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" <jose.valim@gmail.com>)
  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 jose.valim@gmail.com

Copyright (c) 2009 José Valim
http://josevalim.blogspot.com/