= Muck Users

== Installation

The muck users engine is part of the muck framework and relies upon the muck-engine as well as authlogic.
Both gems should be installed automatically when you install the muck-users engine.

Make sure that your 'Gemfile' contains the following:

  config.gem "authlogic"
  config.gem "muck-users"

If you used the muck template to create your rails application you will have a secrets.yml file.  If not then you will need to create a 
secrets.yml file and then add the following to environment.rb right above Rails::Initializer.run do |config|

  require 'ostruct'
  require 'yaml'
  ::Secrets = OpenStruct.new(YAML.load_file(File.expand_path('../secrets.yml', __FILE__))[Rails.env])

Omit secrets.yml from your version control system and use it to keep sensitive data like email server credentials

  email_user_name: 'TODO_admin@#{domain_name}'    # Email server username
  email_password = 'TODO_password'                # Email server password

  production:
    <<: *DEFAULT
    # Add production only secrets
  staging:
    <<: *DEFAULT
    # Add staging only secrets
  development:
    <<: *DEFAULT
    # Development specific
  test:
    <<: *DEFAULT
    # Test specific
  

=== Configuration

Create an initializer and add the following adjusting the settings to meet your specific needs:

  MuckEngine.configure do |config|
  
    # Global application values.  These are used to display the app name, send emails, and configure where system emails go.
    if Rails.env.production?
      config.application_url = 'www.#{domain_name}'     # Url of the application in production
    elsif Rails.env.staging?
      config.application_url = 'www.#{domain_name}'     # Url of the application on staging
    else
      config.application_url = 'localhost:3000'         # Url of the application for test or development
    end
  
    config.application_name = 'Example App'       # Common name for your application.  i.e. My App, Billy Bob, etc
    config.from_email = 'support@example.com'     # Emails will come from this address i.e. noreply@example.com, support@example.com, system@example.com, etc
    config.from_email_name = 'Example App'        # This will show up as the name on emails.  i.e. support@example.com <Example>
    config.support_email = 'support@example.com'  # Support email for your application.  This is used for contact us etc.
    config.admin_email = 'admin@example.com'      # Admin email for your application
    config.customer_service_number = '1-800-'     # Phone number if you have one (optional)
  
    # Email charset.  No need to change this unless you have a good reason to change the encoding.
    config.mail_charset = 'utf-8'

    # Email server configuration
    # Sendgrid is easy: https://sendgrid.com/user/signup
    config.email_server_address = "smtp.sendgrid.net"   # Email server address.  'smtp.sendgrid.net' works for sendgrid
    config.email_user_name = Secrets.email_user_name    # Email server username
    config.email_password = Secrets.email_password      # Email server password
    config.base_domain = 'example.com'                  # Basedomain that emails will come from
    
    # ssl
    config.enable_ssl = false # Enable ssl if you have an ssl certificate installed.  This will provide security between the client and server.
  
    # Google Analtyics Configuration.  This will enable Google Analytics on your site and will be used if your template includes:
    #                                  <%= render :partial => 'layouts/global/google_analytics' %>
    config.google_tracking_code = ""                    # Get a tracking code here: http://www.google.com/analytics/. The codes look like this: 'UA-9685000-0'
    config.google_tracking_set_domain = "example.com"   # Base domain provided to Google Analytics. Useful if you are using subdomains but want all traffic 
                                                # recorded into one account.
  end

  MuckUsers.configure do |config|
    config.automatically_activate = true                    # Automatically active a users account during registration. If true the user won't get a 
                                                            # 'confirm account' email. If false then the user will need to confirm their account via an email.
    config.automatically_login_after_account_create = true  # Automatically log the user in after they have setup their account. This should be false if you 
                                                            # require them to activate their account.
    config.send_welcome = true                              # Send out a welcome email after the user has signed up.

    # if you use recaptcha you will need to also provide a public and private key available from http://recaptcha.net.
    config.use_recaptcha = false      # This will turn on recaptcha during registration. This is an alternative to sending the 
                                      # user a confirm email and can help reduce spam registrations.

    config.require_access_code = false              # Only let a user sign up if they have an access code
    config.let_users_delete_their_account = false   # Turn on/off ability for users to delete their own account. It is not recommended that you let 
                                                    # users delete their own accounts since the delete can cascade through the system with unknown results.
  end

  
== Usage

There are a couple of routes that muck-users will look for:

Route to the site home page:

  root :to => "default#index"

Route to a public user page (this could also go to home etc. if needed)
  match '/profiles/:id' => 'profiles#show', :as => :public_user
  
This is the path that a user will be redirected to if they attempt to access another user's dashboard page.

By default when a user logs out they are sent to the login page.  You can add a new route and change the behavior:
 
  match '/login' => 'user_session#new', :as => :logout_complete

muck-users sends out emails that need to be able to generate links.  Be sure to set a value for MuckEngine.configuration.application_url.

muck-users will let you require an access code to sign up. If you enable this option your sign up form will add a link for a beta code. 
To make it a popup add this to your application.js

  jQuery('a.fancy-access-request').fancybox({'hideOnContentClick':false, 'overlayShow':true, 'width':375, 'height':300 });

=== Assets

Calling rake muck:sync:users will pull in images, javascript and other assets. 
The javascript is automatically included when needed and does not need to be added to the head of your document.
It is recommended that you include muck-users.css or copy it's content's and modify it as needed.

=== Beta Codes
muck-users includes the ability to require a code to sign up. Add a sign up form to collect emails:

  <%= muck_form_for :access_code_request, :url => access_code_requests_path, :html => { :class => 'ajax beta_code_request_form' } do |f| -%>
    <%= f.text_field :email, { :label => translate('muck.users.access_request_email')  } -%>
    <%= f.text_field :name, { :label => translate('muck.users.access_request_name')  } -%>
    <%= f.submit translate('muck.users.submit') %>
  <% end -%>

Note that using the css classes 'ajax beta_code_request_form' will result in an ajax submission. Both classes are important for the request to work.

All emails will be stored in the database. Access the admin to send out beta codes:
  
  http://yoursite.com/admin/access_codes

=== Helpers
Muck users provides an autocomplete login search.  To enable this functionality create a text box with the class 'login-search' and add 
the following code to include the needed javascript and css:

  <% content_for :head do -%>
  <%= javascript_include_tag 'jquery/jquery.autocomplete.min.js' %>
  <%= javascript_include_tag 'muck-users' %>
  <%= stylesheet_link_tag 'jquery/jquery.autocomplete.js' %>
  <% end -%>

If you override the users controller you will also need to include login_search in your routes:
  map.resources :users, :collection => { :login_search => :get }


== General information
This engine implements authlogic.  Some of the code contained was taken from here:
http://railsforum.com/viewtopic.php?id=14216 and here
http://github.com/activefx/restful_authentication_tutorial/tree/master

Inspiration also came from:
http://github.com/tsechingho/authlogic_bundle/tree/master

Example
=======
After installing the engine just create a user model thus:

  class User < ActiveRecord::Base
    acts_as_authentic
    include MuckUsers::Models::MuckUser
  end

Then you will be able to go to:
http//:localhost:3000/login
http//:localhost:3000/signup


Copyright (c) 2009-2010 Tatemae, released under the MIT license