MerbfulAuthentication
=====================
 
A slice for the Merb framework. 
 
MerbfulAuthentication is an authentication framework for the Merb Web Framework.  
 
Currently DataMapper and ActiveRecord supportis available.  It should be pretty easy to add your own.
 
MerbfulAuthentication provides your model with a mixin that gives your model all the required behavior
and links it to the controllers.  
 
As an example.  In your normal applications model directory create your user model.
 
class User
  include MerbfulAuthentication::Adapter::DataMapper
  include MerbfulAuthentication::Adapter::DataMapper::DefaultModelSetup
end
 
This will give the User class the required behavior and provide access to the class through
MerbfulAuthentication[:user] for other slice authors.  To save key presses a handy constant is available
MA.
 
So using the MA constant you can declare your class like this
 
class Person
  include MA::Adapter::DataMapper
  include MerbfulAuthentication::Adapter::DataMapper::DefaultModelSetup
end
 
And in your custom slice, get access to the user class with MA[:user]
 
If you don't want to use the default setup for options.  i.e. you want to see the properties in your model, change the 
validations or whatever, you can just enter them into your model.  To find out the required properties and validations that the
default uses use the rake task to get a print out that you can paste into your model.
 
rake slices:merb_auth:dm:setup # Datamapper defaults
 
rake slices:merb_auth:ar:setup # ActiveRecord defaults
 
===Useful Helpers
 
The normal merbful_authentication helpers are available for your application, but also there is some consistent 
helpers for other slice authors. Most notably is the controller helper
 
:current_ma_user also aliased as :current_person, or :current_user or whatever your user class name is.
 
=== Controllers
 
The controllers that drive MerbfulAuthentication are always named MA::Users, and MA::Sessions
 
These are then mapped to appropriately named routes.  
 
=== Options
 
See notes after installation instructions
 
------------------------------------------------------------------------------
 
Instructions for installation:
 
=== Quick Install
# config/init.rb
dependency "merb-slices"
dependency "merbful_authentication"
 
# router
r.add_slice(:MerbfulAuthentication, "path/to/mount/at")
 
# Boot strap to your app
rake slices:merb_auth:install
 
 
=== Long Install INstructions
 
# add the slice as a regular dependency
 
dependency 'merbful_authentication'
 
# if needed, configure which slices to load and in which order
 
Merb::Plugins.config[:merb_slices] = { :queue => ["MerbfulAuthentication", ...] }
 
 
 
=== Configure Your Router
 
In config/router.rb you need to activate your brand new MerbfulAuthentication Slice.  You can do this a number of ways.
 
The easiest way is like this:
 
r.add_slices
 
If you'd like to specify MerbfulAuthentication for mounting or other routeing options given in slices
 
r.add_slice(:MerbfulAuthentication)
 
By default this will mount the slice at /merbful_authentication.  So your login url will be at 
 
/merbful_authentication/login
 
If you'd like to specify a different mount point in your application do it like this.
 
r.add_slice(:MerbfulAuthentication, 'authentcation') 
 
Your login url will now be /authentication/login, your signup url will be at /authentication/users/new
 
Alternatively you can just mount merbful_authentication directly onto your application. (Recommended)
 
r.add_slice(:MerbfulAuthentication, :path => "", :default_routes => false)
 
If you'd like to set more options, I suggest you look up the merb-slices documentation.
 
 
 
=== Install your slice
 
You need to install the slice.
 
rake slices:merb_auth:install
 
=== Configuring your install.
 
If you don't have any configuration applied some simple defaults will be assumed.  You configure your installation
by writing it to the config/slices.yml file
 
==== Login Field
 
By default merbful_authentication uses the "email" field to login.  If you want to use a different field, even one of your own,
you can use the
\:login_field: jid
 
option.  This example will set the "jid" field to be the default field used for logging in.  One thing to bear in mind is
that this needs to actually be a field in the database.
 
==== Routing options
 
\:route_path_model:    first choice for model route path.  defaults to "users" (used to make single_model_path and 
 
\:route_path_session:  first choice for the sessions route path.  Defaults to "sessions"
 
 
===== Named routes for the MA::Users resource
 
\:user:
  \:new:       # ||= :"new_#{single_model_name}"
  \:show:      # ||= :"#{single_model_name}"
  \:edit:      # ||= :"edit_#{single_model_name}"
  \:delete:    # ||= :"delete_#{single_model_name}"
  \:index:     # ||= :"#{plural_model_path}"
  \:activate:  # ||= :"#{single_model_name}_activation"
 
  
A named route called :login, :logout and :signup are also included.
 
 
=== Including activation emails for account verification
 
To include activation email to your uses use the
 
\:use_activation: true option
 
 
To not use it either leave it out, or set it false like this
 
\:use_activation: false
 
 
If this option is turned off, it will just automatically complete the relevant fields
to have an activated user.  This way, if you decide later that you'd like to include activation
then the previously signed up users are already fully active and ready to fit into the new behavior :)
 
There is also the subjects that you can setup for your emails
 
\:from_email
\:welcome_subject:       # ||= "Welcome"
\:activation_subject:    # ||= "Please Activate Your Account"
 
------------------------------------------------------------------------------
 
=== Override the Views
 
You can override the views MerbfulAuthentication provides.  Lets face it.  They're pretty  basic.
 
To do this, you need to edit the files in the bootstrapped directories in your application.
 
Merb.root/slices/merbful_authentication/app/views/
 
==== Example
 
To change the login form you'd head on over to 
 
Merb.root/slices/merbful_authentication/app/views/users/new.html.(haml|erb)
 
And put in your own view there.  The same is available for any of the components of merbful authentication
 
You can also add your own overrides to the controllers similarly.  
 
=== Using Your own Layout
 
To setup merbful authentication to use your own layout use a before_app_loads block.  
 
==== Example
 
Merb::Slices.config[:merb_auth] = { :layout => :application }
 
=== Migrations
 
There is a migration task for merbful_authentication to generate your migrations.  Make sure you have use_orm selected so that
it knows which generator to use.  Then from your host application
 
rake slices:merb_auth:generate_migration