From 686106d544ecc3b6ffd4db2b665d3bc879a58d8c Mon Sep 17 00:00:00 2001
From: Jules Laplace <jules@okfoc.us>
Date: Mon, 24 Sep 2012 16:22:07 -0400
Subject: ok

---
 node_modules/mongoose/docs/embedded-documents.md | 79 ++++++++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 node_modules/mongoose/docs/embedded-documents.md

(limited to 'node_modules/mongoose/docs/embedded-documents.md')

diff --git a/node_modules/mongoose/docs/embedded-documents.md b/node_modules/mongoose/docs/embedded-documents.md
new file mode 100644
index 0000000..10b6aae
--- /dev/null
+++ b/node_modules/mongoose/docs/embedded-documents.md
@@ -0,0 +1,79 @@
+
+Embedded Documents
+==================
+
+Embedded documents are documents with schemas of their own that are part of
+other documents (as items within an array).
+
+Embedded documents enjoy all the same features as your models. Defaults,
+validators, middleware. Whenever an error occurs, it's bubbled to the `save()`
+error callback, so error handling is a snap!
+
+Mongoose interacts with your embedded documents in arrays _atomically_, out of
+the box.
+
+## Definition and initialization
+
+When you define a Schema like this:
+
+    var Comments = new Schema({
+        title     : String
+      , body      : String
+      , date      : Date
+    });
+
+    var BlogPost = new Schema({
+        author    : ObjectId
+      , title     : String
+      , body      : String
+      , date      : Date
+      , comments  : [Comments]
+      , meta      : {
+            votes : Number
+          , favs  : Number
+        }
+    });
+
+    mongoose.model('BlogPost', BlogPost);
+
+The `comments` key of your `BlogPost` documents will then be an instance of
+`DocumentArray`. This is a special subclassed `Array` that can deal with
+casting, and has special methods to work with embedded documents.
+
+## Adding an embedded document to an array
+
+    // retrieve my model
+    var BlogPost = mongoose.model('BlogPost');
+
+    // create a blog post
+    var post = new BlogPost();
+
+    // create a comment
+    post.comments.push({ title: 'My comment' });
+
+    post.save(function (err) {
+      if (!err) console.log('Success!');
+    });
+
+## Removing an embedded document
+
+    BlogPost.findById(myId, function (err, post) {
+      if (!err) {
+        post.comments[0].remove();
+        post.save(function (err) {
+          // do something
+        });
+      }
+    });
+
+## Finding an embedded document by id
+
+`DocumentArray`s have an special method `id` that filters your embedded
+documents by their `_id` property (each embedded document gets one):
+
+Consider the following snippet:
+
+    post.comments.id(my_id).remove();
+    post.save(function (err) {
+      // embedded comment with id `my_id` removed!
+    });
-- 
cgit v1.2.3-70-g09d2