community_engine 2.0.0.beta1

data/vendor/plugins/acts_as_publishable/generators/publishing/publishing_generator.rb

@@ -0,0 +1,34 @@
+class PublishingGenerator < Rails::Generator::Base
+
+  attr_reader :publishing_class
+  attr_reader :publishing_table_name
+
+  def initialize(args, options = {})
+    klass = args.last
+
+    begin; valid_klass = klass.camelcase.constantize; rescue; end
+
+    if valid_klass
+      @publishing_table_name = klass.to_s.downcase.pluralize
+      @publishing_class = klass.to_s.capitalize
+    else
+      raise "#{klass} is not a valid class in this application."
+    end
+  
+    super
+  end
+
+  def manifest
+    record do |m|
+      unless options[:skip_migration]
+        m.migration_template 'migration.rb', 'db/migrate',
+          :migration_file_name => "add_published_as_to_#{@publishing_table_name}"
+      end
+    end
+  end
+
+  protected
+  def usage
+    puts "Usage: #{$0} publishing [ModelName]"
+  end
+end

data/vendor/plugins/acts_as_publishable/generators/publishing/templates/migration.rb

@@ -0,0 +1,13 @@
+class AddPublishedAsTo<%= publishing_class.pluralize %> < ActiveRecord::Migration
+
+  # Add the new tables.
+  def self.up
+    add_column :<%= publishing_table_name %>, :published_as, :string, :limit => 16, :default => 'draft'
+  end
+
+  # Remove the tables.
+  def self.down
+    remove_column :<%= publishing_table_name %>, :published_as
+  end
+
+end

data/vendor/plugins/acts_as_publishable/init.rb

@@ -0,0 +1,3 @@
+require 'acts_as_publishable'
+ActiveRecord::Base.send(:include, Acts::As::Publishable)
+

data/vendor/plugins/acts_as_publishable/install.rb

@@ -0,0 +1,3 @@
+require 'fileutils'
+
+

data/vendor/plugins/acts_as_publishable/lib/acts_as_publishable.rb

@@ -0,0 +1,81 @@
+module Acts
+  module As
+    module Publishable
+
+      def self.included(base)
+        base.extend(ClassMethods)
+        
+        # All ActiveRecords will now respond to publishable? with false
+        def publishable?; false; end
+      end
+
+      module ClassMethods
+        def acts_as_publishable(*args)
+          unless args.include?(:draft) && args.include?(:live)
+            raise "you must specify :draft and :live in list of publish_states for acts_as_publishable"
+          end
+
+          cattr_accessor :publish_states
+          self.publish_states = args.collect{|state| state.to_s.downcase.to_sym }
+          include InstanceMethods
+          
+          scope :live, where(:published_as => 'live')
+          scope :draft, where(:published_as => 'draft')
+          default_scope live
+
+          # class << self
+          #   alias_method_chain :find, :published_as
+          # end
+
+          # create methods for each publish state
+          self.publish_states.each do |status|
+
+            define_method("is_#{status}?") do
+              self.published_as == status.to_s
+            end
+
+            define_method("save_as_#{status}") do
+              self.published_as = status.to_s
+              save
+            end
+
+          end
+        end
+
+        # def find_with_published_as(*args)
+        #   # hacked to filter out unpublished items by default, when using find(:all)
+        #   # to really find all items, use Class.find_without_published_as
+        #   state = args.first
+        #   state = state.eql?(:all) ? :live : state
+        #   
+        #   if self.publish_states.include?(state)
+        #     args.shift
+        #     # find_all_by_published_as(state.to_s.downcase, *args)
+        #     # again, hacked
+        #     with_scope(:find => {:conditions => ["published_as = ?", state.to_s.downcase] }) do
+        #       find_without_published_as(:all, *args)
+        #     end            
+        #   else
+        #     find_without_published_as(*args)
+        #   end  
+        # end
+
+      end
+
+      module InstanceMethods
+
+        # All ActiveRecords using this plugin will now respond to publishable? with true
+        def publishable?; true; end
+
+        def publish(should_raise = false)
+          if defined?(:save_as_live)
+            save_as_live 
+          else
+            raise "Add 'live' to list of acts_as_published for publish method" if should_raise
+          end
+        end
+
+      end
+    end
+  end
+end

