diff --git a/.gitignore b/.gitignore index ae607966..2155142a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,8 @@ .DS_Store npm-debug.log +tests/key.json + dist/ coverage/ node_modules/ diff --git a/.travis.yml b/.travis.yml index 42a2c43e..0807e2ab 100644 --- a/.travis.yml +++ b/.travis.yml @@ -4,12 +4,17 @@ node_js: - '0.12' # - stable sudo: false +env: + REACTFIRE_TEST_DB_URL=https://reactfire-bbede.firebaseio.com install: - npm install before_script: - export DISPLAY=:99.0 - sh -e /etc/init.d/xvfb start script: -- npm run travis +- "[ -e tests/key.json ] && npm run travis || false" after_script: - cat ./tests/coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js +before_install: +- openssl aes-256-cbc -K $encrypted_f7671fde2e57_key -iv $encrypted_f7671fde2e57_iv + -in tests/key.json.enc -out tests/key.json -d diff --git a/README.md b/README.md index 5365e4b5..f52339f1 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,28 @@ -# ReactFire +# ReactFire [![Build Status](https://travis-ci.org/firebase/reactfire.svg?branch=master)](https://travis-ci.org/firebase/reactfire) [![Coverage Status](https://coveralls.io/repos/firebase/reactfire/badge.svg?branch=master&service=github)](https://coveralls.io/github/firebase/reactfire?branch=master) [![GitHub version](https://badge.fury.io/gh/firebase%2Freactfire.svg)](http://badge.fury.io/gh/firebase%2Freactfire) -[![Build Status](https://travis-ci.org/firebase/reactfire.svg?branch=master)](https://travis-ci.org/firebase/reactfire) -[![Coverage Status](https://coveralls.io/repos/firebase/reactfire/badge.svg?branch=master&service=github)](https://coveralls.io/github/firebase/reactfire?branch=master) -[![GitHub version](https://badge.fury.io/gh/firebase%2Freactfire.svg)](http://badge.fury.io/gh/firebase%2Freactfire) -[ReactJS](http://facebook.github.io/react/) is a framework for building large, complex user -interfaces. [Firebase](http://www.firebase.com/?utm_source=reactfire) complements it perfectly -by providing an easy-to-use, realtime data source for populating the `state` of React components. -With [ReactFire](https://www.firebase.com/docs/web/libraries/react/?utm_source=reactfire), it only -takes a few lines of JavaScript to integrate Firebase data into React apps via the `ReactFireMixin`. +[ReactJS](https://facebook.github.io/react/) is a framework for building large, complex user +interfaces. [Firebase](https://firebase.google.com/) complements it perfectly by providing an +easy-to-use, realtime data source for populating the `state` of React components. With ReactFire, it +only takes a few lines of JavaScript to integrate Firebase data into React apps via the +`ReactFireMixin`. -[Read through our documentation](https://www.firebase.com/docs/web/libraries/react/?utm_source=reactfire) -on using Firebase with React and [check out our live Todo app demo](https://reactfiretodoapp.firebaseapp.com/) -to get started! + +## Table of Contents + + * [Getting Started With Firebase](#getting-started-with-firebase) + * [Downloading ReactFire](#downloading-reactfire) + * [Documentation](#documentation) + * [Examples](#examples) + * [Migration Guides](#migration-guides) + * [Contributing](#contributing) + + +## Getting Started With Firebase + +ReactFire requires [Firebase](https://firebase.google.com/) in order to sync and store data. +Firebase is a suite of integrated products designed to help you develop your app, grow your user +base, and earn money. You can [sign up here for a free account](https://console.firebase.google.com/). ## Downloading ReactFire @@ -25,19 +35,12 @@ In order to use ReactFire in your project, you need to include the following fil - + - + ``` -Use the URL above to download both the minified and non-minified versions of ReactFire from the -Firebase CDN. You can also download them from the -[releases page of this GitHub repository](https://github.com/firebase/reactfire/releases). -[Firebase](https://www.firebase.com/docs/web/quickstart.html?utm_source=reactfire) and -[React](http://facebook.github.io/react/downloads.html) can be downloaded directly from their -respective websites. - You can also install ReactFire via npm or Bower. If downloading via npm, you will have to install React and Firebase separately (that is, they are `peerDependencies`): @@ -45,42 +48,29 @@ React and Firebase separately (that is, they are `peerDependencies`): $ npm install reactfire react firebase --save ``` -On Bower, the React and Firebase dependencies will be downloaded automatically: +On Bower, the React and Firebase dependencies will be downloaded automatically alongside ReactFire: ```bash $ bower install reactfire --save ``` +## Documentation -## Getting Started with Firebase - -ReactFire requires Firebase in order to store data. You can -[sign up here for a free account](https://www.firebase.com/signup/?utm_source=reactfire). - +* [Quickstart](docs/quickstart.md) +* [Guide](docs/guide.md) +* [API Reference](docs/reference.md) -## Usage -To use the `ReactFireMixin` in a React component, add it to the component's `mixins` property: - -```javascript -var ExampleComponent = React.createClass({ - mixins: [ReactFireMixin], - ... -}); -``` +## Examples -The ReactFire APIs will then be available from the `this` object inside of `ExampleComponent`. +* [Todo App](examples/todoApp) +* [Comments Box](examples/commentsBox) -## Documentation and API Reference +## Migration Guides -The [ReactFire quickstart](https://www.firebase.com/docs/web/libraries/react/quickstart.html?utm_source=reactfire) -is a great place to get started. There is a walkthrough on how to create the -[Todo app demo](https://reactfiretodoapp.firebaseapp.com/) in the -[ReactFire guide](https://www.firebase.com/docs/web/libraries/react/guide.html?utm_source=reactfire). -Finally, there is a [full API reference](https://www.firebase.com/docs/web/libraries/react/api.html?utm_source=reactfire) -as well. +* [Migrating from ReactFire `0.7.0` to `1.x.x`](docs/migration/070-to-1XX.md) ## Contributing diff --git a/bower.json b/bower.json index 401a0f68..d6d6d9cb 100644 --- a/bower.json +++ b/bower.json @@ -33,6 +33,6 @@ ], "dependencies": { "react": "0.13.x || 0.14.x || 15.x.x", - "firebase": "2.x.x" + "firebase": "2.x.x || 3.x.x" } } diff --git a/docs/guide.md b/docs/guide.md new file mode 100644 index 00000000..46720ac3 --- /dev/null +++ b/docs/guide.md @@ -0,0 +1,216 @@ +# Guide | ReactFire + + +## Table of Contents + + * [What Is ReactJS?](#what-is-reactjs) + * [Adding Firebase to Your React App](#adding-firebase-to-your-react-app) + * [`ReactFireMixin`](#reactfiremixin) + * [Next Steps](#next-steps) + + +## What Is ReactJS? + +[ReactJS](http://facebook.github.io/react/) is a JavaScript library built by Facebook and Instagram +which makes it easy to build large, complex user interfaces. The creators of React describe it as +the “V[iew] in MVC.” It is not meant to be a replacement for Angular or Ember; instead, it is meant +to extend their functionality by providing a high-performance way to keep a view up-to-date with +JavaScript. Its special sauce is that it renders HTML using an incredibly fast virtual DOM diff +algorithm, providing much better performance than competing platforms. It has a “one-way reactive +data flow” which is much simpler to understand than traditional data-binding. + +Components - the basic building blocks of React apps - are organized in a tree hierarchy in which +parent components send data down to their children through the props variable. Each component also +has a `state` variable which determines the current data for its view. Whenever `state` is changed, +the component’s render() method is called and React figures out the most efficient way to update the +DOM. + +Since React’s main focus is on the user interface, React apps need something else to act as their +backend. That is where Firebase comes in. It adds the “M[odel] and C[ontroller] in MVC” to React +apps, making them fully functioning apps. **Using React’s straightforward binding system, it is easy +to integrate Firebase in a native way with only a small amount of code.** + + +## Adding Firebase to Your React App + +Let's look at the Todo app on the [React homepage](http://facebook.github.io/react/). Within the +`TodoApp` component, `this.state` is used to keep track of the input text and the list of Todo +items. While React ensures that the DOM stays in sync with any changes to `this.state`, the changes +do not persist beyond the life of the page. If you add a few items and then refresh the page, all of +the items disappear! This is because **React has no mechanism for storing data beyond the scope of +the current page session**. It relies on being used with another framework to do that. + +**Firebase is a natural complement to React as it provides React apps with a persistent, realtime +backend**. The first thing we need to do is add Firebase to your project: + +```js + + + + + + +``` + +We'll need to initialize the Firebase SDK before we can use it. This should happen one time, outside +of your React component. You can find more details on the [web](https://firebase.google.com/docs/web/setup) +or [Node.js](https://firebase.google.com/docs/server/setup) setup guides. + +```js + +``` + +Now that we have included Firebase, we can populate the list of Todo items by reading them from the +database. We do this by hooking into the `componentWillMount()` method of the `TodoApp` component +which is run once, immediately before the initial rendering of the component: + +```js +componentWillMount: function() { + this.firebaseRef = firebase.database.ref("items"); + this.firebaseRef.on("child_added", function(dataSnapshot) { + this.items.push(dataSnapshot.val()); + this.setState({ + items: this.items + }); + }.bind(this)); +} +``` + +This code first gets a reference to the `items` node at the root of the database. The call to `on()` +will be run every time a node is added under the `items` node. It is important to realize that a +`child_added` event will be fired for every item under the `items` node, not just new ones that are +added to it. Therefore, when the page is loaded, every existing child under the `items` node will +fire a `child_added` event, meaning they can easily be iterated over and added to `this.state.items`. +Note that the call at the end to `bind()` just sets the scope of callback function to this. + +What about adding new Todo items to the database? That code is just as easy: + +```js +handleSubmit: function(e) { + e.preventDefault(); + this.firebaseRef.push({ + text: this.state.text + }); + this.setState({text: ""}); +} +``` + +Within `handleSubmit()` a new item is pushed onto the database reference which appends it to the end +of the `items` node. The call to `setState()` updates `this.state.text` but does not need to update +`this.state.items` as it did in the original React code. This is because the `child_added` event +handler from `componentWillMount()` will be fired when a new child is pushed onto the `items` node +and that code will update `this.state.items`. + +The last thing that needs to happen is cleaning up the database event handler: + +```js +componentWillUnmount: function() { + this.firebaseRef.off(); +} +``` + +With just the few changes above, items added to the Todo list are updated in realtime. Best of all, +the items stick around if the page is refreshed! You can even open multiple tabs pointed at the same +page and see them all update simultaneously, with Firebase doing all the heavy lifting. Take some +time to [view the code for this example](https://github.com/firebase/ReactFire/blob/master/examples/todoApp/js/todoAppFirebaseExplicit.js) +and [play around with a live demo](https://reactfiretodoapp.firebaseapp.com/). + + +## `ReactFireMixin` + +Although integrating Firebase into a React app only takes a few lines of code out of the box, we +wanted to make it even easier. We also want to be able to handle when array items are removed or +updated from Firebase. **We built the `ReactFireMixin` to make it simple to keep `this.state` in +sync with a database node.** + +To get started with ReactFire, include it in your project by loading the library directly from our +CDN and placing it right after the React and Firebase libraries in the `` tag: + +```js + + + + + + + + + +``` + +ReactFire and its dependencies are also available from npm via `npm install reactfire` and Bower +via `bower install reactfire`. + +After making sure to initialize the Firebase SDK again, we can then use the `ReactFireMixin` in the +`TodoApp` component, add it to the component's `mixins` property: + +```js +var TodoApp = React.createClass({ + mixins: [ReactFireMixin], + ... +}); +``` + +The `ReactFireMixin` extends the functionality of the `TodoApp` component, adding additional +Firebase-specific methods to it. To keep `this.state.items` in sync with any changes to the `items` +node, make the following change in `componentWillMount()`: + +```js +componentWillMount: function() { + var ref = firebase.database().ref("items"); + this.bindAsArray(ref, "items"); +} +``` + +We simply specify that we want to bind a particular Firebase Database reference to `this.state.items` +of the React component. The `ReactFireMixin` allows binding to a node as an array or as a regular +JavaScript object. This creates a one-way binding from the `Firebase` reference to `this.state.items`, +meaning that if the data in the database changes, so will `this.state.items`. However, if we update +`this.state.items`, the database data will not change. Therefore, changes should be made directly to +the database and not by calling `setState()`: + +```js +handleSubmit: function(e) { + e.preventDefault(); + this.firebaseRefs.items.push({ + text: this.state.text + }); + this.setState({ text: "" }); +} +``` + +**ReactFire allows for binding to multiple things at once.** Firebase ensures that this is all done +in an efficient manner. To access the `Firebase` reference which is bound to `this.state.items`, we +can reference `this.firebaseRefs["items"]` which is provided by ReactFire. Finally, calling +`this.firebaseRef.off()` is no longer needed in `componentWillUnmount()` as the mixin handles this +behind the scenes. + +You can [view the code for this example](https://github.com/firebase/ReactFire/blob/master/examples/todoApp/js/todoAppFirebaseImplicit.js) +and [play around with a live demo](https://reactfiretodoapp.firebaseapp.com/). The code and demo add +the ability to delete items in the array and have them automatically synced back to `this.state.items`. + + +## Next Steps + +ReactJS is a wonderful framework for creating user interfaces. When picking a complementary tool to +use alongside it as a backend, Firebase is the easiest and most powerful solution. In just a few +lines of code you can get a React app syncing data across hundreds of clients at once. ReactFire +makes this that much easier, getting rid of even more boilerplate code. + +Head on over to the [ReactFire API reference](reference.md) and then get started building an app +with ReactFire! diff --git a/docs/migration/070-to-1XX.md b/docs/migration/070-to-1XX.md new file mode 100644 index 00000000..d40e1486 --- /dev/null +++ b/docs/migration/070-to-1XX.md @@ -0,0 +1,11 @@ +# Migrating from ReactFire `0.7.0` to `1.x.x` + +This migration document covers all the major breaking changes mentioned in the [ReactFire `1.0.0` +change log](https://github.com/firebase/reactfire/releases/tag/v1.0.0). + + +## Upgrade your Firebase SDK + +While ReactFire `1.0.0` continues to support all `2.x.x` versions of the Firebase SDK, we encourage +you to upgrade to version `3.x.x`. See the [Firebase `3.x.x` migration +guide](https://firebase.google.com/support/guides/firebase-web) for more details. diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 00000000..0f42c501 --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,115 @@ +# Quickstart | ReactFire + +With ReactFire it only takes a few lines of JavaScript to integrate Firebase into React apps. + + +## 1. Create an account + +The first thing we need to do is [sign up for a free Firebase account](https://firebase.google.com/). +A brand new Firebase project will automatically be created for you which you will use in conjunction +with ReactFire to store and sync data. + + +## 2. Include Firebase and ReactFire + +To use ReactFire in our website, we need to add it along with all its dependencies to the `` +section of our HTML file. We recommend including the Firebase and ReactFire libraries directly from +our CDN: + + +```js + + + + + + + + + +``` + +ReactFire and its dependencies are also available from npm via `npm install reactfire` and Bower +via `bower install reactfire`. + + +## 3. Initialize the Firebase SDK + +We'll need to initialize the Firebase SDK before we can use it. This should happen one time, outside +of your React component. You can find more details on the [web](https://firebase.google.com/docs/web/setup) +or [Node.js](https://firebase.google.com/docs/server/setup) setup guides. + +```js + +``` + + +## 4. Add the `ReactFireMixin` + +ReactFire exposes the `ReactFireMixin` which extends the functionality of a React component, adding +additional Firebase-specific methods to it. These methods allow us to create a **one-way data +binding from our Firebase database to our component's `this.state` variable**. Add the +`ReactFireMixin` to our component's `mixins` list: + +```js +var ExampleComponent = React.createClass({ + mixins: [ReactFireMixin], + // ... +}); +``` + +## 5. Bind to Firebase + +Because of the data binding provided by ReactFire, any changes to our remote database will be +reflected in realtime to `this.state`. The data binding does not work in the other way - changes +made to the `this.state` have no effect on our database. Any changes which we want to make to +`this.state` should instead be changed in our database directly by using the Firebase client +library. ReactFire will handle the work of then updating `this.state`. + +**Note that ReactFire creates a one-way data binding from our database to our component, not the +other way around.** + +Taking `ExampleComponent` above, we can keep `this.state.items` in sync with any changes to an +`items` node in the database by using ReactFire in the component's `componentWillMount()` method: + +```js +componentWillMount: function() { + var ref = firebase.database().ref("items"); + this.bindAsArray(ref, "items"); +} +``` + +Now, if we add an item to the `items` node in the database, that change will be automatically +reflected in `this.state.items`. We have the option of binding the data from the database as a +JavaScript array (via `bindAsArray()`) or object (via `bindAsObject()`). + + +## 6. Unbind from Firebase + +When our React component goes out of scope or is being unmounted, ReactFire will automatically +unbind any open connections to our Firebase database. If we want to do this manually at an earlier +time (that is, while the component is still mounted), ReactFire provides an `unbind()` method. For +example, if we no longer want `this.state.items` to be bound to node, we can call +`this.unbind("items")` from anywhere within our component. + + +## 7. Next steps + +This was just a quick run through of the basics of ReactFire. For a more in-depth explanation of how +to use ReactFire, [check out the ReactFire guide](guide.md) or dig right into the +[ReactFire APIreference](reference.md). diff --git a/docs/reference.md b/docs/reference.md new file mode 100644 index 00000000..1f494dd2 --- /dev/null +++ b/docs/reference.md @@ -0,0 +1,199 @@ +# API Reference | GeoFire + + +## Table of Contents + + * [Initialization](#initialization) + * [`bindAsArray(firebaseRef, bindVar, cancelCallback)`](#bindasarrayfirebaseref-bindvar-cancelcallback) + * [`bindAsObject(firebaseRef, bindVar, cancelCallback)`](#bindasobjectfirebaseref-bindvar-cancelcallback) + * [`unbind(bindVar)`](#unbindbindvar) + + +## Initialization + +To add the ReactFire mixin to your React component, add it to your component's `mixins` list: + +```js +var ExampleComponent = React.createClass({ + mixins: [ReactFireMixin], + ... +}); +``` + +## bindAsArray(firebaseRef, bindVar, cancelCallback) + +### Description + +Creates a one-way binding from a list of nodes in your Firebase database to an array in `this.state` +of your React component. The name of the array stored in `this.state` is specified using the +`bindVar` variable. + +### Arguments + +| Argument | Type | Description | +|----------|------|-------------| +| `firebaseRef` | `DatabaseRef` | The database reference to which we are binding. | +| `bindVar` | String | The name of the attribute within `this.state` which will be bound to your database. | +| `cancelCallback` | Function | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an `Error` object indicating why the failure occurred. | + +### Examples + +The following code will make the data stored at the `/items` node as an array and make it available +as `this.state.items` within your component: + +```js +componentWillMount: function() { + var ref = firebase.database().ref("items"); + this.bindAsArray(ref, "items"); +} +``` + +Each record in the bound array will contain a `.key` property which specifies the key where the +record is stored. So if you have data at `/items/-Jtjl482BaXBCI7brMT8`, the record for that data +will have a `.key` of `"-Jtjl482BaXBCI7brMT8"`. + +If an individual record's value in the database is a primitive (boolean, string, or number), the +value will be stored in the `.value` property. If the individual record's value is an object, each +of the object's properties will be stored as properties of the bound record. As an example, let's +assume the `/items` node you bind to contains the following data: + +```js +{ + "items": { + "-Jtjl482BaXBCI7brMT8": 100, + "-Jtjl6tmqjNeAnQvyD4l": { + "first": "fred", + "last": "Flintstone" + }, + "-JtjlAXoQ3VAoNiJcka9": "foo" + } +} +``` + +The resulting bound array stored in `this.state.items` will be: + +```js +[ + { + ".key": "-Jtjl482BaXBCI7brMT8", + ".value": 100 + }, + { + ".key": "-Jtjl6tmqjNeAnQvyD4l", + "first": "Fred" + "last": "Flintstone" + }, + { + ".key": "-JtjlAXoQ3VAoNiJcka9", + ".value": "foo" + } +] +``` + + +## bindAsObject(firebaseRef, bindVar, cancelCallback) + +### Description + +Creates a one-way binding from node in your Firebase database to an object in this.state of your +React component. The name of the object stored in `this.state` is specified using the `bindVar` +variable. + +### Arguments + +| Argument | Type | Description | +|----------|------|-------------| +| `firebaseRef` | `DatabaseRef` | The database reference to which we are binding. | +| `bindVar` | String | The name of the attribute within `this.state` which will be bound to your database. | +| `cancelCallback` | Function | An optional callback that will be notified if your event subscription is ever canceled because your client does not have permission to read this data (or it had permission but has now lost it). This callback will be passed an `Error` object indicating why the failure occurred. | + +### Examples + +The following code will make the data stored at `/users/fred` as an object and make it available as +`this.state.user` within your component: + +```js +componentWillMount: function() { + var ref = firebase.database().ref().child("users/fred"); + this.bindAsObject(ref, "user"); +} +``` + +The bound object will contain a `.key` property which specifies the key where the object is stored. +So in the code above where we bind to `/users/fred`, the bound object will have a `.key` of `"fred"`. + +If the bound node's value in the database is a primitive (boolean, string, or number), the value +will be stored in the `.value` property. If the bound node's value is an object, each of the +object's properties will be stored as properties of the bound object. As an example, let's assume +the `/users/fred` node you bind comes from the following data: + +```js +{ + "users": { + "fred": true + } +} +``` + +The resulting bound object stored in `this.state.user` will be: + +```js +{ + ".key": "fred", + ".value": true +} +``` + +As another example, let's assume the `/users/fred` node contains an object: + +```js +{ + "users": { + "fred": { + "first": "Fred", + "last": "Flintstone" + } + } +} +``` + +The resulting bound object stored in `this.state.user` will be: + +```js +{ + ".key": "fred", + "first": "Fred", + "last": "Flintstone" +} +``` + +As a final example, let's assume the `/users/fred` node does not exist (that is, it has a value of +`null`). The resulting bound object stored in `this.state.user` will be: + +```js +{ + ".key": "fred", + ".value": null +} +``` + + +## unbind(bindVar) + +### Description + +Unbinds the binding between your database and the inputted bind variable. + +### Arguments + +| Argument | Type | Description | +|----------|------|-------------| +| `bindVar` | string | The name of the attribute within `this.state` which will be unbound from your database. | + +The following code will unbind `this.state.items` and set its value to `undefined`: + +```js +componentWillUnmount: function() { + this.unbind("items"); +} +``` diff --git a/examples/README.md b/examples/README.md index 870a4ba5..5aa92b48 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,12 +1,13 @@ -# ReactFire Examples +# Examples | ReactFire -Have you come up with a cool example that uses the ReactFire mixin? Submit a pull request and share -it with everyone else by putting in this `/examples/` directory. Please make sure to include a -`README.md` file in your example's base directory which explains what the example is and how to run -it. +Have you come up with a cool example that uses ReactFire? Submit a pull request and share it with +everyone else by putting in the `examples/` directory. Please make sure to include a `README.md` +file in your example's base directory which explains what the example is and how to run it. -Check out the [Todo app example](./todoApp) to see how to structure your example. +Check out the existing examples below to see how to structure your new example. -Examples: -* [Todo app](./todoApp) - [Jacob Wenger](https://github.com/jwngr) -* [Comments box](./commentsBox) - [Mark Woodall](https://github.com/llad) + +## Examples + +* [Todo App](./todoApp) (created by [Jacob Wenger](https://github.com/jwngr)) +* [Comments Box](./commentsBox) (created by [Mark Woodall](https://github.com/llad)) diff --git a/examples/commentsBox/README.md b/examples/commentsBox/README.md index 2faa0535..634398a7 100644 --- a/examples/commentsBox/README.md +++ b/examples/commentsBox/README.md @@ -1,12 +1,13 @@ -# ReactFire Comments Box Example +# Comments Box | ReactFire Example + ## Setup Instructions To run this example locally, either download the whole ReactFire repository or just this -`/commentsBox/` directory. Then replace the example Firebase URL with your own Firebase URL in the -`index.html` file: +`/examples/commentsBox/` directory. Then replace the example Firebase URL with your own Firebase URL in the +`js/app.js` file: -```javaScript +```js var firebaseApp = "https://my-firebase-app.firebaseio.com/" ``` @@ -18,14 +19,14 @@ $ python -m SimpleHTTPServer 8080 You can then visit the example in the browser of your choice at [http://127.0.0.1:8080/](http://127.0.0.1:8080/). -If you have downloaded the entire repository visit the example at [http://127.0.0.1:8080/examples/commentsBox/](http://127.0.0.1:8080/examples/commentsBox/) +If you have downloaded the entire repository visit the example at [http://127.0.0.1:8080/examples/commentsBox/](http://127.0.0.1:8080/examples/commentsBox/) ## Description The official [React tutorial](http://facebook.github.io/react/docs/tutorial.html) is a great introduction to React. This example replaces the REST-like server used in the tutorial with -Firebase and the ReactFire mixin. +Firebase and ReactFire. ReactFire allows us to strip out the polling concept as well as the jQuery AJAX calls. Instead, -with the ReactFire mixin, we can bind right to Firebase and keep everything in sync in realtime. +with ReactFire, we can bind right to Firebase and keep everything in sync in realtime. diff --git a/examples/commentsBox/index.html b/examples/commentsBox/index.html index 870db735..3d70f89a 100644 --- a/examples/commentsBox/index.html +++ b/examples/commentsBox/index.html @@ -9,10 +9,10 @@ - - + + - + diff --git a/examples/commentsBox/js/app.js b/examples/commentsBox/js/app.js index eff61f03..74a3a7a8 100644 --- a/examples/commentsBox/js/app.js +++ b/examples/commentsBox/js/app.js @@ -1,5 +1,10 @@ -// IMPORTANT: Replace below with your Firebase app URL -var firebaseUrl = "https://my-firebase-app.firebaseio.com/"; +var config = { + apiKey: 'AIzaSyD6NMVI9vCk3-VzXY5k_mRLSZS8waWZFjA', + authDomain: 'reactfire-bbede.firebaseapp.com', + databaseURL: 'https://reactfire-bbede.firebaseio.com', + storageBucket: 'reactfire-bbede.appspot.com', +}; +firebase.initializeApp(config); var converter = new Showdown.converter(); @@ -8,8 +13,8 @@ var Comment = React.createClass({ render: function() { var rawMarkup = converter.makeHtml(this.props.children.toString()); return ( -
-

