@@ -5,13 +5,63 @@ A slice for the Merb framework. MerbfulAuthentication is an authentication framework for the Merb Web Framework. -Currently Activerecord and Datamapper support is planned. Although it's easy to add your own. +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: -file: config/init.rb +=== 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 @@ -21,36 +71,78 @@ dependency 'merbful_authentication' Merb::Plugins.config[:merb_slices] = { :queue => ["MerbfulAuthentication", ...] } -# optionally configure the plugins in a before_app_loads callback -Merb::BootLoader.before_app_loads do - - Merb::Slices::config[:merbful_authentication] = { ... } - -end -file: config/router.rb +=== 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 -# example: /merbful_authentication/:controller/:action/:id +If you'd like to specify MerbfulAuthentication r.add_slice(:MerbfulAuthentication) -# example: /foo/:controller/:action/:id +By default this will mount the slice at /merbful_authentication. So your login url will be at -r.add_slice(:MerbfulAuthentication, 'foo') # same as :path => 'foo' +/merbful_authentication/login -# example: /:lang/:controller/:action/:id (with :a param set) +If you'd like to specify a different mount point in your application (recommended) do it like this. -r.add_slice(:MerbfulAuthentication, :path => ':lang', :params => { :a => 'b' }) +r.add_slice(:MerbfulAuthentication, 'authentcation') -# example: /:controller/:action/:id +Your login url will now be /authentication/login, your signup url will be at /authentication/users/new -r.slice(:MerbfulAuthentication) +If you'd like to set more options, I suggest you look up the merb-slices documentation. -Normally you should also run the following rake task: + + +=== 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: README @@ -86,7 +86,7 @@ if defined?(Merb::Plugins) # routes at any level of your router setup. def self.setup_router(scope) plural_model_path = MA[:route_path_model] || MA[:plural_resource] - plural_model_path ||= (MA[:user_class_name] = "User").to_s.snake_case.singularize.pluralize + plural_model_path ||= "User".snake_case.singularize.pluralize plural_model_path = plural_model_path.to_s.match(%r{^/?(.*?)/?$})[1] single_model_name = plural_model_path.singularize @@ -97,23 +97,23 @@ if defined?(Merb::Plugins) activation_name = (MA[:single_resource].to_s << "_activation").to_sym MA[:routes] = {:user => {}} - MA[:routes][:user][:new] = :"new_#{single_model_name}" - MA[:routes][:user][:show] = :"#{single_model_name}" - MA[:routes][:user][:edit] = :"edit_#{single_model_name}" - MA[:routes][:user][:delete] = :"delete_#{single_model_name}" - MA[:routes][:user][:index] = :"#{plural_model_path}" - MA[:routes][:user][:activate] = :"#{single_model_name}_activation" + MA[:routes][:user][:new] ||= :"new_#{single_model_name}" + MA[:routes][:user][:show] ||= :"#{single_model_name}" + MA[:routes][:user][:edit] ||= :"edit_#{single_model_name}" + MA[:routes][:user][:delete] ||= :"delete_#{single_model_name}" + MA[:routes][:user][:index] ||= :"#{plural_model_path}" + MA[:routes][:user][:activate] ||= :"#{single_model_name}_activation" # Setup the model path scope.to(:controller => "Users") do |c| c.match("/#{plural_model_path}") do |u| # setup the named routes - u.match("/new", :method => :get ).to( :action => "new" ).name(:"new_#{single_model_name}") - u.match("/:id", :method => :get ).to( :action => "show" ).name(:"#{single_model_name}") - u.match("/:id/edit", :method => :get ).to( :action => "edit" ).name(:"edit_#{single_model_name}") - u.match("/:id/delete", :method => :get ).to( :action => "delete" ).name(:"delete_#{single_model_name}") - u.match("/", :method => :get ).to( :action => "index" ).name(:"#{plural_model_path}") - u.match("/activate/:activation_code", :method => :get).to( :action => "activate").name(:"#{single_model_name}_activation") + u.match("/new", :method => :get ).to( :action => "new" ).name(MA[:routes][:user][:new]) + u.match("/:id", :method => :get ).to( :action => "show" ).name(MA[:routes][:user][:show]) + u.match("/:id/edit", :method => :get ).to( :action => "edit" ).name(MA[:routes][:user][:edit]) + u.match("/:id/delete", :method => :get ).to( :action => "delete" ).name(MA[:routes][:user][:delete]) + u.match("/", :method => :get ).to( :action => "index" ).name(MA[:routes][:user][:index]) + u.match("/activate/:activation_code", :method => :get).to( :action => "activate").name(MA[:routes][:user][:activate]) # Make the anonymous routes u.match(%r{(/|/index)?(\.:format)?$}, :method => :get ).to( :action => "index") lib/merbful_authentication.rb @@ -12,7 +12,6 @@ describe MerbfulAuthentication do @adapter_path = File.dirname(__FILE__) / ".." / "lib" / "merbful_authentication" / "adapters" @ar_path = @adapter_path / "activerecord" @config = Merb::Slices::config[:merbful_authentication] - @config[:user_class_name] = "User" DataMapper.setup(:default, 'sqlite3:///:memory:') end spec/merbful_authentication_spec.rb d0f8c6d881ca762486c3daabdd65fa824197082d Daniel Neighman has.sox@gmail.com http://github.com/hassox/merbful_authentication/commit/681046faf3a77c27b6a2c73203d83b326c9959a2 681046faf3a77c27b6a2c73203d83b326c9959a2 2008-06-02T08:25:31-07:00 2008-06-02T08:25:31-07:00 Adds a reasonable readme c053c4dc1eeca70548e1ab4a29a42f976d0fb658 Daniel Neighman has.sox@gmail.com