Merge pull request #258 from cerebris/links

Links

Author: dgeb

README.md

@@ -534,23 +534,22 @@ Callbacks can also be defined for `JSONAPI::OperationsProcessor` events:
 - `:remove_has_many_association_operation`: A `remove_has_many_association_operation`.
 - `:remove_has_one_association_operation`: A `remove_has_one_association_operation`.
 
-The operation callbacks have access to two meta data hashes, `@operations_meta` and `@operation_meta`, the full list of
-`@operations`, each individual `@operation` and the `@result` variables.
+The operation callbacks have access to two meta data hashes, `@operations_meta` and `@operation_meta`, two links hashes,
+`@operations_links` and `@operation_links`, the full list of `@operations`, each individual `@operation` and the 
+`@result` variables.
 
 ##### Custom `OperationsProcessor` Example to Return total_count in Meta
 
+Note: this can also be accomplished with the `top_level_meta_include_record_count` option, and in most cases that will
+be the better option. 
+
 To return the total record count of a find operation in the meta data of a find operation you can create a custom
 OperationsProcessor. For example:
 
 ```ruby
 class CountingActiveRecordOperationsProcessor < ActiveRecordOperationsProcessor
   after_find_operation do
-    count = @operation.resource_klass.find_count(@operation.resource_klass.verify_filters(@operation.filters, @context),
-                                 context: @context,
-                                 include_directives: @operation.include_directives,
-                                 sort_criteria: @operation.sort_criteria)
-
-    @operation_meta[:total_records] = count
+    @operation_meta[:total_records] = @operation.record_count
   end
 end
 ```
@@ -1179,6 +1178,42 @@ end
 
 You would specify this in `JSONAPI.configure` as `:upper_camelized`.
 
+## Configuration
+
+JR has a few configuration options. Some have already been mentioned above. To set configuration options create an 
+initializer and add the options you wish to set. All options have defaults, so you only need to set the options that
+are different. The default options are shown below.
+
+```ruby
+JSONAPI.configure do |config|
+  #:underscored_key, :camelized_key, :dasherized_key, or custom
+  config.json_key_format = :dasherized_key
+
+  #:underscored_route, :camelized_route, :dasherized_route, or custom
+  config.route_format = :dasherized_route
+
+  #:basic, :active_record, or custom
+  config.operations_processor = :active_record
+
+  config.allowed_request_params = [:include, :fields, :format, :controller, :action, :sort, :page]
+
+  # :none, :offset, :paged, or a custom paginator name
+  config.default_paginator = :none
+
+  # Output pagination links at top level
+  config.top_level_links_include_pagination = true
+
+  config.default_page_size = 10
+  config.maximum_page_size = 20
+
+  # Output the record count in top level meta data for find operations
+  config.top_level_meta_include_record_count = false
+  config.top_level_meta_record_count_key = :record_count
+
+  config.use_text_errors = false
+end
+```
+
 ## Contributing
 
 1. Fork it ( http://github.com/cerebris/jsonapi-resources/fork )

lib/jsonapi/acts_as_resource_controller.rb

@@ -123,6 +123,10 @@ def base_response_meta
       {}
     end
 
+    def base_response_links
+      {}
+    end
+
     def render_errors(errors)
       operation_results = JSONAPI::OperationResults.new()
       result = JSONAPI::ErrorsOperationResult.new(errors[0].status, errors)
@@ -147,7 +151,9 @@ def create_response_document(operation_results)
           key_formatter: key_formatter,
           route_formatter: route_formatter,
           base_meta: base_response_meta,
-          resource_serializer_klass: resource_serializer_klass
+          base_links: base_response_links,
+          resource_serializer_klass: resource_serializer_klass,
+          request: @request
         }
       )
     end

lib/jsonapi/configuration.rb

@@ -13,7 +13,10 @@ class Configuration
                 :default_paginator,
                 :default_page_size,
                 :maximum_page_size,
-                :use_text_errors
+                :use_text_errors,
+                :top_level_links_include_pagination,
+                :top_level_meta_include_record_count,
+                :top_level_meta_record_count_key
 
     def initialize
       #:underscored_key, :camelized_key, :dasherized_key, or custom
@@ -30,8 +33,17 @@ def initialize
       # :none, :offset, :paged, or a custom paginator name
       self.default_paginator = :none
 
+      # Output pagination links at top level
+      self.top_level_links_include_pagination = true
+
       self.default_page_size = 10
       self.maximum_page_size = 20
+
+      # Metadata
+      # Output record count in top level meta for find operation
+      self.top_level_meta_include_record_count = false
+      self.top_level_meta_record_count_key = :record_count
+
       self.use_text_errors = false
     end
 
@@ -69,6 +81,18 @@ def maximum_page_size=(maximum_page_size)
     def use_text_errors=(use_text_errors)
       @use_text_errors = use_text_errors
     end
+
+    def top_level_links_include_pagination=(top_level_links_include_pagination)
+      @top_level_links_include_pagination = top_level_links_include_pagination
+    end
+
+    def top_level_meta_include_record_count=(top_level_meta_include_record_count)
+      @top_level_meta_include_record_count = top_level_meta_include_record_count
+    end
+
+    def top_level_meta_record_count_key=(top_level_meta_record_count_key)
+      @top_level_meta_record_count_key = top_level_meta_record_count_key
+    end
   end
 
   class << self

lib/jsonapi/operation.rb

@@ -23,14 +23,41 @@ def initialize(resource_klass, options = {})
       super(resource_klass, false)
     end
 
+    def record_count
+      @_record_count ||= @resource_klass.find_count(@resource_klass.verify_filters(@filters, @context),
+                                                     context: @context,
+                                                     include_directives: @include_directives)
+    end
+
+    def pagination_params
+      if @paginator && JSONAPI.configuration.top_level_links_include_pagination
+        options = {}
+        options[:record_count] = record_count if @paginator.class.requires_record_count
+        return @paginator.links_page_params(options)
+      else
+        return {}
+      end
+    end
+
     def apply(context)
       resource_records = @resource_klass.find(@resource_klass.verify_filters(@filters, context),
                                              context: context,
                                              include_directives: @include_directives,
                                              sort_criteria: @sort_criteria,
                                              paginator: @paginator)
 
-      return JSONAPI::ResourcesOperationResult.new(:ok, resource_records)
+      options = {}
+      if JSONAPI.configuration.top_level_links_include_pagination
+        options[:pagination_params] = pagination_params
+      end
+
+      if JSONAPI.configuration.top_level_meta_include_record_count
+        options[:record_count] = record_count
+      end
+
+      return JSONAPI::ResourcesOperationResult.new(:ok,
+                                                   resource_records,
+                                                   options)
 
     rescue JSONAPI::Exceptions::Error => e
       return JSONAPI::ErrorsOperationResult.new(e.errors[0].code, e.errors)

lib/jsonapi/operation_result.rb

@@ -2,47 +2,53 @@ module JSONAPI
   class OperationResult
     attr_accessor :code
     attr_accessor :meta
+    attr_accessor :links
+    attr_accessor :options
 
-    def initialize(code)
+    def initialize(code, options = {})
       @code = code
-      @meta = {}
+      @options = options
+      @meta = options.fetch(:meta, {})
+      @links = options.fetch(:links, {})
     end
   end
 
   class ErrorsOperationResult < OperationResult
     attr_accessor :errors
 
-    def initialize(code, errors)
+    def initialize(code, errors, options = {})
       @errors = errors
-      super(code)
+      super(code, options)
     end
   end
 
   class ResourceOperationResult < OperationResult
     attr_accessor :resource
 
-    def initialize(code, resource)
+    def initialize(code, resource, options = {})
       @resource = resource
-      super(code)
+      super(code, options)
     end
   end
 
   class ResourcesOperationResult < OperationResult
-    attr_accessor :resources
+    attr_accessor :resources, :pagination_params, :record_count
 
-    def initialize(code, resources)
+    def initialize(code, resources, options = {})
       @resources = resources
-      super(code)
+      @pagination_params = options.fetch(:pagination_params, {})
+      @record_count = options[:record_count]
+      super(code, options)
     end
   end
 
   class LinksObjectOperationResult < OperationResult
     attr_accessor :parent_resource, :association
 
-    def initialize(code, parent_resource, association)
+    def initialize(code, parent_resource, association, options = {})
       @parent_resource = parent_resource
       @association = association
-      super(code)
+      super(code, options)
     end
   end
 end

lib/jsonapi/operation_results.rb

@@ -2,11 +2,13 @@ module JSONAPI
   class OperationResults
     attr_accessor :results
     attr_accessor :meta
+    attr_accessor :links
 
     def initialize
       @results = []
       @has_errors = false
       @meta = {}
+      @links = {}
     end
 
     def add_result(result)

lib/jsonapi/operations_processor.rb

@@ -41,23 +41,29 @@ def process(request)
 
       run_callbacks :operations do
         transaction do
+          # Links and meta data global to the set of operations
           @operations_meta = {}
+          @operations_links = {}
           @operations.each do |operation|
             @operation = operation
+            # Links and meta data for each operation
             @operation_meta = {}
+            @operation_links = {}
             run_callbacks :operation do
               @result = nil
               run_callbacks @operation.class.name.demodulize.underscore.to_sym do
                 @result = process_operation(@operation)
               end
               @result.meta.merge!(@operation_meta)
+              @result.links.merge!(@operation_links)
               @results.add_result(@result)
               if @results.has_errors?
                 rollback
               end
             end
           end
           @results.meta = @operations_meta
+          @results.links = @operations_links
         end
       end
       @results