the_grid 1.0.7

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    YWI3ODZiNmIxNzlkYzkxYzIxNjY5ZWMxNGFmMWZlZWMyNjQ1NGRiNw==
+  data.tar.gz: !binary |-
+    YmVkOGMwNjRjYmJjYTI0MWM3ZmM5ODZmNTkyOTAxZjFjMjdiMDcwMA==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    MDA1ZmJmZjIwYjAzNGQyNTFjOWQwYWRkM2UxZjkzZjYzZDg4YjdiOGZkZDVm
+    ZjUzZTc2YWIzNzA1MTlmMGM2MTI5NmEzOGU1MjE0ZjFjNTM1NjI5Y2U2OGU5
+    NDVkZmMxYWUxMWRiNmIzYzQwYTIwNzljMTkyYzg2MmFjNzdjN2Q=
+  data.tar.gz: !binary |-
+    OWQzNGE2YzlhOGM4NzkxMWViOGNhMzcxMjg1NWFhZjhhZTc0ZTFmM2M5OWFl
+    NGQ3MTBiMzk1ZGZlZDllNDQwMThiNWQ3ZTFmZTA2ZWZhNzA1NzIyNjhkYTRh
+    MjY1OWFlNGM5YTIzNjNlNGRlM2RlOTRlZGIxMWJhODFlYWQ4OGE=

data/.rvmrc

@@ -0,0 +1 @@
+rvm use --create 1.9.3-p392@grid

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+gemspec
+gem 'cover_me', '>= 1.2.0', :group => :test

data/README.md

@@ -0,0 +1,424 @@
+Yet Another Grid
+=========
+
+This plugin is designed to provide API for building json response based on `ActiveRecord::Relation` objects.
+It makes much easier to fetch information from database for displaying it using JavaScript MV* based frameworks such as Knockout, Backbone, Angular, etc.
+
+## Getting started
+
+First of all specify grid in your Gemfile and run `bundle install`.
+After gem is installed you need to run `rails generate grid:install`. This will generate grid initializer file with basic configuration.
+
+## Usage
+
+Controller:
+```ruby
+# app/controllers/articles_controller.rb
+class ArticlesController < ApplicationController
+  respond_to :json
+
+  def index
+    @articles = Article.published
+    respond_with @articles
+  end
+end
+```
+
+View:
+```ruby
+# app/views/articles/index.json.grid_builder
+grid_for @articles, :per_page => 25 do
+  searchable_columns :title
+
+  column :title
+  column(:url)        { |a| article_url(a) }
+  column(:created_at) { |a| a.created_at.to_s(:date) }
+  column(:author)     { |a| a.author.full_name }
+end
+```
+
+## API
+
+The API is based on commands. Term *command* describes client's action which can be simple or complicated as well.
+The general request looks like:
+
+    http://your.domain.com/route.json? with_meta=1 &
+      page=1 &
+      cmd[]=sort & field=title & order=desc &
+      cmd[]=search & query=test &
+      cmd[]=filter & filters[created_at][from]=1363513288 & filters[created_at][to]=1363513288
+
+Each parameter relates to options of a command. The only exception is **with_meta** parameter which is used to retrieve extra meta information of grid.
+
+### Commands
+
+There are 2 types of commands: batch commands (e.g. *update, remove*) and select commands (e.g. *search*, *paginate*, *sort*, *filter*).
+Select commands can be processed per one request (i.e. stacked) by **TheGrid::Builder** (method `execute_on` of such commands always returns `ActiveRecord::Relation`).
+Batch commands can't be processed by **TheGrid::Builder** even more they are ignored (method `execute_on` returns array of processed records or boolean value).
+There are few predefined commands: `paginate`, `search`, `sort`, `filter`, `batch_update`, `batch_remove`.
+
+#### Paginate
+
+This command has 2 non-required parameters:
+
+- **page** specifies page of data (integer number, starts with 1)
+- **per_page** specifies how much records should be selected per one page (integer number)
+
+#### Sort
+
+This command has also 2 paramters:
+
+- **field** specifies sort column (string)
+- **order** specifies sort order (*asc* or *desc*)
+
+#### Filter
+
+This command requires only one hash parameter **filters** but it can be in 3 different forms:
+
+- `{ :title => "test" }` => `name = "test"`
+- `{ :created_at => { :from => ... , :to => ..., :type => "time|date|nil" } }` => `created_at >= :from AND created_at <= :to`
+
+    - *type* specifies type of from/to parameters (optional, can be *date* or *time*). If `:type` is *date* from/to fields will be parsed into dates using `to_time` method. If `:type` is *time* from/to fields should be timestamps.
+    - *from/to* specifies top and bottom limits (one of them can be omitted)
+
+- `{ :id => [1, 2, 3] }` => `id IN (1,2,3)`
+
+#### Search
+
+This command requires only one parameter **query** which specifies search string.
+
+#### Batch Update
+
+This command requires one parameter **items** - an array of hashes (with stringified keys).
+Each hash should contain integer value with key *id*. Hash row is ignored if *id* is omitted or non-integer.
+
+#### Batch Remove
+
+This command also requires one parameter **item_ids** - array of integer ids.
+Value of array is ignored if it's non-integer.
+
+### Run batch commands
+
+It's impossible to run batch commands using `TheGrid::Builder`.
+By default command is considered as batch one if its class name starts with **Batch**. If you want to override this behavior you need to implement instance method `batch?`.
+So, client has to manually build grid instance and call `run_command!` method:
+```ruby
+TheGrid.build_for(Article).run_command!('batch_update', params)
+```
+Actually it's possible to run any command as shown in line above.
+Example of controller's batch action:
+```ruby
+class ArticlesController < ApplicationController
+  def batch_update
+    articles = TheGrid.build_for(Article).run_command!('batch_update', :items => params[:articles])
+    render :json => build_grid_response_for(articles, :success => "Articles has been successfully updated")
+  rescue ArgumentError => e
+    render :json => { :message => e.message, :status => :error }
+  end
+
+private
+  def build_grid_response_for(records, options = {})
+    error_message = records.select(&:invalid?).map{ |r| r.errors.full_messages }.join('. ')
+    if error_message.blank?
+      {:status => :success, :message => options[:success]}
+    else
+      {:status => :error, :message => error_message}
+    end
+  end
+ end
+```
+### Create/override commands
+
+It's a normal situation when client needs a custom command or a custom version of existing command.
+Suppose there is a need in `suspend` command which change status of records into *suspended*.
+Command class should implement at least 2 methods: `configure` and `run_on` (if command is a batch one it should implement `batch?` method which returs `true`).
+`configure` method should return validated parameters or raise an error if one of the required options is missed. Example:
+```ruby
+module GridCommands
+  class BatchSuspend < TheGrid::Api::Command
+    def configure(relation, params)
+      ids = params[:item_ids].reject{ |id| id.to_i <= 0 }
+      raise ArgumentError, "There is nothing to update" if ids.blank?
+      { :item_ids => ids }
+    end
+
+    def run_on(relation, params)
+      relation.where(relation.table.primary_key.in(params[:item_ids])).update_all(:status => 'suspended')
+    end
+  end
+end
+```
+For running this command it's also necessarely to update `commands_lookup_scopes`. It can be done inside grid intializer file:
+```ruby
+# config/initializers/grid.rb
+TheGrid.configure do |config|
+  # Specifies scopes for custom commands
+  config.commands_lookup_scopes += %w{ grid_commands }
+  # ....
+end
+```
+Then it will be possible to run:
+```ruby
+TheGrid.build_for(Article).run_command!('batch_suspend', :item_ids => params[:id])
+```
+Using lookup technique it's possible to override existing commands. Suppose there is a need to customize `batch_update` command to allow non-integer ids:
+```ruby
+module GridCommands
+  class BatchUpdate < TheGrid::Api::Command::BatchUpdate
+    def configure(relation, params)
+      items = params[:items].reject{ |item| item['id'].to_s.strip.blank? }
+      raise ArgumentError, "There is nothing to update" if items.blank?
+      { :items => items }
+    end
+  end
+end
+```
+
+## Template Builder
+
+For Rails based application there is a template builder which does all the stuff under the hood.
+```ruby
+# app/views/articles/index.json.grid_builder
+grid_for @articles, :per_page => 2 do
+  column :title
+  column :description
+end
+```
+Such view is converted into the next json response:
+```json
+{
+  "max_page": 3,
+  "items": [
+    {
+      "id": 1,
+      "title": "My test article",
+      "description": "Something interesting"
+    },
+    {
+      "id": 2,
+      "title": "My hidden article",
+      "description": "Something not interesting"
+    }
+  ]
+}
+```
+It's possible to format column output by passing block into column declaration:
+```ruby
+# app/views/articles/index.json.grid_builder
+grid_for @articles, :per_page => 2 do
+  column :title
+  column :description
+  column(:created_at){ |article| article.created_at.to_s(:date) }
+end
+```
+Also it's possible to specify extra information for each column (e.g. *editable*, *searchable*, etc):
+```ruby
+# app/views/articles/index.json.grid_builder
+grid_for @articles, :per_page => 2 do
+  column :title, :editable => true, :sortable => true, :an_option => "any extra information"
+  column :description, :editable => true
+  column(:created_at, :editable => true){ |article| article.created_at.to_s(:date) }
+end
+```
+Looks like a mess, don't it? However there are helper's methods which helps to clean up this view:
+```ruby
+# app/views/articles/index.json.grid_builder
+grid_for @articles, :per_page => 2 do
+  editable_columns :title, :description, :created_at
+  sortable_columns :title
+
+  column :title, :an_option => "any extra information"
+  column :description
+  column(:created_at){ |article| article.created_at.to_s(:date) }
+end
+```
+It's possible to specify any features for columns using the next DSL method template: `"#{feature}ble_columns"` (e.g. `visible_columns *columns_list`).
+`searchable_columns` method is a bit special. It not only marks column with searchable flag but also specifies which columns will be searched when `search` command is run.
+
+Sometimes it's reasonable to add extra meta information into response:
+```ruby
+grid_for @articles, :per_page => 2 do
+  searchable_columns :title, :created_at
+
+  # specify any kind of meta parameter
+  server_time Time.now
+  my_option   "Something important for Frontend side"
+
+  column :title
+  column(:created_at){ |r| r.created_at.to_s(:date) }
+end
+```
+Columns meta and extra meta information will be accessible in response only if client specifies non-empty **with_meta** parameter in request.
+The previous example is converted into:
+```json
+{
+  "meta": {
+    "server_time": "2013-03-17 02:11:05 +0200",
+    "my_option": "Something important for Frontend side"
+  },
+  "columns": {
+    "title": {
+      "searchable": true,
+      "editable": true
+    },
+    "created_at": {
+      "searchable": true
+    }
+  },
+  "max_page": 3,
+  "items": [
+    {
+      "id": 1,
+      "title": "My test article",
+      "created_at": "03/17/2013"
+    },
+    {
+      "id": 2,
+      "title": "My hidden article",
+      "created_at": "03/16/2013"
+    }
+  ]
+}
+```
+`per_page` option can be omitted. In such cases will be used `params[:per_page]` or default per page value specified inside grid initializer.
+Sometimes client need to retrieve all records without pagination. So, for disabling pagination just set `per_page` option to `false`. In such cases `max_page` will be omitted in response.
+
+#### Nested scopes and tree-like structures
+
+If you need to create tree-like stucture for custom grid view (e.g. complex navigation) you can use `scope_for` declaration:
+```ruby
+grid_for @groups, :per_page => 2 do
+  column :name
+  column :is_active do |p|
+    params[:current_id].to_i == p.id
+  end
+
+  scope_for :articles do
+    column :title
+    column :created_at do |a|
+      a.created_at.to_s(:date)
+    end
+  end
+end
+```
+This example builds the next response:
+```json
+{
+  "max_page": 2,
+  "items": [
+    {
+      "id": 1,
+      "name": "test",
+      "is_active": true,
+      "articles": [
+        {
+          "id": 2,
+          "title": "Something inetresting",
+          "created_at": "03/17/2013"
+        },
+        {
+          "id": 4,
+          "title": "test article",
+          "created_at": "03/14/2013"
+        }
+      ]
+    },
+    {
+      "id": 3,
+      "name": "test2",
+      "is_active": false,
+      "articles": [
+        {
+          "id": 3,
+          "title": "test article 2",
+          "created_at": "03/13/2013"
+        }
+      ]
+    }
+  ]
+}
+```
+If you need to standardize output you can specify `:as` option - the column name for nested grid (e.g. if you specify `:as => :children` then *articles* key will be substituted with *children* key).
+Also there are 2 conditional options `:unless` and `:if` which accepts lambda or symbol.
+If you specify symbol as condition will be used column value with such name (in this case it's important that column is defined before scope).
+If you need some custom logic to detect if scope should be created for such row or not you can pass lambda.
+
+For example we want to get articles only of active/current group:
+```ruby
+grid_for @groups, :per_page => 2 do
+  column :name
+  column :is_active do |p|
+    params[:current_id].to_i == p.id
+  end
+
+  scope_for :articles, :as => :children, :if => :is_active do
+    column :title
+  end
+end
+```
+Or the same with lambda:
+```ruby
+grid_for @groups, :per_page => 2 do
+  column :name
+  column :is_active do |p|
+    params[:current_id].to_i == p.id
+  end
+
+  scope_for :articles, :as => :children, :if => lambda{ |group| group.id == params[:current_id].to_i } do
+    column :title
+  end
+end
+```
+This produces the response:
+```json
+{
+  "max_page": 2,
+  "items": [
+    {
+      "id": 1,
+      "name": "test",
+      "is_active": true,
+      "children": [
+        {
+          "id": 2,
+          "title": "Something inetresting",
+          "created_at": "03/17/2013"
+        },
+        {
+          "id": 4,
+          "title": "test article",
+          "created_at": "03/14/2013"
+        }
+      ]
+    },
+    {
+      "id": 3,
+      "name": "test2",
+      "is_active": false,
+      "children": null
+    }
+  ]
+}
+```
+#### Command delegation
+
+Sometimes there is a need to delegate command processing to nested nested grid. For example, there are groups and articles.
+You need to display groups sorted by name asc and provide ability to sort articles inside each group by any columns.
+For such purposes you can use `delegate` declaration:
+```ruby
+grid_for @groups, :per_page => 2 do
+  delegate :sort => :articles, :filter => :articles
+
+  column :name
+  column :is_active do |p|
+    params[:current_id].to_i == p.id
+  end
+
+  scope_for :articles, :as => :children, :if => :is_active do
+    column :title
+  end
+end
+```
+## License
+
+Released under the [MIT License](http://www.opensource.org/licenses/MIT)

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/generators/the_grid/install/install_generator.rb

@@ -0,0 +1,11 @@
+module TheGrid
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("../templates", __FILE__)
+
+      def copy_initializer
+        template "the_grid.rb", "config/initializers/the_grid.rb"
+      end
+    end
+  end
+end

data/lib/generators/the_grid/install/templates/the_grid.rb

@@ -0,0 +1,10 @@
+TheGrid.configure do |config|
+  # Specifies scopes for custom commands
+  # config.commands_lookup_scopes += %w{ command_scope_1 command_scope_2 }
+
+  # Default number of items per page for pagination
+  config.default_max_per_page = 25
+
+  # Print json response with new lines and tabs
+  config.prettify_json = ActionView::Base.pretty_print_json
+end

data/lib/the_grid/api/command/batch_remove.rb

@@ -0,0 +1,14 @@
+module TheGrid
+  class Api::Command::BatchRemove < Api::Command
+    def configure(relation, params)
+      {}.tap do |o|
+        o[:item_ids] = params.fetch(:item_ids, []).reject{ |id| id.to_i <= 0 }
+        raise ArgumentError, "There is nothing to remove" if o[:item_ids].blank?
+      end
+    end
+
+    def run_on(relation, params)
+      relation.where(relation.scoped.table.primary_key.in(params[:item_ids])).destroy_all
+    end
+  end
+end

data/lib/the_grid/api/command/batch_update.rb

@@ -0,0 +1,21 @@
+module TheGrid
+  class Api::Command::BatchUpdate < Api::Command
+    def configure(relation, params)
+      {}.tap do |o|
+        o[:items] = params.fetch(:items, []).reject{ |item| item['id'].to_i <= 0 }
+        raise ArgumentError, "There is nothing to update" if o[:items].blank?
+      end
+    end
+
+    def run_on(relation, params)
+      record_ids = params[:items].map{ |row| row['id'] }
+      primary_key = relation.scoped.table.primary_key
+      records = relation.where(primary_key.in(record_ids)).index_by(&primary_key.name.to_sym)
+
+      params[:items].map do |row|
+        record = records[row['id'].to_i]
+        record.tap{ |r| r.update_attributes(row.except('id')) } unless record.nil?
+      end.compact
+    end
+  end
+end

data/lib/the_grid/api/command/filter.rb

@@ -0,0 +1,43 @@
+module TheGrid
+  class Api::Command::Filter < Api::Command
+    def configure(relation, params)
+      params.fetch(:filters, {}).dup
+    end
+
+    def run_on(relation, filters)
+      conditions = build_conditions_for(relation, filters)
+      relation = relation.where(conditions) unless conditions.blank?
+      relation
+    end
+
+  private
+
+    def build_conditions_for(relation, filters)
+      conditions = filters.map do |name, filter|
+        if filter.kind_of?(Array)
+          relation.table[name].in(filter)
+        elsif filter.kind_of?(Hash)
+          expr = []
+          expr << relation.table[name].gteq(prepare_value filter, :from) if filter.has_key?(:from)
+          expr << relation.table[name].lteq(prepare_value filter, :to)   if filter.has_key?(:to)
+          expr.inject(:and)
+        else
+          relation.table[name].eq(filter)
+        end
+      end
+      conditions.compact.inject(:and)
+    end
+
+    def prepare_value(filter, name)
+      case filter[:type].to_s
+      when 'time'
+        Time.at(Float filter[name])
+      when 'date'
+        filter[name].to_time
+      else
+        filter[name]
+      end
+    end
+
+  end
+end

data/lib/the_grid/api/command/paginate.rb

@@ -0,0 +1,29 @@
+module TheGrid
+  class Api::Command::Paginate < Api::Command
+    cattr_accessor(:default_per_page){ 10 }
+
+    def configure(relation, params)
+      {}.tap do |o|
+        o[:page] = params[:page].to_i
+        o[:page] = 1 if o[:page] <= 0
+
+        o[:per_page] = params[:per_page].to_i
+        o[:per_page] = self.class.default_per_page if o[:per_page] <= 0
+      end
+    end
+
+    def run_on(relation, params)
+      relation.offset((params[:page] - 1) * params[:per_page]).limit(params[:per_page])
+    end
+
+    def calculate_max_page_for(relation, params)
+      params = configure(relation, params)
+      (relation.except(:limit, :offset).count / params[:per_page].to_f).ceil
+    end
+
+    def contextualize(relation, params)
+      {:max_page => calculate_max_page_for(relation, params)}
+    end
+
+  end
+end

data/lib/the_grid/api/command/search.rb

@@ -0,0 +1,86 @@
+module TheGrid
+  class Api::Command::Search < Api::Command
+    def configure(relation, params)
+      {}.tap do |o|
+        o[:query] = params.fetch(:query, '').strip
+        o[:searchable_columns] = params[:searchable_columns]
+        o[:search_over] = params[:search_over]
+        o[:search_over] = Hash[o[:search_over].zip] if o[:search_over].kind_of?(Array)
+      end
+    end
+
+    def run_on(relation, params)
+      if params[:query].blank?
+        relation
+      elsif params[:search_over].present?
+        search_over(relation, params)
+      else
+        relation.where build_conditions_for(relation, params)
+      end
+    end
+
+  private
+
+    def searchable_columns_of(relation)
+      relation.column_names.select do |column_name|
+        relation.columns_hash[column_name].type == :string
+      end
+    end
+
+    def build_conditions_for(relation, params)
+      query = "%#{params[:query]}%"
+      (params[:searchable_columns] || searchable_columns_of(relation)).map do |column|
+        relation.table[column].matches(query)
+      end.inject(:or)
+    end
+
+    def build_conditions_for_associations_of(relation, params)
+      params[:search_over].each_with_object({}) do |options, conditions|
+        assoc_name, assoc_fields = options
+        assoc = relation.reflections[assoc_name.to_sym]
+        assoc_condition = build_conditions_for(assoc.klass.scoped, params.merge(:searchable_columns => assoc_fields))
+        conditions[assoc] = assoc_condition unless assoc_condition.blank?
+      end
+    end
+
+    def search_over(relation, params)
+      search_relation = relation.where(build_conditions_for(relation, params))
+      assoc_conditions = build_conditions_for_associations_of(relation, params.except(:searchable_columns))
+      matched_row_ids = row_ids_matched_for(search_relation, assoc_conditions)
+
+      conditions = assoc_conditions.values
+      conditions << relation.table.primary_key.in(matched_row_ids) unless matched_row_ids.blank?
+      relation.where(conditions.inject(:or))
+    end
+
+    def row_ids_matched_for(relation, conditions)
+      conditions.flat_map do |assoc, condition|
+        query = join_relations_with(condition, relation, assoc).to_sql
+        relation.connection.select_all(query).map(&:values)
+      end.uniq
+    end
+
+    def join_relations_with(condition, relation, assoc)
+      primary_key, foreign_key = relationship_between(relation, assoc)
+
+      relation.select(relation.table.primary_key).
+        where(assoc.klass.arel_table.primary_key.eq(nil)).
+        joins("LEFT OUTER JOIN #{assoc.table_name} ON #{primary_key.eq(foreign_key).and(condition).to_sql}")
+    end
+
+    def relationship_between(relation, assoc)
+      case assoc.macro
+      when :belongs_to, :has_one
+        primary_key = assoc.klass.arel_table.primary_key
+        foreign_key = relation.table[assoc.foreign_key]
+      when :has_many
+        primary_key = relation.table.primary_key
+        foreign_key = assoc.klass.arel_table[assoc.foreign_key]
+      else
+        raise ArgumentError, "Unable to search over #{assoc.macro}"
+      end
+      [ primary_key, foreign_key ]
+    end
+
+  end
+end

data/lib/the_grid/api/command/sort.rb

@@ -0,0 +1,17 @@
+module TheGrid
+  class Api::Command::Sort < Api::Command
+    def configure(relation, params)
+      {}.tap do |o|
+        o[:field] = params[:field]
+        o[:field] = "#{relation.table_name}.#{o[:field]}" if relation.table[o[:field]].present?
+
+        o[:order] = params[:order]
+        o[:order] = 'asc' unless %w{ asc desc }.include?(o[:order])
+      end
+    end
+
+    def run_on(relation, params)
+      relation.order("#{params[:field]} #{params[:order]}")
+    end
+  end
+end