data/vendor/plugins/acts_as_publishable/test/acts_as_publishable_test.rb

@@ -0,0 +1,8 @@
+require 'test/unit'
+
+class ActsAsPublishableTest < Test::Unit::TestCase
+  # Replace this with your real tests.
+  def test_this_plugin
+    flunk
+  end
+end

data/vendor/plugins/acts_as_publishable/uninstall.rb

@@ -0,0 +1 @@
+# Uninstall hook code here

data/vendor/plugins/auto_complete/README

@@ -0,0 +1,23 @@
+Example:
+
+  # Controller
+  class BlogController < ApplicationController
+    auto_complete_for :post, :title
+  end
+
+  # View
+  <%= text_field_with_auto_complete :post, title %>
+
+By default, auto_complete_for limits the results to 10 entries,
+and sorts by the given field.
+
+auto_complete_for takes a third parameter, an options hash to
+the find method used to search for the records:
+
+  auto_complete_for :post, :title, :limit => 15, :order => 'created_at DESC'
+
+For more examples, see script.aculo.us:
+* http://script.aculo.us/demos/ajax/autocompleter
+* http://script.aculo.us/demos/ajax/autocompleter_customized
+
+Copyright (c) 2007 David Heinemeier Hansson, released under the MIT license   

data/vendor/plugins/auto_complete/Rakefile

@@ -0,0 +1,22 @@
+require 'rake' 
+require 'rake/testtask' 
+require 'rake/rdoctask' 
+ 
+desc 'Default: run unit tests.' 
+task :default => :test 
+ 
+desc 'Test auto_complete plugin.' 
+Rake::TestTask.new(:test) do |t| 
+  t.libs << 'lib' 
+  t.pattern = 'test/**/*_test.rb' 
+  t.verbose = true 
+end 
+ 
+desc 'Generate documentation for auto_complete plugin.' 
+Rake::RDocTask.new(:rdoc) do |rdoc| 
+  rdoc.rdoc_dir = 'rdoc' 
+  rdoc.title    = 'Auto Complete' 
+  rdoc.options << '--line-numbers' << '--inline-source' 
+  rdoc.rdoc_files.include('README') 
+  rdoc.rdoc_files.include('lib/**/*.rb') 
+end

data/vendor/plugins/auto_complete/init.rb

@@ -0,0 +1,2 @@
+ActionController::Base.send :include, AutoComplete
+ActionController::Base.helper AutoCompleteMacrosHelper

data/vendor/plugins/auto_complete/lib/auto_complete.rb

@@ -0,0 +1,47 @@
+module AutoComplete      
+  
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  #
+  # Example:
+  #
+  #   # Controller
+  #   class BlogController < ApplicationController
+  #     auto_complete_for :post, :title
+  #   end
+  #
+  #   # View
+  #   <%= text_field_with_auto_complete :post, title %>
+  #
+  # By default, auto_complete_for limits the results to 10 entries,
+  # and sorts by the given field.
+  # 
+  # auto_complete_for takes a third parameter, an options hash to
+  # the find method used to search for the records:
+  #
+  #   auto_complete_for :post, :title, :limit => 15, :order => 'created_at DESC'
+  #
+  # For help on defining text input fields with autocompletion, 
+  # see ActionView::Helpers::JavaScriptHelper.
+  #
+  # For more examples, see script.aculo.us:
+  # * http://script.aculo.us/demos/ajax/autocompleter
+  # * http://script.aculo.us/demos/ajax/autocompleter_customized
+  module ClassMethods
+    def auto_complete_for(object, method, options = {})
+      define_method("auto_complete_for_#{object}_#{method}") do
+        find_options = { 
+          :conditions => [ "LOWER(#{method}) LIKE ?", '%' + params[object][method].downcase + '%' ], 
+          :order => "#{method} ASC",
+          :limit => 10 }.merge!(options)
+        
+        @items = object.to_s.camelize.constantize.find(:all, find_options)
+
+        render :inline => "<%= auto_complete_result @items, '#{method}' %>"
+      end
+    end
+  end
+  
+end

