brainstem 0.2.6.1 → 1.0.0.pre.1

data/lib/brainstem/dsl/associations_block.rb

@@ -0,0 +1,12 @@
+module Brainstem
+  module Concerns
+    module PresenterDSL
+      class AssociationsBlock < BaseBlock
+        def association(name, target_class, *args)
+          description, options = parse_args(args)
+          configuration[:associations][name] = DSL::Association.new(name, target_class, description, block_options.merge(options))
+        end
+      end
+    end
+  end
+end

data/lib/brainstem/dsl/base_block.rb

@@ -0,0 +1,31 @@
+module Brainstem
+  module Concerns
+    module PresenterDSL
+      class BaseBlock
+        attr_accessor :configuration, :block_options
+
+        def initialize(configuration, block_options = {}, &block)
+          @configuration = configuration
+          @block_options = block_options
+          block.arity < 1 ? self.instance_eval(&block) : block.call(self) if block_given?
+        end
+
+        def with_options(new_options = {}, &block)
+          descend self.class, configuration, new_options, &block
+        end
+
+        protected
+
+        def descend(klass, new_config = configuration, new_options = {}, &block)
+          klass.new(new_config, block_options.merge(new_options), &block)
+        end
+
+        def parse_args(args)
+          options = args.last.is_a?(Hash) ? args.pop : {}
+          description = args.shift
+          [description, options]
+        end
+      end
+    end
+  end
+end

data/lib/brainstem/dsl/conditional.rb

@@ -0,0 +1,25 @@
+module Brainstem
+  module DSL
+    class Conditional
+      attr_reader :name, :type, :action, :description
+
+      def initialize(name, type, action, description)
+        @name = name
+        @type = type
+        @action = action
+        @description = description
+      end
+
+      def matches?(model, helper_instance = Object.new, conditional_cache = { model: {}, request: {} })
+        case type
+          when :model
+            conditional_cache[:model].fetch(name) { conditional_cache[:model][name] = helper_instance.instance_exec(model, &action) }
+          when :request
+            conditional_cache[:request].fetch(name) { conditional_cache[:request][name] = helper_instance.instance_exec(&action) }
+          else
+            raise "Unknown Brainstem Conditional type #{type}"
+        end
+      end
+    end
+  end
+end

data/lib/brainstem/dsl/conditionals_block.rb

@@ -0,0 +1,15 @@
+module Brainstem
+  module Concerns
+    module PresenterDSL
+      class ConditionalsBlock < BaseBlock
+        def request(name, action, description = nil)
+          configuration[:conditionals][name] = DSL::Conditional.new(name, :request, action, description)
+        end
+
+        def model(name, action, description = nil)
+          configuration[:conditionals][name] = DSL::Conditional.new(name, :model, action, description)
+        end
+      end
+    end
+  end
+end

data/lib/brainstem/dsl/configuration.rb

