framer-Firebase

The Firebase module allows your Framer prototype to load, save and sync data effortlessly between multiple sessions and devices.

Updated to support Promises.

Demo Projects

Simple	Advanced
Loads, saves and syncs slider.value w/ 2 lines of code	World's first(?) bubble popping MMO
Live @ firebaseSlider	Live @ firebaseBubbles

Placeholder	Advanced
	Like-counts, three of them
	Live @ firebaseLikes

These examples include access to a public demo database for the purpose of demonstration.

Please DON'T use this demo database for your projects! Your data will be deleted.

Getting started in under 5 minutes

OR

I'd also like to recommend reading Supercharge your Framer prototype with Firebase, pt.1 on Medium, if you haven't already.

Tips

Data

Data on Firebase is stored as JSON, the supported data types are: Number, String, Boolean, Array, Object and Null. For more information on JSON data types, please refer to the JSON article on Wikipedia.org.

The database used for the provided Demo Projects looks something like this:

Contact & Help

If you need further assistance or want to leave me some feedback,
you can reach me via Twitter, Facebook or Slack.

Firebase Class Reference

This module is based on Firebase's REST API.

1) Properties

• firebase.projectID, firebase.secret

The property projectID is required for the module to work.

secret is now an optional property and it can be either set (see below) or it can be substitued by changing your database access rules.

The required information is located at https://firebase.google.com → Console → YourProject → ...

firebase = new Firebase
  projectID: ___________ # 1) ... Database → first part of URL
  secret: ______________ # 2) ... Project Settings → Service Accounts → Database Secrets → Show (mouse-over)

1) projectID	2) secret

Protip: Contrary to what I did in the gif, I advise you NOT to share your Firebase secret publicly, as it allow others to alter the data stored in your database. If you do so by accident, you can always revoke access by deleting the shared secret and creating a new one at https://firebase.google.com → Console → Project Settings → Service Accounts → Database Secrets.

• firebase.secret

Optional: If you wish not to use and share your database secret in your Framer project like shown above, you can do the following instead:

{
  "rules": {
  ".read": "true",
  ".write": "true"
  }
}

Caution: Similar to sharing your database secret key publicly, this will grant everyone on the web with write-access, which will allow everyone to read and modify data saved in your database! Please only share your projects (and Firebase projectIDs) with people you trust.

• firebase.debug

If set to true, relevant connection messages will be logged to the console.

• firebase.status (read only)

Returns the current connection status, either "connected" or "disconnected".

2) Methods

Overview

Protip: As a beginner, you can ignore separated callback-functions and parameters.

• firebase.get(path, callback, parameters)

Retrieves data from the database.

Examples:

# Simple 1, expecting single value
firebase.get "/value", (value) ->
  print value

# Promise
firebase.get "/value"
.then (value) -> print value

# Simple 2, expecting dataset
firebase.get "/names", (names) ->
  namesArray = _.toArray(names) # converts JSON to array
  print name for name in namesArray

# Promise
firebase.get "/names"
.then (names) ->
  namesArray = _.toArray(names) # converts JSON to array
  print name for name in namesArray

# Advanced
response = (names) ->
  namesArray = _.toArray(names)
  print name for name in namesArray

firebase.get("/names",response,{orderBy: "$key", limitToFirst: 5})

# Promise
firebase.get("/names",{orderBy: "$key", limitToFirst: 5})
.then(response)

• firebase.put(path, data, callback, parameters)

Writes data to the database.

If the path does not exist, it will be created, if it does exist, the specified node will be updated with the new data.

The following data types are supported: Number, String, Boolean, Array, Object and Null.
For more information on JSON data types, please refer to the JSON article on Wikipedia.org.

Tip: To update data without deleting omitted children- or sibling-nodes, use firebase.patch() instead.

Examples:

# Simple
firebase.put("/value", true)

# Advanced
response = (confirmation) ->
  print confirmation

firebase.put("/values", {"foo": true, "bar": false}, response)

# Promise
firebase.put("/values", {"foo": true, "bar": false})
.then(response)

• firebase.post(path, data, callback, parameters)

Adds data to the specified path using a random key (eg. "/addressBook/-KIU9s3bWOpODk9cai_n/").

This is useful when adding new data to a node (eg. adding a new entry to an address book). The random key also prevents possible data interference between multiple, concurrent users.

The following data types are supported: Number, String, Boolean, Array, Object and Null.
For more information on JSON data types, please refer to the JSON article on Wikipedia.org.

Examples:

# Simple
firebase.post("/value", true)

# Advanced
firebase.post("/addressBook", { # JSON encoded:
  "name" :  {
      "forename" : "Jane",
      "surename" : "Doe"
      }

  "birthday" :  {
     "day"  : 4,
     "month": 7,
     "year" : 1976
     }

  "tel" : "202-555-0101"
  })

• firebase.patch(path, data, callback, parameters)

Updates data of the specified path, without deleting omitted sibling-nodes.

Example:

firebase.patch("/values/foo", false) # `/values/bar´ persists

• firebase.delete(path, callback, parameters)

Deletes the node and children of the specified path.

Example:

firebase.delete("/values")

• firebase.onChange(path or "connection", callback)

Monitoring a database path:
Fires, when the Framer project is loaded (returns all current data of the path) and whenever some of its data was changed (returns only the newly added or changed data), across multiple devices or browser windows. If it returns null, the node has been deleted.

Example:

# Simple
firebase.onChange "/values", (value) ->
  print value

# Advanced
response = (data, method, path, breadcrumbs) ->
  # method returns either `put´ or `patch´, depending on what method changed the data
  # path returns the path that was changed
  # breadcrumbs returns the path as segments (array)
  print "received #{data} via #{method}"

firebase.onChange("/values", response)

Monitoring the connection status:
First argument must be set to "connection".
Fires, whenever the connection status to Firebase has changed.

Example:

firebase.onChange "connection", (status) ->
  # status is either `connected´ or `disconnected´
  print "Hooray, we're connected to Firebase" if status is "connected"

# Or

firebase.onChange "connection" -> print "Current connection status: #{firebase.status}"

3) Parameters:

Available parameters:

• OrderBy- and Limit-parameters:

For further information on how to order or limit requests please refer to Firebase REST Guide / Retriving data.

orderBy-parameter

Indexing example:

{
  "rules":  {
   ".read": "auth != null",
   ".write": "auth != null",
   "routes": {".indexOn": ["distance"]}
   }
}

Limit-paramters

Note: Limit-parameters require the orderBy-parameter to be set.