data/vendor/plugins/auto_complete/lib/auto_complete_macros_helper.rb

@@ -0,0 +1,143 @@
+module AutoCompleteMacrosHelper      
+  # Adds AJAX autocomplete functionality to the text input field with the 
+  # DOM ID specified by +field_id+.
+  #
+  # This function expects that the called action returns an HTML <ul> list,
+  # or nothing if no entries should be displayed for autocompletion.
+  #
+  # You'll probably want to turn the browser's built-in autocompletion off,
+  # so be sure to include an <tt>autocomplete="off"</tt> attribute with your text
+  # input field.
+  #
+  # The autocompleter object is assigned to a Javascript variable named <tt>field_id</tt>_auto_completer.
+  # This object is useful if you for example want to trigger the auto-complete suggestions through
+  # other means than user input (for that specific case, call the <tt>activate</tt> method on that object). 
+  # 
+  # Required +options+ are:
+  # <tt>:url</tt>::                  URL to call for autocompletion results
+  #                                  in url_for format.
+  # 
+  # Addtional +options+ are:
+  # <tt>:update</tt>::               Specifies the DOM ID of the element whose 
+  #                                  innerHTML should be updated with the autocomplete
+  #                                  entries returned by the AJAX request. 
+  #                                  Defaults to <tt>field_id</tt> + '_auto_complete'
+  # <tt>:with</tt>::                 A JavaScript expression specifying the
+  #                                  parameters for the XMLHttpRequest. This defaults
+  #                                  to 'fieldname=value'.
+  # <tt>:frequency</tt>::            Determines the time to wait after the last keystroke
+  #                                  for the AJAX request to be initiated.
+  # <tt>:indicator</tt>::            Specifies the DOM ID of an element which will be
+  #                                  displayed while autocomplete is running.
+  # <tt>:tokens</tt>::               A string or an array of strings containing
+  #                                  separator tokens for tokenized incremental 
+  #                                  autocompletion. Example: <tt>:tokens => ','</tt> would
+  #                                  allow multiple autocompletion entries, separated
+  #                                  by commas.
+  # <tt>:min_chars</tt>::            The minimum number of characters that should be
+  #                                  in the input field before an Ajax call is made
+  #                                  to the server.
+  # <tt>:on_hide</tt>::              A Javascript expression that is called when the
+  #                                  autocompletion div is hidden. The expression
+  #                                  should take two variables: element and update.
+  #                                  Element is a DOM element for the field, update
+  #                                  is a DOM element for the div from which the
+  #                                  innerHTML is replaced.
+  # <tt>:on_show</tt>::              Like on_hide, only now the expression is called
+  #                                  then the div is shown.
+  # <tt>:after_update_element</tt>:: A Javascript expression that is called when the
+  #                                  user has selected one of the proposed values. 
+  #                                  The expression should take two variables: element and value.
+  #                                  Element is a DOM element for the field, value
+  #                                  is the value selected by the user.
+  # <tt>:select</tt>::               Pick the class of the element from which the value for 
+  #                                  insertion should be extracted. If this is not specified,
+  #                                  the entire element is used.
+  # <tt>:method</tt>::               Specifies the HTTP verb to use when the autocompletion
+  #                                  request is made. Defaults to POST.
+  def auto_complete_field(field_id, options = {})
+    function =  "var #{field_id}_auto_completer = new Ajax.Autocompleter("
+    function << "'#{field_id}', "
+    function << "'" + (options[:update] || "#{field_id}_auto_complete") + "', "
+    function << "'#{url_for(options[:url])}'"
+    
+    js_options = {}
+    js_options[:tokens] = array_or_string_for_javascript(options[:tokens]) if options[:tokens]
+    js_options[:callback]   = "function(element, value) { return #{options[:with]} }" if options[:with]
+    js_options[:indicator]  = "'#{options[:indicator]}'" if options[:indicator]
+    js_options[:select]     = "'#{options[:select]}'" if options[:select]
+    js_options[:paramName]  = "'#{options[:param_name]}'" if options[:param_name]
+    js_options[:frequency]  = "#{options[:frequency]}" if options[:frequency]
+    js_options[:method]     = "'#{options[:method].to_s}'" if options[:method]
+
+    { :after_update_element => :afterUpdateElement, 
+      :on_show => :onShow, :on_hide => :onHide, :min_chars => :minChars }.each do |k,v|
+      js_options[v] = options[k] if options[k]
+    end
+
+    function << (', ' + options_for_javascript(js_options) + ')')
+
+    javascript_tag(function)
+  end
+  
+  # Use this method in your view to generate a return for the AJAX autocomplete requests.
+  #
+  # Example action:
+  #
+  #   def auto_complete_for_item_title
+  #     @items = Item.find(:all, 
+  #       :conditions => [ 'LOWER(description) LIKE ?', 
+  #       '%' + request.raw_post.downcase + '%' ])
+  #     render :inline => "<%= auto_complete_result(@items, 'description') %>"
+  #   end
+  #
+  # The auto_complete_result can of course also be called from a view belonging to the 
+  # auto_complete action if you need to decorate it further.
+  def auto_complete_result(entries, field, phrase = nil)
+    return unless entries
+    items = entries.map { |entry| content_tag("li", phrase ? highlight(entry[field], phrase) : h(entry[field])) }
+    content_tag("ul", items.uniq)
+  end
+  
+  # Wrapper for text_field with added AJAX autocompletion functionality.
+  #
+  # In your controller, you'll need to define an action called
+  # auto_complete_for to respond the AJAX calls,
+  # 
+  def text_field_with_auto_complete(object, method, tag_options = {}, completion_options = {})
+    (completion_options[:skip_style] ? "" : auto_complete_stylesheet) +
+    text_field(object, method, tag_options) +
+    content_tag("div", "", :id => "#{object}_#{method}_auto_complete", :class => "auto_complete") +
+    auto_complete_field("#{object}_#{method}", { :url => { :action => "auto_complete_for_#{object}_#{method}" } }.update(completion_options))
+  end
+
+  private
+    def auto_complete_stylesheet
+      content_tag('style', <<-EOT, :type => Mime::CSS)
+        div.auto_complete {
+          width: 350px;
+          background: #fff;
+        }
+        div.auto_complete ul {
+          border:1px solid #888;
+          margin:0;
+          padding:0;
+          width:100%;
+          list-style-type:none;
+        }
+        div.auto_complete ul li {
+          margin:0;
+          padding:3px;
+        }
+        div.auto_complete ul li.selected {
+          background-color: #ffb;
+        }
+        div.auto_complete ul strong.highlight {
+          color: #800; 
+          margin:0;
+          padding:0;
+        }
+      EOT
+    end
+
+end   

