faceted 0.5.0 → 0.6.0

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2012 Corey Ehmke
+Copyright (c) 2012 Trunk Club
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,6 +1,105 @@
 faceted
 =======
 
-A set of tools, patterns, and modules for use in API implementations.
+Faceted provides set of tools, patterns, and modules for use in API implementations.
+
+It was written and is maintained by Corey Ehmke (@bantik) and Max Thom Stahl (@villainous) at Trunk Club.
+
+Presenters
+----------
+
+Let's say that you have an ActiveRecord model called Musician, and you want to expose it through your API using a *Presenter* pattern. Faceted makes it easy. Create a new class namespaced inside of your API like so:
+
+
+
+    module MyApi
+      class Musician
+        include Faceted::Presenter
+        presents :musician
+        field :name
+        field :genre
+      end
+    end
+
+That's actually all you have to do. The `presents` method maps your Musician presenter to a root-level class called `Musician`, and the `field` methods map to attributes *or* methods on the associated AR Musician instance.
+
+What's that, you say? How is the appropriate AR Musican record associated? Simple. Invoke an instance of the `MyApi::Musician` passing in an `:id` parameter, and it just works:
+
+    m = Musician.create(:name => 'Johnny Cash', :genre => 'Western')
+    m.id
+    => 13
+
+    presenter = MyApi::Musician.new(:id => 13)
+    presenter.name
+    => "Johnny Cash"
+
+You can also invoke methods on AR instances using the same syntax. Let's say that your base `Musician` class has a `random_song_title` method that returns one of the musician's popular songs. Simply wire up the method in your presenter:
+
+    field :random_song_title
+
+That's it.
+
+    presenter.random_song_title
+    => "Ring of Fire"
+
+Relationships work almost the same way. If `Musician` actually `has_one` birthplace, and includes a `birthplace_id` attribute, wire it up like this:
+
+    field :birthplace_id
+
+Create a presenter for the associated Birthplace model:
+
+    module MyApi
+      class Birthplace
+        include Faceted::Presenter
+        presents :birthplace
+        field :city
+        field :state
+      end
+    end
+
+Now your `Musician` presenter responds the way it should:
+
+    presenter.birthplace.city
+    => "Kingsland"
+
+It's smart enough to identify that `birthplace_id` indicates a relationship and builds the association for you. If you don't want it to do this, simply pass the `skip_association` flag:
+
+    field :record_label_id, :skip_association => true
+
+You can also explicitly declare the class of the association:
+
+  field :genre_id, :class_name => 'MusicalGenre'
+
+Collectors
+----------
+Collectors are simply models that collect multiple instances of another model. An example:
+
+    module MyApi
+      class Playlist
+        include Faceted::Collector
+        collects :musicians, :find_by => :genre_id
+      end
+    end
+
+    l = MyApi::Playlist.new(:genre_id => 3)
+    l.musicians.count
+    => 14
+
+    l.musicians.first.name
+    => "American Music Club"
+
+Contributing to faceted
+=======================
+
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+Copyright
+=========
+Copyright (c) 2012 Trunk Club. See LICENSE.txt for further details.
 
-This software is alpha and not production-ready.

data/VERSION

@@ -1 +1 @@
-0.5.0
+0.6.0

data/faceted.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = "faceted"
-  s.version = "0.5.0"
+  s.version = "0.6.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Corey Ehmke", "Max Thom Stahl"]
@@ -29,6 +29,7 @@ Gem::Specification.new do |s|
     "faceted.gemspec",
     "lib/faceted.rb",
     "lib/faceted/collector.rb",
+    "lib/faceted/controller.rb",
     "lib/faceted/presenter.rb",
     "spec/collector_spec.rb",
     "spec/presenter_spec.rb",

data/lib/faceted/collector.rb

@@ -19,7 +19,7 @@ module Faceted
       def collects(name, args={})
         @collects = eval "#{scope}#{args[:class_name] || name.to_s.classify}"
         define_method :"#{name.downcase}" do
-          self.objects
+          objects
         end
         define_method :finder do
           {"#{args[:find_by]}" => self.send(args[:find_by])}
@@ -45,15 +45,17 @@ module Faceted
       self.success = true
     end
 
+    def to_hash
+      objects.map{|o| o.to_hash}
+    end
+
+    private
+
     def objects
       return unless self.class.collected_class
       @objects ||= self.class.collected_class.where(self.finder)
     end
 
-    def to_hash
-      self.objects.map{|o| o.to_hash}
-    end
-
   end
 
 end

data/lib/faceted/controller.rb