{this.props.author}

+
+

{this.props.author}

); @@ -22,7 +27,7 @@ var CommentList = React.createClass({ var commentNodes = this.props.data.map(function (comment, index) { return {comment.text}; }); - return
{commentNodes}
; + return
{commentNodes}
; } }); @@ -39,10 +44,10 @@ var CommentForm = React.createClass({ render: function() { return ( -
- - - + + + +
); } @@ -54,7 +59,7 @@ var CommentBox = React.createClass({ handleCommentSubmit: function(comment) { // Here we push the update out to Firebase and let ReactFire update this.state.data - this.firebaseRefs["data"].push(comment); + this.firebaseRefs['data'].push(comment); }, getInitialState: function() { @@ -66,12 +71,12 @@ var CommentBox = React.createClass({ componentWillMount: function() { // Here we bind the component to Firebase and it handles all data updates, // no need to poll as in the React example. - this.bindAsArray(new Firebase(firebaseUrl + "commentBox"), "data"); + this.bindAsArray(firebase.database().ref('commentsBox'), 'data'); }, render: function() { return ( -
+

Comments

diff --git a/examples/todoApp/README.md b/examples/todoApp/README.md index bd498e8f..13cb9ab2 100644 --- a/examples/todoApp/README.md +++ b/examples/todoApp/README.md @@ -1,4 +1,5 @@ -# ReactFire Todo App Example +# Todo App | ReactFire Example + ## Live Demo @@ -8,7 +9,7 @@ You can view a live version of this demo [here](https://reactfiretodoapp.firebas ## Setup Instructions To run this example locally, either download the whole ReactFire repository or just this -`/todoApp/` directory. Then start up a server via Python (or your preferred method): +`/examples/todoApp/` directory. Then start up a server via Python (or your preferred method): ```bash $ python -m SimpleHTTPServer 8080 @@ -16,7 +17,8 @@ $ python -m SimpleHTTPServer 8080 You can then visit the example in the browser of your choice at [http://127.0.0.1:8080/](http://127.0.0.1:8080/). -If you have downloaded the entire repository visit the example at [http://127.0.0.1:8080/examples/todoApp/](http://127.0.0.1:8080/examples/todoApp/) +If you have downloaded the entire repository visit the example at [http://127.0.0.1:8080/examples/todoApp/](http://127.0.0.1:8080/examples/todoApp/) + ## Description @@ -30,14 +32,11 @@ code with no Firebase code at all. Changes made to this example are not persiste 2. __React + Plain Firebase:__ A version of the first example with explicit Firebase calls. Changes made to this example are persistent. -3. __ReactFire:__ A version of the first example which uses the ReactFire mixin. Changes made to -this example are persistent. +3. __ReactFire:__ A version of the first example which uses ReactFire. Changes made to this example +are persistent. ## Walkthrough -To learn more about how this example works, see the following blog posts on the official Firebase -blog: -* [Using Firebase With React](https://www.firebase.com/blog/2014-05-01-using-firebase-with-react.html) -* [ReactFire 0.5.0](https://www.firebase.com/blog/2015-07-15-reactfire-0-5-0.html). +To learn more about how this example works, see the [ReactFire guide](../../docs/guide.md). diff --git a/examples/todoApp/index.html b/examples/todoApp/index.html index f0ce8c1c..7ecb0c2b 100644 --- a/examples/todoApp/index.html +++ b/examples/todoApp/index.html @@ -1,21 +1,32 @@ - ReactFire Todo App Demo + Todo App | ReactFire Demo - + - + + + + @@ -27,31 +38,30 @@
-

ReactFire Todo App Demo

-

- ReactFire is a - ReactJS mixin which allows for easy - integration of Firebase into your React apps. - See how this was made by reading the - blog post - or checking out the source code on GitHub. -

- -
-

Plain React

-
-
- -
-

React + Plain Firebase

-
-
- -
-

React + ReactFire

-
-
-
+

Todo App | ReactFire Demo

+

+ ReactFire is a + ReactJS mixin which allows for easy + integration of Firebase into your React apps. + See how this was made by reading the + ReactFire documentation. +

+ +
+

Plain React

+
+
+ +
+

React + Plain Firebase

+
+
+ +
+

React + ReactFire

+
+
+
diff --git a/examples/todoApp/js/todoAppFirebaseExplicit.js b/examples/todoApp/js/todoAppFirebaseExplicit.js index 2b6fae0b..df65ce9d 100644 --- a/examples/todoApp/js/todoAppFirebaseExplicit.js +++ b/examples/todoApp/js/todoAppFirebaseExplicit.js @@ -25,12 +25,12 @@ var TodoApp2 = React.createClass({ }, componentWillMount: function() { - this.firebaseRef = new Firebase('https://ReactFireTodoApp.firebaseio.com/items/'); + this.firebaseRef = firebase.database().ref('todoApp/items'); this.firebaseRef.limitToLast(25).on('value', function(dataSnapshot) { var items = []; dataSnapshot.forEach(function(childSnapshot) { var item = childSnapshot.val(); - item['.key'] = childSnapshot.key(); + item['.key'] = childSnapshot.key; items.push(item); }.bind(this)); @@ -49,7 +49,7 @@ var TodoApp2 = React.createClass({ }, removeItem: function(key) { - var firebaseRef = new Firebase('https://ReactFireTodoApp.firebaseio.com/items/'); + var firebaseRef = firebase.database().ref('todoApp/items');; firebaseRef.child(key).remove(); }, diff --git a/examples/todoApp/js/todoAppFirebaseImplicit.js b/examples/todoApp/js/todoAppFirebaseImplicit.js index 66d5cc89..ee9e0d57 100644 --- a/examples/todoApp/js/todoAppFirebaseImplicit.js +++ b/examples/todoApp/js/todoAppFirebaseImplicit.js @@ -27,7 +27,7 @@ var TodoApp3 = React.createClass({ }, componentWillMount: function() { - var firebaseRef = new Firebase('https://ReactFireTodoApp.firebaseio.com/items/'); + var firebaseRef = firebase.database().ref('todoApp/items');; this.bindAsArray(firebaseRef.limitToLast(25), 'items'); }, @@ -36,7 +36,7 @@ var TodoApp3 = React.createClass({ }, removeItem: function(key) { - var firebaseRef = new Firebase('https://ReactFireTodoApp.firebaseio.com/items/'); + var firebaseRef = firebase.database().ref('todoApp/items');; firebaseRef.child(key).remove(); }, diff --git a/examples/todoApp/js/todoAppOriginal.js b/examples/todoApp/js/todoAppOriginal.js index 71b52a6a..8500f376 100644 --- a/examples/todoApp/js/todoAppOriginal.js +++ b/examples/todoApp/js/todoAppOriginal.js @@ -9,7 +9,7 @@ var TodoList1 = React.createClass({ var TodoApp1 = React.createClass({ getInitialState: function() { - return {items: [], text: ""}; + return {items: [], text: ''}; }, onChange: function(e) { @@ -24,7 +24,7 @@ var TodoApp1 = React.createClass({ }]); this.setState({ items: nextItems, - text: "" + text: '' }); } }, @@ -35,11 +35,11 @@ var TodoApp1 = React.createClass({
- +
); } }); -ReactDOM.render(, document.getElementById("todoApp1")); +ReactDOM.render(, document.getElementById('todoApp1')); diff --git a/package.json b/package.json index bb1025fa..cf4fc7a8 100644 --- a/package.json +++ b/package.json @@ -29,12 +29,12 @@ "dependencies": {}, "peerDependencies": { "react": "0.13.x || 0.14.x || 15.x.x", - "firebase": "2.x.x" + "firebase": "2.x.x || 3.x.x" }, "devDependencies": { "chai": "^3.0.0", "coveralls": "^2.11.2", - "firebase": "2.x.x", + "firebase": "3.x.x", "gulp": "^3.9.0", "gulp-eslint": "^0.15.0", "gulp-exit": "0.0.2", diff --git a/src/reactfire.js b/src/reactfire.js index 2db52ae1..600ce5b8 100644 --- a/src/reactfire.js +++ b/src/reactfire.js @@ -30,6 +30,41 @@ /*************/ /* HELPERS */ /*************/ + /** + * Returns the key of a Firebase snapshot across SDK versions. + * + * @param {DataSnapshot} snapshot A Firebase snapshot. + * @return {string|null} key The Firebase snapshot's key. + */ + function _getKey(snapshot) { + var key; + if (typeof snapshot.key === 'function') { + key = snapshot.key(); + } else if (typeof snapshot.key === 'string' || snapshot.key === null) { + key = snapshot.key; + } else { + key = snapshot.name(); + } + return key; + } + + /** + * Returns the reference of a Firebase snapshot or reference across SDK versions. + * + * @param {DataSnapshot|DatabaseReference} snapshotOrRef A Firebase snapshot or reference. + * @return {DatabaseReference} ref The Firebase reference corresponding to the inputted snapshot + * or reference. + */ + function _getRef(snapshotOrRef) { + var ref; + if (typeof snapshotOrRef.ref === 'function') { + ref = snapshotOrRef.ref(); + } else { + ref = snapshotOrRef.ref; + } + return ref; + } + /** * Returns the index of the key in the list. If an item with the key is not in the list, -1 is * returned. @@ -114,7 +149,7 @@ * @param {Firebase.DataSnapshot} snapshot A snapshot of the data being bound. */ function _objectValue(bindVar, snapshot) { - var key = snapshot.key(); + var key = _getKey(snapshot); var value = snapshot.val(); this.data[bindVar] = _createRecord(key, value); @@ -135,7 +170,7 @@ * is positioned; null if the provided snapshot is in the first position. */ function _arrayChildAdded(bindVar, snapshot, previousChildKey) { - var key = snapshot.key(); + var key = _getKey(snapshot); var value = snapshot.val(); var array = this.data[bindVar]; @@ -165,7 +200,7 @@ var array = this.data[bindVar]; // Look up the record's index in the array - var index = _indexForKey(array, snapshot.key()); + var index = _indexForKey(array, _getKey(snapshot)); // Splice out the record from the array array.splice(index, 1); @@ -181,7 +216,7 @@ * @param {Firebase.DataSnapshot} snapshot A snapshot of the data to bind. */ function _arrayChildChanged(bindVar, snapshot) { - var key = snapshot.key(); + var key = _getKey(snapshot); var value = snapshot.val(); var array = this.data[bindVar]; @@ -204,7 +239,7 @@ * is positioned; null if the provided snapshot is in the first position. */ function _arrayChildMoved(bindVar, snapshot, previousChildKey) { - var key = snapshot.key(); + var key = _getKey(snapshot); var array = this.data[bindVar]; // Look up the record's index in the array @@ -254,7 +289,7 @@ } // Keep track of the Firebase reference we are setting up listeners on - this.firebaseRefs[bindVar] = firebaseRef.ref(); + this.firebaseRefs[bindVar] = _getRef(firebaseRef); if (bindAsArray) { // Set initial state to an empty array diff --git a/tests/helpers.js b/tests/helpers.js index d86a7eda..45dc25c6 100644 --- a/tests/helpers.js +++ b/tests/helpers.js @@ -2,18 +2,5 @@ module.exports = { invalidFirebaseRefs: [null, undefined, true, false, [], 0, 5, '', 'a', ['hi', 1]], - invalidBindVars: ['', 1, true, false, [], {}, [1, 2], {a: 1}, null, undefined, 'te.st', 'te$st', 'te[st', 'te]st', 'te#st', 'te/st', 'a#i]$da[s', 'te/nst', 'te/rst', 'te/u0000st', 'te/u0015st', 'te/007Fst', Array(800).join('a')], - - /* Returns a random alphabetic string of variable length */ - generateRandomString: function() { - var possibleCharacters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'; - var numPossibleCharacters = possibleCharacters.length; - - var text = ''; - for (var i = 0; i < 10; i++) { - text += possibleCharacters.charAt(Math.floor(Math.random() * numPossibleCharacters)); - } - - return text; - } + invalidBindVars: ['', 1, true, false, [], {}, [1, 2], {a: 1}, null, undefined, 'te.st', 'te$st', 'te[st', 'te]st', 'te#st', 'te/st', 'a#i]$da[s', 'te/nst', 'te/rst', 'te/u0000st', 'te/u0015st', 'te/007Fst', Array(800).join('a')] }; diff --git a/tests/key.json.enc b/tests/key.json.enc new file mode 100644 index 00000000..bcfe3577 Binary files /dev/null and b/tests/key.json.enc differ diff --git a/tests/reactfire.spec.js b/tests/reactfire.spec.js index 095bda1b..ce651ad2 100644 --- a/tests/reactfire.spec.js +++ b/tests/reactfire.spec.js @@ -1,5 +1,7 @@ 'use strict'; +var path = require('path'); + // Mocha / Chai / Sinon var chai = require('chai'); var expect = chai.expect; @@ -11,7 +13,7 @@ var React = require('react'); var ReactTestUtils = require('react-addons-test-utils'); // ReactFire -var Firebase = require('firebase'); +var firebase = require('firebase'); var ReactFireMixin = require('../src/reactfire.js'); // JSDom @@ -21,8 +23,12 @@ global.document = jsdom.jsdom(); // Needed for ReactTestUtils shallow renderer // Test helpers var TH = require('./helpers.js'); -// Get a reference to a random demo Firebase -var demoFirebaseUrl = 'https://' + TH.generateRandomString() + '.firebaseio-demo.com'; + +// Initialize the Firebase SDK +firebase.initializeApp({ + databaseURL: process.env.REACTFIRE_TEST_DB_URL, + serviceAccount: path.resolve(__dirname, 'key.json') +}); describe('ReactFire', function() { @@ -32,12 +38,12 @@ describe('ReactFire', function() { beforeEach(function(done) { shallowRenderer = ReactTestUtils.createRenderer(); - firebaseRef = new Firebase(demoFirebaseUrl); + firebaseRef = firebase.database().ref().push(); firebaseRef.remove(function(error) { if (error) { done(error); } else { - firebaseRef = firebaseRef.child(TH.generateRandomString()); + firebaseRef = firebaseRef.push(); done(); } }); @@ -803,7 +809,7 @@ describe('ReactFire', function() { mixins: [ReactFireMixin], componentWillMount: function() { - var rootRef = firebaseRef.root(); + var rootRef = firebaseRef.root; this.bindAsObject(rootRef, 'item');