@aibsweb/faceted-search-biccn/readme.md

A generalized faceted search application. Used for BICCN

# Faceted Search #
A generalized faceted search for use across all of the allen institute sites. It has these components:

- data-table
- checkbox-filter
- filter-box-list
- filter-box
- text-search
- data-store-[and associated data stuff]

exports all data-store, data-tables, filter-box, text-search


## Setup ##
1. `git clone http://brandonb@stash.corp.alleninstitute.org/scm/aib/faceted-search.git`
1. `npm i`
2. `npm run start`


## Process ## 

Please use pull requests when adding features or making changes. 
If you need to update data-tables don't forget that it is used without faceted search in several places, so don't go breakin' things.


## Configuration ##
The FacetedSearch application uses a composite config to provide configuration values to each of the components in addition to providing the necessary information to make a query on that components behalf. The next few sections will detail each of the discreet configs within the composite.

    const config = { 

    }

### Component Configs
Each component config within the root config should be defined following this pattern:

    const config = {
        'my-component': {
            componentDefinition: 'my-component',
            componentProp: 'prop-values'
        }
    }

componentDefinition: This is a reference to one of the definitions located in the componentDefinition file. This allows us to create different queryBuilder, dataTransform, and component compositions to support a wide variety of requests and data models.

componentProp: Using this config you can pass component props directly to the component. As an example: 

    const config = {
        'counts': {
            componentDefinition: 'counts',
            position: 'right'
        }
    }

Here we're passing the property/value `position: 'right'` directly to the counts components indicating that it should render its individual counts from right to left.

_gotchas:_ 

* Providing a property named `data` will throw an error.

#### Network
The network section of the config is used to define how and where we make a graphql connections. Currently this contains only one value: `uri`

    const config = {
        'network': {
            uri: 'http://my-graphql-server.org/'
        }
    }

#### Unit Counts
The unit counts section provides values indicating which units to watch and where to position the counts within the widget.
    
    const config = {
        'counts': {
            componentDefinition: 'counts',
            unitsToWatch: ['brains', 'cells'],
            position: 'left'
        },
    }

componentDefinition: see Component Configs.

unitsToWatch: These are the units to request the counts for. I.e. Brains, cells, or whatever (future).

position: this property gets passed directly to the component and determines how the counts are arranged inside the component

#### Data Table
The data table takes in several properties that allow us to shape the table and indicate what it should display.

    const config = {
        'data-table': {
            componentDefinition: 'data-table',
            schema: [
                {
                    column: 'Species',
                    type: 'string',
                    key: 'genusSpecies.name'
                },
                {
                    column: 'Grant',
                    type: 'string',
                    key: 'grant.name'
                }
            ],
        },
    }

All of these properties can be found in the styleguide.

schema: This is a description of which columns to render such as data type, key, and friendly name.
order-by: no longer available here, this has been moved to the state store's config (see below)
data: static data is not supported by the faceted search

#### Filter Box
The Filter Box takes in several properties only one of which is available on the config.

    const config = {
        'filter-box': {
            componentDefinition: 'filter-box',
            showFilterTextSearch: true
        }
    }

showFilterTextSearch: A bool indicating if the user should be able to search the filters using a text box.

#### State Store
The state store allows you to specify a default ordering for query results

    const config = {
        'state-store': {
            order-by: ['genusSpecies', 'grant', 'principalInvestigator', 'modality', 'technique']
        }
    }
    
orderBy: A list of graphql property names to sort by. This will act like SQL where whatever is in spot [0] takes precedence over anything with a higher indice value. Example: using the above `sort-by` mice will always be grouped and humans will always be grouped.