@@ -0,0 +1,48 @@
+module Faceted
+
+  module Controller
+
+    # For rendering a response with a single object, e.g.
+    # render_response(@addresses)
+    def render_response(obj)
+      render :json => {
+        success:  obj.success,
+        response: obj.to_hash,
+        errors:   obj.errors
+      }.to_json
+    end
+
+    # For rendering a response with a multiple objects, e.g.
+    # render_response_with_collection(:addresses, @addresses)
+    def render_response_with_collection(key, array)
+      render :json => {
+        success: true,
+        response: {"#{key}".to_sym => array},
+        errors:   nil
+      }.to_json
+    end
+
+    # In your base API controller:
+    # rescue_from ActiveRecord::RecordNotFound, :with => :record_not_found
+    def render_400(exception)
+      render :json => {
+        success: false,
+        response: nil,
+        errors: "Record not found: #{exception.message}"
+      }, :status => 404
+    end
+
+    # In your base API controller:
+    # rescue_from Exception, :with => :render_500
+    def render_500(exception)
+      Rails.logger.info("!!! #{self.class.name} exception caught: #{exception} #{exception.backtrace.join("\n")}")
+      render :json => {
+        success: false,
+        response: nil,
+        errors: "#{exception.message}"
+      }, :status => 500
+    end
+
+  end
+
+end

data/lib/faceted/presenter.rb

@@ -5,7 +5,7 @@ module Faceted
     require 'json'
     require 'active_support/core_ext/hash'
 
-    # Class methods ==========================================================
+    # Class methods ===========================================================
 
     def self.included(base)
       base.extend ActiveModel::Naming
@@ -27,6 +27,12 @@ module Faceted
         end
       end
 
+      def create(params={})
+        obj = self.new(params)
+        obj.save
+        obj
+      end
+
       def field(name, args={})
 
         fields << name
@@ -43,12 +49,6 @@ module Faceted
 
       end
 
-      def create(params={})
-        object = self.new(params)
-        object.save
-        object
-      end
-
       def fields
         @fields ||= [:id]
       end
@@ -67,10 +67,10 @@ module Faceted
       end
 
       def presents(name, args={})
-        @presents = args[:class_name] || name.to_s.classify
-        klass = eval "::#{@presents}"
-        define_method :"#{@presents.downcase}" do
-          self.object
+        class_name = args[:class_name] || name.to_s.classify
+        @presents = eval(class_name)
+        define_method :"#{class_name.downcase}" do
+          object
         end
       end
 
@@ -79,7 +79,7 @@ module Faceted
       end
 
       def where(args)
-        materialize(eval(presented_class).where(args))
+        materialize(presented_class.where(args))
       end
 
     end
@@ -88,20 +88,31 @@ module Faceted
 
     def initialize(args={})
       self.id = args[:id]
-      self.initialize_with_object
+      initialize_with_object
       ! args.empty? && args.symbolize_keys.delete_if{|k,v| v.nil?}.each{|k,v| self.send("#{k}=", v) if self.respond_to?("#{k}=") && ! v.blank? }
       self.errors = []
       self.success = true
     end
 
+    def save
+      schema_fields.each{ |k| object.send("#{k}=", self.send(k)) if object.respond_to?("#{k}=") }
+      object.save!
+    end
+
+    def to_hash
+      schema_fields.inject({}) {|h,k| h[k] = self.send(k); h}
+    end
+
+    private
+
     def initialize_with_object
       return unless object
-      self.class.fields.each{ |k| self.send("#{k}=", self.object.send(k)) if self.respond_to?("#{k}=") }
+      schema_fields.each{ |k| self.send("#{k}=", object.send(k)) if self.respond_to?("#{k}=") }
     end
 
     def object
       return unless self.class.presented_class
-      @object ||= self.id ? eval(self.class.presented_class).find(self.id) : eval(self.class.presented_class).new
+      @object ||= self.id ? self.class.presented_class.find(self.id) : self.class.presented_class.new
     end
 
     def object=(obj)
@@ -109,13 +120,8 @@ module Faceted
       self.id = obj.id
     end
 
-    def save
-      self.class.fields.each{ |k| self.object.send("#{k}=", self.send(k)) if self.object.respond_to?("#{k}=") }
-      self.object.save!
-    end
-
-    def to_hash
-      self.class.fields.inject({}) {|h,k| h[k] = self.send(k); h}
+    def schema_fields
+      self.class.fields
     end
 
   end

data/spec/collector_spec.rb

@@ -31,7 +31,7 @@ module MyApi
 
   class Band
     include Faceted::Collector
-    collects :musicians, :class_name => 'Musician', :find_by => :birthplace_id
+    collects :musicians, :find_by => :birthplace_id
   end
 
   describe Band do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: faceted
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
   prerelease: 
 platform: ruby
 authors:
@@ -160,6 +160,7 @@ files:
 - faceted.gemspec
 - lib/faceted.rb
 - lib/faceted/collector.rb
+- lib/faceted/controller.rb
 - lib/faceted/presenter.rb
 - spec/collector_spec.rb
 - spec/presenter_spec.rb
@@ -179,7 +180,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3092283735648102372
+      hash: 4456343410133406999
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: