# ih-black-lion

The core of your `Ih` project, `BlackLion` is the link between the front and backend of your project. It uses `redux` to store data and trigger changes within your app.

Redux uses a combination of `Reducers` and `Actions` to handle changes to state within an app.

## Usage

You can use the default export of this module the same way you would use any redux store.

```js
import BlackLion from 'ih-black-lion';
import { Provider } from 'react-redux';

React.render((
  <Provider store={BlackLion}>...</Provider>
), document.body);
```

From within a 'smart' component, you can dispatch actions. Actions generally follow this formula: `someAction(Connector, requestParams, ...<other action specific parameters>)`

`Connector` - it is strongly suggested that you use `ih-ps-connector`, or a fork of it, for this. It handles al communication with the database and does any modeling needed to format the response object.

`requestParams` - an object containing a `url` property that defines the endpoint url of the request, and other properties that might be necessary such as authorization and request headers.

## Caching with black-lion

This module also provides a way to cache your stores state in another location by using the [`redux-persist` library](https://github.com/rt2zz/redux-persist).

The following is an example of how to set up `black-lion` to cache its state.

```js
import { initBlackLionCaching } from 'ih-black-lion';
import { Provider } from 'react-redux';

initBlackLionCaching(
  (blackLion, blackLionPersistor) => {
    React.render((
      <Provider store={blackLion}>...</Provider>
    ), document.body);
  },
  {
    skipRestore: true,
  }
);
```

### `initBlackLionCaching(cb, [config, finalCreateStore])`

The `cb` takes two parameters: a created redux store using `finalCreateStore` or `ih-black-lion`'s default `createStore`, and a `persistor` object created by `redux-persist`'s `persistStore` function. If you want black-lion to rehydrate its state from the cache before your initial render then call `React.render` from within the callback. Otherwise your app will render and then attempt to rehydrate the state after the fact.

`config` is the same as the config object that you would pass to the `persistStore` function.

`finalCreateStore` allows you to pass in a custom `createStore` function if you don't want to use `ih-black-lion`'s default middleware.

## Reducers

Reducers handle the actual modification of the state given a specified action.

[Reducer Documentation](./lib/reducers/ReducerDocs.md)

## Actions

Actions tell the Reducer what is going on so that it can modify the state appropriately.

[Action Documentation](./lib/actions/ActionDocs.md)

### Further Reading

If you wish to learn more about Redux please help yourself to [their  documentation](http://rackt.github.io/redux/index.html)

### Adding Services

1. create actions in `./lib/actions/<ServiceName>Actions.js`

2. create a reducer in `./lib/reducers/<ServiceName>Reducer.js`

3. add `<serviceName>State` field to the `reducer` object in `./index.js` with a value of the imported `<ServiceName>Reducer.js` file

4. add `<ServiceName>Actions` field to the `actions` object in `./index.js` with a value of the imported `<ServiceName>Actions.js` file

5. add mock response data to the `./test/lib/mocks.js` file and export them

6. add a mock service call to the `./test/lib/Connector.js` file that returns the mock data you just created

7. create tests
  - there's a template for tests located at `./test/lib/test.template.js`
  - copy and paste the template into a new file in the `test` directory and name it `test<ServiceName>.js`
  - refactor the template to match your service

8. make sure all tests are still passing by running `npm test`

9. add your name and email to the `contributors` field in `package.json`

10. run `npm version prerelease`

11. submit a pull-request to the `master` branch

------------
### See Also

* [redux](http://rackt.github.io/redux/index.html)
* [redux-persist](https://github.com/rt2zz/redux-persist)
* [ih-ps-connector](https://www.npmjs.com/package/ih-ps-connector)