theworkinggroup-wristband 1.0.0

data/README.rdoc

@@ -0,0 +1,130 @@
+= Wristband plugin
+Author:: {The Working Group, Inc}[http://www.theworkinggroup.ca]
+Version:: 1.0.0
+
+The Wristband plug-in simplifies the user authentication process necessary in most web applications.
+
+It handles:
+
+* Login and logout
+* Password storage with encryption
+* Remember me functionality
+* Authority definitions
+  
+  
+== Usage
+
+From a clean project
+(assuming you just did <tt>rails myproject</tt> )
+
+<b>1.</b> Install the plugin
+  cd vendor/plugins
+  svn export http://twg.unfuddle.com/svn/twg_twgplugins/wristband/trunk wristband
+
+<b>2.</b> Run the wristband generator:
+  script/generate wristband
+  
+This will output something like:
+
+  exists  app/models
+  create  app/models/user.rb
+  create  app/controllers/users_controller.rb
+  create  app/views/users/index.html.haml
+  exists  app/controllers
+  create  app/controllers/sessions_controller.rb
+  create  app/views/sessions/new.html.haml
+  exists  db/migrate
+  exists  db/migrate
+  create  db/migrate/001_wristband.rb
+  route  specific routes
+  route  map.resources :sessions, :users
+
+<b>3.</b> Run migrations
+  
+  rake db:migrate
+  
+<b>4.</b> Restart your server
+
+<b>5.</b> Add whatever validations you need in your User model
+
+<b>6.</b> Read the documentation on each one of the generated files
+
+
+== Configuration
+
+
+=== User model
+
+  class User < ActiveRecord::Base
+    wristband [options]
+  end
+
+==== Options:
+
+[:login_with] Array of fields you want to authenticate the user with. Default: usename 
+  
+  wristband :login_with => [:username, :email]
+
+
+[:before_authentication] Array of functions run after the user authentication takes place. Default: [] 
+
+  wristband :before_authentication => :do_something
+
+
+[:after_authentication] Array of functions run before the user authentication takes place. Default: [] 
+
+  wristband :after_authentication => :do_something
+
+
+[:plain_text_password] If true the password won't be encrypted. Default: false 
+
+  wristband :plain_text_password => true
+
+[:has_authorities] If true the password won't be encrypted. Default: false 
+
+  wristband :plain_text_password => true
+
+==== Remarks:
+
+* While password_crypt is limited to 40 characters, the standard output of the hashing function used to encrypt it, there is no such limit on the length of the password as input by the user.
+* There are no default restrictions on the content of the username. These should be added as required.
+* A user's password is stored encrypted by default but support for plain- text passwords is also provided. Leaving 'password_salt' as blank or nil means the password is not encrypted. This makes the content of user
+fixtures easy to read and understand.
+* The 'remember_token' field is used for login authentication via persistent cookie. This value changes each time the user's password is reassigned.
+
+
+== Functionality
+
+=== 1. Remember me
+If you want to automatically login a user when he comes back to your site, add <tt>before_filter :login_from_cookie</tt> to your AplicationController.
+
+=== 2. Authority Definitions
+
+Check the documentation on the link:files/lib/authority_check_rb.html file
+
+==== Other Reading
+
+"The Emerging Standards Bureau" on naming methods
+http://giantrobots.thoughtbot.com/2008/4/10/the-emerging-standards-bureau
+   
+
+== Database configuration
+
+The generator gives you a head start.
+The basic columns are defined as such:
+
+  create_table :users do |t|
+    t.string :email
+    t.string :password_crypt, :limit => 40
+    t.string :password_salt,  :limit => 40
+    t.string :remember_token
+    t.string :email_validation_key
+    t.string :role
+    t.datetime :created_at
+    t.datetime :updated_at
+    # Add your own stuff here ...
+  end
+
+
+
+

data/Rakefile

@@ -0,0 +1,39 @@
+require 'rubygems'
+require 'rake'
+require 'echoe'
+
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the wristband plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+
+desc 'Generate documentation for the wristband plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Wristband'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+Echoe.new('wristband', '1.0.0') do |p|
+  p.description    = "Simplifies the process of authenticating and authorizing users."
+  p.url            = "http://github.com/theworkinggroup/wristband"
+  p.author         = "Jack Neto"
+  p.email          = "jack@theworkinggroup.ca"
+  p.ignore_pattern = ["tmp/*", "script/*"]
+  p.development_dependencies = []
+end
+
+Dir["#{File.dirname(__FILE__)}/tasks/*.rake"].sort.each { |ext| load ext }
+

data/generators/wristband/templates/app/controllers/sessions_controller.rb

@@ -0,0 +1,50 @@
+# -----------------------------------------------
+# This file was generated by the acts_as_authenticated_user plugin
+# Edit as needed ...
+#
+# More details at http://www.theworkinggroup.ca/rails/plugins/wristband
+# -----------------------------------------------
+class SessionsController < ApplicationController
+  
+  # login_required is defined by the wristband plugin
+  # if the user is not logged in it will call respond_not_logged_in
+  before_filter :login_required,        :only => :destroy
+  
+  # This one is just usefull to have
+  before_filter :redirect_if_logged_in, :only => [:new, :create]
+  
+  def new
+    # ...
+  end
+
+  # Logs the user in
+  # Adjust as necessary
+  def create
+    if @user = authenticate_and_login(params[:user][:username], params[:user][:password], params[:user][:remember_me]=='1')
+      flash[:notice] = "Welcome, you are now logged in."
+      redirect_to users_path
+    else
+      flash[:notice] = 'Login failed.'
+      redirect_to login_path
+    end
+  end
+  
+  # Logs out the user 
+  # Adjust as necessary
+  def destroy
+    logout
+    redirect_to home_path 
+  end
+  
+private
+  def redirect_if_logged_in
+    redirect_to home_path if logged_in?
+  end
+  
+  # This will be called by the login_required filter when the user is not logged in
+  # You can replace this with whatever you want.
+  # You can also move this to Application controller so it can be shared with other controllers.
+  def respond_not_logged_in
+    redirect_to login_path
+  end
+end

data/generators/wristband/templates/app/controllers/users_controller.rb

@@ -0,0 +1,47 @@
+# -----------------------------------------------
+# This file was generated by the acts_as_authenticated_user plugin
+# Edit as needed ...
+#
+# More details at http://www.theworkinggroup.ca/rails/plugins/wristband
+# -----------------------------------------------
+class UsersController < ApplicationController
+  
+  # login_required is defined by the wristband plugin
+  # if the user is not logged in it will call respond_not_logged_in
+  before_filter :login_required
+  
+  
+  def verify_email
+    @user = User.verify_email!(params[:email_validation_key])
+    flash[:notice] = 'Your email address has been verified. You may now login to your account.'
+    redirect_to login_path
+  rescue UserVerificationError => error
+    flash[:error] = error.message
+    redirect_to login_path
+  end
+  
+  def forgot_password
+    if request.post?
+      if @user = User.find_by_username(params[:user][:username])
+        @user.password = Wristband::Support.random_string(6)
+        @user.save!
+        UserNotifier::deliver_forgot_password(@user)
+        flash[:notice] = 'A new password has been generated and emailed to the address you entered.'
+        redirect_to login_path and return
+      else
+        @user = User.new
+        @user.errors.add("email", "Cannot find that email address, did you mistype?")
+      end
+    end
+  end
+  
+  
+private
+  # This will be called by the login_required filter when the user is not logged in
+  # You can replace this with whatever you want.
+  # You can also move this to Application controller so it can be shared with other controllers.
+  def respond_not_logged_in
+    redirect_to login_path
+  end
+
+end

data/generators/wristband/templates/app/models/user.rb

@@ -0,0 +1,30 @@
+# -----------------------------------------------
+# This file was generated by the acts_as_authenticated_user plugin
+# Edit as needed ...
+#
+# More details at http://www.theworkinggroup.ca/rails/plugins/wristband
+# -----------------------------------------------
+class User < ActiveRecord::Base
+  
+  # Add your own stuff here...
+  # Possible options are:
+  #
+  # :login_with 
+  #     The fields a user will be validated againts.
+  #     Defaults to :username
+  #
+  # :password_column 
+  #     Sets the name of your password column.
+  #     If :plain_text_password => true it defaults to :password otherwise it defaults to :password_crypt
+  #
+  # :plain_text_password 
+  #     Defaults to false
+  #
+  # :before_authentication 
+  #     Stuff you may want to do before authentication
+  #
+  # :after_authentication 
+  #     Stuff you may want to do after authentication
+  #
+  wristband
+end

data/generators/wristband/templates/app/models/user_notifier.rb

@@ -0,0 +1,54 @@
+# -----------------------------------------------
+# This file was generated by the acts_as_authenticated_user plugin
+# Edit as needed ...
+#
+# More details at http://www.theworkinggroup.ca/rails/plugins/wristband
+# -----------------------------------------------
+class UserNotifier < ActionMailer::Base
+  # Define on you config/environments folder:
+  # development: 
+  #   HOST_NAME = 'localhost:3000'
+  #   SITE_URL = 'http://localhost:3000'
+  #   FROM_EMAIL = 'your_email@your_domain.com'
+  # test: 
+  #   HOST_NAME = 'localhost:3000'
+  #   SITE_URL = 'http://localhost:3000'
+  #   FROM_EMAIL = 'your_email@your_domain.com'
+  # staging: 
+  #   HOST_NAME = 'staging.yourapp.com'
+  #   SITE_URL = 'http://staging.yourapp.com'
+  #   FROM_EMAIL = 'info@staging.yourapp.com'
+  # production: 
+  #   HOST_NAME = 'yourapp.com'
+  #   SITE_URL = 'http://www.yourapp.com'
+  #   FROM_EMAIL = 'info@yourapp.com'
+  
+  default_url_options[:host] = HOST_NAME
+  
+  def email_verification(user)
+    setup_email(user)
+    @subject         += "Your account has been created. Please verify your email address"
+  end  
+
+  def forgot_password(user)
+    setup_email(user)
+    @subject          += "You have requested a new password"
+  end
+
+
+protected
+  # Change YourApp to whatever you application is called
+  def setup_email(user)
+    @recipients  = user.email
+    @body[:user] = user
+    @from        = FROM_EMAIL
+    @subject = case ENV['RAILS_ENV'] 
+      when 'development': "[YourApp Development] "
+      when 'staging': "[YourApp Staging] "
+      else "[YourApp] "
+    end
+    @sent_on     = Time.now
+    headers       "Reply-to" => FROM_EMAIL
+  end
+
+end

data/generators/wristband/templates/app/views/sessions/new.html.haml

@@ -0,0 +1,17 @@
+%h1 Login
+
+= error_messages_for :user
+- form_for :user, @user, :url => sessions_path, :builder => CustomForm do |f|
+  = f.text_field :username
+  = f.password_field :password
+  = f.check_box :remember_me, :label => 'Remember me when I come back'
+  = f.submit 'Log In'
+
+
+%p
+  Did you forget your password?
+  = link_to 'Recover it here.', forgot_password_path
+%p 
+  If you don't have a login yet, click
+  = link_to 'here', register_path
+  to register.

data/generators/wristband/templates/app/views/user_notifier/email_verification.text.html.rhtml

@@ -0,0 +1,7 @@
+<p>Hi,</p>
+
+<p>Your account has been set up.</p>
+
+<p>To verify your email address so that you may login, please click <%= link_to 'here', verify_email_url(@user.email_validation_key) %>.</p>
+
+<p>Thanks</p>

data/generators/wristband/templates/app/views/user_notifier/email_verification.text.plain.rhtml

@@ -0,0 +1,9 @@
+Hi,
+
+Your account has been set up.
+
+To verify your email address so that you may login, please visit the following link:
+  
+<%= verify_email_url(@user.email_validation_key) %>
+
+Thanks

data/generators/wristband/templates/app/views/user_notifier/forgot_password.text.html.rhtml

@@ -0,0 +1,10 @@
+<p>Hi,</p>
+
+<p>A new password was requested for this email address.</p>
+
+<p>Your new password is: <b><%= @user.password %></b> </p>
+
+<p><%= link_to 'Click here to login', login_url %>.</p>
+<p>Once you have logged in, you can edit your profile and change your password to something you can easily remember.</p>
+
+<p>Thanks</p>

data/generators/wristband/templates/app/views/user_notifier/forgot_password.text.plain.rhtml

@@ -0,0 +1,10 @@
+Hi,
+
+A new password was requested for this email address.
+
+Your new password is: <b><%= @user.password %></b> 
+
+To login go to: <%= login_url %>.
+Once you have logged in, you can edit your profile and change your password to something you can easily remember.
+
+Thanks

data/generators/wristband/templates/app/views/users/forgot_password.html.haml

@@ -0,0 +1,10 @@
+%h1 Password Recovery
+  
+%p
+  If you have forgotten your Password, please enter your email address below. 
+  %br/
+  You will be sent an email with new login information.
+      
+  - form_for :user, @user, :url => forgot_password_path do |f|
+    = f.text_field :email, :label => 'Your Email:'   
+    = f.submit 'Recover Username/Password', link_to('Cancel', login_path)

data/generators/wristband/templates/app/views/users/index.html.haml

@@ -0,0 +1,6 @@
+%h1= "Hi #{session_user.username}"
+
+- if logged_in?
+  = link_to 'Logout', logout_path
+- else
+  = link_to 'Login', login_path

data/generators/wristband/templates/db/migrate/create_wristband_tables.rb

@@ -0,0 +1,28 @@
+# -----------------------------------------------
+# This file was generated by the wristband plugin
+# Edit as needed ...
+#
+# More details at http://www.theworkinggroup.ca/rails/plugins/wristband
+# -----------------------------------------------
+class CreateWristbandTables < ActiveRecord::Migration
+  def self.up
+    create_table :users do |t|
+      # uncomment if you want a username in addition to an email
+      # t.string :username
+      t.string :email
+      t.string :password_crypt, :limit => 40
+      t.string :password_salt,  :limit => 40
+      t.string :remember_token
+      t.string :email_validation_key
+      t.datetime :validated_at
+      t.string :role
+      t.datetime :created_at
+      t.datetime :updated_at
+      # Add your own stuff here ...
+    end
+  end
+  
+  def self.down
+    drop_table :users
+  end
+end