Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

flesh out more of this.

  • Loading branch information...
commit 5e100a452e28f771c63c6d5964f9b3ad83476720 1 parent 732a6ef
@robey authored
Showing with 129 additions and 14 deletions.
  1. +129 −14 docs/example.md
View
143 docs/example.md
@@ -15,13 +15,13 @@ instead of calling a fauna-js function with a callback as the last argemunt,
like this:
```javascript
- squirrel.findNuts(forest, function (error, nuts) {
- ...
- });
+squirrel.findNuts(forest, function (error, nuts) {
+ ...
+});
```
-the function will return a new object which has a "then" method. you call the
-"then" method with your callback function (and optionally an error-handling
+the function will return a new object which has a `then` method. you call the
+`then` method with your callback function (and optionally an error-handling
function), like this:
```javascript
@@ -32,7 +32,7 @@ squirrel.findNuts(forest).then(function (nuts) {
});
```
-in both cases, the callback functions are called when the 'findNuts' operation
+in both cases, the callback functions are called when the `findNuts` operation
is finished, either by finding nuts, or because there was an error.
## schema
@@ -88,7 +88,7 @@ add our own fields and references here, just like any other class.
`Message` has a text field for the message content, and a reference named
"author". marking it as a reference lets fauna know that it's a reference to
another object in the database (usually with an identifier like
-"`user/95183857239`" or "`classes/message/18374838271`"). usually, when
+`user/95183857239` or `classes/message/18374838271`). usually, when
responding to a query, fauna will helpfully look up these objects and fill
them in, so that our response doesn't contain just the object id, but the
whole object.
@@ -101,7 +101,7 @@ the finer points.
the javascript syntax for creating new prototypes and calling static methods
on them is a bit more opaque, and usually requires a helper library to define
-the "extend" function, but it will generally look like this:
+the "extends" function, but it will generally look like this:
```javascript
function User() {
@@ -130,21 +130,136 @@ ChatRoom.eventSet("messages");
first, we need to register our models with the fauna-js library:
```javascript
-faunaClient = require('fauna-js').FaunaClient;
+var faunaClient = require('fauna-js').FaunaClient;
faunaClient.addPrototypes(User, Message, ChatRoom);
```
-then, we need to tell fauna about our user-defined classes (or models). we
-can do this as often as we want, and fauna will just ignore us if it already
-knows about these models. it requires publisher-level access, though, so we
-should do it from a tool outside the app.
+fauna authentication takes a few forms (again, read the fauna documentation,
+if you haven't already). fauna-js knows which methods require which kind of
+authentication, so usually you can set authentication keys once, and the
+library will use the right kind of authentication for each call. if a fauna
+request can be authenticated multiple ways, fauna-js prefers to use a less-
+capable key first. for example, if a fauna operation can be done by either a
+user or publisher, then fauna-js will use a user token if one has been set,
+falling back to a publisher token otherwise. if a key of the right type hasn't
+been set, an exception will be thrown without bothering to talk to the server.
+
+so, to set the publisher key, which is needed to define new classes:
```javascript
-// login as a publisher
faunaClient.setPublisherKey("...");
+```
+
+we can tell fauna about our user-defined classes (or models) as often as we
+want, and fauna will just ignore us if it already knows about these models.
+since it requires publisher-level access, though, we should do it from a tool
+outside the app.
+
+```javascript
faunaClient.installSchema();
```
+the 'installSchema' call just tells fauna about the names of the
+classes/models we've defined, and any event sets on those classes.
+
+## create a new user
+
+okay, let's login to fauna as a user, make a chat room, most a message to it,
+and read the last 20 messages posted. simple!
+
+if no users exist yet, we should create one:
+
+```javascript
+var user = new User({ email: "rocky@example.com", password: "acornz" });
+user.persist().then(function (user) {
+ console.log("Created a new user: " + user);
+ console.log("The new user's id is: " + user._fauna.id);
+});
+```
+
+to create a new object ("instance") in fauna, just create a new javascript
+object out of a fauna model prototype, and persist it. this works fine for
+native (built-in) types like `User` as well as our own user-defined classes.
+
+the callback receives a "user" object, but its the same object you passed in,
+and is only chained into the callback for convenience. the fauna identifiers
+are attached to the object in a new `_fauna` field, which contains the fauna
+reference id in `id`.
+
+the default constructor for a fauna-js `Class` takes an object and copies the
+fields into the new fauna object. this is just a convenience; you can also set
+them manually:
+
+```javascript
+var user = new User();
+user.email = "rocky@example.com";
+user.password = "acornz";
+user.persist().then( ... );
+```
+
+for user objects, fauna-js knows that `email` and `password` are built-in
+fields. if we had defined other fields or references on the class, we could
+set them the same way in the constructor, and fauna-js would put them into the
+`data` and `references` sections of the object inside the fauna database.
+
+the `persist` call may look a little magical, but it's using the `FaunaClient`
+that the `User` prototype was registered with. if you're juggling multiple
+`FaunaClient`s for some reason, you can pass one to `persist` to override the
+default.
+
+## login as a user
+
+if you already have an auth token for a user, setting it is easy:
+
+```javascript
+faunaClient.loginWithToken(userId, token).then(function (user) {
+ ...
+});
+```
+
+fauna-js will use the token to attempt to fetch the user object, so you can
+tell immediately if the token is invalid. the user object is passed into the
+promise.
+
+if you don't have an auth token for a user, you can get one by logging in:
+
+```javascript
+faunaClient.login(email, password).then(function (token) {
+ console.log("auth token is: " + token.token);
+});
+```
+
+## create a new chat room and post a message
+
+creating a new chat room is identical to creating a new user.
+
+```javascript
+var room = new ChatRoom({ name: "woodland creatures" });
+room.persist().then(function (room) {
+ console.log("The new room's id is: " + room._fauna.id);
+});
+```
+
+creating a new message is more of the same, but this time we'll use the
+promise callback to add the new message to our chat room's "messages" event
+set.
+
+```javascript
+var message = new Message({ text: "hello everybody!", author: user });
+message.persist().then(function (message) {
+ room.messages.add(message).then(function () {
+ ...
+ });
+});
+```
+
+notice that we pass an object for the `author` reference in the new message.
+since we told fauna-js that it's a reference, it'll pull out the object
+identifier and put it in the "references" section of the object.
+
+### read recent messages
+
+
Please sign in to comment.
Something went wrong with that request. Please try again.