resource_full 0.7.6

data/lib/resource_full/models/resourced_route.rb

@@ -0,0 +1,84 @@
+module ResourceFull
+  module Models
+    class RouteNotFound < Exception
+    end
+
+    class ResourcedRoute
+      attr_reader :verb, :name, :pattern, :action, :controller
+
+      class << self
+        def find(what, opts={})
+          case what
+          when :all
+            find_all_routes(opts)
+          else
+            find_named_route(what)
+          end
+        end
+
+        def find_named_route(name)
+          all_named_routes.find {|route| route.name == name} or raise ResourceFull::Models::RouteNotFound, "Could not find route #{name}"
+        end
+
+        def find_all_routes(opts={})
+          all_named_routes(opts).reject do |route|
+            opts.has_key?(:resource_id) && opts[:resource_id].to_s != route.resource.to_s
+          end.sort_by {|r| r.name.to_s}
+        end
+
+        private
+
+          # Translates an AR route into something a little more human-friendly, adding some extra
+          # relationships as it goes and cutting out the stuff we're not interested in--for example,
+          # formatted variants of regular routes.
+          def all_named_routes(opts={})
+            @all_named_routes ||= ActionController::Routing::Routes.named_routes.routes.collect do |name, route|
+              verb = route.conditions[:method].to_s.upcase
+              segs = route.segments.join
+              new(
+                :name     => name,
+                :verb     => verb,
+                :pattern  => segs,
+                :action   => route.requirements[:action],
+                :controller => route.requirements[:controller]
+              )
+            end.reject do |route|
+              route.formatted?
+            end
+          end
+
+      end
+
+      def initialize(opts={})
+        @verb     = opts[:verb]
+        @name     = opts[:name]
+        @pattern  = opts[:pattern]
+        @action   = opts[:action]
+        @controller = ResourceFull::Base.controller_for(opts[:controller])
+      end
+
+      def to_xml(opts={})
+        {
+          :resource => resource,
+          :verb => verb,
+          :name => name,
+          :pattern => pattern,
+          :action => action
+        }.to_xml(opts.merge(:root => "route"))
+      end
+
+      def formatted?
+        name.to_s =~ /^formatted/
+      end
+
+      def resource
+        controller.controller_name
+      end
+
+      def resourced?
+        controller.ancestors.include?(ResourceFull::Base)
+      end
+
+    end
+  end
+end

data/lib/resource_full/query.rb

