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 = '[email protected]'     # Emails will come from this address i.e. [email protected], [email protected], [email protected], etc
  config.from_email_name = 'Example App'        # This will show up as the name on emails.  i.e. [email protected] <Example>
  config.support_email = '[email protected]'  # Support email for your application.  This is used for contact us etc.
  config.admin_email = '[email protected]'      # 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. = 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. = 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.
  config.send_access_code_request_confirm # Determines whether or not to send a confirmation email after a user requests an access code.
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 '/public_user/:id', :to => '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.

Access 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 helpers that will build your signup form (@user is a new empty user):

<%= signup_form(@user) %>

This will build a sign in form:

<%= signin_form %>

If you need a random access code in a page just call (@user is optional but if set it should be the user sharing the access code with another user):

<%= random_access_code(@user) %>

Notes

If you override any of the controllers in muck-users be sure to include the appropriate routes in your project. Look at lib/config/routes.rb for examples.

General information

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

Inspiration also came from: 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 © 2009-2010 Tatemae, released under the MIT license