json_serializer 0.0.1 → 0.1.0

data/README.md

@@ -18,7 +18,86 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+The gem offers two primary features, serialize ActiveRecord models and collections into JSON and providing JSON Output helpers for an API. 
+
+### ActiveRecord Patch and Custom API Attributes
+
+We patch ActiveRecord::Base and Array with a serializer method. You can simple call `.serialize` to see this in action. If you want to customize the attributes that are serialized, simple add an `api_attributes` method to your model:
+
+    
+    class Post < ActiveRecord::Base
+      ...
+      def api_attributes
+        {
+          id: self.id.to_s,
+          title: self.title.to_s,
+          body: self.body.to_s,
+          created_at: self.created_at.to_s,
+          author: self.user.api_attributes,
+        }
+      end
+      ...
+    end
+    
+Adding the `api_attributes` method will allow you to control and customize the out attributes. Also note that you can have associated models, in this case Author attribute is an associated model User. We'll need to add the `api_attributes` to that model also.
+
+
+### JSON Output Helper
+
+After you have setup your custom API attributes, you can easily output JSON with a few helper methods:
+
+#### JSON Model
+Output a model in JSON:
+
+    post = Post.find(params[:id])
+    json_model :accepted, post
+    
+It's that simple. This will automatically serialize and output your model as JSON. Notice the `:accepted` attribute, this will set the Header Status Code to 202. You can always modify this, take a look at (this nice list of Rails HTTP Status Codes)[http://www.codyfauser.com/2008/7/4/rails-http-status-code-to-symbol-mapping] for more details.
+
+You can optionally pass parameters by simple adding them to your `json_model` method:
+
+    post = Post.find(params[:id])
+    json_model :accepted, post, param: "Some extra parameters", more: "And some more..."
+    
+You can also append full serialized objects:
+
+  post = Post.find(params[:id])
+  json_model :accepted, post, comments: post.comments.serialize
+
+In this case we called `post.comments.serialize`, which will actually collect all the objects in the array or ActiveRecord collection and serialize each one based on the API Attributes (if available) or just to_json.
+
+
+#### JSON Models
+
+Similar to the json_model method, there is a json_models method. This is simple:
+
+    posts = Posts.all
+    json_models :accepted, posts
+
+Similarly, you can append additional parameters:
+
+    posts = Posts.all
+    json_models :accepted, posts, categories: Category.all.serialize, tags: Tag.all.serialize
+
+
+#### Success and Error
+
+You can create simple success and errors with a few helps. To create a successful JSON response, simple call:
+
+    # json_success message, hash={}
+    json_success "Great success!", extra_params: hash
+    # => { success: "true", message: "message...", ... additional params ... }
+    
+This will automatically send a 200 Ok response in the Header Status Code.
+
+Error codes are similar:
+
+    # json_error code, message, metadata={}
+    json_error 404, "Post not found.", errors: "Whatever extra metadata and params"
+    # => { error: { message: "Message goes here", code: 404, meta_data: "goes here..." } }
+
+And this will automatically add your status code to the HTTP response
+
 
 ## Contributing
 

data/lib/json_serializer/json_responses.rb

@@ -0,0 +1,80 @@
+module JsonSerializer
+  module JsonResponses
+    
+    
+    # JSON helpers
+    # Simple methods for DRYing up and standardizing JSON output
+    # ----------------------------------------------------------------------------------------------------
+
+    # a nice standard response schema for json
+    def json_response(type, hash = {})
+      # we require one of these types
+      unless [ :ok, :redirect, :error ].include?(type)
+        raise "Invalid json response type: #{type}"
+      end
+
+      # To keep the structure consistent, we'll build the json 
+      # structure with these default properties.
+      default_json = { 
+        :status => type, 
+        :html => nil, 
+        :notice => nil, 
+        :to => nil
+      }.merge(hash)
+      return default_json
+    end
+
+    # render our standardized json response
+    def render_json_response(type, hash = {})
+      render :json => json_response(type, hash)
+    end
+    
+    
+    
+    # Response specific helper: For Success and error handling
+    # ----------------------------------------------------------------------------------------------------
+
+    # helper for success messages (for actions like delete which dont return models)
+    def json_success message, hash = {}
+      json = {
+        :success => true,
+        :message => message
+      }.merge(hash)
+      render :json => json, status: :accepted
+    end
+
+    # helper for returning failure messages in a common format
+    def json_error code, message=nil, metadata={}
+      render :json => {
+        :error => metadata.merge({
+          :message => message || t("api.errors.#{code}"),
+          :code => code
+        }),
+      }, status: code
+    end
+    
+    
+    
+    # JSON Heper for Models
+    # ----------------------------------------------------------------------------------------------------
+    
+    # a standard way to return models. if they have errors then we return the error message
+    # this is a DRY approach to creating and updating and then returning JSON responses
+    def json_model status, model, extra_params={}
+      render json: model.serialize.merge(extra_params), status: status
+    end
+    
+    # a standard way to return an array of models
+    # arrays of models are passed back in a data object, this is so we can add things we may need in the future such as pagination
+    def json_models status, models, extra_params={}
+      render json: models.serialize.merge(extra_params), status: status
+    end
+    
+    
+  end
+end
+
+class ActionController::Base
+  include JsonSerializer
+  include JsonSerializer::JsonResponses
+end

data/lib/json_serializer/rails/active_record_patch.rb

@@ -0,0 +1,19 @@
+module ActiveRecord
+  class Base
+    def serialize
+      {"#{self.class.name.downcase.underscore}" => self.send((self.respond_to? :api_attributes) ? :api_attributes : :to_json)}
+    end
+    
+    def self.serialize
+      self.collect{|model| model.send((model.respond_to? :api_attributes) ? :api_attributes : :to_json).merge({:_class_name => self.first.class.name.downcase.pluralize})}.group_by{|d| d[:_class_name] }
+    end
+     
+  end
+end
+
+
+class Array
+  def serialize
+    self.collect{|model| model.send((model.respond_to? :api_attributes) ? :api_attributes : :to_json).merge({:_class_name => self.first.class.name.downcase.pluralize})}.group_by{|d| d[:_class_name] }
+  end
+end

data/lib/json_serializer/version.rb

@@ -1,3 +1,3 @@
 module JsonSerializer
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: json_serializer
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-22 00:00:00.000000000 Z
+date: 2013-07-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -57,6 +57,8 @@ files:
 - Rakefile
 - json_serializer.gemspec
 - lib/json_serializer.rb
+- lib/json_serializer/json_responses.rb
+- lib/json_serializer/rails/active_record_patch.rb
 - lib/json_serializer/version.rb
 homepage: ''
 licenses: