ih-black-lion
Version:
State handler for Arus projects
105 lines (64 loc) • 4.14 kB
Markdown
# 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)