Permalink
Browse files

start of example docs.

  • Loading branch information...
robey committed May 5, 2013
1 parent c2bb3d3 commit 732a6ef7579c2bb13b1a810d694f0e6633507a3b
Showing with 151 additions and 0 deletions.
  1. +151 −0 docs/example.md
View
@@ -0,0 +1,151 @@
+
+# an example
+
+the best way to get the feel of this library is probably through a simple
+example. let's say we'd like to build a small chat server, like redpanda.
+
+## promises
+
+fauna-js is written in coffeescript and uses the Q promises library, but
+neither is necessary to use it. coffeescript is just a functional veneer on
+javascript, and Q is just an advanced form of the callback system used in
+node and jquery.
+
+instead of calling a fauna-js function with a callback as the last argemunt,
+like this:
+
+```javascript
+ 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
+function), like this:
+
+```javascript
+squirrel.findNuts(forest).then(function (nuts) {
+ ...
+}, function (error) {
+ ...
+});
+```
+
+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
+
+the first thing we need to do is define our schema. for the littlest chat
+server, we just need three models:
+
+- users
+- messages
+- chat rooms
+
+users already exist as a native model in fauna, but we'll create the other
+two. in addition, we need to define relationships between them.
+
+- a message is written by a user.
+- a chat room contains many messages.
+
+the first type of relationship is what database people call "one to many":
+each message is written by exactly one user, but each user may write many
+messages. in this case, we don't care about looking up which messages a user
+wrote -- we'll never ask "which messages did jack write?" -- so we only need
+to keep a reference on the message, pointing to the user who wrote it.
+
+the second type is also "one to many". each message is in one chat room, but
+each chat room may contain many messages. but in this case, we'll be asking
+questions in the opposite direction: what are the messages in each chat room?
+luckily, this relationship fits well with fauna's event system. each message
+can be added to a chat room as an event, and we can page through them in order
+of recency.
+
+so, in coffeescript, we'd have:
+
+```coffeescript
+fauna = require 'fauna'
+
+class User extends fauna.Class
+ @native()
+
+class Message extends fauna.Class
+ @field "text"
+ @reference "author"
+
+class ChatRoom extends fauna.Class
+ @field "name"
+ @eventSet "messages"
+```
+
+this defines a class `User` and marks it as a native fauna model, so it will
+live in the fauna namespace instead of being created as a user-defined class.
+`User` is usually the only class that needs this special treatment. we could
+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
+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 usually requires a helper library to define
+the "extend" function, but it will generally look like this:
+
+```javascript
+function User() {
+ fauna.Class.apply(this, arguments);
+}
+extends(User, fauna.Class);
+User.native();
+
+function Message() {
+ fauna.Class.apply(this, arguments);
+}
+extends(Message, fauna.Class);
+Message.field("text");
+Message.reference("author");
+
+function ChatRoom() {
+ fauna.Class.apply(this, arguments);
+}
+extends(ChatRoom, fauna.Class);
+ChatRoom.field("name");
+ChatRoom.eventSet("messages");
+```
+
+## initialize
+
+first, we need to register our models with the fauna-js library:
+
+```javascript
+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.
+
+```javascript
+// login as a publisher
+faunaClient.setPublisherKey("...");
+faunaClient.installSchema();
+```
+
+
+
+
+

0 comments on commit 732a6ef

Please sign in to comment.