Merge branch 'master' into v2.0.0

prescottprue · Dec 30, 2017 · 17261a9 · 17261a9
2 parents 989d299 + 1cf00bd
commit 17261a9
Show file tree

Hide file tree

Showing 5 changed files with 8,958 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -306,6 +306,14 @@ If you plan to use Firestore, you should checkout [`redux-firestore`][redux-fire
 
 Currently `react-redux-firebase` still handles auth when using [`redux-firestore`][redux-firestore] - The future plan is to also have auth standalone auth library that will allow the developer to choose which pieces they do/do not want.
 
+## Firestore
+
+If you plan to use Firestore, you should checkout [`redux-firestore`][redux-firestore]. It integrates nicely with `react-redux-firebase` (v2 only) and it allows you to run Real Time Database and Firestore along side each other.
+
+`react-redux-firebase` provides the `firestoreConnect` HOC (similar to `firebaseConnect`) for easy setting/unsetting of listeners.
+
+Currently `react-redux-firebase` still handles auth when using [`redux-firestore`][redux-firestore] - The future plan is to also have auth standalone auth library that will allow the developer to choose which pieces they do/do not want.
+
 ## Starting A Project
 
 ### Generator

diff --git a/docs/api/compose.md b/docs/api/compose.md
@@ -0,0 +1,96 @@
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+### Table of Contents
+
+-   [reactReduxFirebase](#reactreduxfirebase)
+
+## reactReduxFirebase
+
+Middleware that handles configuration (placed in redux's
+`compose` call)
+
+**Parameters**
+
+-   `fbConfig` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Firebase config including databaseURL
+    -   `fbConfig.apiKey` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Firebase apiKey
+    -   `fbConfig.authDomain` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Firebase auth domain
+    -   `fbConfig.databaseURL` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Firebase database url
+    -   `fbConfig.storageBucket` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Firebase storage bucket
+-   `config` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Containing react-redux-firebase specific config
+    such as userProfile
+    -   `config.userProfile` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Location on firebase to store user
+        profiles
+    -   `config.enableLogging` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Whether or not to enable Firebase
+        database logging
+    -   `config.updateProfileOnLogin` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Whether or not to update
+        profile when logging in. (default: `false`)
+    -   `config.resetBeforeLogin` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Whether or not to empty profile
+        and auth state on login
+    -   `config.enableRedirectHandling` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Whether or not to enable
+        auth redirect handling listener. (default: `true`)
+    -   `config.onAuthStateChanged` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** Function run when auth state
+        changes. Argument Pattern: `(authData, firebase, dispatch)`
+    -   `config.enableEmptyAuthChanges` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Whether or not to enable
+        empty auth changes. When set to true, `onAuthStateChanged` will be fired with,
+        empty auth changes such as undefined on initialization. See
+        [#137](https://github.com/prescottprue/react-redux-firebase/issues/137) for
+        more details. (default: `false`)
+    -   `config.onRedirectResult` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** Function run when redirect
+        result is returned. Argument Pattern: `(authData, firebase, dispatch)`
+    -   `config.customAuthParameters` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Object for setting which
+        customAuthParameters are passed to external auth providers.
+    -   `config.profileFactory` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** Factory for modifying how user
+        profile is saved.
+    -   `config.fileMetadataFactory` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** Factory for modifying
+        how file meta data is written during file uploads
+    -   `config.profileParamsToPopulate` **([Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) \| [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String))** Parameters within
+        profile object to populate
+    -   `config.autoPopulateProfile` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Whether or not to
+        automatically populate profile with data loaded through
+        profileParamsToPopulate config. (default: `true`)
+    -   `config.setProfilePopulateResults` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Whether or not to
+        call SET actions for data that results from populating profile to redux under
+        the data path. For example role parameter on profile populated from 'roles'
+        root. True will call SET_PROFILE as well as a SET action with the role that
+        is loaded (places it in data/roles). (default: `false`)
+
+**Examples**
+
+_Setup_
+
+```javascript
+import { createStore, compose } from 'redux'
+import { reactReduxFirebase } from 'react-redux-firebase'
+
+// React Redux Firebase Config
+const config = {
+  userProfile: 'users', // saves user profiles to '/users' on Firebase
+  // here is where you place other config options
+}
+
+// Add react-redux-firebase to compose
+// Note: In full projects this will often be within createStore.js or store.js
+const createStoreWithFirebase = compose(
+ reactReduxFirebase(fbConfig, config),
+)(createStore)
+
+// Use Function later to create store
+const store = createStoreWithFirebase(rootReducer, initialState)
+```
+
+_Custom Auth Parameters_
+
+```javascript
+// Follow Setup example with the following config:
+const config = {
+  customAuthParameters: {
+     google: {
+       // prompts user to select account on every google login
+       prompt: 'select_account'
+     }
+  }
+}
+```
+
+Returns **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** That accepts a component and returns a Component which
+wraps the provided component (higher order component).
diff --git a/docs/queries.md b/docs/queries.md
@@ -112,6 +112,73 @@ Visit [Populate Section](/docs/populate.md) for full documentation.
 ## Types of Queries
 
 There are multiple types of queries
+Queries can be attached in two different ways:
+1. Manually - Call `watchEvents` and `unWatchEvents` directly (such as within component lifecycle hooks)
+2. Automatically - Using `firebaseConnect` HOC Wrapper (manages attaching/detaching listeners on component mount/dismount/props change)
+
+## Manually
+**NOTE** You must track and unmount all of then listeners you create in this way. [`firebaseConnect`](#automatically) has been created to [do this for you automatically](#automatically).
+
+`watchEvent` and `watchEvents` can be called directly to create listeners. Be careful when doing this though! You will have to track and unmount all of your listeners using either `unWatchEvent` or `unWatchEvents`. `firebaseConnect` has been created to [do this for you automatically](#automatically), but there are still times where it is nice to do it manually.
+
+```js
+import React, { PureComponent } from 'react'
+import PropTypes from 'prop-types'
+import { connect } from 'react-redux'
+import { isLoaded, isEmpty, toJS } from 'react-redux-firebase'
+
+class SomeThing extends PureComponent {
+  static contextTypes = {
+    store: PropTypes.object.isRequired
+  }
+
+  static propTypes = {
+    todosMap: PropTypes.object
+  }
+
+  componentWillMount () {
+    this.context.store.firebase.helpers.watchEvent('value', 'todos')
+  }
+
+  componentWillUnMount () {
+    this.context.store.firebase.helpers.unWatchEvent('value', 'todos')
+  }
+
+  render () {
+    const { todosMap } = this.props
+
+    if (!isLoaded(todosMap)) {
+      return <div>Loading...</div>
+    }
+
+    if (isEmpty(todosMap)) {
+      return <div>No Todos Found</div>
+    }
+    const todos = toJS(todosMap) // convert ImmutableJS Map to JS Object (not needed in v2)
+
+    return <div>{JSON.stringify(todos, null, 2)}</div>
+  }
+}
+
+export default connect(
+  ({ firebase }) => ({
+    todosMap: firebase.getIn(['data', 'todos']) // pass ImmutableJS Map
+  })
+)(SomeThing)
+```
+
+## Automatically {#automatically}
+
+Query listeners are attached by using the `firebaseConnect` higher order component. `firebaseConnect` accepts an array of paths for which to create queries. When listening to paths, it is possible to modify the query with any of [Firebase's included query methods](https://firebase.google.com/docs/reference/js/firebase.database.Query).
+
+**NOTE:**
+By default the results of queries are stored in redux under the path of the query. If you would like to change where the query results are stored in redux, use [`storeAs` (more below)](#storeAs).
+
+Below are examples using Firebase query config options as well as other options that are included (such as 'populate').
+
+`firebaseConnect` is a Higher Order Component (wraps a provided component) that attaches listeners to relevant paths on Firebase when mounting, and removes them when unmounting.
+
+>>>>>>> master
 
 ## once
 To load a firebase location once instead of binding, the once option can be used: