Permalink
Browse files

more feedback,

  • Loading branch information...
1 parent 7a35e89 commit fccc517a04edf0e1d0a34281ad9fcd5005223c8d @robey committed Jun 4, 2013
Showing with 41 additions and 38 deletions.
  1. +41 −38 docs/example.md
View
@@ -84,30 +84,8 @@ class ChatRoom extends fauna.Class
@eventSet "messages"
```
-User-defined classes live in the `classes/` namespace in fauna, so normally
-fauna-js will determine the fauna class name by converting the javascript
-class name to lowercase, adding an "s", and using the `classes/` namespace:
-`Message` becomes `classes/messages`. We've marked `User` as a native fauna
-class, so it will use the fauna built-in class `users` instead of creating a
-new user-defined class. But we can add our own fields and references here,
-just like any other class, so we add a display name.
-
-`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`). 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.
-
-`ChatRoom` has a name field, and also an event set for holding messages. Event
-sets are like containers with history -- but read the fauna documentation for
-the finer points.
-
-## Schema in javascript
-
-The javascript syntax for creating new prototypes and calling static methods
-on them is a bit more opaque, and requires a helper library to define the
-"extends" function, but it will generally look like this:
+It looks a little more opaque in javascript, because of the lack of syntax
+for extending objects and calling static methods:
```javascript
function User() {
@@ -132,15 +110,40 @@ ChatRoom.field("name");
ChatRoom.eventSet("messages");
```
+User-defined classes live in the `classes/` namespace in fauna, so normally
+fauna-js will determine the fauna class name by converting the javascript
+class name to lowercase, adding an "s", and using the `classes/` namespace:
+`Message` becomes `classes/messages`. We've marked `User` as a native fauna
+class, so it will use the fauna built-in class `users` instead of creating a
+new user-defined class. But we can add our own fields and references here,
+just like any other class, so we add a display name.
+
+`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`). 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.
+
+`ChatRoom` has a name field, and also an event set for holding messages. Event
+sets are like containers with history -- but read the fauna documentation for
+the finer points.
+
## Initialize
-First, we need to register our models with the fauna-js library:
+First, we need to register our classes with the fauna-js library. This lets
+fauna-js map incoming json objects into our model classes:
```javascript
var faunaClient = require('fauna-js').FaunaClient;
faunaClient.addPrototypes(User, Message, ChatRoom);
```
+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.
+
Fauna authentication uses different types of tokens to grant different access
levels. Fauna-js knows which API methods require which kind of authentication,
so usually you can set authentication keys once, and the library will use the
@@ -151,27 +154,22 @@ 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:
+So, to set the publisher key (which is needed to define new classes) and
+install our schema on the fauna servers:
```javascript
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.
+The 'installSchema' call just tells fauna about the names of the classes we've
+defined, and any event sets on those classes. This code should live in a setup
+script, and never in the client, because the publisher key should remain
+secret.
## Create a new user
-Okay, let's login to fauna as a user, make a chat room, most a message to it,
+Okay, let's login to fauna as a user, make a chat room, post a message to it,
and read the last 20 messages posted. Simple!
If no users exist yet, we should create one:
@@ -191,7 +189,12 @@ 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`.
+reference id in `id`. The `_fauna` object contains these useful fields:
+
+- `id`: the fauna resource reference ID
+- `className`: fauna class name
+- `ts`: javascript timestamp (milliseconds) of the last update
+- `deleted`: true/false if this refers to a deleted object
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

0 comments on commit fccc517

Please sign in to comment.