@@ -0,0 +1,337 @@
+module ResourceFull
+  module Query    
+    class << self      
+      def included(base)
+        super(base)
+        base.send :extend, ClassMethods
+        base.queryable_with :limit,  :scope => lambda {|limit|  { :limit  => limit  }}
+        base.queryable_with :offset, :scope => lambda {|offset| { :offset => offset }}
+        base.queryable_with_order
+      end
+    end
+    
+    # A Parameter represents the information necessary to describe a query relationship.  It's inherently
+    # tied to ActiveRecord at the moment, unfortunately.  Objects of this class should not be instantiated
+    # directly; instead, use the +queryable_with+ method.
+    class Parameter
+      attr_reader :name, :resource
+    
+      def initialize(name, resource, opts={})
+        @name      = name
+        @resource  = resource
+        @fuzzy     = opts[:fuzzy] || false
+        @allow_nil = opts[:allow_nil] || false
+        @default_value = opts[:default]
+      end
+      
+      def fuzzy?; @fuzzy; end
+      def allow_nil?; @allow_nil; end
+      
+      def to_xml(opts={})
+        {
+          :name => name.to_s,
+          :resource => resource.model_name.pluralize,
+          :fuzzy => fuzzy?,
+        }.to_xml(opts.merge(:root => "parameter"))
+      end
+      
+      def applicable_to?(request_params)
+        if allow_nil?
+          request_params.has_key?(self.name.to_s) || request_params.has_key?(self.name.to_s.pluralize)
+        else
+          not param_values_for(request_params).blank?
+        end
+      end
+      
+      def find(finder, request_params)
+        raise NotImplementedError, "Subclasses implement this behavior."
+      end
+      
+      def subclass(new_resource)
+        raise NotImplementedError, "Subclasses implement this behavior."
+      end
+      
+      protected
+      
+        def param_values_for(params)
+          values = (params[self.name.to_s] || params[self.name.to_s.pluralize] || @default_value || '')
+          values = values.to_s.split(',') unless values.is_a?(Array)
+          values.map! {|value| "%#{value}%" } if fuzzy?
+          values
+        end
+        
+        def table_for(opts={})
+          if opts.has_key?(:table)
+            opts[:table]
+          elsif opts.has_key?(:from)
+            infer_model_from(resource.model_class, opts[:from]).table_name
+          else
+            resource.model_class.table_name
+          end
+        end
+        
+        def infer_model_from(model, join)
+          if join.is_a? Symbol
+            model.reflect_on_association(join).klass
+          elsif join.is_a? Hash
+            new_model = model.reflect_on_association(join.keys.first).klass
+            infer_model_from new_model, join.values.first
+          end
+        end
+      
+    end
+        
+    class CustomParameter < Parameter
+      attr_reader :table, :columns, :include
+
+      def initialize(name, resource, opts={})
+        super(name, resource, opts)
+        
+        @table     = table_for(opts)
+        @columns   = columns_for(name, resource, opts)
+        @negated   = opts[:negated] || false
+        @include   = opts[:from] || []
+      end
+      
+      def allow_nil?; @allow_nil; end
+      def negated?; @negated; end
+      
+      def find(finder, request_params)
+        return finder unless applicable_to?(request_params)
+        finder.scoped :conditions => conditions_for(request_params), :include => @include
+      end
+      
+      def subclass(new_resource)
+        new_table = if @table == @resource.model_class.table_name
+          new_resource.model_class.table_name
+        else @table end
+          
+        self.class.new(@name, new_resource,
+          :fuzzy     => @fuzzy,
+          :allow_nil => @allow_nil,
+          :table     => new_table,
+          :columns   => @columns,
+          :from      => @include,
+          :negated   => @negated
+        )
+      end
+      
+      private
+      
+        def conditions_for(params)
+          values = param_values_for(params)
+          unless values.empty?
+            final_query_string = if negated?
+              values.collect { |value| negated_query_string(value) }.join(" AND ")
+            else
+              values.collect { |value| query_string(value) }.join(" OR ")
+            end
+
+            final_values       = values.sum([]) { |value| Array.new(columns.size, value) }
+
+            [ final_query_string ] + final_values
+          else
+            if (allow_nil? && params.has_key?(self.name) && params[self.name].blank?)
+              [query_string(params[self.name])]
+            else
+              []
+            end
+          end
+        end
+          
+        def columns_for(name, resource, opts={})
+          if opts.has_key?(:columns)
+            opts[:columns]
+          elsif opts.has_key?(:column)
+            [ opts[:column] ]
+          elsif opts[:resource_identifier] && opts.has_key?(:from)
+            [ ResourceFull::Base.controller_for(infer_model_from(resource.model_class, opts[:from]).name.demodulize.pluralize).resource_identifier ]
+          else
+            [ name ]
+          end
+        end
+      
+        def query_string(value)
+          columns.collect do |column|
+            # Convert to a column name if column is a proc. TODO There must be a cleaner way to do this.
+            column = column.call(value) if column.is_a?(Proc)
+            if fuzzy?
+              "(#{table}.#{column} LIKE ?)"
+            elsif !value.blank?
+              "(#{table}.#{column} = ?)"
+            elsif allow_nil?
+              "(COALESCE(#{table}.#{column},'')='')"
+            end
+          end.join(" OR ")
+        end
+        
+        def negated_query_string(value)
+          columns.collect do |column|
+            # Convert to a column name if column is a proc. TODO There must be a cleaner way to do this.
+            column = column.call(value) if column.is_a?(Proc)
+            if fuzzy?
+              "(#{table}.#{column} NOT LIKE ? OR #{table}.#{column} IS NULL)"
+            elsif !value.blank?
+              "(#{table}.#{column} != ? OR #{table}.#{column} IS NULL)"
+            end
+          end.join(" AND ")
+        end
+    end
+    
+    class ScopedParameter < Parameter
+      attr_reader :scope
+      
+      def initialize(name, resource, opts={})
+        super(name, resource, opts)
+        @scope = opts[:scope]
+      end
+      
+      def method_scoped?; @scope.is_a?(Symbol); end
+      def proc_scoped?; @scope.is_a?(Proc); end
+      def hash_scoped?; @scope.is_a?(Hash); end
+      
+      def find(finder, request_params)        
+        return finder unless applicable_to?(request_params)
+        
+        if proc_scoped?
+          finder.scoped scope.call(*param_values_for(request_params))
+        elsif hash_scoped?
+          finder.scoped scope
+        else
+          finder.send(scope, *param_values_for(request_params))
+        end
+      end
+      
+      def subclass(new_resource)
+        self.class.new @name, new_resource, :scope => @scope
+      end
+      
+    end
+    
+    class OrderParameter < Parameter
+      
+      def applicable_to?(request_params)
+        request_params.has_key?(:order_by)
+      end
+      
+      def natural_sort_for(opts)
+        if opts.has_key?(:natural_sort)
+          opts[:natural_sort]
+        else
+          false
+        end
+      end
+  
+      def find(finder, request_params)
+        return finder unless applicable_to?(request_params)
+    
+        order_by = request_params[:order_by]
+        order_direction = request_params[:order_direction] || "asc"
+        sort_params = resource.orderables[order_by.to_sym] || {}
+        table = table_for(sort_params)
+        column = sort_params[:column] || order_by
+    
+        order_params = returning({}) do |hash|
+          hash[:include] = sort_params[:from]
+        end
+    
+        if natural_sort_for(sort_params)
+          # to use this natural sort you must follow these instructions: http://www.ciarpame.com/2008/06/28/true-mysql-natural-order-by-trick/
+          finder.scoped order_params.merge( :order => "natsort_canon(#{table}.#{column}, 'natural') #{order_direction}" )
+        else
+          finder.scoped order_params.merge( :order => "#{table}.#{column} #{order_direction}" )
+        end
+      end
+      
+      def subclass(new_resource)
+        self.class.new(@name, new_resource)
+      end
+      
+    end
+    
+    module ClassMethods
+      # Indicates that the resource should be queryable with the given parameters, which will be pulled from
+      # the params hash on an index or count call.  Accepts the following options:
+      # 
+      #   * :fuzzy => true : Use a LIKE query instead of =.
+      #   * :columns / :column => ... : Override the default column, or provide a list of columns to query for this value.
+      #   * :from => :join_name : Indicate that this value should be queried by joining on another model.  Should use
+      #     a valid relationship from this controller's exposed model (e.g., :account if belongs_to :account is specified.)
+      #   * :resource_identifier => true : Try to look up the resource controller for this value and honor its
+      #     specified resource identifier.  Useful for nesting relationships.
+      #   * :allow_nils => true : Indicates that a nil value for a parameter should be taken to literally indicate
+      #     that null values should be returned.  This may be changed in the future to expect the literal string 'null'
+      #     or some other reasonable standin.
+      #
+      # Examples:
+      #
+      #   queryable_with :user_id
+      #   queryable_with :description, :fuzzy => true
+      #   queryable_with :name, :columns => [:first_name, :last_name]
+      #   queryable_with :street_address, :from => :address, :column => :street
+      #
+      # TODO No full-text search support.
+      def queryable_with(*args)
+        opts = args.extract_options!
+        opts.assert_valid_keys :default, :fuzzy, :column, :columns, :from, :table, :resource_identifier, :allow_nil, :negated, :scope
+        args.each do |param|
+          self.queryable_params << if opts.has_key?(:scope)
+            ResourceFull::Query::ScopedParameter.new(param, self, opts)
+          else
+            ResourceFull::Query::CustomParameter.new(param, self, opts)
+          end
+        end
+      end
+      
+      # :nodoc:
+      def clear_queryable_params!
+        @queryable_params = []
+      end
+      
+      # All queryable parameters.  Objects are of type +ResourceFull::Query::Parameter+ or one of its subclasses.
+      def queryable_params
+        unless defined?(@queryable_params) && !@queryable_params.nil?
+          @queryable_params = []
+          if superclass.respond_to?(:queryable_params)
+            @queryable_params += superclass.queryable_params.collect {|param| param.subclass(self)}
+          end
+        end
+        @queryable_params
+      end
+      
+      # Returns true if the controller is queryable with all of the named parameters.
+      def queryable_with?(*params)
+        (queryable_params.collect(&:name) & params.collect(&:to_sym)).size == params.size
+      end
+      
+      # :nodoc:
+      def queryable_params=(params)
+        @queryable_params = params
+      end
+      
+      def nests_within(*resources)
+        resources.each do |resource|
+          expected_nest_id = "#{resource.to_s.singularize}_id"
+          queryable_with expected_nest_id, :from => resource.to_sym, :resource_identifier => true
+        end
+      end
+      
+      def orderable_by(*params)
+        opts = params.extract_options!
+        params.each do |param|
+          orderables[param] = opts
+        end
+      end
+      
+      def queryable_with_order
+        unless queryable_with?(:order_by)
+          queryable_params << ResourceFull::Query::OrderParameter.new(:order_by, self)
+        end
+      end
+            
+      def orderables
+        read_inheritable_attribute(:orderables) || write_inheritable_hash(:orderables, {})
+      end
+    end
+  end
+end