data/vendor/plugins/auto_complete/test/auto_complete_test.rb

@@ -0,0 +1,67 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '../../../../test/test_helper')) 
+
+class AutoCompleteTest < Test::Unit::TestCase
+  include AutoComplete
+  include AutoCompleteMacrosHelper
+  
+  include ActionView::Helpers::UrlHelper
+  include ActionView::Helpers::TagHelper
+  include ActionView::Helpers::TextHelper
+  include ActionView::Helpers::FormHelper
+  include ActionView::Helpers::CaptureHelper
+  
+  def setup
+    @controller = Class.new do
+      def url_for(options)
+        url =  "http://www.example.com/"
+        url << options[:action].to_s if options and options[:action]
+        url
+      end
+    end
+    @controller = @controller.new
+  end
+
+
+  def test_auto_complete_field
+    assert_dom_equal %(<script type=\"text/javascript\">\n//<![CDATA[\nvar some_input_auto_completer = new Ajax.Autocompleter('some_input', 'some_input_auto_complete', 'http://www.example.com/autocomplete', {})\n//]]>\n</script>),
+      auto_complete_field("some_input", :url => { :action => "autocomplete" });
+    assert_dom_equal %(<script type=\"text/javascript\">\n//<![CDATA[\nvar some_input_auto_completer = new Ajax.Autocompleter('some_input', 'some_input_auto_complete', 'http://www.example.com/autocomplete', {tokens:','})\n//]]>\n</script>),
+      auto_complete_field("some_input", :url => { :action => "autocomplete" }, :tokens => ',');
+    assert_dom_equal %(<script type=\"text/javascript\">\n//<![CDATA[\nvar some_input_auto_completer = new Ajax.Autocompleter('some_input', 'some_input_auto_complete', 'http://www.example.com/autocomplete', {tokens:[',']})\n//]]>\n</script>),
+      auto_complete_field("some_input", :url => { :action => "autocomplete" }, :tokens => [',']);  
+    assert_dom_equal %(<script type=\"text/javascript\">\n//<![CDATA[\nvar some_input_auto_completer = new Ajax.Autocompleter('some_input', 'some_input_auto_complete', 'http://www.example.com/autocomplete', {minChars:3})\n//]]>\n</script>),
+      auto_complete_field("some_input", :url => { :action => "autocomplete" }, :min_chars => 3);
+    assert_dom_equal %(<script type=\"text/javascript\">\n//<![CDATA[\nvar some_input_auto_completer = new Ajax.Autocompleter('some_input', 'some_input_auto_complete', 'http://www.example.com/autocomplete', {onHide:function(element, update){alert('me');}})\n//]]>\n</script>),
+      auto_complete_field("some_input", :url => { :action => "autocomplete" }, :on_hide => "function(element, update){alert('me');}");
+    assert_dom_equal %(<script type=\"text/javascript\">\n//<![CDATA[\nvar some_input_auto_completer = new Ajax.Autocompleter('some_input', 'some_input_auto_complete', 'http://www.example.com/autocomplete', {frequency:2})\n//]]>\n</script>),
+      auto_complete_field("some_input", :url => { :action => "autocomplete" }, :frequency => 2);
+    assert_dom_equal %(<script type=\"text/javascript\">\n//<![CDATA[\nvar some_input_auto_completer = new Ajax.Autocompleter('some_input', 'some_input_auto_complete', 'http://www.example.com/autocomplete', {afterUpdateElement:function(element,value){alert('You have chosen: '+value)}})\n//]]>\n</script>),
+      auto_complete_field("some_input", :url => { :action => "autocomplete" }, 
+        :after_update_element => "function(element,value){alert('You have chosen: '+value)}");
+    assert_dom_equal %(<script type=\"text/javascript\">\n//<![CDATA[\nvar some_input_auto_completer = new Ajax.Autocompleter('some_input', 'some_input_auto_complete', 'http://www.example.com/autocomplete', {paramName:'huidriwusch'})\n//]]>\n</script>),
+      auto_complete_field("some_input", :url => { :action => "autocomplete" }, :param_name => 'huidriwusch');
+    assert_dom_equal %(<script type=\"text/javascript\">\n//<![CDATA[\nvar some_input_auto_completer = new Ajax.Autocompleter('some_input', 'some_input_auto_complete', 'http://www.example.com/autocomplete', {method:'get'})\n//]]>\n</script>),
+      auto_complete_field("some_input", :url => { :action => "autocomplete" }, :method => :get);
+  end
+  
+  def test_auto_complete_result
+    result = [ { :title => 'test1'  }, { :title => 'test2'  } ]
+    assert_equal %(<ul><li>test1</li><li>test2</li></ul>), 
+      auto_complete_result(result, :title)
+    assert_equal %(<ul><li>t<strong class=\"highlight\">est</strong>1</li><li>t<strong class=\"highlight\">est</strong>2</li></ul>), 
+      auto_complete_result(result, :title, "est")
+    
+    resultuniq = [ { :title => 'test1'  }, { :title => 'test1'  } ]
+    assert_equal %(<ul><li>t<strong class=\"highlight\">est</strong>1</li></ul>), 
+      auto_complete_result(resultuniq, :title, "est")
+  end
+  
+  def test_text_field_with_auto_complete
+    assert_match %(<style type="text/css">),
+      text_field_with_auto_complete(:message, :recipient)
+
+    assert_dom_equal %(<input id=\"message_recipient\" name=\"message[recipient]\" size=\"30\" type=\"text\" /><div class=\"auto_complete\" id=\"message_recipient_auto_complete\"></div><script type=\"text/javascript\">\n//<![CDATA[\nvar message_recipient_auto_completer = new Ajax.Autocompleter('message_recipient', 'message_recipient_auto_complete', 'http://www.example.com/auto_complete_for_message_recipient', {})\n//]]>\n</script>),
+      text_field_with_auto_complete(:message, :recipient, {}, :skip_style => true)
+  end
+  
+end

data/vendor/plugins/enumerations_mixin/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2005 Trevor Squires
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject
+to the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
+ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/vendor/plugins/enumerations_mixin/README_ENUMERATIONS

@@ -0,0 +1,163 @@
+Enumerations Mixin
+Copyright (c) 2005 Trevor Squires
+Released under the MIT License.  See the LICENSE file for more details.
+
+What is this?:
+
+The enumerations mixin allows you to treat instances of your
+ActiveRecord models as though they were an enumeration of values.
+
+At it's most basic level, it allows you to say things along the lines of:
+
+booking = Booking.new(:status => BookingStatus[:provisional])
+booking.update_attribute(:status, BookingStatus[:confirmed])
+
+Booking.find :first, 
+						 :conditions => ['status_id = ?', BookingStatus[:provisional].id]
+
+BookingStatus.all.collect {|status|, [status.name, status.id]}
+
+See "How to use it" below for more information.
+
+Package Contents:
+
+This package adds two mixins and a helper to Rails' ActiveRecord:
+
+acts_as_enumerated provides capabilities to treat your model and
+its records as an enumeration. At a minimum, the database table for
+an acts_as_enumerated must contain an 'id' column and a 'name'
+column.  All instances for the acts_as_enumerated model are cached
+in memory.
+
+has_enumerated adds methods to your ActiveRecord model for setting
+and retrieving enumerated values using an associated acts_as_enumerated
+model.
+
+There is also an ActiveRecord::VirtualEnumerations helper module
+to create 'virtual' acts_as_enumerated models which helps to avoid
+cluttering up your models directory with acts_as_enumerated classes.
+
+How to use it:
+
+* acts_as_enumerated
+
+class BookingStatus < ActiveRecord::Base
+acts_as_enumerated  :conditions => 'optional_sql_conditions', 
+                    :order => 'optional_sql_orderby',
+                    :on_lookup_failure => :optional_class_method
+end
+
+With that, your BookingStatus class will have the following methods defined:
+
+* BookingStatus[arg] : lookup the BookingStatus instance for arg.
+The arg value can be a 'string' or a :symbol, in which case the
+lookup will be against the BookingStatus.name field.  Alternatively
+arg can be a Fixnum, in which case the lookup will be against the
+BookingStatus.id field.
+
+The :on_lookup_failure option specifies the name of a class method
+to invoke when the [] method is unable to locate a BookingStatus
+record for arg.  The defeault is the built-in :enforce_strict_literals
+which causes an exception to be raised when no record is found and
+the arg is a Fixnum or Symbol, otherwise it returns nil.  There are
+also built-ins for :enforce_strict (raise and exception regardless
+of the type for arg) and :enforce_none which just returns nil.
+
+The whole point of the :on_lookup_failure option is that I'm pretty
+opinionated that a) if the value can't be looked-up for a :symbol
+that I've passed, it's probably a typo so I want a *big* hint that
+something is wrong and b) it's likely that my opinion isn't shared
+by everyone so it should be configurable.
+
+* BookingStatus.all : returns an array of all BookingStatus records
+that match the :conditions specified in acts_as_enumerated, in the
+order specified by :order.
+
+NOTE: acts_as_enumerated records are considered immutable.  By
+default you cannot create/alter/destroy instances because they are
+cached in memory.  Because of Rails' process-based model it is not
+safe to allow updating acts_as_enumerated records as the caches
+will get out of sync.
+
+However, one instance where updating the models *should* be allowed
+is if you are using ActiveRecord Migrations.
+
+Using the above example you would do the following:
+
+BookingStatus.enumeration_model_updates_permitted = true
+BookingStatus.create(:name => 'newname')
+
+* has_enumerated
+
+First of all, note that you *could* specify the relationship
+to an acts_as_enumerated class using the belongs_to association.
+However, has_enumerated is preferable because you aren't really
+associated to the enumerated value, you are *aggregating* it.
+As such, the has_enumerated macro behaves more like an aggregation
+than an association.
+
+class Booking < ActiveRecord::Base
+has_enumerated  :status, :class_name => 'BookingStatus',
+                :foreign_key => 'status_id', 
+                :on_lookup_failure => :optional_instance_method
+end
+
+By default, the foreign key is interpreted to be the name of your
+has_enumerated field (in this case 'status') plus '_id'.  Additionally,
+the default value for :class_name is the camel-ized version of the
+name for your has_enumerated field.  :on_lookup_failure is explained
+below.
+
+With that, your Booking class will have the following methods defined:
+
+* status : returns the BookingStatus with an id that matches the
+value in the Booking.status_id.
+
+* status= : sets the value for Booking.status_id using the id of
+the BookingStatus instance passed as an argument.  As a short-hand,
+you can also pass it the 'name' of a BookingStatus instance, either
+as a 'string' or :symbol.
+
+I.e. mybooking.status = :confirmed or mybooking.update_attribute(:status,
+:confirmed)
+
+The :on_lookup_failure option in has_enumerated is there because
+(again) I'm opinionated about what should happen.  By default, if
+booking.status_id contains an id that isn't a valid BookingStatus.id
+I just want booking.status to return nil rather than throw an
+exception.  This ensures I can edit my Booking instances without
+having to put rescue blocks around all my booking.status calls.
+However, if I call booking.status = :bogus I want noisy hints about
+the bug.
+
+Of course, you may not agree with that in which case you can specify
+an *instance* method to be called in the case of a lookup failure.
+The method signature is as follows:
+
+your_lookup_handler(operation, name, name_foreign_key, 
+										acts_enumerated_class_name, lookup_value)
+
+The 'operation' arg will be either :read or :write.  In the case
+of :read you are expected to return something or raise an exception,
+while in the case of a :write you don't have to return anything.
+
+Note that there's enough information in the method signature that
+you can specify one method to handle all lookup failures for all
+has_enumerated fields if you happen to have more than one defined
+in your model.
+
+* ActiveRecord::VirtualEnumerations
+
+For the most part, your acts_as_enumerated classes will do nothing
+more than just act as enumerated.  
+
+In that case there isn't much point cluttering up your models
+directory with those class files.  You can use
+ActiveRecord::VirtualEnumerations to reduce that clutter.
+
+Copy virtual_enumerations_sample.rb to
+Rails.root/config/virtual_enumerations.rb and configure it accordingly.
+
+See virtual_enumerations_sample.rb in this directory for a full
+description.
+