@@ -0,0 +1,112 @@
+require 'active_support/hash_with_indifferent_access'
+
+# A hash-like object that accepts a parent configuration object that defers to
+# the parent in the absence of one of its own keys (thus simulating inheritance).
+module Brainstem
+  module DSL
+    class Configuration
+
+      # Returns a new configuration object.
+      #
+      # @params [Object] parent_configuration The parent configuration object
+      #   which the new configuration object should use as a base.
+      def initialize(parent_configuration = nil)
+        @parent_configuration = parent_configuration || ActiveSupport::HashWithIndifferentAccess.new
+        @storage = ActiveSupport::HashWithIndifferentAccess.new
+      end
+
+      def [](key)
+        get!(key)
+      end
+
+      def []=(key, value)
+        existing_value = get!(key)
+        if existing_value.is_a?(Configuration)
+          raise 'You cannot override a nested value'
+        elsif existing_value.is_a?(InheritableAppendSet)
+          raise 'You cannot override an inheritable array once set'
+        else
+          @storage[key] = value
+        end
+      end
+
+      def nest!(key)
+        get!(key)
+        @storage[key] ||= Configuration.new
+      end
+
+      def array!(key)
+        get!(key)
+        @storage[key] ||= InheritableAppendSet.new
+      end
+
+      def keys
+        @parent_configuration.keys | @storage.keys
+      end
+
+      def has_key?(key)
+        @storage.has_key?(key) || @parent_configuration.has_key?(key)
+      end
+
+      def length
+        keys.length
+      end
+
+      def each
+        keys.each do |key|
+          yield key, get!(key)
+        end
+      end
+
+      delegate :empty?, to: :keys
+
+      private
+
+      # @api private
+      #
+      # Retrieves the value stored at key.
+      #
+      # - If +key+ is already defined, it returns that;
+      # - If +key+ in the parent is a +Configuration+, returns a new
+      #   +Configuration+ with the parent set;
+      # - If +key+ in the parent is an +InheritableAppendSet+, returns a new
+      #   +InheritableAppendSet+ with the parent set;
+      # - Elsewise returns the parent configuration's value for the key.
+      def get!(key)
+        @storage[key] || begin
+          if @parent_configuration[key].is_a?(Configuration)
+            @storage[key] = Configuration.new(@parent_configuration[key])
+          elsif @parent_configuration[key].is_a?(InheritableAppendSet)
+            @storage[key] = InheritableAppendSet.new(@parent_configuration[key])
+          else
+            @parent_configuration[key]
+          end
+        end
+      end
+
+      # An Array-like object that provides `push`, `concat`, `each`, `empty?`, and `to_a` methods that act the combination
+      # of its own entries and those of a parent InheritableAppendSet, if present.
+      class InheritableAppendSet
+        def initialize(parent_array = nil)
+          @parent_array = parent_array || []
+          @storage = []
+        end
+
+        def push(item)
+          @storage.push item
+        end
+        alias_method :<<, :push
+
+        def concat(items)
+          @storage.concat items
+        end
+
+        def to_a
+          @parent_array.to_a + @storage
+        end
+
+        delegate :each, :empty?, to: :to_a
+      end
+    end
+  end
+end

data/lib/brainstem/dsl/field.rb

@@ -0,0 +1,68 @@
+require 'brainstem/concerns/lookup'
+
+module Brainstem
+  module DSL
+    class Field
+      include Brainstem::Concerns::Lookup
+
+      attr_reader :name, :type, :description, :conditionals, :options
+
+      def initialize(name, type, description, options)
+        @name = name.to_s
+        @type = type
+        @description = description
+        @conditionals = [options[:if]].flatten.compact
+        @options = options
+      end
+
+      def conditional?
+        conditionals.length > 0
+      end
+
+      def method_name
+        if options[:dynamic] || options[:lookup]
+          nil
+        else
+          (options[:via].presence || name).to_s
+        end
+      end
+
+      def optioned?(requested_optional_fields)
+        !optional? || requested_optional_fields.include?(@name)
+      end
+
+      def optional?
+        options[:optional]
+      end
+
+      def run_on(model, context, helper_instance = Object.new)
+        if options[:lookup]
+          run_on_with_lookup(model, context, helper_instance)
+        elsif options[:dynamic]
+          proc = options[:dynamic]
+          if proc.arity == 1
+            helper_instance.instance_exec(model, &proc)
+          else
+            helper_instance.instance_exec(&proc)
+          end
+        else
+          model.send(method_name)
+        end
+      end
+
+      def conditionals_match?(model, presenter_conditionals, helper_instance = Object.new, conditional_cache = { model: {}, request: {} })
+        return true unless conditional?
+
+        conditionals.all? { |conditional|
+          presenter_conditionals[conditional].matches?(model, helper_instance, conditional_cache)
+        }
+      end
+
+      private
+
+      def key_for_lookup
+        :fields
+      end
+    end
+  end
+end

data/lib/brainstem/dsl/fields_block.rb

@@ -0,0 +1,25 @@
+module Brainstem
+  module Concerns
+    module PresenterDSL
+      class FieldsBlock < BaseBlock
+        def field(name, type, *args)
+          description, options = parse_args(args)
+          configuration[name] = DSL::Field.new(name, type, description, smart_merge(block_options, options))
+        end
+
+        def fields(name, &block)
+          descend FieldsBlock, configuration.nest!(name), &block
+        end
+
+        private
+
+        def smart_merge(block_options, options)
+          if_clause = ([block_options[:if]] + [options[:if]]).flatten(2).compact.uniq
+          block_options.merge(options).tap do |opts|
+            opts.merge!(if: if_clause) if if_clause.present?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/brainstem/preloader.rb

@@ -0,0 +1,98 @@
+module Brainstem
+  # Takes a list of arbitrarily nested objects, compacts them, de-duplicates
+  # them, and passes them to ActiveRecord to preload.
+  #
+  # The following is considered a valid data structure:
+  #
+  #     [:workspaces, {"workspaces" => [:projects], "users" }
+  #
+  # Which will produce the following for ActiveRecord:
+  #
+  #     {"workspaces" => [:projects], "users" => []}
+  #
+  class Preloader
+
+    ################################################################################
+    # Class API
+    ################################################################################
+    class << self
+      def preload(*args)
+        new(*args).call
+      end
+    end
+
+    ################################################################################
+    # Instance API
+    ################################################################################
+    attr_accessor :models,
+                  :preloads,
+                  :reflections,
+                  :valid_preloads
+
+    private :valid_preloads=
+
+    attr_writer   :preload_method
+
+    def initialize(models, preloads, reflections, preload_method = nil)
+      self.models         = models
+      self.preloads       = preloads.compact
+      self.reflections    = reflections
+      self.preload_method = preload_method
+      self.valid_preloads = {}
+    end
+
+    def call
+      clean!
+      preload!
+    end
+
+    ################################################################################
+    private
+    ################################################################################
+
+    # De-duplicates, reformats, and prunes requested preloads into an acceptable
+    # format for the preloader
+    def clean!
+      dedupe!
+      remove_unreflected_preloads!
+    end
+
+    def preload!
+      preload_method.call(models, valid_preloads) if valid_preloads.keys.any?
+    end
+
+    # Returns a proc that takes two arguments, +models+ and +association_names+,
+    # which, when called, preloads those.
+    #
+    # @return [Proc] A callable proc
+    def preload_method
+      @preload_method ||= begin
+        if Gem.loaded_specs['activerecord'].version >= Gem::Version.create('4.1')
+          ActiveRecord::Associations::Preloader.new.method(:preload)
+        else
+          Proc.new do |models, association_names|
+            ActiveRecord::Associations::Preloader.new(models, association_names).run
+          end
+        end
+      end
+    end
+
+    def dedupe!
+      preloads.each do |preload_name|
+        case preload_name
+        when Hash
+          preload_name.each do |key, value|
+            (valid_preloads[key.to_s] ||= Array.new) << value
+          end
+        when NilClass
+        else
+          valid_preloads[preload_name.to_s] ||= []
+        end
+      end
+    end
+
+    def remove_unreflected_preloads!
+      valid_preloads.select! { |preload_name, _| reflections.has_key?(preload_name.to_s) }
+    end
+  end
+end

data/lib/brainstem/presenter.rb

@@ -1,133 +1,274 @@
 require 'date'
-require 'brainstem/association_field'
 require 'brainstem/time_classes'
+require 'brainstem/preloader'
+require 'brainstem/concerns/presenter_dsl'
 
 module Brainstem
   # @abstract Subclass and override {#present} to implement a presenter.
   class Presenter
+    include Concerns::PresenterDSL
 
     # Class methods
 
-    # Accepts a list of classes this presenter knows how to present.
+    # Accepts a list of classes that this specific presenter knows how to present. These are not inherited.
     # @param [String, [String]] klasses Any number of names of classes this presenter presents.
     def self.presents(*klasses)
