README.md in reports_kit-0.0.2 vs README.md in reports_kit-0.0.3

- old
+ new

@@ -1,32 +1,43 @@ ReportsKit ===== -Beautiful, interactive charts for Ruby on Rails +ReportsKit lets you easily create beautiful charts with customizable, interactive filters. -Table of Contents ------------------ +Add powerful reporting to your Rails app in minutes, not months! -* [Overview](#overview) -* [Installation](#installation) -* [Usage](#usage) - * [Your First Chart](#your-first-chart) - * [Measures](#measures) - * [Dimensions](#dimensions) - * [Filters](#filters) - * [Display Options](#display-options) -* [License](#license) +For interactive examples, see [reportskit.co](https://www.reportskit.co/). -Overview --------- -ReportsKit lets you easily create beautiful charts with customizable, interactive filters. +--- -For interactive examples, see [reportskit.co](https://www.reportskit.co). +[<img src="docs/images/demo.gif?raw=true" width="500" />](docs/images/demo.gif?raw=true) -[<img src="docs/images/flights_with_filters.png?raw=true" width="500" />](docs/images/flights_with_filters.png?raw=true) +[<img src="docs/images/demo_area.png?raw=true" width="500" />](docs/images/demo_area.png?raw=true) -ReportsKit integrates with ActiveRecord, abstracting away complex aggregation logic to make it easy to create powerful charts and filters. +[<img src="docs/images/demo_dashed_line.png?raw=true" width="500" />](docs/images/demo_dashed_line.png?raw=true) +[<img src="docs/images/demo_horizontal_stacked.png?raw=true" width="500" />](docs/images/demo_horizontal_stacked.png?raw=true) + +[<img src="docs/images/demo_legend.png?raw=true" width="500" />](docs/images/demo_legend.png?raw=true) + +[<img src="docs/images/demo_multiautocomplete.png?raw=true" width="500" />](docs/images/demo_multiautocomplete.png?raw=true) + +[<img src="docs/images/demo_radar.png?raw=true" width="250" />](docs/images/demo_radar.png?raw=true) + +--- + +1. **Quick setup** - Install ReportsKit and create your first chart in less than one minute using just ~5 lines of code. +1. **Simple chart configuration** - Create charts using your existing Rails models. ReportsKit examines the column types and associations to understand how to render the chart. +1. **Powerful results** - To see what ReportsKit can create with minimal code, see [reportskit.co](https://www.reportskit.co/). + +Resources +--------- + +* [Installation](#installation) +* [Quick Start](#quick-start) +* [Examples](https://www.reportskit.co/) +* [Documentation](documentation) + Installation ------------ In `Gemfile`: ```ruby @@ -49,24 +60,27 @@ mount ReportsKit::Engine, at: '/' # ... end ``` -Usage ------ -### Your First Chart +Quick Start +----------- -In any view, render a chart that shows the number of records of a model (e.g. `user`) created over time: +After installation, you can create your first chart with a single line! +In any view, create a chart that shows the number of records of a model (e.g. `user`) created over time: + `app/views/users/index.html.haml` ```haml = render_report measure: 'user', dimensions: ['created_at'] ``` +You're done! `render_report` will render the following chart: + [<img src="docs/images/users_by_created_at.png?raw=true" width="500" />](docs/images/users_by_created_at.png?raw=true) -You can also configure your charts using YAML and then pass the filename to `render_report`: +Instead of passing a hash to `render_report`, you can alternatively configure your charts using YAML and then pass the filename to `render_report`: `config/reports_kit/reports/my_users.yml` ```yaml measure: user dimensions: @@ -76,392 +90,33 @@ `app/views/users/index.html.haml` ```haml = render_report 'my_users' ``` -### Measures +The YAML approach is more maintainable and readable, so we'll use it in the rest of the documentation. -The measure is what is being counted (or aggregated). You can use any model for the measure. +### Form Controls -For example, say we have a `Flight` model with a `flight_at` datetime column. We can chart the number of flights over time: +You can add a date range form control to the above chart with a single line, using one of ReportsKit's form helpers: -```yaml -measure: flight -dimensions: -- flight_at -``` -[<img src="docs/images/flights_by_flight_at.png?raw=true" width="500" />](docs/images/flights_by_flight_at.png?raw=true) - -### Dimensions - -#### Overview - -The dimension is what the measure is being grouped by. You can use datetime columns, integer columns, string columns, associations, or even define custom dimensions. - -For example, the chart below groups by a `carrier` association on `Flight` - -```yaml -measure: flight -dimensions: -- carrier -``` -[<img src="docs/images/flights_by_carrier.png?raw=true" width="500" />](docs/images/flights_by_carrier.png?raw=true) - -You can also use two dimensions: - -```yaml -measure: flight -dimensions: -- carrier -- flight_at -``` -[<img src="docs/images/flights_by_carrier_and_flight_at.png?raw=true" width="500" />](docs/images/flights_by_carrier_and_flight_at.png?raw=true) - -Dimensions can be configured using a string: - -```yaml -measure: flight -dimensions: -- carrier -``` - -Or, if you need to use options, you can configure them using a hash: - -```yaml -measure: flight -dimensions: -- key: carrier - limit: 5 -``` -#### Types - -##### Association - -```yaml -measure: flight -dimensions: -- carrier -``` -[<img src="docs/images/flights_by_carrier.png?raw=true" width="500" />](docs/images/flights_by_carrier.png?raw=true) - -##### Datetime Column - -```yaml -measure: flight -dimensions: -- flight_at -``` -[<img src="docs/images/flights_by_flight_at.png?raw=true" width="500" />](docs/images/flights_by_flight_at.png?raw=true) - -##### Integer Column - -```yaml -measure: flight -dimensions: -- delay -``` -[<img src="docs/images/flights_by_delay.png?raw=true" width="500" />](docs/images/flights_by_delay.png?raw=true) - -##### Custom - -You can define custom dimensions in your model. For example, if `Flight` has a column named `delay` (in minutes), we can define a `hours_delayed` dimension: - -```ruby -class Flight < ApplicationRecord - include ReportsKit::Model - - reports_kit do - dimension :hours_delayed, group: 'GREATEST(ROUND(flights.delay::float/60), 0)' - end -end -``` - -We can then use the `hours_delayed` dimension: - -```yaml -measure: flight -dimensions: -- hours_delayed -``` -[<img src="docs/images/flights_by_hours_delayed.png?raw=true" width="500" />](docs/images/flights_by_hours_delayed.png?raw=true) - -#### Options - -##### `key` *String* - -The dimension's identifier. You can use association names (e.g. `author`), column names (e.g. `created_at`), or the keys of custom dimensions (e.g. `my_dimension`). - -##### `limit` *Integer* - -The maximum number of dimension instances to include. - -### Filters - -#### Overview - -A filter is like a `where`: it filters the results to only include results that match a condition. You can use datetime columns, integer columns, string columns, associations, or even define custom filters. - -For example, if the `Flight` model has a `delay` column that's an integer, the chart below will show only flights that have a delay of greater than 15 minutes: - -```yaml -measure: - key: flight - filters: - - key: delay - criteria: - operator: '>' - value: 15 -dimensions: -- carrier -``` -[<img src="docs/images/flights_with_configured_number.png?raw=true" width="500" />](docs/images/flights_with_configured_number.png?raw=true) - -You can also create form controls that the user can use to filter the chart: - -```yaml -measure: - key: flight - filters: - - carrier - - carrier_name - - is_on_time - - flight_at -dimensions: -- flight_at -- carrier -``` - -In `app/views/my_view.html.haml`: +`app/views/users/index.html.haml` ```haml -= render_report 'filters' do - .pull-right - = f.date_range :flight_at - = f.multi_autocomplete :carrier, scope: 'top', placeholder: 'Carrier...' - = f.string_filter :carrier_name, placeholder: 'Carrier name (e.g. Airlines)...', style: 'width: 175px;' - .checkbox - = label_tag :is_on_time do - = f.check_box :is_on_time - On time += render_report 'my_users' do |f| + = f.date_range :created_at ``` -[<img src="docs/images/flights_with_filters.png?raw=true" width="500" />](docs/images/flights_with_filters.png?raw=true) -#### Types +[<img src="docs/images/users_by_created_at_with_filter.png?raw=true" width="500" />](docs/images/users_by_created_at_with_filter.png?raw=true) -##### Boolean +Many other form controls are available; see [Filters](docs/filters.md) for more. -```yaml -measure: - key: flight - filters: - - key: is_on_time - criteria: - operator: true - value: 15 -dimensions: -- carrier -``` -[<img src="docs/images/flights_with_configured_boolean.png?raw=true" width="500" />](docs/images/flights_with_configured_boolean.png?raw=true) +### How It Works -##### Datetime +In the Quick Start chart, `measure: 'user'` tells ReportsKit to count the number of `User` records, and `dimensions: ['created_at']` tells it to group by the week of the `created_at` column. Since `created_at` is a `datetime` column, ReportsKit knows that it should sort the results chronologically. -```yaml -measure: - key: flight - filters: - - key: flight_at - criteria: - operator: between - value: Oct 1, 2016 - Jan 1, 2017 -dimensions: -- carrier -``` -[<img src="docs/images/flights_with_configured_datetime.png?raw=true" width="500" />](docs/images/flights_with_configured_datetime.png?raw=true) +To learn how to use more of ReportsKit's features, check out the following resources: -##### Number - -```yaml -measure: - key: flight - filters: - - key: delay - criteria: - operator: '>' - value: 15 -dimensions: -- carrier -``` -[<img src="docs/images/flights_with_configured_number.png?raw=true" width="500" />](docs/images/flights_with_configured_number.png?raw=true) - -##### String - -```yaml -measure: - key: flight - filters: - - key: carrier_name - criteria: - operator: contains - value: airlines -dimensions: -- carrier -``` -[<img src="docs/images/flights_with_configured_string.png?raw=true" width="500" />](docs/images/flights_with_configured_string.png?raw=true) - - -#### Form Controls - -##### Check Box - -```yaml -measure: - key: flight - filters: - - is_on_time -dimensions: -- flight_at -- carrier -``` -```haml -= render_report 'filter_check_box' do - .checkbox - = label_tag :is_on_time do - = f.check_box :is_on_time - On time -``` -[<img src="docs/images/flights_with_check_box.png?raw=true" width="500" />](docs/images/flights_with_check_box.png?raw=true) - -##### Date Range - -```yaml -measure: - key: flight - filters: - - flight_at -dimensions: -- flight_at -- carrier -``` -```haml -= render_report 'filter_date_range' do - = f.date_range :flight_at -``` -[<img src="docs/images/flights_with_date_range.png?raw=true" width="500" />](docs/images/flights_with_date_range.png?raw=true) - -##### Multi-Autocomplete - -```yaml -measure: - key: flight - filters: - - carrier -dimensions: -- flight_at -- carrier -``` -```haml -= render_report 'filter_multi_autocomplete' do - = f.multi_autocomplete :carrier, scope: 'top', placeholder: 'Carrier...' -``` -[<img src="docs/images/flights_with_multi_autocomplete.png?raw=true" width="500" />](docs/images/flights_with_multi_autocomplete.png?raw=true) - -##### String Filter - -```yaml -measure: - key: flight - filters: - - carrier_name -dimensions: -- flight_at -- carrier -``` -```haml -= render_report 'filter_string' do - = f.string_filter :carrier_name, placeholder: 'Carrier name (e.g. Airlines)...', style: 'width: 175px;' -``` -[<img src="docs/images/flights_with_string_filter.png?raw=true" width="500" />](docs/images/flights_with_string_filter.png?raw=true) - -### Display Options - -#### Overview - -Charts are rendered using [Chart.js](http://www.chartjs.org/). You can configure your ReportsKit chart using any [Chart.js options](http://www.chartjs.org/docs/). - -##### `type` - -You can use any `type` value supported by Chart.js, including `bar`, `line`, `horizontalBar`, `radar`, and more. - -Here's an example of a horizontal bar chart: - -```yaml -measure: flight -dimensions: -- carrier -chart: - type: horizontalBar - options: - scales: - xAxes: - - scaleLabel: - display: true - labelString: Flights - yAxes: - - scaleLabel: - display: true - labelString: Carrier -``` -[<img src="docs/images/horizontal_bar.png?raw=true" width="500" />](docs/images/horizontal_bar.png?raw=true) - -##### `options` - -You can use any `options` that are supported by Chart.js. - -Here's an example of a chart with Chart.js options: - -```yaml -measure: flight -dimensions: -- origin_market -- carrier -chart: - type: horizontalBar - options: - scales: - xAxes: - - stacked: true - scaleLabel: - display: true - labelString: Flights - yAxes: - - stacked: true - scaleLabel: - display: true - labelString: Market -``` -[<img src="docs/images/chart_options.png?raw=true" width="500" />](docs/images/chart_options.png?raw=true) - -##### `datasets` - -You can use any `datasets` options that are supported by Chart.js. - -Here's an example of a chart with `datasets` options: - -```yaml -measure: flight -dimensions: -- flight_at -- key: carrier - limit: 3 -chart: - type: line - datasets: - fill: false - borderDash: - - 5 - - 5 -``` -[<img src="docs/images/dashed_line.png?raw=true" width="500" />](docs/images/dashed_line.png?raw=true) - +* [Examples](https://www.reportskit.co/) +* [Documentation](documentation) License ------- ReportsKit is released under the MIT License. Please see the MIT-LICENSE file for details.