data/lib/resource_full/render/html.rb

@@ -0,0 +1,74 @@
+module ResourceFull
+  module Render
+    module HTML
+      protected
+
+      def show_html
+        self.model_object = send("find_#{model_name}")
+      rescue ActiveRecord::RecordNotFound => e
+        flash[:error] = e.message
+      rescue => e
+        flash[:error] = e.message
+        redirect_to :back
+      end
+
+      def index_html
+        self.model_objects = send("find_all_#{model_name.pluralize}")
+      end
+
+      def count_html
+        send("count_all_#{model_name.pluralize}")
+      end
+
+      def new_html
+        self.model_object = send("new_#{model_name}")
+      end
+
+      def create_html
+        self.model_object = transactional_create_model_object
+        if model_object.errors.empty?
+          flash[:info] = "Successfully created #{model_name.humanize} with ID of #{model_object.id}."
+          redirect_to :action => :index, :format => :html
+        else
+          render :action => "new"
+        end
+      rescue => e
+        flash[:error] = e.message
+        redirect_to :back
+      end
+
+      def edit_html
+        self.model_object = send("edit_#{model_name}")
+      end
+
+      def update_html
+        self.model_object = transactional_update_model_object
+        if model_object.errors.empty?
+          flash[:info] = "Successfully updated #{model_name.humanize} with ID of #{model_object.id}."
+          redirect_to :action => :index, :format => :html
+        else
+          render :action => "edit"
+        end
+      rescue => e
+        flash[:error] = e.message
+        redirect_to :back
+      end
+
+      def destroy_html
+        self.model_object = transactional_destroy_model_object
+        if model_object.errors.empty?
+          flash[:info] = "Successfully destroyed #{model_name.humanize} with ID of #{params[:id]}."
+          redirect_to :action => :index, :format => :html
+        else
+          flash[:error] = model_object.errors
+        end
+      rescue ActiveRecord::RecordNotFound => e
+        flash[:error] = e.message
+        redirect_to :back
+      rescue => e
+        flash[:error] = e.message
+        redirect_to :back
+      end
+    end
+  end
+end

data/lib/resource_full/render/json.rb

@@ -0,0 +1,107 @@
+module ResourceFull
+  module Render
+    module JSON
+      protected
+
+      def json_class_name(obj)
+        obj.class.name.demodulize.underscore
+      end
+
+      def show_json_options
+        {}
+      end
+      def show_json
+        self.model_object = send("find_#{model_name}")
+        render :json => model_object.to_json(show_json_options)
+      rescue ActiveRecord::RecordNotFound => e
+        render :json => e.to_json, :status => :not_found
+      rescue => e
+        handle_generic_error_in_json(e)
+      end
+
+      def index_json_options
+        {}
+      end
+      def index_json
+        self.model_objects = send("find_all_#{model_name.pluralize}")
+        render :json => model_objects.to_json(index_json_options)
+      end
+
+      def count_json
+        count = send("count_all_#{model_name.pluralize}")
+        render :json => {"count" => count}.to_json
+      end
+
+      def new_json_options
+        {}
+      end
+      def new_json
+        render :json => send("new_#{model_name}").to_json(new_json_options)
+      end
+
+      def create_json_options
+        {}
+      end
+      def create_json
+        self.model_object = transactional_create_model_object
+        if model_object.errors.empty?
+          render :json => model_object.to_json(create_json_options), :status => :created, :location => send("#{model_name}_url", model_object.id)
+        else
+          json_data = model_object.attributes
+          json_data[:errors] = {:list => model_object.errors,
+                               :full_messages => model_object.errors.full_messages}
+          render :json => {json_class_name(model_object) => json_data}.to_json, :status => status_for(model_object.errors)
+        end
+      rescue => e
+        handle_generic_error_in_json(e)
+      end
+
+      def edit_json_options
+        {}
+      end
+      def edit_json
+        render :json => send("edit_#{model_name}").to_json(edit_json_options)
+      end
+
+      def update_json_options
+        {}
+      end
+      def update_json
+        self.model_object = transactional_update_model_object
+        if model_object.errors.empty?
+          render :json => model_object.to_json(update_json_options)
+        else
+          json_data = model_object.attributes
+          json_data[:errors] = {:list => model_object.errors,
+                               :full_messages => model_object.errors.full_messages}
+          render :json => {json_class_name(model_object) => json_data}.to_json, :status => status_for(model_object.errors)
+        end
+      rescue ActiveRecord::RecordNotFound => e
+        render :json => e.to_json, :status => :not_found
+      rescue => e
+        handle_generic_error_in_json(e)
+      end
+
+      def destroy_json
+        self.model_object = transactional_destroy_model_object
+        if model_object.errors.empty?
+          head :ok
+        else
+          json_data = model_object.attributes
+          json_data[:errors] = {:list => model_object.errors,
+                               :full_messages => model_object.errors.full_messages}
+          render :json => {json_class_name(model_object) => json_data}.to_json, :status => :unprocessable_entity
+        end
+      rescue ActiveRecord::RecordNotFound => e
+        render :json => e.to_json, :status => :not_found
+      rescue => e
+        handle_generic_error_in_json(e)
+      end
+
+      private
+      def handle_generic_error_in_json(exception)
+        render :json => exception, :status => :unprocessable_entity
+      end
+    end
+  end
+end