-      Brainstem.add_presenter_class(self, *klasses)
-    end
-
-    # @overload default_sort_order(sort_string)
-    #   Sets a default sort order.
-    #   @param [String] sort_string The sort order to apply by default while presenting. The string must contain the name of a sort order that has explicitly been declared using {sort_order}. The string may end in +:asc+ or +:desc+ to indicate the default order's direction.
-    #   @return [String] The new default sort order.
-    # @overload default_sort_order
-    #   @return [String] The default sort order, or nil if one is not set.
-    def self.default_sort_order(sort_string = nil)
-      if sort_string
-        @default_sort_order = sort_string
-      else
-        @default_sort_order
+      @presents ||= []
+      if klasses.length > 0
+        if klasses.any? { |klass| klass.is_a?(String) || klass.is_a?(Symbol) }
+          raise "Brainstem Presenter#presents now expects a Class instead of a class name"
+        end
+        @presents.concat(klasses).uniq!
+        Brainstem.add_presenter_class(self, namespace, *klasses)
       end
+      @presents
     end
 
-    # @overload sort_order(name, order)
-    #   @param [Symbol] name The name of the sort order.
-    #   @param [String] order The SQL string to use to sort the presented data.
-    # @overload sort_order(name, &block)
-    #   @yieldparam scope [ActiveRecord::Relation] The scope representing the data being presented.
-    #   @yieldreturn [ActiveRecord::Relation] A new scope that adds ordering requirements to the scope that was yielded.
-    #   Create a named sort order, either containing a string to use as ORDER in a query, or with a block that adds an order Arel predicate to a scope.
-    # @raise [ArgumentError] if neither an order string or block is given.
-    def self.sort_order(name, order = nil, &block)
-      raise ArgumentError, "A sort order must be given" unless block_given? || order
-      @sort_orders ||= HashWithIndifferentAccess.new
-      @sort_orders[name] = (block_given? ? block : order)
+    # Return the second-to-last module in the name of this presenter, which Brainstem considers to be the 'namespace'.
+    # E.g., Api::V1::FooPresenter has a namespace of "V1".
+    # @return [String] The name of the second-to-last module containing this presenter.
+    def self.namespace
+      self.to_s.split("::")[-2].try(:downcase)
     end
 
-    # @return [Hash] All defined sort orders, keyed by their name.
-    def self.sort_orders
-      @sort_orders
-    end
+    def self.merged_helper_class
+      @helper_classes ||= {}
 
-    # @overload filter(name, options = {})
-    #   @param [Symbol] name The name of the scope that may be applied as a filter.
-    #   @option options [Object] :default If set, causes this filter to be applied to every request. If the filter accepts parameters, the value given here will be passed to the filter when it is applied.
-    # @overload filter(name, options = {}, &block)
-    #   @param [Symbol] name The filter can be requested using this name.
-    #   @yieldparam scope [ActiveRecord::Relation] The scope that the filter should use as a base.
-    #   @yieldparam arg [Object] The argument passed when the filter was requested.
-    #   @yieldreturn [ActiveRecord::Relation] A new scope that filters the scope that was yielded.
-    def self.filter(name, options = {}, &block)
-      @filters ||= HashWithIndifferentAccess.new
-      @filters[name] = [options, (block_given? ? block : nil)]
+      @helper_classes[configuration[:helpers].to_a.map(&:object_id)] ||= begin
+        Class.new.tap do |klass|
+          (configuration[:helpers] || []).each do |helper|
+            klass.send :include, helper
+          end
+        end
+      end
     end
 
-    # @return [Hash]  All defined filters, keyed by their name.
-    def self.filters
-      @filters
+    def self.reset!
+      clear_configuration!
+      @helper_classes = @presents = nil
     end
 
-    def self.search(&block)
-      @search_block = block
+    # In Rails 4.2, ActiveRecord::Base#reflections started being keyed by strings instead of symbols.
+    def self.reflections(klass)
+      klass.reflections.each_with_object({}) { |(key, value), memo| memo[key.to_s] = value }
     end
 
-    def self.search_block
-      @search_block
+    # Instance methods
+
+    # @deprecated
+    def present(model)
+      raise "#present is now deprecated"
     end
 
