README.md in pivot_table-0.3.0 vs README.md in pivot_table-0.4.0
- old
+ new
@@ -1,6 +1,6 @@
-# Pivot Table [](http://travis-ci.org/edjames/pivot_table) [](https://codeclimate.com/github/edjames/pivot_table) [](https://gemnasium.com/edjames/pivot_table) [](http://badge.fury.io/rb/pivot_table)
+# Pivot Table [](http://travis-ci.org/edjames/pivot_table) [](https://codeclimate.com/github/edjames/pivot_table) [](https://gemnasium.com/edjames/pivot_table) [](http://badge.fury.io/rb/pivot_table) [](https://www.omniref.com/ruby/gems/pivot_table)
A handy tool for transforming a dataset into a spreadsheet-style pivot table.
### Why make this?
@@ -41,11 +41,10 @@
g.column_name = :quarter
g.row_name = :city
g.value_name = :sales
end
-
The `value_name` parameter is only required if you want to access totals;
the others are required.
All you have to do now is build the grid...
@@ -93,12 +92,10 @@
g.columns[3].row_data('London') => obj_4
The API should give you a lot of flexibility with regards to rendering this information in your views.
E.g. The rows and columns collections make it very easy to produce horizontal, vertical and overall total values.
-Ah, that's better.
-
If you want to get the totals for rows, columns, or the entire grid, you can pass a `value_name` as shown above, and then query the Grid like this:
g.column_totals
g.columns[0].total
g.columns[1].total
@@ -106,19 +103,61 @@
g.row_totals
g.rows[0].total
g.rows[1].total
g.grand_total
+##### Specifying the pivot field
+
+You can also specify the field name which should be used as the pivot. Typically you would use this when you want to pivot on a string field which cannot be aggregated.
+
+This option will generate a simplified grid which will contain the specified field value instead of the objects.
+
+Consider the following data (similar to above):
+
+ obj_1 = Order.new(city: 'London', quarter: 'Q1', top_sales: 'Ed')
+ obj_2 = Order.new(city: 'London', quarter: 'Q2', top_sales: 'Jim')
+ obj_3 = Order.new(city: 'London', quarter: 'Q3', top_sales: 'Sam')
+ obj_4 = Order.new(city: 'London', quarter: 'Q4', top_sales: 'Ed')
+ obj_5 = Order.new(city: 'New York', quarter: 'Q1', top_sales: 'Tom')
+ obj_6 = Order.new(city: 'New York', quarter: 'Q2', top_sales: 'Sandy')
+ obj_7 = Order.new(city: 'New York', quarter: 'Q3', top_sales: 'Phil')
+ obj_8 = Order.new(city: 'New York', quarter: 'Q4', top_sales: 'Jim')
+
+Instantiate a new PivotTable::Grid object, this time specifying the `field_name`:
+
+ g = PivotTable::Grid.new do |g|
+ g.source_data = data
+ g.column_name = :quarter
+ g.row_name = :city
+ g.value_name = :sales
+ g.field_name = :top_sales
+ end
+
+Build the grid...
+
+ g.build
+
+This will give you a logical grid (represented by an two-dimensional array) which can be likened to this table:
+
+ --------------------------------------------
+ | | Q1 | Q2 | Q3 | Q4 |
+ |----------|--------------------------------
+ | London | Ed | Jim | Sam | Ed |
+ | New York | Tom | Sandy | Phil | Jim |
+ --------------------------------------------
+
+Compare this to the first example above. It's simpler, if that's what you need.
+
+
#### Configuration Options
You can also provide additional configuration options when instantiating your Grid. Options are provided as a hash e.g.
g = PivotTable::Grid.new(:sort => true) do |g|
g.source_data = data
g.column_name = :quarter
g.row_name = :city
- g.value_name = :sales
end
Here are the available configuration options:
###### 1. Sort
@@ -126,10 +165,9 @@
**Usage:** `sort: false`
**Default:** `true`
This option will automatically sort your data alphabetically based on your column and row headers. If you disable sorting your original data ordering will be preserved.
-
### Ruby Support
* 1.9.3
* 2.x