Minor styling edits to README. Updates to CHANGELOG

antillas21 · antillas21 · commit 240e8fb8f270 · 2014-08-31T08:13:26.000-07:00
* Polishes syntax highlighting on contributed README content from [Zoltan Paulovics](https://github.com/zpaulovics). * Updates CHANGELOG to document what is currently unreleased.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,10 @@
 # CHANGELOG
 
+## (yet) Unreleased
+* Fix count method to work with select statements under Rails 4.1. Thanks to [Jason Mitchell](https://github.com/mitchej123) for the contribution.
+* Edits to `README` documentation about the `options` hash. Thanks to [Jonathan E Hogue](https://github.com/hoguej) for pointing out that previous documentation was confusing and didn't address its usage properly.
+* Edits to `README` documentation on complex model queries inside the `get_raw_records` method. A round of applause to [Zoltan Paulovics](https://github.com/zpaulovics) for contributing this awesome piece of documentation. :smile:
+
 ## 0.2.0
 * This version works with jQuery dataTables ver. 1.10 and it's new API syntax.
 * Added `legacy` branch to repo. If your project is working with jQuery
@@ -12,7 +17,7 @@
 
 ## 0.1.1
 * Fixes problem on `searchable_columns` where the corresponding model is
-a composite model name, e.g. `UserData`, `BillingAddress`. 
+a composite model name, e.g. `UserData`, `BillingAddress`.
 Thanks to [iruca3](https://github.com/iruca3) for the fix.
 
 ## 0.1.0
@@ -25,8 +30,8 @@ Thanks to [iruca3](https://github.com/iruca3) for the fix.
 * Removes dependency to pass in a model name to the generator. This way,
   the developer has more flexibility to implement whatever datatable feature is required.
 * Datatable constructor accepts an optional `options` hash to provide
-  more flexibility. 
+  more flexibility.
   See [README](https://github.com/antillas21/ajax-datatables-rails/blob/master/README.mds#options) for examples.
 * Sets generator inside the `Rails` namespace. To generate an
   `AjaxDatatablesRails` child class, just execute the
-  generator like this: `$ rails generate datatable NAME`.
+  generator like this: `$ rails generate datatable NAME`.
diff --git a/README.md b/README.md
@@ -154,7 +154,7 @@ this method, will be chained (for now) to `ActiveRecord` methods for sorting, fi
 #### Associated and nested models
 The previous example has only one single model. But what about if you have some associated nested models and in a report you want to show fields from these tables.
 
-Take an example that has an Event, Course, Coursetype, Allocation, Teacher, Contact, Competency and Competency_type models. We want to have a datatables report which has the following column:
+Take an example that has an `Event, Course, Coursetype, Allocation, Teacher, Contact, Competency and CompetencyType` models. We want to have a datatables report which has the following column:
 ```ruby
         'coursetypes.name',
         'courses.name',
@@ -195,22 +195,34 @@ We want to sort and search on all columns of the list. The related definition wo
   end
 
   def get_raw_records
-     Event.joins([{course: :coursetype}, {allocations: {teacher: [:contact, {competencies: :competency_type}]}} ]).distinct
+     Event.joins(
+      { course: :coursetype },
+      { allocations: {
+          teacher: [:contact, {competencies: :competency_type}]
+        }
+      }).distinct
   end
 ```
 
 __Some comments for the above code:__
 
-1. In the list we show full_name, but in sortable_columns and searchable_columns we use last_name from the Contact model. The reason is we can use only database columns as sort or search fields and the full_name is not a database field.
+1. In the list we show `full_name`, but in `sortable_columns` and `searchable_columns` we use `last_name` from the `Contact` model. The reason is we can use only database columns as sort or search fields and the full_name is not a database field.
 
-2. In the get_raw_records method we have quite a complex query having one to many and may to many associations using the joins ActiveRecord method. The joins will generate INNER JOIN relations in the SQL query. In this case we do not include all event in the report if we have events which is not associated with any model record from the relation.
+2. In the `get_raw_records` method we have quite a complex query having one to many and may to many associations using the joins ActiveRecord method. The joins will generate INNER JOIN relations in the SQL query. In this case we do not include all event in the report if we have events which is not associated with any model record from the relation.
 
-3. To have all event records in the list we should use the .includes method, which generate LEFT OUTER JOIN relation of the SQL query. __IMPORTANT:__ Make sure to append .references(:related_model) with any associated model. That forces the eager loading of all the associated models by one SQL query, and the search condition for any column works fine. Otherwise the :recordsFiltered => filter_records(get_raw_records).count(:all) will generate 2 SQL queries (one for the Event model, and then another for the associated tables). The :recordsFiltered => filter_records(get_raw_records).count(:all) will use only the first one to return from the ActiveRecord::Relation object in get_raw_records and you will get an error message of __Unknown column 'yourtable.yourfield' in 'where clause'__ in case the search field value is not empty.
+3. To have all event records in the list we should use the `.includes` method, which generate LEFT OUTER JOIN relation of the SQL query. __IMPORTANT:__ Make sure to append `.references(:related_model)` with any associated model. That forces the eager loading of all the associated models by one SQL query, and the search condition for any column works fine. Otherwise the `:recordsFiltered => filter_records(get_raw_records).count(:all)` will generate 2 SQL queries (one for the Event model, and then another for the associated tables). The `:recordsFiltered => filter_records(get_raw_records).count(:all)` will use only the first one to return from the ActiveRecord::Relation object in `get_raw_records` and you will get an error message of __Unknown column 'yourtable.yourfield' in 'where clause'__ in case the search field value is not empty.
 
-So the query with includes() method is:
-```
+So the query using the `.includes()` method is:
+
+```ruby
   def get_raw_records
-     Event.includes([{course: :coursetype}, {allocations: {teacher: [:contact, {competencies: :competency_type}]}} ]).references(:course).distinct
+     Event.includes(
+      { course: :coursetype },
+      { allocations: {
+          teacher: [:contact, { competencies: :competency_type }]
+        }
+      }
+      ).references(:course).distinct
   end
 ```
 