-    # Declares a helper module whose methods will be available in instances of the presenter class and available inside sort and filter blocks.
-    # @param [Module] mod A module whose methods will be made available to filter and sort blocks, as well as inside the {#present} method.
-    # @return [self]
-    def self.helper(mod)
-      include mod
-      extend mod
+    def get_query_strategy
+      if configuration.has_key? :query_strategy
+        strat = configuration[:query_strategy]
+        strat.respond_to?(:call) ? fresh_helper_instance.instance_exec(&strat) : strat
+      end
     end
 
+    # Calls {#custom_preload} and then presents all models.
+    # @params [ActiveRecord::Relation, Array] models
+    # @params [Array] requested_associations An array of permitted lower-case string association names, e.g. 'post'
+    # @params [Hash] options The options passed to `load_associations!`
+    def group_present(models, requested_associations = [], options = {})
+      association_objects_by_name = requested_associations.each_with_object({}) do |assoc_name, memo|
+        memo[assoc_name.to_s] = configuration[:associations][assoc_name] if configuration[:associations][assoc_name]
+      end
 
-    # Instance methods
+      # It's slightly ugly, but more efficient if we pre-load everything we
+      # need and pass it through.
+      context = {
+        conditional_cache:            { request: {} },
+        fields:                       configuration[:fields],
+        conditionals:                 configuration[:conditionals],
+        associations:                 configuration[:associations],
+        reflections:                  reflections_for_model(models.first),
+        association_objects_by_name:  association_objects_by_name,
+        optional_fields:              options[:optional_fields] || [],
+        models:                       models,
+        lookup:                       empty_lookup_cache(configuration[:fields].keys, association_objects_by_name.keys)
+      }
 
-    # @raise [RuntimeError] if this method has not been overridden in the presenter subclass.
-    def present(model)
-      raise "Please override #present(model) in your subclass of Brainstem::Presenter"
+      sanitized_association_names = association_objects_by_name.values.map(&:method_name)
+      preload_associations! models, sanitized_association_names, context[:reflections]
+
+      # Legacy: Overridable for custom preload behavior.
+      custom_preload(models, association_objects_by_name.keys)
+
+      models.map do |model|
+        context[:conditional_cache][:model] = {}
+        context[:helper_instance] = fresh_helper_instance
+        result = present_fields(model, context, context[:fields])
+        load_associations!(model, result, context, options)
+        add_id!(model, result)
+        datetimes_to_json(result)
+      end
     end
 
-    # @api private
-    # Calls {#post_process} on the output from {#present}.
-    # @return (see #post_process)
-    def present_and_post_process(model, associations = [])
-      post_process(present(model), model, associations)
+    def present_model(model, requested_associations = [], options = {})
+      group_present([model], requested_associations, options).first
     end
 
     # @api private
-    # Loads associations and converts dates to epoch strings.
-    # @return [Hash] The hash representing the models and associations, ready to be converted to JSON.
-    def post_process(struct, model, associations = [])
-      add_id(model, struct)
-      load_associations!(model, struct, associations)
-      datetimes_to_json(struct)
+    #
+    # Returns the reflections for a model's class if the model is not nil.
+    def reflections_for_model(model)
+      model && Brainstem::Presenter.reflections(model.class)
     end
+    private :reflections_for_model
 
     # @api private
-    # Adds :id as a string from the given model.
-    def add_id(model, struct)
-      if model.class.respond_to?(:primary_key)
-        struct[:id] = model[model.class.primary_key].to_s
+    # Determines which associations are valid for inclusion in the current context.
+    # Mostly just removes only-restricted associations when needed.
+    # @return [Hash] The associations that can be included.
+    def allowed_associations(is_only_query)
+      ActiveSupport::HashWithIndifferentAccess.new.tap do |associations|
+        configuration[:associations].each do |name, association|
+          associations[name] = association unless association.options[:restrict_to_only] && !is_only_query
+        end
       end
     end
 