data/lib/resource_full/render/xml.rb

@@ -0,0 +1,106 @@
+module ResourceFull
+  module Render
+    module XML
+      protected
+
+      def show_xml_options
+        {}
+      end
+      def show_xml
+        self.model_object = send("find_#{model_name}")
+        render :xml => model_object.to_xml({:root => model_name}.merge(show_xml_options))
+      rescue ActiveRecord::RecordNotFound => e
+        render :xml => e.to_xml, :status => :not_found
+      rescue => e
+        handle_generic_error_in_xml(e)
+      end
+
+      def index_xml_options
+        {}
+      end
+      def index_xml
+        self.model_objects = send("find_all_#{model_name.pluralize}")
+        root_tag = model_objects.all? { |e| e.is_a?(model_objects.first.class) && model_objects.first.class.to_s != "Hash" } ? model_objects.first.class.name.demodulize.underscore.pluralize : model_name.pluralize
+        render :xml => model_objects.to_xml({:root => root_tag}.merge(index_xml_options))
+      end
+
+      # Renders the number of objects in the database, in the following form:
+      #
+      #   <count type="integer">34</count>
+      #
+      # This accepts the same queryable parameters as the index method.
+      #
+      # N.B. This may be highly specific to my previous experience and may go away
+      # in previous releases.
+      def count_xml
+        xml = Builder::XmlMarkup.new :indent => 2
+        xml.instruct!
+        render :xml => xml.count(send("count_all_#{model_name.pluralize}"))
+      ensure
+        xml = nil
+      end
+
+      def new_xml_options
+        {}
+      end
+      def new_xml
+        render :xml => send("new_#{model_name}").to_xml({:root => model_name}.merge(new_xml_options))
+      end
+
+      def create_xml_options
+        {}
+      end
+      def create_xml
+        self.model_object = transactional_create_model_object
+        if model_object.errors.empty?
+          render :xml => model_object.to_xml({:root => model_name}.merge(create_xml_options)), :status => :created, :location => send("#{model_name}_url", model_object.id)
+        else
+          render :xml => model_object.errors.to_xml, :status => status_for(model_object.errors)
+        end
+      rescue => e
+        handle_generic_error_in_xml(e)
+      end
+
+      def edit_xml_options
+        {}
+      end
+      def edit_xml
+        render :xml => send("edit_#{model_name}").to_xml({:root => model_name}.merge(edit_xml_options))
+      end
+
+      def update_xml_options
+        {}
+      end
+      def update_xml
+        self.model_object = transactional_update_model_object
+        if model_object.errors.empty?
+          render :xml => model_object.to_xml({:root => model_name}.merge(update_xml_options))
+        else
+          render :xml => model_object.errors.to_xml, :status => status_for(model_object.errors)
+        end
+      rescue ActiveRecord::RecordNotFound => e
+        render :xml => e.to_xml, :status => :not_found
+      rescue => e
+        handle_generic_error_in_xml(e)
+      end
+
+      def destroy_xml
+        self.model_object = transactional_destroy_model_object
+        if model_object.errors.empty?
+          head :ok
+        else
+          render :xml => model_object.errors, :status => :unprocessable_entity
+        end
+      rescue ActiveRecord::RecordNotFound => e
+        render :xml => e.to_xml, :status => :not_found
+      rescue => e
+        handle_generic_error_in_xml(e)
+      end
+
+      private
+      def handle_generic_error_in_xml(exception)
+        render :xml => exception, :status => :unprocessable_entity
+      end
+    end
+  end
+end