add example #1

Merged
merged 9 commits into from May 10, 2014

Conversation

Projects
None yet
2 participants
Owner

robey commented May 5, 2013

No description provided.

@zerotrickpony zerotrickpony and 1 other commented on an outdated diff May 5, 2013

docs/example.md
+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
@zerotrickpony

zerotrickpony May 5, 2013

you might say "fauna schema" or "fauna object schema" or "fauna classes", to clarify that your library doesn't require some other notion of a schema

@robey

robey Jun 4, 2013

Owner

fixed!

@zerotrickpony zerotrickpony and 1 other commented on an outdated diff May 5, 2013

docs/example.md
+
+```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:
@zerotrickpony

zerotrickpony May 5, 2013

you might call these "classes" instead of "models" to match Fauna's terminology. Or at least explain that you've got your own terminology ("model") that maps to Fauna's terminology ("class")

@robey

robey Jun 4, 2013

Owner

replaced "model" with "class" throughout this section.

@zerotrickpony zerotrickpony and 1 other commented on an outdated diff May 5, 2013

docs/example.md
+
+class User extends fauna.Class
+ @native()
+ @field "name"
+
+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.
@zerotrickpony

zerotrickpony May 5, 2013

is "live in fauna namespace" mean that this is now "fauna.User"? Is this something Coffeescript-specific? In Javascript this would just make "User" in the global namespace, which is what your JS code does below. Not clear what makes it be part of "fauna"... perhaps for clarity you ought to make the JS code below behave the same?

@zerotrickpony

zerotrickpony May 5, 2013

Ohhh when you say "namespace" you're probably referring to fauna's URL namespace, not the javascript variable namespace. I was confused at first.

@robey

robey Jun 4, 2013

Owner

i rewrote this whole paragraph to explain that Message becomes classes/messages, and why User needs to be marked native.

@zerotrickpony zerotrickpony commented on the diff May 5, 2013

docs/example.md
+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. 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
@zerotrickpony

zerotrickpony May 5, 2013

Since User is a built-in class, could fauna-js just provide it so that the caller doesn't have to define it? Or is there some reason why the caller ought to make their own User flavor?

@robey

robey Jun 4, 2013

Owner

i think i've clarified this in the new paragraph...

@zerotrickpony zerotrickpony commented on the diff May 5, 2013

docs/example.md
@@ -0,0 +1,298 @@
+
+# An example
+
+The best way to get the feel of this library is probably through a simple
@zerotrickpony

zerotrickpony May 5, 2013

You might add a one-liner that says something like "this doc assumes that you've read and understand the Fauna REST API [link], and uses its terms and concepts"

@zerotrickpony zerotrickpony and 1 other commented on an outdated diff May 5, 2013

docs/example.md
+}
+extends(ChatRoom, fauna.Class);
+ChatRoom.field("name");
+ChatRoom.eventSet("messages");
+```
+
+## Initialize
+
+First, we need to register our models with the fauna-js library:
+
+```javascript
+var faunaClient = require('fauna-js').FaunaClient;
+faunaClient.addPrototypes(User, Message, ChatRoom);
+```
+
+Fauna authentication takes a few forms (again, read the fauna documentation,
@robey

robey Jun 4, 2013

Owner

i don't want to link to the docs since they aren't public (and i don't know if/when they will be), but it does sound weird to keep telling people to read the docs. i added a pithy terse explanation sentence and removed the "again, read the docs" bit.

@zerotrickpony zerotrickpony commented on the diff May 5, 2013

docs/example.md
+- 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. 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:
@zerotrickpony

zerotrickpony May 5, 2013

It looks like the rest of the example is in javascript, so maybe the coffeescript here is distracting? If I were a JS programmer I think I would basically like to not see any coffeescript at all. And if I'm a coffeescript programmer i probably wouldn't mind reading the whole thing in JS (they must all be used to that) and then seeing the coffeescript analog all at once at the end.

@robey

robey Jun 4, 2013

Owner

hm, true, this is the only coffee-script on the page. the section below is meant to be the "also in javascript" bit, but it's too far separated. i'm going to merge it together. the coffee-script code is much clearer because js doesn't really have subclasses or static methods, so i do want to show the simple version first.

@zerotrickpony zerotrickpony and 1 other commented on an outdated diff May 5, 2013

docs/example.md
+
+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
+var faunaClient = require('fauna-js').FaunaClient;
+faunaClient.addPrototypes(User, Message, ChatRoom);
@zerotrickpony

zerotrickpony May 5, 2013

So is this making metadata creation calls on the Fauna server? Or simply registering these Javascript classes with the library? If the former, then it seems like you'd better explain publisher keys first...

@robey

robey Jun 4, 2013

Owner

the latter -- i'll add a sentence to explain that.

@zerotrickpony zerotrickpony and 1 other commented on an outdated diff May 5, 2013

docs/example.md
+```
+
+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
+faunaClient.setPublisherKey("...");
@zerotrickpony

zerotrickpony May 5, 2013

This is kind of odd because you'd definitely not want to put the publisher key into the client code. Which means that this aspect of the fauna-js library is only for use in an administration console or something. As I started reading this I expected it to be a client connection library, but now i see that it's also got administrative features rolled into it as well. It might be good to clarify these as very distinct.

@robey

robey Jun 4, 2013

Owner

reordered this a bit to explain the schema install, then authentication, and emphasize that this is only for a setup script.

@zerotrickpony zerotrickpony and 1 other commented on an outdated diff May 5, 2013

docs/example.md
+
+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,
@zerotrickpony

zerotrickpony May 5, 2013

_P_ost a message to it

@robey

robey Jun 4, 2013

Owner

fixed!

@zerotrickpony zerotrickpony commented on the diff May 5, 2013

docs/example.md
+
+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) {
@zerotrickpony

zerotrickpony May 5, 2013

in the fauna docs they show the JSON block that comes back from the server. I found that really helpful, and so I'd recommend putting something like that here. What does "room" look like? What other fields are in it besides what I got from the example?

@robey

robey Jun 4, 2013

Owner

i dunno. i just added a section on the "_fauna" object, but the rest of it should just be whatever's in the schema -- there isn't really a format.

Owner

robey commented May 5, 2013

separate admin-style commands from stuff you'd put in a real client (client key only etc)

@robey robey merged commit 236ebb4 into master May 10, 2014

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment