Merge pull request jbox-web#6 from JoelQ/generators

Joel Quenneville · Joel Quenneville · commit 9835efab30ce · 2012-04-30T12:52:56.000-07:00
Generators
diff --git a/.rspec b/.rspec
@@ -0,0 +1 @@
+--color
diff --git a/README.md b/README.md
@@ -6,21 +6,132 @@ Datatables is a nifty jquery plugin that adds the ability to paginate, sort, and
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add these lines to your application's Gemfile:
 
+    gem 'jquery-datatables-rails'
     gem 'ajax-datatables-rails'
 
 And then execute:
 
     $ bundle
 
-Or install it yourself as:
+## Usage
+*The following examples assume that we are setting up ajax-datatables-rails for an index of users from a `User` model*
+### Model
+Run the following command:
 
-    $ gem install ajax-datatables-rails
+    $ rails generate ajaxdatatable User
 
-## Usage
+This will generate a file named `users_datatable.rb` in `app/datatables`. Open the file and customize in the functions as directed by the comments
+
+#### Initializer
+```ruby
+def initialize(view)
+  @model_name = User
+  @columns = # insert array of column names here
+  @searchable_columns = #insert array of columns that will be searched
+  super(view)
+end
+```
+
+* For `@columns`, assign an array of the database columns that correspond to the columns in our view table. For example `[users.f_name, users.l_name, users.bio]`. This array is used for sorting by various columns
+
+* For `@searchable_columns`, assign an array of the database columns that you want searchable by datatables. For example `[users.f_name, users.l_name]`
+
+This gives us: 
+```ruby
+def initialize(view)
+  @model_name = User
+  @columns = [users.f_name, users.l_name, users.bio]
+  @searchable_columns = [users.f_name, users.l_name]
+  super(view)
+end
+```
+
+#### Data
+```ruby
+def data
+  users.map do |user|
+    [
+      # comma separated list of the values for each cell of a table row
+    ]
+  end
+end
+```
+
+This method builds a 2d array that is used by datatables to construct the html table. Insert the values you want on each column.
+
+```ruby
+def data
+  users.map do |user|
+    [
+      user.f_name,
+      user.l_name,
+      user.bio
+    ]
+  end
+end
+```
+
+#### Get Raw Records
+```ruby
+def get_raw_records
+  # insert query here
+end
+```
+
+This is where your query goes.
+
+```ruby
+def get_raw_records
+  User.all
+end
+```
+
+### Controller
+Set up the controller to respond to JSON
+
+```ruby
+def index
+  respond_to do |format|
+    format.html
+    format.json { render json: UsersDatatable.new(view_context) }
+  end
+end
+```
+
+### View
+* Set up an html `<table>` with a `<thead>` and `<tbody>`
+* Add in your table headers if desired
+* Don't add any rows to the body of the table, datatables does this automatically
+* Add a data attribute to the `<table>` tag with the url of the JSON feed
+
+The resulting view may look like this:
+
+```erb
+<table id="user-table", data-source="<%= users_path(format: :json) %>">
+  <thead>
+    <tr>
+      <th>First Name</th>
+      <th>Last Name</th>
+      <th>Brief Bio</th>
+    </tr>
+  </thead>
+  <tbody>
+  </tbody>
+</table>
+```
+
+### Javascript
+Finally, the javascript to tie this all together. In the appropriate `js.coffee` file:
 
-TODO: Write usage instructions here
+```coffeescript
+$ ->
+  $('#users-table').dataTable
+    bProcessing: true
+    bServerSide: true
+    sAjaxSource: $('#users-table').data('source')
+```
 
 ## Contributing
 
diff --git a/Rakefile b/Rakefile
@@ -1,2 +1,6 @@
 #!/usr/bin/env rake
 require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+task default: :spec
diff --git a/ajax-datatables-rails.gemspec b/ajax-datatables-rails.gemspec
@@ -14,4 +14,6 @@ Gem::Specification.new do |gem|
   gem.name          = "ajax-datatables-rails"
   gem.require_paths = ["lib"]
   gem.version       = AjaxDatatablesRails::VERSION
+  
+  gem.add_development_dependency "rspec"
 end
diff --git a/spec/ajax-datatables-rails/ajax_datatables_rails_spec.rb b/spec/ajax-datatables-rails/ajax_datatables_rails_spec.rb
@@ -0,0 +1,7 @@
+require 'spec_helper'
+
+describe AjaxDatatablesRails do
+  describe "as_json" do
+    it "should return the correct json feed"
+  end
+end
diff --git a/spec/spec_helper.rb b/spec/spec_helper.rb
@@ -0,0 +1 @@
+require 'ajax-datatables-rails'
