From b99dd6793f6689a95a9ac806c05debc739eff6e5 Mon Sep 17 00:00:00 2001 From: Justin Tulloss Date: Sat, 10 Jun 2017 16:42:38 -0700 Subject: [PATCH] docs(connect): Expand on argument documentation for `firebaseConnect` (#156) ### Description documentation for `firebaseConnect` expanded and now includes another example ### Check List - [x] All tests passing - [x] Docs updated with any changes or examples --- docs/api/compose.md | 397 +++++++++++++++++++++++++++++++++++++++++- docs/api/connect.md | 30 +++- docs/api/constants.md | 15 +- docs/api/helpers.md | 43 +++-- docs/api/reducer.md | 12 +- src/connect.js | 17 +- 6 files changed, 488 insertions(+), 26 deletions(-) diff --git a/docs/api/compose.md b/docs/api/compose.md index 24f882fba..0e9a10384 100644 --- a/docs/api/compose.md +++ b/docs/api/compose.md @@ -1,8 +1,25 @@ -# reactReduxFirebase + + +### Table of Contents + +- [reactReduxFirebase](#reactreduxfirebase) +- [set](#set) +- [auth](#auth) +- [ref](#ref) +- [database](#database) +- [storage](#storage) +- [getFirebase](#getfirebase) + +## reactReduxFirebase Middleware that handles configuration (placed in redux's `compose` call) +**Parameters** + +- `fbConfig` +- `otherConfig` + **Properties** - `fbConfig` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Object containing Firebase config including @@ -80,3 +97,381 @@ const config = { ``` Returns **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** That accepts a component a returns a wrapped version of component + +## + +Sets data to Firebase along with meta data. Currently, +this includes createdAt and createdBy. _Warning_ using this function +may have unintented consequences (setting createdAt even if data already +exists) + +**Parameters** + +- `path` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Path to location on Firebase which to set +- `value` **([Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) \| [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))** Value to write to Firebase +- `onComplete` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** Function to run on complete (`not required`) + +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** Containing reference snapshot + +## set + +Sets data to Firebase. + +**Parameters** + +- `path` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Path to location on Firebase which to set +- `value` **([Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) \| [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))** Value to write to Firebase +- `onComplete` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** Function to run on complete (`not required`) + +**Examples** + +_Basic_ + +```javascript +import React, { Component, PropTypes } from 'react' +import { firebaseConnect } from 'react-redux-firebase' +const Example = ({ firebase: { set } }) => ( + +) +export default firebaseConnect()(Example) +``` + +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** Containing reference snapshot + +## + +Pushes data to Firebase. + +**Parameters** + +- `path` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Path to location on Firebase which to push +- `value` **([Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) \| [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))** Value to push to Firebase +- `onComplete` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** Function to run on complete (`not required`) + +**Examples** + +_Basic_ + +```javascript +import React, { Component, PropTypes } from 'react' +import { firebaseConnect } from 'react-redux-firebase' +const Example = ({ firebase: { push } }) => ( + +) +export default firebaseConnect()(Example) +``` + +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** Containing reference snapshot + +## + +Pushes data to Firebase along with meta data. Currently, +this includes createdAt and createdBy. + +**Parameters** + +- `path` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Path to location on Firebase which to set +- `value` **([Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) \| [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))** Value to write to Firebase +- `onComplete` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** Function to run on complete (`not required`) + +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** Containing reference snapshot + +## + +Updates data on Firebase and sends new data. + +**Parameters** + +- `path` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Path to location on Firebase which to update +- `value` **([Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) \| [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))** Value to update to Firebase +- `onComplete` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** Function to run on complete (`not required`) + +**Examples** + +_Basic_ + +```javascript +import React, { Component, PropTypes } from 'react' +import { firebaseConnect } from 'react-redux-firebase' +const Example = ({ firebase: { update } }) => ( + +) +export default firebaseConnect()(Example) +``` + +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** Containing reference snapshot + +## + +Updates data on Firebase along with meta. _Warning_ +using this function may have unintented consequences (setting +createdAt even if data already exists) + +**Parameters** + +- `path` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Path to location on Firebase which to update +- `value` **([Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) \| [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))** Value to update to Firebase +- `onComplete` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** Function to run on complete (`not required`) + +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** Containing reference snapshot + +## + +Removes data from Firebase at a given path. + +**Parameters** + +- `path` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Path to location on Firebase which to remove +- `onComplete` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** Function to run on complete (`not required`) + +**Examples** + +_Basic_ + +```javascript +import React, { Component, PropTypes } from 'react' +import { firebaseConnect } from 'react-redux-firebase' +const Example = ({ firebase: { remove } }) => ( + +) +export default firebaseConnect()(Example) +``` + +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** Containing reference snapshot + +## + +Sets data to Firebase only if the path does not already +exist, otherwise it rejects. + +**Parameters** + +- `path` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Path to location on Firebase which to set +- `value` **([Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) \| [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))** Value to write to Firebase +- `onComplete` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** Function to run on complete (`not required`) + +**Examples** + +_Basic_ + +```javascript +import React, { Component, PropTypes } from 'react' +import { firebaseConnect } from 'react-redux-firebase' +const Example = ({ firebase: { uniqueSet } }) => ( + +) +export default firebaseConnect()(Example) +``` + +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** Containing reference snapshot + +## + +Upload a file to Firebase Storage with the option to store +its metadata in Firebase Database + +**Parameters** + +- `path` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Path to location on Firebase which to set +- `file` **File** File object to upload (usually first element from + array output of select-file or a drag/drop `onDrop`) +- `dbPath` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Database path to place uploaded file metadata + +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** Containing the File object + +## + +Upload multiple files to Firebase Storage with the option +to store their metadata in Firebase Database + +**Parameters** + +- `path` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Path to location on Firebase which to set +- `files` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** Array of File objects to upload (usually from + a select-file or a drag/drop `onDrop`) +- `dbPath` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Database path to place uploaded files metadata. + +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** Containing an array of File objects + +## + +Delete a file from Firebase Storage with the option to +remove its metadata in Firebase Database + +**Parameters** + +- `path` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Path to location on Firebase which to set +- `dbPath` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Database path to place uploaded file metadata + +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** Containing the File object + +## + +Watch event. **Note:** this method is used internally +so examples have not yet been created, and it may not work as expected. + +**Parameters** + +- `type` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Type of watch event +- `dbPath` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Database path on which to setup watch event +- `storeAs` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Name of listener results within redux store + +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** + +## + +Unset a listener watch event. **Note:** this method is used +internally so examples have not yet been created, and it may not work +as expected. + +**Parameters** + +- `eventName` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Type of watch event +- `eventPath` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Database path on which to setup watch event +- `storeAs` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Name of listener results within redux store + +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** + +## + +Logs user into Firebase. For examples, visit the [auth section](/docs/auth.md) + +**Parameters** + +- `credentials` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Credentials for authenticating + - `credentials.provider` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** External provider (google | facebook | twitter) + - `credentials.type` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Type of external authentication (popup | redirect) (only used with provider) + - `credentials.email` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Credentials for authenticating + - `credentials.password` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Credentials for authenticating (only used with email) + +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** Containing user's auth data + +## + +Logs user out of Firebase and empties firebase state from +redux store + +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** + +## + +Creates a new user in Firebase authentication. If +`userProfile` config option is set, user profiles will be set to this +location. + +**Parameters** + +- `credentials` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Credentials for authenticating + - `credentials.email` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Credentials for authenticating + - `credentials.password` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Credentials for authenticating (only used with email) +- `profile` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Data to include within new user profile + +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** Containing user's auth data + +## + +Sends password reset email + +**Parameters** + +- `credentials` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Credentials for authenticating + - `credentials.email` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Credentials for authenticating + +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** + +## + +Confirm that a user's password has been reset + +**Parameters** + +- `code` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Password reset code to verify +- `password` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** New Password to confirm reset to + +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** + +## + +Verify that a password reset code from a password reset +email is valid + +**Parameters** + +- `code` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Password reset code to verify + +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** Containing user auth info + +## auth + +Firebase auth service instance including all Firebase auth methods + +Returns **Auth** + +## ref + +Firebase ref function + +Returns **database.Reference** + +## database + +Firebase database service instance including all Firebase storage methods + +Returns **Database** Firebase database service + +## storage + +Firebase storage service instance including all Firebase storage methods + +Returns **Storage** Firebase storage service + +## getFirebase + +Expose Firebase instance created internally. Useful for +integrations into external libraries such as redux-thunk and redux-observable. + +**Examples** + +_redux-thunk integration_ + +```javascript +import { applyMiddleware, compose, createStore } from 'redux'; +import thunk from 'redux-thunk'; +import { reactReduxFirebase } from 'react-redux-firebase'; +import makeRootReducer from './reducers'; +import { getFirebase } from 'react-redux-firebase'; + +const fbConfig = {} // your firebase config + +const store = createStore( + makeRootReducer(), + initialState, + compose( + applyMiddleware([ + // Pass getFirebase function as extra argument + thunk.withExtraArgument(getFirebase) + ]), + reactReduxFirebase(fbConfig) + ) +); +// then later +export const addTodo = (newTodo) => + (dispatch, getState, getFirebase) => { + const firebase = getFirebase() + firebase + .push('todos', newTodo) + .then(() => { + dispatch({ type: 'SOME_ACTION' }) + }) +}; +``` diff --git a/docs/api/connect.md b/docs/api/connect.md index d19f7d30d..9b4f424f1 100644 --- a/docs/api/connect.md +++ b/docs/api/connect.md @@ -1,4 +1,10 @@ -# firebaseConnect + + +### Table of Contents + +- [firebaseConnect](#firebaseconnect) + +## firebaseConnect **Extends React.Component** @@ -7,7 +13,8 @@ to provided firebase paths using React's Lifecycle hooks. **Parameters** -- `watchArray` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** Array of objects or strings for paths to sync from Firebase +- `dataOrFn` (optional, default `[]`) +- `watchArray` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** Array of objects or strings for paths to sync from Firebase. Can also be a function that returns the array. The function is passed the current props and the firebase object. **Examples** @@ -38,4 +45,23 @@ export default connect(({ firebase }) => ({ }))(fbWrapped) ``` +_Data that depends on props_ + +```javascript +import { connect } from 'react-redux' +import { firebaseConnect, dataToJS } from 'react-redux-firebase' + +// sync /todos from firebase into redux +const fbWrapped = firebaseConnect((props, firebase) => ([ + `todos/${firebase.database().currentUser.uid}/${props.type}` +])(App) + +// pass todos list for the specified type of todos from redux as `this.props.todosList` +export default connect(({ firebase, type }) => ({ + todosList: dataToJS(firebase, `data/todos/${firebase.getIn(['auth', 'uid'])}/${type}`), + profile: pathToJS(firebase, 'profile'), // pass profile data as this.props.profile + auth: pathToJS(firebase, 'auth') // pass auth data as this.props.auth +}))(fbWrapped) +``` + Returns **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** that accepts a component to wrap and returns the wrapped component diff --git a/docs/api/constants.md b/docs/api/constants.md index 87647f53a..3b9568b23 100644 --- a/docs/api/constants.md +++ b/docs/api/constants.md @@ -1,7 +1,16 @@ -# actionsPrefix + + +### Table of Contents + +- [actionsPrefix](#actionsprefix) +- [actionTypes](#actiontypes) + +## actionsPrefix Prefix for all actions within library +Type: [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) + **Examples** ```javascript @@ -9,7 +18,7 @@ import { constants } from 'react-redux-firebase' constants.actionsPrefix === '@@reactReduxFirebase' // true ``` -# actionTypes +## actionTypes Object containing all action types @@ -41,7 +50,7 @@ import { actionTypes } from 'react-redux-firebase' actionTypes.SET === '@@reactReduxFirebase/SET' // true ``` -# defaultConfig +## Default configuration options diff --git a/docs/api/helpers.md b/docs/api/helpers.md index 63d7e88a1..82e97cb7d 100644 --- a/docs/api/helpers.md +++ b/docs/api/helpers.md @@ -1,4 +1,16 @@ -# isLoaded + + +### Table of Contents + +- [isLoaded](#isloaded) +- [isEmpty](#isempty) +- [toJS](#tojs) +- [pathToJS](#pathtojs) +- [dataToJS](#datatojs) +- [orderedToJS](#orderedtojs) +- [customToJS](#customtojs) + +## isLoaded Detect whether items are loaded yet or not @@ -16,14 +28,14 @@ import { firebaseConnect, isLoaded, dataToJS } from 'react-redux-firebase' Returns **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Whether or not item is loaded -# isEmpty +## isEmpty Detect whether items are empty or not **Parameters** -- `item` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Item to check loaded status of. A comma seperated list is also acceptable. - `data` +- `item` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Item to check loaded status of. A comma seperated list is also acceptable. **Examples** @@ -35,7 +47,7 @@ import { firebaseConnect, isEmpty, dataToJS } from 'react-redux-firebase' Returns **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Whether or not item is empty -# toJS +## toJS Convert Immutable Map to a Javascript object @@ -47,16 +59,16 @@ Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refer Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Data located at path within Immutable Map -# pathToJS +## pathToJS Convert parameter from Immutable Map to a Javascript object **Parameters** -- `firebase` **[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)** Immutable Map to be converted to JS object (state.firebase) - `data` - `path` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Path from state.firebase to convert to JS object - `notSetValue` **([Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) \| [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean))** Value to use if data is not available +- `firebase` **[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)** Immutable Map to be converted to JS object (state.firebase) **Examples** @@ -69,19 +81,19 @@ import { firebaseConnect, pathToJS } from 'react-redux-firebase' Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Data located at path within Immutable Map -# dataToJS +## dataToJS Convert parameter under "data" path of Immutable Map to a Javascript object. **NOTE:** Setting a default value will cause `isLoaded` to always return true **Parameters** -- `firebase` **[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)** Immutable Map to be converted to JS object (state.firebase) - `data` - `path` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Path of parameter to load - `notSetValue` **([Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) \| [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean))** Value to return if value is not found in redux. This will cause `isLoaded` to always return true (since value is set from the start). +- `firebase` **[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)** Immutable Map to be converted to JS object (state.firebase) **Examples** @@ -106,17 +118,17 @@ const defaultValue = { Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Data located at path within Immutable Map -# orderedToJS +## orderedToJS Convert parameter under "ordered" path of Immutable Map to a Javascript array. This preserves order set by query. **Parameters** -- `firebase` **[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)** Immutable Map to be converted to JS object (state.firebase) - `data` - `path` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Path of parameter to load - `notSetValue` **([Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) \| [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean))** Value to return if value is not found +- `firebase` **[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)** Immutable Map to be converted to JS object (state.firebase) **Examples** @@ -129,7 +141,7 @@ import { firebaseConnect, orderedToJS } from 'react-redux-firebase' Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Data located at path within Immutable Map -# populatedDataToJS +## Convert parameter under "data" path of Immutable Map to a Javascript object with parameters populated based on populates array @@ -137,7 +149,6 @@ Javascript object with parameters populated based on populates array **Parameters** - `firebase` **[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)** Immutable Map to be converted to JS object (state.firebase) -- `data` - `path` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Path of parameter to load - `populates` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** Array of populate objects - `notSetValue` **([Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) \| [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean))** Value to return if value is not found @@ -166,18 +177,18 @@ export default connect(({ firebase }) => ({ Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Data located at path within Immutable Map -# customToJS +## customToJS Load custom object from within store **Parameters** -- `firebase` **[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)** Immutable Map to be converted to JS object (state.firebase) -- `path` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Path of parameter to load -- `customPath` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Part of store from which to load - `data` +- `path` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Path of parameter to load - `custom` - `notSetValue` **([Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) \| [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean))** Value to return if value is not found +- `firebase` **[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)** Immutable Map to be converted to JS object (state.firebase) +- `customPath` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Part of store from which to load **Examples** diff --git a/docs/api/reducer.md b/docs/api/reducer.md index 22c2a991a..8e4330f17 100644 --- a/docs/api/reducer.md +++ b/docs/api/reducer.md @@ -1,4 +1,10 @@ -# firebaseStateReducer + + +### Table of Contents + +- [firebaseStateReducer](#firebasestatereducer) + +## firebaseStateReducer Reducer for react redux firebase. This function is called automatically by redux every time an action is fired. Based on which action @@ -7,8 +13,8 @@ changes. **Parameters** -- `state` **[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)** Current Redux State -- `action` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Action which will modify state +- `state` **[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)** Current Redux State (optional, default `initialState`) +- `action` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Action which will modify state (optional, default `{}`) - `action.type` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Type of Action being called - `action.data` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Type of Action which will modify state diff --git a/src/connect.js b/src/connect.js index 5600f128b..4636b398c 100644 --- a/src/connect.js +++ b/src/connect.js @@ -9,7 +9,7 @@ import { getEventsFromInput, createCallable } from './utils' * @extends React.Component * @description Higher Order Component that automatically listens/unListens * to provided firebase paths using React's Lifecycle hooks. - * @param {Array} watchArray - Array of objects or strings for paths to sync from Firebase + * @param {Array} watchArray - Array of objects or strings for paths to sync from Firebase. Can also be a function that returns the array. The function is passed the current props and the firebase object. * @return {Function} - that accepts a component to wrap and returns the wrapped component * @example Basic * // this.props.firebase set on App component as firebase object with helpers @@ -30,6 +30,21 @@ import { getEventsFromInput, createCallable } from './utils' * profile: pathToJS(firebase, 'profile'), // pass profile data as this.props.profile * auth: pathToJS(firebase, 'auth') // pass auth data as this.props.auth * }))(fbWrapped) + * @example Data that depends on props + * import { connect } from 'react-redux' + * import { firebaseConnect, dataToJS } from 'react-redux-firebase' + * + * // sync /todos from firebase into redux + * const fbWrapped = firebaseConnect((props, firebase) => ([ + * `todos/${firebase.database().currentUser.uid}/${props.type}` + * ])(App) + * + * // pass todos list for the specified type of todos from redux as `this.props.todosList` + * export default connect(({ firebase, type }) => ({ + * todosList: dataToJS(firebase, `data/todos/${firebase.getIn(['auth', 'uid'])}/${type}`), + * profile: pathToJS(firebase, 'profile'), // pass profile data as this.props.profile + * auth: pathToJS(firebase, 'auth') // pass auth data as this.props.auth + * }))(fbWrapped) */ export default (dataOrFn = []) => WrappedComponent => { class FirebaseConnect extends Component {