+    # Subclasses can define this if they wish. This method will be called by {#group_present}.
+    def custom_preload(models, requested_associations = [])
+    end
+
+    # Given user params, build a hash of validated filter names to their unsanitized arguments.
+    def extract_filters(user_params, options = {})
+      filters_hash = {}
+
+      apply_default_filters = options.fetch(:apply_default_filters) { true }
+
+      configuration[:filters].each do |filter_name, filter|
+        user_value = format_filter_value(user_params[filter_name])
+
+        filter_options = filter[0]
+        filter_arg = apply_default_filters && user_value.nil? ? filter_options[:default] : user_value
+        filters_hash[filter_name] = filter_arg unless filter_arg.nil?
+      end
+
+      filters_hash
+    end
+
     # @api private
-    # Calls {#custom_preload}, and then {#present} and {#post_process}, for each model.
-    def group_present(models, associations = [])
-      custom_preload models, associations
+    # @param [Array, Hash, String, Boolean, nil] value
+    #
+    # @return [Array, Hash, String, Boolean, nil]
+    def format_filter_value(value)
+      return value if value.is_a?(Array) || value.is_a?(Hash)
+      return nil if value.blank?
 
-      models.map do |model|
-        present_and_post_process model, associations
+      value = value.to_s
+      case value
+        when 'true', 'TRUE' then true
+        when 'false', 'FALSE' then false
+        else
+          value
       end
     end
+    private :format_filter_value
+
+    # Given user params, build a hash of validated filter names to their unsanitized arguments.
+    def apply_filters_to_scope(scope, user_params, options)
+      helper_instance = fresh_helper_instance
+
+      requested_filters = extract_filters(user_params, options)
+      requested_filters.each do |filter_name, filter_arg|
+        filter_lambda = configuration[:filters][filter_name][1]
+
+        args_for_filter_lambda = [filter_arg]
+        args_for_filter_lambda << requested_filters if configuration[:filters][filter_name][0][:include_params]
 
-    # Subclasses can define this if they wish. This method will be called before {#present}.
-    def custom_preload(models, associations = [])
+        if filter_lambda
+          scope = helper_instance.instance_exec(scope, *args_for_filter_lambda, &filter_lambda)
+        else
+          scope = scope.send(filter_name, *args_for_filter_lambda)
+        end
+      end
+
+      scope
     end
 
-    # @api private
+    # Given user params, apply a validated sort order to the given scope.
+    def apply_ordering_to_scope(scope, user_params)
+      sort_name, direction = calculate_sort_name_and_direction(user_params)
+      order = configuration[:sort_orders][sort_name]
+
+      ordered_scope = case order
+        when Proc
+          fresh_helper_instance.instance_exec(scope, direction, &order)
+        when nil
+          scope
+        else
+          scope.reorder(order.to_s + " " + direction)
+      end
+
+      fallback_deterministic_sort = assemble_primary_key_sort(scope)
+      # Chain on a tiebreaker sort to ensure deterministic ordering of multiple pages of data
+
+      if fallback_deterministic_sort
+        ordered_scope.order(fallback_deterministic_sort)
+      else
+        ordered_scope
+      end
+    end
+
+    def assemble_primary_key_sort(scope)
+      table_name = scope.table.name
+      primary_key = scope.model.primary_key
+
+      if table_name && primary_key
+        "#{scope.connection.quote_table_name(table_name)}.#{scope.connection.quote_column_name(primary_key)} ASC"
+      else
+        nil
+      end
+    end
+    private :assemble_primary_key_sort
+
+    # Execute the stored search block
+    def run_search(query, search_options)
+      fresh_helper_instance.instance_exec(query, search_options, &configuration[:search])
+    end
+
+    # Clean and validate a sort order and direction from user params.
+    def calculate_sort_name_and_direction(user_params = {})
+      default_column, default_direction = (configuration[:default_sort_order] || "updated_at:desc").split(":")
+      sort_name, direction = user_params['order'].to_s.split(":")
+      unless sort_name.present? && configuration[:sort_orders][sort_name]
+        sort_name = default_column
+        direction = default_direction
+      end
+
+      [sort_name, direction == 'desc' ? 'desc' : 'asc']
+    end
+
+    protected
+
+    # @api protected
+    # Run preloading on the given models, asking Rails to include both any named associations and any preloads declared in the Brainstem DSL..
+    def preload_associations!(models, sanitized_association_names, memoized_reflections)
+      return unless models.any?
+
+      preloads  = sanitized_association_names + configuration[:preloads].to_a
+      Brainstem::Preloader.preload(models, preloads, memoized_reflections)
+    end
+
+    # @api protected
+    # Instantiate and return a new instance of the merged helper class for this presenter.
+    def fresh_helper_instance
+      self.class.merged_helper_class.new
+    end
+
+    # @api protected
+    # Adds :id as a string from the given model.
+    def add_id!(model, struct)
+      if model.class.respond_to?(:primary_key)
+        struct['id'] = model[model.class.primary_key].to_s
+      end
+    end
+
+    # @api protected
     # Recurses through any nested Hash/Array data structure, converting dates and times to JSON standard values.
     def datetimes_to_json(struct)
       case struct
