arturo 1.0.0 → 1.1.0

data/README.md

@@ -48,7 +48,7 @@ the feature:
 
     # in app/controllers/postings_controller:
     class PostingsController < ApplicationController
-      require_feature! :live_postings, :only => :recent
+      require_feature :live_postings, :only => :recent
       # ...
     end
 
@@ -92,13 +92,17 @@ checkout.
 
 ### In Rails
 
-#### Run the migrations:
+#### Run the generators:
 
     $ rails g arturo:migration
     $ rails g arturo:initializer
     $ rails g arturo:route
     $ rails g arturo:assets
 
+#### Run the migration:
+
+    $ rake db:migrate
+
 #### Edit the configuration
 
 ##### Initializer
@@ -106,10 +110,10 @@ checkout.
 Open up the newly-generated `config/initializers/arturo_initializer.rb`.
 There are configuration options for the following:
 
- * the block that determines whether a user has permission to manage features
+ * the method that determines whether a user has permission to manage features
    (see [admin permissions](#adminpermissions))
- * the block that yields the object that has features
-   (a User, Person, or Account, see
+ * the method that returns the object that has features
+   (e.g. User, Person, or Account; see
    [feature recipients](#featurerecipients))
  * whitelists and blacklists for features
    (see [white- and blacklisting](#wblisting))
@@ -132,20 +136,19 @@ work with you on support for your favorite framework.
 
 ### <span id='adminpermissions'>Admin Permissions</span>
 
-`Arturo.permit_management` is a block that is run in the context of
-a Controller instance. It should return `true` iff the current user
-can manage permissions. Configure the block in
-`config/initializers/arturo_initializer.rb`. A reasonable implementation
-might be
+`Arturo::FeatureManagement#may_manage_features?` is a method that is run in
+the context of a Controller or View instance. It should return `true` if
+and only if the current user may manage permissions. The default implementation
+is as follows:
 
-    Arturo.permit_management do
-      current_user.admin?
-    end
+    current_user.present? && current_user.admin?
 
-or
+You can change the implementation in
+`config/initializers/arturo_initializer.rb`. A reasonable implementation
+might be
 
     Arturo.permit_management do
-      signed_in? && signed_in_person.can?(:manage_features)
+      signed_in? && current_user.can?(:manage_features)
     end
 
 ### <span id='featurerecipients'>Feature Recipients</span>
@@ -157,35 +160,23 @@ early days -- may have deployed features on a per-university basis. It wouldn't
 make much sense to deploy a feature to one user of a Basecamp project but not
 to others, so 37Signals would probably want a per-project or per-account basis.
 
-`Arturo.feature_recipient` is intended to support these many use cases. It is a
-block that returns the current "thing" (a user, account, project, university,
-...) that is a member of the category that is the basis for deploying new
-features. Like `Arturo.permit_management`, it is configured in
-`config/initializers/arturo_initializer.rb`. It should return an `Object` that
-responds to `#id`. If you want to deploy features on a per-user basis, a
-reasonable implementation might be
-
-    Arturo.thing_that_has_features do
-      current_user
-    end
-
-or
-
-    Arturo.thing_that_has_features do
-      signed_in_person
-    end
+`Arturo::FeatureAvailability#feature_recipient` is intended to support these
+many use cases. It is a method that returns the current "thing" (a user, account,
+project, university, ...) that is a member of the category that is the basis for
+deploying new features. It should return an `Object` that responds to `#id`.
 
-If, on the other hand, you have accounts that have many users and you
-want to deploy features on a per-account basis, a reasonable implementation
-might be
+The default implementation simply returns `current_user`. Like
+`Arturo::FeatureManagement#may_manage_features?`, this method can be configured
+in `config/initializers/arturo_initializer.rb`. If you want to deploy features
+on a per-account basis, a reasonable implementation might be
 
-    Arturo.thing_that_has_features do
+    Arturo.feature_recipient do
       current_account
     end
 
 or
 
-    Arturo.thing_that_has_features do
+    Arturo.feature_recipient do
       current_user.account
     end
 
@@ -224,10 +215,10 @@ every action within `BookHoldsController` that is invoked by a user who
 does not have the `:hold_book` feature.
 
     class BookHoldsController < ApplicationController
-      require_feature! :hold_book
+      require_feature :hold_book
     end
 
-`require_feature!` accepts as a second argument a `Hash` that it passes on
+`require_feature` accepts as a second argument a `Hash` that it passes on
 to `before_filter`, so you can use `:only` and `:except` to specify exactly
 which actions are filtered.
 
@@ -258,11 +249,11 @@ The latter can be used like so:
 
 **Note**: Arturo does not yet have caching support. Be very careful when
 caching actions or pages that involve feature detection as you will get
-strange behavior when a use who has access to a feature requests a page
+strange behavior when a user who has access to a feature requests a page
 just after one who does not (and vice versa). The following is the
 **intended** support for caching.
 
-Both the `require_feature!` before filter and the `if_feature_enabled` block
+Both the `require_feature` before filter and the `if_feature_enabled` block
 evaluation automatically append a string based on the feature's
 `last_modified` timestamp to cache keys that Rails generates. Thus, you don't
 have to worry about expiring caches when you increase a feature's deployment
@@ -272,4 +263,4 @@ percentage. See `Arturo::CacheSupport` for more information.
 
 Arturo gets its name from
 [Professor Maximillian Arturo](http://en.wikipedia.org/wiki/Maximillian_Arturo)
-on [Sliders](http://en.wikipedia.org/wiki/Sliders).
+on [Sliders](http://en.wikipedia.org/wiki/Sliders).

data/app/controllers/arturo/features_controller.rb

@@ -17,6 +17,8 @@ module Arturo
   # should redefine Arturo::FeaturesController#permitted? to
   # return true only for users who are permitted to manage features.
   class FeaturesController < base
+    include Arturo::FeatureManagement
+
     unloadable
     respond_to :html, :json, :xml
     before_filter :require_permission
@@ -95,7 +97,7 @@ module Arturo
     protected
 
     def require_permission
-      unless Arturo.permit_management?(self)
+      unless may_manage_features?
         render :action => 'forbidden', :status => 403
         return false
       end

data/lib/arturo.rb

@@ -1,8 +1,8 @@
 module Arturo
 
-  require 'arturo/configuration'
   require 'arturo/special_handling'
   require 'arturo/feature_availability'
+  require 'arturo/feature_management'
   require 'arturo/controller_filters'
   require 'arturo/engine' if defined?(Rails) && Rails::VERSION::MAJOR == 3
 

data/lib/arturo/controller_filters.rb

@@ -18,7 +18,7 @@ module Arturo
 
     module ClassMethods
 
-      def require_feature!(name, options = {})
+      def require_feature(name, options = {})
         before_filter options do |controller|
           unless controller.feature_enabled?(name)
             controller.on_feature_disabled(name)

data/lib/arturo/engine.rb

@@ -4,6 +4,7 @@ module Arturo
       include Arturo::FeatureAvailability
       helper  Arturo::FeatureAvailability
       include Arturo::ControllerFilters
+      helper  Arturo::FeatureManagement
     end
   end
 end

data/lib/arturo/feature_availability.rb

@@ -12,8 +12,7 @@ module Arturo
     def feature_enabled?(symbol_or_feature)
       feature = ::Arturo::Feature.to_feature(symbol_or_feature)
       return false if feature.blank?
-      thing = ::Arturo.feature_recipient.bind(self).call
-      feature.enabled_for?(thing)
+      feature.enabled_for?(feature_recipient)
     end
 
     def if_feature_enabled(symbol_or_feature, &block)
@@ -24,6 +23,15 @@ module Arturo
       end
     end
 
+    # By default, returns current_user.
+    # 
+    # If you would like to change this implementation, it is recommended
+    # you do so in config/initializers/arturo_initializer.rb
+    # @return [Object] the recipient of features.
+    def feature_recipient
+      current_user
+    end
+
   end
 
 end

data/lib/arturo/feature_management.rb

@@ -0,0 +1,23 @@
+module Arturo
+
+  # A mixin that is included by Arturo::FeaturesController and is declared
+  # as a helper for all views. It provides a single method,
+  # may_manage_features?, that returns whether or not the current user
+  # may manage features. By default, it is implemented as follows:
+  # 
+  #   def may_manage_features?
+  #     current_user.present? && current_user.admin?
+  #   end
+  # 
+  # If you would like to change this implementation, it is recommended
+  # you do so in config/initializers/arturo_initializer.rb
+  module FeatureManagement
+
+    # @return [true,false] whether the current user may manage features
+    def may_manage_features?
+      current_user.present? && current_user.admin?
+    end
+
+  end
+
+end

data/lib/generators/arturo/templates/initializer.rb

@@ -1,21 +1,29 @@
 require 'arturo'
 
-Arturo.permit_management do
-  # current_user.present? && current_user.admin?
-end
+# Configure who may manage features here.
+# The following is the default implementation.
+# Arturo::FeatureManagement.class_eval do
+#   def may_manage_features?
+#     current_user.present? && current_user.admin?
+#   end
+# end
 
-Arturo.feature_recipient do
-  # current_user
-end
+# Configure what receives features here.
+# The following is the default implementation.
+# Arturo::FeatureAvailability.class_eval do
+#   def feature_recipient
+#     current_user
+#   end
+# end
 
 # Whitelists and Blacklists:
 #
-# # Enable feature one for all admins:
-# Arturo::Feature.whitelist('feature one') do |user|
+# Enable feature one for all admins:
+# Arturo::Feature.whitelist(:feature_one) do |user|
 #   user.admin?
 # end
 #
-# # Disable feature two for all small accounts:
-# Arturo::Feature.blacklist('feature two') do |user|
+# Disable feature two for all small accounts:
+# Arturo::Feature.blacklist(:feature_two) do |user|
 #   user.account.small?
 # end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 1
+  - 1
   - 0
-  - 0
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors: 
 - James A. Rosen
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-24 00:00:00 -07:00
+date: 2010-10-25 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -108,11 +108,11 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
-- lib/arturo/configuration.rb
 - lib/arturo/controller_filters.rb
 - lib/arturo/engine.rb
 - lib/arturo/feature_availability.rb
 - lib/arturo/feature_factories.rb
+- lib/arturo/feature_management.rb
 - lib/arturo/special_handling.rb
 - lib/arturo.rb
 - lib/generators/arturo/assets_generator.rb

data/lib/arturo/configuration.rb

@@ -1,43 +0,0 @@
-require 'active_support/core_ext/module'
-
-module Arturo
-
-  # A block that, when bound to a Controller instance, returns
-  # true iff the current user can manage features.
-  mattr_writer :permit_management
-  @@permit_management = lambda { false }
-
-  # A block that, when bound to a Controller or Helper instance,
-  # returns an object (probably a User, Person, or Account),
-  # that may or may not have features enabled.
-  mattr_writer :feature_recipient
-  @@feature_recipient = lambda { nil }
-
-  # Get or set Arturo's permission block.
-  # @param [block] block
-  # @return [block]
-  # @see Arturo.permission_block
-  def self.permit_management(&block)
-    if block
-      @@permit_management = block
-    end
-    @@permit_management
-  end
-
-  def self.permit_management?(controller)
-    block = self.permit_management
-    block && block.call(controller)
-  end
-
-  # Get or set Arturo's block for retrieving the
-  # thing that may or may not have features enabled.
-  # @param [block] block
-  # @return [block]
-  def self.feature_recipient(&block)
-    if block
-      @@feature_recipient = block
-    end
-    @@feature_recipient
-  end
-
-end