# Discerner

Discerner is an engine for Rails that provides basic search UI, search reqults export UI and allows to configure available search parameters/values. Discerner is not aimed to be a SQL-generator, but it allows the host application to access stored search conditions and provide search results.

Reader's note: this README uses [YARD][] markup to provide links to
Discerner's API documentation. If you aren't already, consider reading it
on [rubydoc.info][] so that the links will be followable.

[YARD]: http://yardoc.org/
[rubydoc.info]: http://rubydoc.info/github/NUBIC/discerner/master/file/README.md

# Requirements

This code has been run and tested on Ruby 1.9. and Ruby 2.1

# Dependencies

* haml
* sass
* jquery-rails
* jquery-ui-rails

# Installation

## Install gem with Bundler

```ruby
gem 'discerner'
bundle install
```
## Run the installer

```ruby
rails generate discerner:install
```

By default, Discerner installer performs following tasks:

* it copies Discerner's migrations into db/migrate and runs migrations
* it sets up default Discerner operators. As of now, default operators cannot be changed.
* it prompts for current_user helper name and inserts `discerner_user` method into the application controller. This allows Discerner to attibure created searches to the current user.
* it adds discerner helpers used for configuring dicerner functionality into application helper. This will be changed in the future.
  * show_discerner_results? - helper used to determine if search results should be displayed.
  * export_discerner_results? - helper used to determine if search results should be exportable.
  * enable_combined_searches? - helper used to determine if search interface should allow to combine searches
* it mounts Discerner::Engine
* it copies sample search dictionary into lib/setup

Discerner installer accepts following parameters:

* --no-migrate - prevent installer from running migrations. If this flag is set, Discerner operators would have to be loaded manually using **rake discerner:setup:operators**
* --current-user-helper   - allows to specify current user method name
* --customize-controllers - copy Discerner controllers into application, so they can be customized
* --customize-models      - copy Discerner models into application, so they can be customized
* --customize-helpers     - copy Discerner helpers into application, so they can be customized
* --customize-layout      - copy Discerner layout into application, so it can be customized
* --customize-all         - copy Discerner controllers, models, helpers, and layout into application, so they can be customized


# Usage
## Setting up dictionaries

```ruby
rails generate discerner:dictionary [FILENAME]
```
Discerner uses dictionaries to define parameters and values that can be used for constructing searches. Discerner dictionary generator performs following tasks:

* it parses provided file and sets up or updates corresponding search dictionary, its parameter categories, parameters and parameter values
* it creates a model for each specified dictionary that is expected to implement "search" and "export" methods.
* it generates template views for search results and export.

Discerner dictionary generator accepts following parameters:

* --no-load   - skip dictionary generation/update
* --no-models - skip models generation
* --no-views  - skip views generation

Installer adds a sample dictionary than can be used as a template anr/or can be parsed and used to explore Discerner Search UI:

```ruby
rails generate discerner:dictionary lib/setup/dictionaries.yml
```

## Updating dictionaries

In most cases, dictionary generator needs to be run only once per dictionary. Dictionary updates, excluding name change, should be handled by re-parcing definition file with Discerner parser:

```ruby
rails discerner:setup:dictionaries FILE=xxx
```

Discerner parser processes YML definition file line by line, detecting and creating/updating dictionaries, parameter categories, parameters and parameter values. It runs in silent mode by default, --trace option can be used to make it verbose.

## User Interface

Index of all saved searches scoped by current user (if available) can be accessed from '/searches' route.