MerbfulAuthentication
=====================

A slice for the Merb framework. 

MerbfulAuthentication is an authentication framework for the Merb Web Framework.  

Currently DataMapper is available and ActiveRecord is planned.  Although it's 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
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
end

And in your custom slice, get access to the user class with MA[:user]

===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:merbful_authentication:install


=== Load the slice in your init.rb file

# 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

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 (recommended) 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

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:merbful_authentication: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

==== Routing options
:route_path_model:    first choice for model route path.  defaults to "users" (used to make single_model_path and plural_model_path)
: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, and one called :logout is 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

:welcome_subject:       # ||= "Welcome"
:activation_subject:    # ||= "Please Activate Your Account"

------------------------------------------------------------------------------

You can put your application-level overrides in:

host-app/slices/merbful_authentication/app - controllers, models, views ...

Templates are located in this order:

1. host-app/slices/merbful_authentication/app/views/*
2. gems/merbful_authentication/app/views/*
3. host-app/app/views/*

You can use the host application's layout by configuring the
merbful_authentication slice in a before_app_loads block:

Merb::Slices.config[:merbful_authentication] = { :layout => :application }

By default :merbful_authentication is used. If you need to override
stylesheets or javascripts, just specify your own files in your layout
instead/in addition to the ones supplied (if any) in 
host-app/public/slices/merbful_authentication.

In any case don't edit those files directly as they may be clobbered any time
rake merbful_authentication:install is run.

------------------------------------------------------------------------------