== Installation

After generating the login system, edit your app/controllers/application.rb
file. The beginning of your ApplicationController should look something like
this:

  require 'user_system'

  class ApplicationController < ActionController::Base
    include UserSystem
    helper :user
    model :user
    before_filter :login_required

After you have done the modifications the the ApplicationController and its
helper, you can import the user model into the database. This
model is meant as an example and you should extend it. If you just want to get
things up and running you can find some create table syntax in
db/user_model.sql.

You also need to add the following at the end of your config/environment.rb
file:

require 'environments/user_environment'

Under the 'enviroments' subdirectory, you'll find user_environment.rb.
Edit this file as necessary.

Also, you must properly configure ActionMailer for your mail settings. For
example, I have the following in config/environments/development.rb (for a
.Mac account, and without my username and password, obviously):

ActionMailer::Base.server_settings = {
  :address => "smtp.mac.com",
  :port => 25,
  :domain => "smtp.mac.com",
  :user_name => "<your user name here>",
  :password => "<your password here>",
  :authentication => :login
}

You'll need to configure it properly so that email can be sent. One of the
easiest ways to test your configuration is to temporarily reraise exceptions
from the signup method (so that you get the actual mailer exception string).
In the rescue statement, put a single "raise" statement in. Once you've
debugged any setting problems, remove that statement to get the proper flash
error handling back.

== Requirements

You need a database table corresponding to the User model. Note
the table type for MySQL. Whatever DB you use, it must support transactions.
If it does not, the functional tests will not work properly, nor will the
application in the face of failures during certain DB creates and updates.

  mysql syntax:
  CREATE TABLE users (
    id INTEGER UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
    login VARCHAR(80) NOT NULL,
    salted_password VARCHAR(40) NOT NULL,
    email VARCHAR(60) NOT NULL,
    firstname VARCHAR(40),
    lastname VARCHAR(40),
    salt CHAR(40) NOT NULL,
    verified INT default 0,
    role VARCHAR(40) default NULL,
    security_token CHAR(40) default NULL,
    token_expiry DATETIME default NULL,
    deleted INT default 0,
    delete_after DATETIME default NULL
  ) TYPE=InnoDB DEFAULT CHARSET=utf8;

  postgres:
  CREATE TABLE "users" (
    id SERIAL PRIMARY KEY
    login VARCHAR(80) NOT NULL,
    salted_password VARCHAR(40) NOT NULL,
    email VARCHAR(60) NOT NULL,
    firstname VARCHAR(40),
    lastname VARCHAR(40),
    salt CHAR(40) NOT NULL,
    verified INT default 0,
    role VARCHAR(40) default NULL,
    security_token CHAR(40) default NULL,
    token_expiry TIMESTAMP default NULL,
    deleted INT default 0,
    delete_after TIMESTAMP default NULL
  ) WITH OIDS;

  sqlite:
  CREATE TABLE 'users' (
    id INTEGER PRIMARY KEY,
    login VARCHAR(80) NOT NULL,
    salted_password VARCHAR(40) NOT NULL,
    email VARCHAR(60) NOT NULL,
    firstname VARCHAR(40),
    lastname VARCHAR(40),
    salt CHAR(40) NOT NULL,
    verified INT default 0,
    role VARCHAR(40) default NULL,
    security_token CHAR(40) default NULL,
    token_expiry DATETIME default NULL,
    deleted INT default 0,
    delete_after DATETIME default NULL
  );

Of course your user model can have any amount of extra fields.
This is just a starting point.

Supplied with the generator is a .erbsql schema file. If you download the
db_structure gem, you can run script/create_db to automatically create all of
your databases and tables based on this file. ** BEWARE ** This script
drops and recreates all tables in test, production and development databases.
The supplied file has been tested with MySQL, though others have reported
success with SQLite and PostgreSQL.

== How to use it 

Now you can go around and happily add "before_filter :login_required" to the
controllers which you would like to protect. 

After integrating the login system with your rails application navigate to your
new controller's signup method. There you can create a new account. After you
are done you should have a look at your DB. Your freshly created user
will be there but the password will be a sha1 hashed 40 digit mess. I find
this should be the minimum of security which every page offering login &
password should give its customers. Now you can move to one of those 
controllers which you protected with the before_filter :login_required snippet.
You will automatically be re-directed to your freshly created login controller
and you are asked for a password. After entering valid account data you will be
taken back to the controller which you requested earlier. Simple huh?

== Tips & Tricks

How do I...

  ... access the user who is currently logged in

  A: You can get the user object from the session using @session['user']
     Example: 
       Welcome <%= @session['user'].name %> 

  ... restrict access to only a few methods? 
  
  A: Use before_filters build in scoping. 
     Example: 
       before_filter :login_required, :only => [:myaccount, :changepassword]
       before_filter :login_required, :except => [:index]
     
  ... check if a user is logged-in in my views?
  
  A: @session['user'] will tell you. Here is an example helper which you can use to make this more pretty:
     Example: 
       def user?
         !@session['user'].nil?
       end

  ... return a user to the page they came from before logging in?

  A: The user will be send back to the last url which called the method "store_location"
     Example:
       User was at /articles/show/1, wants to log in.
       in articles_controller.rb, add store_location to the show function and
       send the user to the login form. 
       After he logs in he will be send back to /articles/show/1

You can find more help at http://wiki.rubyonrails.com/rails/show/SaltedLoginGenerator

== Troubleshooting

One of the more common problems people have seen is that after verifying an
account by following the emailed URL, they are unable to login via the
normal login method since the verified field is not properly set in the
user model's row in the DB.

The most common cause of this problem is that the DB and session get out of
sync. In particular, it always happens for me after recreating the DB if I
have run the server previously. To fix the problem, remove the /tmp/ruby*
session files (from whereever they are for your installation) while the server
is stopped, and then restart. This usually is the cause of the problem.

A forthcoming release will probably fix this via a well placed reset_session
call (or requirement to add it after running the generator) so that it is done
automatically on startup.

== Changelog

1.0.9 Fixed hardcoded generator name (in controller test and schema) and README
1.0.8 Generator/schema fixes and some README fixes/improvements
1.0.7 Fixed bad bug with missing attr_accessor :new_password in user class
1.0.6 Proper delete support and bug fixes
1.0.5 Lots of fixes and changes (see rubyforge.org/salted-login)
1.0.0 First gem release