Added some documentation for acts_as_cms_user

doc/release_notes.txt

@@ -10,6 +10,12 @@ Add the ability to add BrowserCMS to Rails projects.
 
     create_table prefix(:users)
 
+* Added some basic support for making other 'user' objects act like CMS users via Cms::Acts::User. For example, the following would make a custom non-CMS user gain permission to act like an admin.
+
+ class MyCustomUser < ActiveRecord::Base
+    acts_as_cms_user :groups => [Cms::Group.find_by_code('admin')]
+ end
+
 v3.3.0
 ======
 

lib/cms/acts/cms_user.rb

@@ -1,16 +1,29 @@
-# A class designed to be included in Active Record models that makes it act like a CMS user for a specific group.
-#
-
 module Cms
   module Acts
+
+    # Allows any ActiveRecord object to behave like a Cms User. This is a bit of an experiment being added to 3.4, so
+    # so it might be deprecated in a future version if we add something like devise.
+    #
+    # The use case would be something like:
+    #
+    #   class AdminUser < ActiveRecord::Base
+    #     acts_as_cms_user :groups => [Cms::Group.find_by_code('admin')]
+    #   end
+    #
+    # where groups could be an array, proc, or instance method (as a symbol).
+    # Could be used it with authlogic to grant logins and permissions to
+    # everyone in a custom model.  It's not quite a drop in authentication
+    # schema, but it does make it easier to wire up just about any model to be
+    # the current_user on CMS pages.
     module CmsUser
       def self.included(model_class)
         model_class.extend(MacroMethods)
       end
+
       module MacroMethods
         def acts_as_cms_user(options = {})
           include InstanceMethods
-          
+
           # Adding a cms_group method to each person object that returns a list of
           # CMS Groups the user belongs to.  Can be set with an array, proc, or
           # instance method on the person.  Defaults to Cms::Group.guest
@@ -28,23 +41,23 @@ def acts_as_cms_user(options = {})
                 raise ArgumentError, "acts_as_cms_user :groups option expected to be of type Array, Proc, or instance method - #{options[:groups].class} found instead"
               end
             end
-            
+
             @cms_groups ||= begin
-              specified = Array(fetch_group_list.call).select{|x| x.kind_of? Cms::Group }
+              specified = Array(fetch_group_list.call).select { |x| x.kind_of? Cms::Group }
               specified << Cms::Group.guest if specified.empty?
               specified
             end
-              
-          end                    
+
+          end
         end
-        
+
         module InstanceMethods
-          
+
           # The following came from Cms::User
           def guest?
             false
           end
-          
+
           # Determine if this user has permission to view the specific object. Permissions
           #   are always tied to a specific section. This method can take different input parameters
           #   and will attempt to determine the relevant section to check.
@@ -58,26 +71,26 @@ def guest?
           def able_to_view?(object)
             section = object
             if object.is_a?(String)
-               section = Cms::Section.find_by_path(object)
-               raise ActiveRecord::RecordNotFound.new("Could not find section with path = '#{object}'") unless section
+              section = Cms::Section.find_by_path(object)
+              raise ActiveRecord::RecordNotFound.new("Could not find section with path = '#{object}'") unless section
             elsif !object.is_a?(Cms::Section)
               section = object.section
             end
             viewable_sections.include?(section) || cms_access?
           end
-          
-          
+
+
           # The following came from Cms::GuestUser or Cms::User
-          
+
           # Expects a list of names of Permissions
           # true if the user has any of the permissions
           def able_to?(*required_permissions)
             perms = required_permissions.map(&:to_sym)
-            permissions.any? do |p| 
-              perms.include?(p.name.to_sym) 
+            permissions.any? do |p|
+              perms.include?(p.name.to_sym)
             end
           end
-          
+
 
           # Guests never get access to the CMS.
           def cms_access?
@@ -89,7 +102,7 @@ def cms_access?
           def viewable_sections
             @viewable_sections ||= Cms::Section.find(:all, :include => :groups, :conditions => ["#{Cms::Group.table_name}.id  in (?)", cms_groups.collect(&:id)])
           end
-          
+
           def permissions
             @permissions ||= Cms::Permission.find(:all, :include => :groups, :conditions => ["#{Cms::Group.table_name}.id  in (?)", cms_groups.collect(&:id)])
           end