@@ -146,74 +287,124 @@ module Brainstem
       end
     end
 
-    # @api private
-    # Makes sure that associations are loaded and converted into ids.
-    def load_associations!(model, struct, associations)
-      reflections = Brainstem::PresenterCollection.reflections(model.class)
-      struct.to_a.each do |key, value|
-        if value.is_a?(AssociationField)
-          struct.delete key
-          id_attr = value.method_name ? "#{value.method_name}_id" : nil
-
-          if id_attr && model.class.columns_hash.has_key?(id_attr)
-            reflection = value.method_name && reflections[value.method_name.to_s]
-            if reflection && reflection.options[:polymorphic] && !value.ignore_type
-              struct["#{key.to_s.singularize}_ref".to_sym] = begin
-                if (id_attr = model.send(id_attr)).present?
-                  {
-                    :id => to_s_except_nil(id_attr),
-                    :key => model.send("#{value.method_name}_type").try(:constantize).try(:table_name)
-                  }
-                end
-              end
-            else
-              struct["#{key}_id".to_sym] = to_s_except_nil(model.send(id_attr))
+    # @api protected
+    # Uses the fields DSL to output a presented model.
+    # @return [Hash]  A hash representation of the model.
+    def present_fields(model, context, fields, result = {})
+      fields.each do |name, field|
+        case field
+          when DSL::Field
+            if field.conditionals_match?(model, context[:conditionals], context[:helper_instance], context[:conditional_cache]) && field.optioned?(context[:optional_fields])
+              result[name] = field.run_on(model, context, context[:helper_instance])
             end
-          elsif associations.include?(key.to_s)
-            result = value.call(model)
-            if result.is_a?(Array) || result.is_a?(ActiveRecord::Relation)
-              struct["#{key.to_s.singularize}_ids".to_sym] = result.map {|a| to_s_except_nil(a.is_a?(ActiveRecord::Base) ? a.id : a) }
-            else
-              if result.is_a?(ActiveRecord::Base)
-                struct["#{key.to_s.singularize}_id".to_sym] = to_s_except_nil(result.id)
-              else
-                struct["#{key.to_s.singularize}_id".to_sym] = to_s_except_nil(result)
-              end
+          when DSL::Configuration
+            result[name] ||= {}
+            present_fields(model, context, field, result[name])
+          else
+            raise "Unknown Brianstem Field type encountered: #{field}"
+        end
+      end
+      result
+    end
+
+    # @api protected
+    # Makes sure that associations are loaded and converted into ids.
+    def load_associations!(model, struct, context, options)
+      context[:associations].each do |external_name, association|
+        method_name = association.method_name && association.method_name.to_s
+        id_attr = method_name && "#{method_name}_id"
+
+        # If this association has been explictly requested, execute the association here.  Additionally, store
+        # the loaded models in the :load_associations_into hash for later use.
+        if context[:association_objects_by_name][external_name]
+          associated_model_or_models = association.run_on(model, context, context[:helper_instance])
+
+          if options[:load_associations_into]
+            Array(associated_model_or_models).flatten.each do |associated_model|
+              key = presenter_collection.brainstem_key_for!(associated_model.class)
+              options[:load_associations_into][key] ||= {}
+              options[:load_associations_into][key][associated_model.id.to_s] = associated_model
             end
           end
         end
+
+        if id_attr && model.class.columns_hash.has_key?(id_attr) && !association.polymorphic?
+          # We return *_id keys when they exist in the database, because it's free to do so.
+          struct["#{external_name}_id"] = to_s_except_nil(model.send(id_attr))
+        elsif association.always_return_ref_with_sti_base?
+          # Deprecated support for legacy always-return-ref mode without loading the association.
+          struct["#{external_name}_ref"] = legacy_polymorphic_base_ref(model, id_attr, method_name)
+        elsif context[:association_objects_by_name][external_name]
+          # This association has been explicitly requested.  Add the *_id, *_ids, *_ref, or *_refs keys to the presented data.
+          add_ids_or_refs_to_struct!(struct, association, external_name, associated_model_or_models)
+        end
       end
     end
 
-    # @!attribute [r] default_sort_order
-    # The default sort order set on this presenter's class.
-    def default_sort_order
-      self.class.default_sort_order
+    # @api protected
+    # Inject 'foo_ids' keys into the presented data if the foos association has been requested.
+    def add_ids_or_refs_to_struct!(struct, association, external_name, associated_model_or_models)
+      singular_external_name = external_name.to_s.singularize
+      if association.polymorphic?
+        if associated_model_or_models.is_a?(Array) || associated_model_or_models.is_a?(ActiveRecord::Relation)
+          struct["#{singular_external_name}_refs"] = associated_model_or_models.map { |associated_model| make_model_ref(associated_model) }
+        else
+          struct["#{singular_external_name}_ref"] = make_model_ref(associated_model_or_models)
+        end
+      else
+        if associated_model_or_models.is_a?(Array) || associated_model_or_models.is_a?(ActiveRecord::Relation)
+          struct["#{singular_external_name}_ids"] = associated_model_or_models.map { |associated_model| to_s_except_nil(associated_model.try(:id)) }
+        else
+          struct["#{singular_external_name}_id"] = to_s_except_nil(associated_model_or_models.try(:id))
+        end
+      end
     end
 
-    # @!attribute [r] sort_orders
-    # The sort orders that were declared in the definition of this presenter.
-    def sort_orders
-      self.class.sort_orders
+    # @api protected
+    # Deprecated support for legacy always-return-ref mode without loading the association.
+    # This tries to find the key based on the *_type value in the DB (which will be the STI base class, and may error if no presenter exists)
+    def legacy_polymorphic_base_ref(model, id_attr, method_name)
+      if (id = model.send(id_attr)).present?
+        {
+          'id' => to_s_except_nil(id),
+          'key' => presenter_collection.brainstem_key_for!(model.send("#{method_name}_type").try(:constantize))
+        }
+      end
     end
 
-    # @!attribute [r] filters
-    # The filters that were declared in the definition of this presenter.
-    def filters
-      self.class.filters
+    # @api protected
+    # Call to_s on the input unless the input is nil.
+    def to_s_except_nil(thing)
+      thing.nil? ? nil : thing.to_s
     end
 
-    def search_block
-      self.class.search_block
+    # @api protected
+    # Return a polymorphic id/key object for a model, or nil if no model was given.
+    def make_model_ref(model)
+      if model
+        {
+          'id' => to_s_except_nil(model.id),
+          'key' => presenter_collection.brainstem_key_for!(model.class)
+        }
+      else
+        nil
+      end
     end
 
-    # An association on the object being presented that should be included in the presented data.
-    def association(*args, &block)
-      AssociationField.new *args, &block
+    # @api protected
+    # Find the global presenter collection for our namespace.
+    def presenter_collection
+      Brainstem.presenter_collection(self.class.namespace)
     end
 
-    def to_s_except_nil(thing)
-      thing.nil? ? nil : thing.to_s
+    # @api protected
+    # Create an empty lookup cache with the fields and associations as keys and nil for the values
+    # @return [Hash]
+    def empty_lookup_cache(field_keys, association_keys)
+      {
+        fields: Hash[field_keys.map { |key| [key, nil] }],
+        associations: Hash[association_keys.map { |key| [key, nil] }]
+      }
     end
   end
 end