Permalink
Browse files

fix ga and use layouts

  • Loading branch information...
1 parent 221cfee commit 878d4d632b8d1d1a56e3fd4620cc8b82e58199dd @aheckmann aheckmann committed Aug 8, 2012
View
12 docs/contributing.html
@@ -1,3 +1,11 @@
-<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"><title>Mongoose Quick Start v3.0.0</title><link href="http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700" rel="stylesheet" type="text/css"><link href="/docs/css/default.css" rel="stylesheet" type="text/css"><link href="/docs/css/guide.css" rel="stylesheet" type="text/css"></head><body><a id="forkbanner" href="http://github.com/learnboost/mongoose"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" alt="Fork me on GitHub"></a><div id="links"><div id="header"><h1><a href="../index.html"><div class="mongoose">Mongoose</div></a></h1></div><ul><li class="home"><a href="../index.html">home</a></li><li class="plugins"><a href="http://plugins.mongoosejs.com">plugins</a></li><li class="changelog"><a href="http://github.com/learnboost/mongoose/tree/master/History.md">change log</a></li><li class="support"><a href="../index.html#support">support</a></li><li class="fork"><a href="http://github.com/learnboost/mongoose">fork</a></li><li class="guide"><a href="./guide.html">guide</a><ul><li class="double"><a href="./guide.html">schemas</a><ul><li class="schematypes"><a href="./schematypes.html"><span>schema</span>types</a></li></ul></li><li class="double"><a href="./documents.html">documents</a><ul><li class="subdocs"><a href="./subdocs.html">sub docs</a></li></ul></li><li><a href="./models.html">models</a></li><li><a href="./queries.html">queries</a></li><li><a href="./plugins.html">plugins</a></li><li><a href="./middleware.html">middleware</a></li><li><a href="./validation.html">validation</a></li><li><a href="./populate.html">populate</a></li><li><a href="./migration.html">migrating from 2.x</a></li><li><a href="./contributing.html">contributing</a></li></ul></li><li class="api"><a href="./api.html">api docs</a></li><li class="quickstart"><a href="./index.html">quick start</a></li><li class="contrib"><a href="http://github.com/learnboost/mongoose/contributors">contributors</a></li><li class="prior"><a href="./prior.html">prior releases</a></li></ul></div><div id="content"><div class="module"><h2>Contributing</h2><h3>Bugfixes</h3><ul><li>Before starting to write code, look for existing <a href="https://github.com/learnboost/mongoose/issues">tickets</a> or <a href="https://github.com/learnboost/mongoose/issues/new">create one</a> for your specific issue. That way you avoid working on something that might not be of interest or that has been addressed already in a different branch.</li><li>Fork the <a href="https://github.com/learnboost/mongoose">repo</a> <em>or</em> for small documentation changes, navigate to the source on github and click the <a href="https://github.com/blog/844-forking-with-the-edit-button">Edit</a> button.</li><li>Write inline documentation for new methods or class members.</li><li>Write tests and make sure they pass (execute <code>make test</code> from the cmd line to run the test suite).</li><li>Follow the general coding style of the rest of the project (comma first, etc).</li></ul><h3>Documentation</h3><p>To contribute to the <a href="./api.html">API documentation</a> just make your changes to the inline documentation of the appropriate <a href="https://github.com/LearnBoost/mongoose/tree/master/lib">source code</a> in the master branch and submit a <a href="https://help.github.com/articles/using-pull-requests/">pull request</a>. You might also use the github <a href="https://github.com/blog/844-forking-with-the-edit-button">Edit</a> button.</p>
+<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"><title>Mongoose Contributing v3.0.0</title><link href="http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700" rel="stylesheet" type="text/css"><link href="/docs/css/default.css" rel="stylesheet" type="text/css"><link href="/docs/css/guide.css" rel="stylesheet" type="text/css"></head><body><a id="forkbanner" href="http://github.com/learnboost/mongoose"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" alt="Fork me on GitHub"></a><div id="links"><div id="header"><h1><a href="../index.html"><div class="mongoose">Mongoose</div></a></h1></div><ul><li class="home"><a href="../index.html">home</a></li><li class="plugins"><a href="http://plugins.mongoosejs.com">plugins</a></li><li class="changelog"><a href="http://github.com/learnboost/mongoose/tree/master/History.md">change log</a></li><li class="support"><a href="../index.html#support">support</a></li><li class="fork"><a href="http://github.com/learnboost/mongoose">fork</a></li><li class="guide"><a href="./guide.html">guide</a><ul><li class="double"><a href="./guide.html">schemas</a><ul><li class="schematypes"><a href="./schematypes.html"><span>schema</span>types</a></li></ul></li><li class="double"><a href="./documents.html">documents</a><ul><li class="subdocs"><a href="./subdocs.html">sub docs</a></li></ul></li><li><a href="./models.html">models</a></li><li><a href="./queries.html">queries</a></li><li><a href="./plugins.html">plugins</a></li><li><a href="./middleware.html">middleware</a></li><li><a href="./validation.html">validation</a></li><li><a href="./populate.html">populate</a></li><li><a href="./migration.html">migrating from 2.x</a></li><li><a href="./contributing.html">contributing</a></li></ul></li><li class="api"><a href="./api.html">api docs</a></li><li class="quickstart"><a href="./index.html">quick start</a></li><li class="contrib"><a href="http://github.com/learnboost/mongoose/contributors">contributors</a></li><li class="prior"><a href="./prior.html">prior releases</a></li></ul></div><div id="content"><div class="module"><h2>Contributing</h2><h3>Bugfixes</h3><ul><li>Before starting to write code, look for existing <a href="https://github.com/learnboost/mongoose/issues">tickets</a> or <a href="https://github.com/learnboost/mongoose/issues/new">create one</a> for your specific issue. That way you avoid working on something that might not be of interest or that has been addressed already in a different branch.</li><li>Fork the <a href="https://github.com/learnboost/mongoose">repo</a> <em>or</em> for small documentation changes, navigate to the source on github and click the <a href="https://github.com/blog/844-forking-with-the-edit-button">Edit</a> button.</li><li>Write inline documentation for new methods or class members.</li><li>Write tests and make sure they pass (execute <code>make test</code> from the cmd line to run the test suite).</li><li>Follow the general coding style of the rest of the project (comma first, etc).</li></ul><h3>Documentation</h3><p>To contribute to the <a href="./api.html">API documentation</a> just make your changes to the inline documentation of the appropriate <a href="https://github.com/LearnBoost/mongoose/tree/master/lib">source code</a> in the master branch and submit a <a href="https://help.github.com/articles/using-pull-requests/">pull request</a>. You might also use the github <a href="https://github.com/blog/844-forking-with-the-edit-button">Edit</a> button.</p>
-<p>To contribute to the <a href="./guide.html">guide</a> or <a href="./index.html">quick start</a> docs, make your changes to the appropriate <code>.jade</code> files in the <a href="https://github.com/LearnBoost/mongoose/tree/master/docs">docs</a> directory of the master branch and submit a pull request. Again, the <a href="https://github.com/blog/844-forking-with-the-edit-button">Edit</a> button might work for you here.</p><h3>Plugins</h3><p>The <a href="http://plugins.mongoosejs.com/">plugins</a> site is also an <a href="https://github.com/aheckmann/mongooseplugins">open source project</a> that you can get involved with. Feel free to fork and improve it as well!</p></div></div></body></html>
+<p>To contribute to the <a href="./guide.html">guide</a> or <a href="./index.html">quick start</a> docs, make your changes to the appropriate <code>.jade</code> files in the <a href="https://github.com/LearnBoost/mongoose/tree/master/docs">docs</a> directory of the master branch and submit a pull request. Again, the <a href="https://github.com/blog/844-forking-with-the-edit-button">Edit</a> button might work for you here.</p><h3>Plugins</h3><p>The <a href="http://plugins.mongoosejs.com/">plugins</a> site is also an <a href="https://github.com/aheckmann/mongooseplugins">open source project</a> that you can get involved with. Feel free to fork and improve it as well!</p></div></div><script>document.body.className = 'load';</script><script>var _gaq = _gaq || [];
+_gaq.push(['_setAccount', 'UA-1122274-9']);
+_gaq.push(['_trackPageview']);
+
+(function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+})();</script></body></html>
View
53 docs/contributing.jade
@@ -1,39 +1,22 @@
-doctype html
-html(lang='en')
- head
- meta(charset="utf-8")
- meta(name="viewport", content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no")
- title Mongoose Quick Start v#{package.version}
- link(href='http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700', rel='stylesheet', type='text/css')
- link(href='/docs/css/default.css', rel='stylesheet', type='text/css')
- link(href='/docs/css/guide.css', rel='stylesheet', type='text/css')
- body
- a#forkbanner(href="http://github.com/learnboost/mongoose")
- img(style="position: absolute; top: 0; right: 0; border: 0;", src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png", alt="Fork me on GitHub")
- #links
- #header
- h1
- a(href="../index.html")
- .mongoose Mongoose
- include includes/nav
- #content
- .module
- h2 Contributing
+extends layout
- h3 Bugfixes
- :markdown
- - Before starting to write code, look for existing [tickets](https://github.com/learnboost/mongoose/issues) or [create one](https://github.com/learnboost/mongoose/issues/new) for your specific issue. That way you avoid working on something that might not be of interest or that has been addressed already in a different branch.
- - Fork the [repo](https://github.com/learnboost/mongoose) _or_ for small documentation changes, navigate to the source on github and click the [Edit](https://github.com/blog/844-forking-with-the-edit-button) button.
- - Write inline documentation for new methods or class members.
- - Write tests and make sure they pass (execute `make test` from the cmd line to run the test suite).
- - Follow the general coding style of the rest of the project (comma first, etc).
+block content
+ h2 Contributing
- h3 Documentation
- :markdown
- To contribute to the [API documentation](./api.html) just make your changes to the inline documentation of the appropriate [source code](https://github.com/LearnBoost/mongoose/tree/master/lib) in the master branch and submit a [pull request](https://help.github.com/articles/using-pull-requests/). You might also use the github [Edit](https://github.com/blog/844-forking-with-the-edit-button) button.
+ h3 Bugfixes
+ :markdown
+ - Before starting to write code, look for existing [tickets](https://github.com/learnboost/mongoose/issues) or [create one](https://github.com/learnboost/mongoose/issues/new) for your specific issue. That way you avoid working on something that might not be of interest or that has been addressed already in a different branch.
+ - Fork the [repo](https://github.com/learnboost/mongoose) _or_ for small documentation changes, navigate to the source on github and click the [Edit](https://github.com/blog/844-forking-with-the-edit-button) button.
+ - Write inline documentation for new methods or class members.
+ - Write tests and make sure they pass (execute `make test` from the cmd line to run the test suite).
+ - Follow the general coding style of the rest of the project (comma first, etc).
- To contribute to the [guide](./guide.html) or [quick start](./index.html) docs, make your changes to the appropriate `.jade` files in the [docs](https://github.com/LearnBoost/mongoose/tree/master/docs) directory of the master branch and submit a pull request. Again, the [Edit](https://github.com/blog/844-forking-with-the-edit-button) button might work for you here.
+ h3 Documentation
+ :markdown
+ To contribute to the [API documentation](./api.html) just make your changes to the inline documentation of the appropriate [source code](https://github.com/LearnBoost/mongoose/tree/master/lib) in the master branch and submit a [pull request](https://help.github.com/articles/using-pull-requests/). You might also use the github [Edit](https://github.com/blog/844-forking-with-the-edit-button) button.
- h3 Plugins
- :markdown
- The [plugins](http://plugins.mongoosejs.com/) site is also an [open source project](https://github.com/aheckmann/mongooseplugins) that you can get involved with. Feel free to fork and improve it as well!
+ To contribute to the [guide](./guide.html) or [quick start](./index.html) docs, make your changes to the appropriate `.jade` files in the [docs](https://github.com/LearnBoost/mongoose/tree/master/docs) directory of the master branch and submit a pull request. Again, the [Edit](https://github.com/blog/844-forking-with-the-edit-button) button might work for you here.
+
+ h3 Plugins
+ :markdown
+ The [plugins](http://plugins.mongoosejs.com/) site is also an [open source project](https://github.com/aheckmann/mongooseplugins) that you can get involved with. Feel free to fork and improve it as well!
View
12 docs/documents.html
@@ -1,4 +1,4 @@
-<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"><title>Mongoose Quick Start v3.0.0</title><link href="http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700" rel="stylesheet" type="text/css"><link href="/docs/css/default.css" rel="stylesheet" type="text/css"><link href="/docs/css/guide.css" rel="stylesheet" type="text/css"></head><body><a id="forkbanner" href="http://github.com/learnboost/mongoose"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" alt="Fork me on GitHub"></a><div id="links"><div id="header"><h1><a href="../index.html"><div class="mongoose">Mongoose</div></a></h1></div><ul><li class="home"><a href="../index.html">home</a></li><li class="plugins"><a href="http://plugins.mongoosejs.com">plugins</a></li><li class="changelog"><a href="http://github.com/learnboost/mongoose/tree/master/History.md">change log</a></li><li class="support"><a href="../index.html#support">support</a></li><li class="fork"><a href="http://github.com/learnboost/mongoose">fork</a></li><li class="guide"><a href="./guide.html">guide</a><ul><li class="double"><a href="./guide.html">schemas</a><ul><li class="schematypes"><a href="./schematypes.html"><span>schema</span>types</a></li></ul></li><li class="double"><a href="./documents.html">documents</a><ul><li class="subdocs"><a href="./subdocs.html">sub docs</a></li></ul></li><li><a href="./models.html">models</a></li><li><a href="./queries.html">queries</a></li><li><a href="./plugins.html">plugins</a></li><li><a href="./middleware.html">middleware</a></li><li><a href="./validation.html">validation</a></li><li><a href="./populate.html">populate</a></li><li><a href="./migration.html">migrating from 2.x</a></li><li><a href="./contributing.html">contributing</a></li></ul></li><li class="api"><a href="./api.html">api docs</a></li><li class="quickstart"><a href="./index.html">quick start</a></li><li class="contrib"><a href="http://github.com/learnboost/mongoose/contributors">contributors</a></li><li class="prior"><a href="./prior.html">prior releases</a></li></ul></div><div id="content"><div class="module"><h2>Documents</h2><p>Mongoose <a href="./api.html#document-js">documents</a> represent a one-to-one mapping to documents as stored in MongoDB. Each document is an instance of its <a href="./models.html">Model</a>.</p><h3>Retreiving</h3><p>There are many ways to retreive documents from MongoDB. We won&#39;t cover that in this section. See the chapter on <a href="./queries.html">querying</a> for detail.</p><h3>Updating</h3><p>There are a number of ways to update documents. We&#39;ll first look at a traditional approach using <a href="./api.html#model_Model-findById">findById</a>:</p><pre><code class="javascript">Tank.findById(id, <span class="function"><span class="keyword">function</span> <span class="params">(err, tank)</span> {</span>
+<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"><title>Mongoose Documents v3.0.0</title><link href="http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700" rel="stylesheet" type="text/css"><link href="/docs/css/default.css" rel="stylesheet" type="text/css"><link href="/docs/css/guide.css" rel="stylesheet" type="text/css"></head><body><a id="forkbanner" href="http://github.com/learnboost/mongoose"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" alt="Fork me on GitHub"></a><div id="links"><div id="header"><h1><a href="../index.html"><div class="mongoose">Mongoose</div></a></h1></div><ul><li class="home"><a href="../index.html">home</a></li><li class="plugins"><a href="http://plugins.mongoosejs.com">plugins</a></li><li class="changelog"><a href="http://github.com/learnboost/mongoose/tree/master/History.md">change log</a></li><li class="support"><a href="../index.html#support">support</a></li><li class="fork"><a href="http://github.com/learnboost/mongoose">fork</a></li><li class="guide"><a href="./guide.html">guide</a><ul><li class="double"><a href="./guide.html">schemas</a><ul><li class="schematypes"><a href="./schematypes.html"><span>schema</span>types</a></li></ul></li><li class="double"><a href="./documents.html">documents</a><ul><li class="subdocs"><a href="./subdocs.html">sub docs</a></li></ul></li><li><a href="./models.html">models</a></li><li><a href="./queries.html">queries</a></li><li><a href="./plugins.html">plugins</a></li><li><a href="./middleware.html">middleware</a></li><li><a href="./validation.html">validation</a></li><li><a href="./populate.html">populate</a></li><li><a href="./migration.html">migrating from 2.x</a></li><li><a href="./contributing.html">contributing</a></li></ul></li><li class="api"><a href="./api.html">api docs</a></li><li class="quickstart"><a href="./index.html">quick start</a></li><li class="contrib"><a href="http://github.com/learnboost/mongoose/contributors">contributors</a></li><li class="prior"><a href="./prior.html">prior releases</a></li></ul></div><div id="content"><div class="module"><h2>Documents</h2><p>Mongoose <a href="./api.html#document-js">documents</a> represent a one-to-one mapping to documents as stored in MongoDB. Each document is an instance of its <a href="./models.html">Model</a>.</p><h3>Retreiving</h3><p>There are many ways to retreive documents from MongoDB. We won&#39;t cover that in this section. See the chapter on <a href="./queries.html">querying</a> for detail.</p><h3>Updating</h3><p>There are a number of ways to update documents. We&#39;ll first look at a traditional approach using <a href="./api.html#model_Model-findById">findById</a>:</p><pre><code class="javascript">Tank.findById(id, <span class="function"><span class="keyword">function</span> <span class="params">(err, tank)</span> {</span>
<span class="keyword">if</span> (err) <span class="keyword">return</span> handleError(err);
tank.size = <span class="string">'large'</span>;
@@ -9,4 +9,12 @@
});</code></pre><p>This approach involves first retreiving the document from Mongo, then issuing an update command (triggered by calling <code>save</code>). However, if we don&#39;t need the document returned in our application and merely want to update a property in the database directly, <a href="./api.html#model_Model-update">Model#update</a> is right for us:</p><pre><code class="javascript">Tank.update({ _id: id }, { $set: { size: <span class="string">'large'</span> }}, callback);</code></pre><p>If we do need the document returned in our application there is another, often <a href="./api.html#model_Model-findByIdAndUpdate">better</a>, option:</p><pre><code class="javascript">Tank.findByIdAndUpdate(id, { $set: { size: <span class="string">'large'</span> }}, <span class="function"><span class="keyword">function</span> <span class="params">(err, tank)</span> {</span>
<span class="keyword">if</span> (err) <span class="keyword">return</span> handleError(err);
res.send(tank);
-});</code></pre><p>The <code>findAndUpdate/Remove</code> static methods all make a change to at most one document, and return it with just one call to the database. There <a href="./api.html#model_Model-findByIdAndRemove">are</a> <a href="./api.html#model_Model-findOneAndUpdate">several</a> <a href="./api.html#model_Model-findOneAndRemove">variations</a> on the <a href="http://www.mongodb.org/display/DOCS/findAndModify+Command">findAndModify</a> theme. Read the <a href="./api.html">API</a> docs for more detail.</p><h3>Validating</h3><p>Documents are validated before they are saved. Read the <a href="./api.html#document_Document-validate">api</a> docs or the <a href="./validation.html">validation</a> chapter for detail.</p></div></div></body></html>
+});</code></pre><p>The <code>findAndUpdate/Remove</code> static methods all make a change to at most one document, and return it with just one call to the database. There <a href="./api.html#model_Model-findByIdAndRemove">are</a> <a href="./api.html#model_Model-findOneAndUpdate">several</a> <a href="./api.html#model_Model-findOneAndRemove">variations</a> on the <a href="http://www.mongodb.org/display/DOCS/findAndModify+Command">findAndModify</a> theme. Read the <a href="./api.html">API</a> docs for more detail.</p><h3>Validating</h3><p>Documents are validated before they are saved. Read the <a href="./api.html#document_Document-validate">api</a> docs or the <a href="./validation.html">validation</a> chapter for detail.</p></div></div><script>document.body.className = 'load';</script><script>var _gaq = _gaq || [];
+_gaq.push(['_setAccount', 'UA-1122274-9']);
+_gaq.push(['_trackPageview']);
+
+(function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+})();</script></body></html>
View
91 docs/documents.jade
@@ -1,55 +1,38 @@
-doctype html
-html(lang='en')
- head
- meta(charset="utf-8")
- meta(name="viewport", content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no")
- title Mongoose Quick Start v#{package.version}
- link(href='http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700', rel='stylesheet', type='text/css')
- link(href='/docs/css/default.css', rel='stylesheet', type='text/css')
- link(href='/docs/css/guide.css', rel='stylesheet', type='text/css')
- body
- a#forkbanner(href="http://github.com/learnboost/mongoose")
- img(style="position: absolute; top: 0; right: 0; border: 0;", src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png", alt="Fork me on GitHub")
- #links
- #header
- h1
- a(href="../index.html")
- .mongoose Mongoose
- include includes/nav
- #content
- .module
- h2 Documents
- :markdown
- Mongoose [documents](./api.html#document-js) represent a one-to-one mapping to documents as stored in MongoDB. Each document is an instance of its [Model](./models.html).
- h3 Retreiving
- :markdown
- There are many ways to retreive documents from MongoDB. We won't cover that in this section. See the chapter on [querying](./queries.html) for detail.
- h3 Updating
- :markdown
- There are a number of ways to update documents. We'll first look at a traditional approach using [findById](./api.html#model_Model-findById):
- :js
- Tank.findById(id, function (err, tank) {
- if (err) return handleError(err);
+extends layout
- tank.size = 'large';
- tank.save(function (err) {
- if (err) return handleError(err);
- res.send(tank);
- });
- });
- :markdown
- This approach involves first retreiving the document from Mongo, then issuing an update command (triggered by calling `save`). However, if we don't need the document returned in our application and merely want to update a property in the database directly, [Model#update](./api.html#model_Model-update) is right for us:
- :js
- Tank.update({ _id: id }, { $set: { size: 'large' }}, callback);
- :markdown
- If we do need the document returned in our application there is another, often [better](./api.html#model_Model-findByIdAndUpdate), option:
- :js
- Tank.findByIdAndUpdate(id, { $set: { size: 'large' }}, function (err, tank) {
- if (err) return handleError(err);
- res.send(tank);
- });
- :markdown
- The `findAndUpdate/Remove` static methods all make a change to at most one document, and return it with just one call to the database. There [are](./api.html#model_Model-findByIdAndRemove) [several](./api.html#model_Model-findOneAndUpdate) [variations](./api.html#model_Model-findOneAndRemove) on the [findAndModify](http://www.mongodb.org/display/DOCS/findAndModify+Command) theme. Read the [API](./api.html) docs for more detail.
- h3 Validating
- :markdown
- Documents are validated before they are saved. Read the [api](./api.html#document_Document-validate) docs or the [validation](./validation.html) chapter for detail.
+block content
+ h2 Documents
+ :markdown
+ Mongoose [documents](./api.html#document-js) represent a one-to-one mapping to documents as stored in MongoDB. Each document is an instance of its [Model](./models.html).
+ h3 Retreiving
+ :markdown
+ There are many ways to retreive documents from MongoDB. We won't cover that in this section. See the chapter on [querying](./queries.html) for detail.
+ h3 Updating
+ :markdown
+ There are a number of ways to update documents. We'll first look at a traditional approach using [findById](./api.html#model_Model-findById):
+ :js
+ Tank.findById(id, function (err, tank) {
+ if (err) return handleError(err);
+
+ tank.size = 'large';
+ tank.save(function (err) {
+ if (err) return handleError(err);
+ res.send(tank);
+ });
+ });
+ :markdown
+ This approach involves first retreiving the document from Mongo, then issuing an update command (triggered by calling `save`). However, if we don't need the document returned in our application and merely want to update a property in the database directly, [Model#update](./api.html#model_Model-update) is right for us:
+ :js
+ Tank.update({ _id: id }, { $set: { size: 'large' }}, callback);
+ :markdown
+ If we do need the document returned in our application there is another, often [better](./api.html#model_Model-findByIdAndUpdate), option:
+ :js
+ Tank.findByIdAndUpdate(id, { $set: { size: 'large' }}, function (err, tank) {
+ if (err) return handleError(err);
+ res.send(tank);
+ });
+ :markdown
+ The `findAndUpdate/Remove` static methods all make a change to at most one document, and return it with just one call to the database. There [are](./api.html#model_Model-findByIdAndRemove) [several](./api.html#model_Model-findOneAndUpdate) [variations](./api.html#model_Model-findOneAndRemove) on the [findAndModify](http://www.mongodb.org/display/DOCS/findAndModify+Command) theme. Read the [API](./api.html) docs for more detail.
+ h3 Validating
+ :markdown
+ Documents are validated before they are saved. Read the [api](./api.html#document_Document-validate) docs or the [validation](./validation.html) chapter for detail.
View
10 docs/faq.html
@@ -1 +1,9 @@
-<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"><title>Mongoose Quick Start v3.0.0</title><link href="http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700" rel="stylesheet" type="text/css"><link href="/docs/css/default.css" rel="stylesheet" type="text/css"><link href="/docs/css/guide.css" rel="stylesheet" type="text/css"></head><body><a id="forkbanner" href="http://github.com/learnboost/mongoose"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" alt="Fork me on GitHub"></a><div id="links"><div id="header"><h1><a href="../index.html"><div class="mongoose">Mongoose</div></a></h1></div><ul><li class="home"><a href="../index.html">home</a></li><li class="plugins"><a href="http://plugins.mongoosejs.com">plugins</a></li><li class="changelog"><a href="http://github.com/learnboost/mongoose/tree/master/History.md">change log</a></li><li class="support"><a href="../index.html#support">support</a></li><li class="fork"><a href="http://github.com/learnboost/mongoose">fork</a></li><li class="guide"><a href="./guide.html">guide</a><ul><li class="double"><a href="./guide.html">schemas</a><ul><li class="schematypes"><a href="./schematypes.html"><span>schema</span>types</a></li></ul></li><li class="double"><a href="./documents.html">documents</a><ul><li class="subdocs"><a href="./subdocs.html">sub docs</a></li></ul></li><li><a href="./models.html">models</a></li><li><a href="./queries.html">queries</a></li><li><a href="./plugins.html">plugins</a></li><li><a href="./middleware.html">middleware</a></li><li><a href="./validation.html">validation</a></li><li><a href="./populate.html">populate</a></li><li><a href="./migration.html">migrating from 2.x</a></li><li><a href="./contributing.html">contributing</a></li></ul></li><li class="api"><a href="./api.html">api docs</a></li><li class="quickstart"><a href="./index.html">quick start</a></li><li class="contrib"><a href="http://github.com/learnboost/mongoose/contributors">contributors</a></li><li class="prior"><a href="./prior.html">prior releases</a></li></ul></div><div id="content"><div class="module"><h2>FAQ</h2><p>We need to write this! Edit [this page]() on github and send a pull request!</p></div></div></body></html>
+<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"><title>Mongoose FAQ v3.0.0</title><link href="http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700" rel="stylesheet" type="text/css"><link href="/docs/css/default.css" rel="stylesheet" type="text/css"><link href="/docs/css/guide.css" rel="stylesheet" type="text/css"></head><body><a id="forkbanner" href="http://github.com/learnboost/mongoose"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" alt="Fork me on GitHub"></a><div id="links"><div id="header"><h1><a href="../index.html"><div class="mongoose">Mongoose</div></a></h1></div><ul><li class="home"><a href="../index.html">home</a></li><li class="plugins"><a href="http://plugins.mongoosejs.com">plugins</a></li><li class="changelog"><a href="http://github.com/learnboost/mongoose/tree/master/History.md">change log</a></li><li class="support"><a href="../index.html#support">support</a></li><li class="fork"><a href="http://github.com/learnboost/mongoose">fork</a></li><li class="guide"><a href="./guide.html">guide</a><ul><li class="double"><a href="./guide.html">schemas</a><ul><li class="schematypes"><a href="./schematypes.html"><span>schema</span>types</a></li></ul></li><li class="double"><a href="./documents.html">documents</a><ul><li class="subdocs"><a href="./subdocs.html">sub docs</a></li></ul></li><li><a href="./models.html">models</a></li><li><a href="./queries.html">queries</a></li><li><a href="./plugins.html">plugins</a></li><li><a href="./middleware.html">middleware</a></li><li><a href="./validation.html">validation</a></li><li><a href="./populate.html">populate</a></li><li><a href="./migration.html">migrating from 2.x</a></li><li><a href="./contributing.html">contributing</a></li></ul></li><li class="api"><a href="./api.html">api docs</a></li><li class="quickstart"><a href="./index.html">quick start</a></li><li class="contrib"><a href="http://github.com/learnboost/mongoose/contributors">contributors</a></li><li class="prior"><a href="./prior.html">prior releases</a></li></ul></div><div id="content"><div class="module"><h2>FAQ</h2><p>We need to write this! Edit [this page]() on github and send a pull request!</p></div></div><script>document.body.className = 'load';</script><script>var _gaq = _gaq || [];
+_gaq.push(['_setAccount', 'UA-1122274-9']);
+_gaq.push(['_trackPageview']);
+
+(function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+})();</script></body></html>
View
29 docs/faq.jade
@@ -1,24 +1,7 @@
-doctype html
-html(lang='en')
- head
- meta(charset="utf-8")
- meta(name="viewport", content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no")
- title Mongoose Quick Start v#{package.version}
- link(href='http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700', rel='stylesheet', type='text/css')
- link(href='/docs/css/default.css', rel='stylesheet', type='text/css')
- link(href='/docs/css/guide.css', rel='stylesheet', type='text/css')
- body
- a#forkbanner(href="http://github.com/learnboost/mongoose")
- img(style="position: absolute; top: 0; right: 0; border: 0;", src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png", alt="Fork me on GitHub")
- #links
- #header
- h1
- a(href="../index.html")
- .mongoose Mongoose
- include includes/nav
- #content
- .module
- h2 FAQ
- :markdown
- We need to write this! Edit [this page]() on github and send a pull request!
+extends layout
+
+block content
+ h2 FAQ
+ :markdown
+ We need to write this! Edit [this page]() on github and send a pull request!
View
2 docs/guide.html
@@ -1,4 +1,4 @@
-<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"><title>Mongoose Quick Start v3.0.0</title><link href="http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700" rel="stylesheet" type="text/css"><link href="/docs/css/default.css" rel="stylesheet" type="text/css"><link href="/docs/css/guide.css" rel="stylesheet" type="text/css"></head><body><a id="forkbanner" href="http://github.com/learnboost/mongoose"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" alt="Fork me on GitHub"></a><div id="links"><div id="header"><h1><a href="../index.html"><div class="mongoose">Mongoose</div></a></h1></div><ul><li class="home"><a href="../index.html">home</a></li><li class="plugins"><a href="http://plugins.mongoosejs.com">plugins</a></li><li class="changelog"><a href="http://github.com/learnboost/mongoose/tree/master/History.md">change log</a></li><li class="support"><a href="../index.html#support">support</a></li><li class="fork"><a href="http://github.com/learnboost/mongoose">fork</a></li><li class="guide"><a href="./guide.html">guide</a><ul><li class="double"><a href="./guide.html">schemas</a><ul><li class="schematypes"><a href="./schematypes.html"><span>schema</span>types</a></li></ul></li><li class="double"><a href="./documents.html">documents</a><ul><li class="subdocs"><a href="./subdocs.html">sub docs</a></li></ul></li><li><a href="./models.html">models</a></li><li><a href="./queries.html">queries</a></li><li><a href="./plugins.html">plugins</a></li><li><a href="./middleware.html">middleware</a></li><li><a href="./validation.html">validation</a></li><li><a href="./populate.html">populate</a></li><li><a href="./migration.html">migrating from 2.x</a></li><li><a href="./contributing.html">contributing</a></li></ul></li><li class="api"><a href="./api.html">api docs</a></li><li class="quickstart"><a href="./index.html">quick start</a></li><li class="contrib"><a href="http://github.com/learnboost/mongoose/contributors">contributors</a></li><li class="prior"><a href="./prior.html">prior releases</a></li></ul></div><div id="content"><div class="module"><h2>Schemas</h2><p>If you haven't yet done so, please take a minute to read the <a href="./index.html">quickstart</a> to get an idea of how Mongoose works.</p><p>This page covers <code>Schema</code> <a href="#definition">definition</a>, <a href="#plugins">plugins</a>, instance <a href="#methods">methods</a>, <a href="#statics">statics</a>, <a href="#indexes">indexes</a>, <a href="#virtuals">virtuals</a> and <a href="#options">options</a>. Let&#39;s start with <code>Schema</code> definition.</p><h3 id="definition">Defining your schema</h3><p>Everything in Mongoose starts with a Schema. Each schema maps to a MongoDB collection and defines the shape of the documents within that collection.</p><pre><code class="javascript"><span class="keyword">var</span> blogSchema = <span class="keyword">new</span> Schema({
+<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"><title>Mongoose Schemas v3.0.0</title><link href="http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700" rel="stylesheet" type="text/css"><link href="/docs/css/default.css" rel="stylesheet" type="text/css"><link href="/docs/css/guide.css" rel="stylesheet" type="text/css"></head><body><a id="forkbanner" href="http://github.com/learnboost/mongoose"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" alt="Fork me on GitHub"></a><div id="links"><div id="header"><h1><a href="../index.html"><div class="mongoose">Mongoose</div></a></h1></div><ul><li class="home"><a href="../index.html">home</a></li><li class="plugins"><a href="http://plugins.mongoosejs.com">plugins</a></li><li class="changelog"><a href="http://github.com/learnboost/mongoose/tree/master/History.md">change log</a></li><li class="support"><a href="../index.html#support">support</a></li><li class="fork"><a href="http://github.com/learnboost/mongoose">fork</a></li><li class="guide"><a href="./guide.html">guide</a><ul><li class="double"><a href="./guide.html">schemas</a><ul><li class="schematypes"><a href="./schematypes.html"><span>schema</span>types</a></li></ul></li><li class="double"><a href="./documents.html">documents</a><ul><li class="subdocs"><a href="./subdocs.html">sub docs</a></li></ul></li><li><a href="./models.html">models</a></li><li><a href="./queries.html">queries</a></li><li><a href="./plugins.html">plugins</a></li><li><a href="./middleware.html">middleware</a></li><li><a href="./validation.html">validation</a></li><li><a href="./populate.html">populate</a></li><li><a href="./migration.html">migrating from 2.x</a></li><li><a href="./contributing.html">contributing</a></li></ul></li><li class="api"><a href="./api.html">api docs</a></li><li class="quickstart"><a href="./index.html">quick start</a></li><li class="contrib"><a href="http://github.com/learnboost/mongoose/contributors">contributors</a></li><li class="prior"><a href="./prior.html">prior releases</a></li></ul></div><div id="content"><div class="module"><h2>Schemas</h2><p>If you haven't yet done so, please take a minute to read the <a href="./index.html">quickstart</a> to get an idea of how Mongoose works.</p><p>This page covers <code>Schema</code> <a href="#definition">definition</a>, <a href="#plugins">plugins</a>, instance <a href="#methods">methods</a>, <a href="#statics">statics</a>, <a href="#indexes">indexes</a>, <a href="#virtuals">virtuals</a> and <a href="#options">options</a>. Let&#39;s start with <code>Schema</code> definition.</p><h3 id="definition">Defining your schema</h3><p>Everything in Mongoose starts with a Schema. Each schema maps to a MongoDB collection and defines the shape of the documents within that collection.</p><pre><code class="javascript"><span class="keyword">var</span> blogSchema = <span class="keyword">new</span> Schema({
title: String,
author: String,
body: String,
View
669 docs/guide.jade
@@ -1,343 +1,326 @@
-doctype html
-html(lang='en')
- head
- meta(charset="utf-8")
- meta(name="viewport", content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no")
- title Mongoose Quick Start v#{package.version}
- link(href='http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700', rel='stylesheet', type='text/css')
- link(href='/docs/css/default.css', rel='stylesheet', type='text/css')
- link(href='/docs/css/guide.css', rel='stylesheet', type='text/css')
- body
- a#forkbanner(href="http://github.com/learnboost/mongoose")
- img(style="position: absolute; top: 0; right: 0; border: 0;", src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png", alt="Fork me on GitHub")
- #links
- #header
- h1
- a(href="../index.html")
- .mongoose Mongoose
- include includes/nav
- #content
- .module
- h2 Schemas
- p
- | If you haven't yet done so, please take a minute to read the
- a(href="./index.html") quickstart
- | to get an idea of how Mongoose works.
- :markdown
- This page covers `Schema` [definition](#definition), [plugins](#plugins), instance [methods](#methods), [statics](#statics), [indexes](#indexes), [virtuals](#virtuals) and [options](#options). Let's start with `Schema` definition.
- h3#definition Defining your schema
- p
- | Everything in Mongoose starts with a Schema. Each schema maps to a MongoDB collection and defines the shape of the documents within that collection.
- :js
- var blogSchema = new Schema({
- title: String,
- author: String,
- body: String,
- comments: [{ body: String, date: Date }],
- date: { type: Date, default: Date.now },
- hidden: Boolean,
- meta: {
- votes: Number,
- favs: Number
- }
- })
- p
- em
- | If you want to add additional keys later, use the
- a(href="./api.html#schema_Schema-add") Schema#add
- | method.
- p
- | Each key in our
- code blogSchema
- | defines a property in our documents which will be cast to its associated
- a(href="./api.html#schematype_SchemaType") SchemaType
- |. Keys may also be assigned nested objects containing further key/type definitions
- em (e.g. the `meta` property above).
- | For example, we've defined a
- code title
- | which will be cast to the
- a(href="./api.html#schema-string-js") String
- | SchemaType and
- code date
- | which will be cast to a
- code Date
- | SchemaType.
- p
- | The permitted SchemaTypes are
- ul
- li String
- li Number
- li Date
- li Buffer
- li Boolean
- li Mixed
- li ObjectId
- li Array
- | Read more about them
- a(href="./schematypes.html") here
- | .
- p
- | Schemas not only define the structure of your document and casting of properties, they also define document
- a(href="#methods") instance methods
- |, static
- a(href="#statics") Model methods
- |,
- a(href="#indexes") compound indexes
- | and document lifecycle hooks called
- a(href="./middleware.html") middleware
- |.
- h3#plugins Pluggable
- p
- | Schemas are
- a(href="./plugins.html") pluggable
- | which allows us to package up reusable features into
- a(href="http://plugins.mongoosejs.com") plugins
- | that can be shared with the community or just between your projects.
- h3#methods Instance methods
- p
- a(href="./models.html") Models
- | are just fancy
- code constructor
- | functions. As such they can have prototype methods inherited by their instances. In the case of Mongoose, instances are
- a(href="./documents.html") documents
- |.
- p
- | Defining an instance method is easy.
- :js
- var animalSchema = new Schema({ name: String, type: String });
-
- animalSchema.methods.findSimilarTypes = function (cb) {
- return this.model('Animal').find({ type: this.type }, cb);
- }
- p
- | Now all of our
- code animal
- | instances have a
- code findSimilarTypes
- | method available to it.
- :js
- var Animal = mongoose.model('Animal', animalSchema);
- var dog = new Animal({ type: 'dog' })
-
- dog.findSimilarTypes(function (err, dogs) {
- console.log(dogs) // woof
- })
- h3#statics Statics
- p
- | Adding static constructor methods to Models is simple as well. Continuing with our
- code animalSchema
- |:
- :js
- animalSchema.statics.findByName = function (name, cb) {
- this.find({ name: new RegExp(name, 'i'), cb);
- }
-
- var Animal = mongoose.model('Animal', animalSchema);
- Animal.findByName('fido', function (err, animals) {
- console.log(animals);
- })
- h3#indexes Indexes
- p
- a(href="http://www.mongodb.org/display/DOCS/Indexes") Indexes
- | can be defined
- a(href="./api.html#schematype_SchemaType-index") at
- |
- a(href="./api.html#schematype_SchemaType-unique") the
- |
- a(href="./api.html#schematype_SchemaType-sparse") path
- |
- a(href="./api.html#schematype_SchemaType-expires") level
- | or the
- code schema
- | level. Defining indexes at the schema level is necessary when defining
- a(href="http://www.mongodb.org/display/DOCS/Indexes#Indexes-CompoundKeys", target="_blank") compound indexes
- |.
- :js
- animalSchema.index({ name: 1, type: -1 });
- p
- | When your application starts up, Mongoose automatically calls
- code ensureIndex
- | for each defined index. This behavior can be disabled by setting the
- code autoIndex
- | option of your schema to false.
- :js
- animalSchema.set('autoIndex', false)
- // or
- new Schema({..}, { autoIndex: false })
- p
- | See also the
- a(href="./api.html#model_Model-ensureIndexes")
- code Model#ensureIndexes
- | method.
-
- h3#virtuals Virtuals
- :markdown
- [Virtual](./api.html#schema_Schema-virtual) attributes are attributes that are convenient to have around but that do not get persisted to MongoDB.
- :js
- var personSchema = new Schema({
- name: {
- first: String,
- last: String
- }
- });
-
- var Person = mongoose.model('Person', personSchema);
-
- var bad = new Person({
- name: { first: 'Walter', last: 'White' }
- });
- :markdown
- Suppose we want to log the full name of `bad`. We could do this manually like so:
- :js
- console.log(bad.name.first + ' ' + bad.name.last); // Walter White
- :markdown
- Or we could add a `virtual` attribute [getter](./api.html#virtualtype_VirtualType-get) to our `personSchema` so we don't need to write out this string concatenation mess each time:
- :js
- personSchema.virtual('name.full').get(function () {
- return this.name.first + ' ' + this.name.last;
- })
- :markdown
- Now, when we access our virtual full name property, our getter function will be invoked and the value returned:
- :js
- console.log('%s is insane', bad.name.full) // Walter White is insane
- :markdown
- It would also be nice to be able to set `this.name.first` and `this.name.last` by setting `this.name.full`. For example, if we wanted to change `bad`'s `name.first` and `name.last` to 'Breaking' and 'Bad' respectively, it'd be nice to just:
- :js
- bad.name.full = 'Breaking Bad';
- :markdown
- Mongoose let's you do this as well through its virtual attribute [setters](./api.html#virtualtype_VirtualType-set):
- :js
- personSchema.virtual('name.full').set(function (name) {
- var split = name.split(' ');
- this.name.first = split[0];
- this.name.last = split[1];
- })
-
- ...
-
- mad.name.full = 'Breaking Bad';
- console.log(mad.name.first) // Breaking
- :markdown
- If you need attributes that you can get and set but that are not themselves persisted to MongoDB, virtual attributes is the Mongoose feature for you.
-
- h3#options Options
- :markdown
- `Schema`s have a few configurable options which can be passed to the constructor or `set` directly:
- :js
- new Schema({..}, options);
-
- // or
-
- var schema = new Schema({..});
- schema.set(option, value);
-
- :markdown
- Valid options:
-
- - [safe](#safe)
- - [strict](#strict)
- - [capped](#capped)
- - [versionKey](#versionKey)
- - [autoIndex](#autoIndex)
-
- h4#safe option: safe
- :markdown
- This option is passed to MongoDB with all operations and let's us specify if errors should be returned to our callbacks as well as tune write behavior.
-
- :js
- var safe = true;
- new Schema({ .. }, { safe: safe })
-
- :markdown
- By default this is set to `true` for all schemas which guarentees that any occurring error gets passed back to our callback.
- By setting `safe` to something else like `{ j: 1, w: 2, wtimeout: 10000 }` we can guarantee the write was committed to the MongoDB journal (j: 1), at least 2 replicas (w: 2), and that the write will timeout if it takes longer than 10 seconds (wtimeout: 10000). Errors will still be passed to our callback.
-
- There are other write concerns like `{ w: "majority" }` too. See the MongoDB [docs](http://www.mongodb.org/display/DOCS/getLastError+Command) for more details.
-
- :js
- var safe = { w: "majority", wtimeout: 10000 };
- new Schema({ .. }, { safe: safe })
-
- h4#strict option: strict
- :markdown
- The strict option, (enabled by default), ensures that values added to our model instance that were not specified in our schema do not get saved to the db.
- _NOTE: do not set to false unless you have good reason._
-
- :js
- var thingSchema = new Schema({..})
- var Thing = db.model('Thing', schemaSchema);
- var thing = new Thing({ iAmNotInTheSchema: true });
- thing.save() // iAmNotInTheSchema is not saved to the db
-
- // set to false..
- var thingSchema = new Schema({..}, { strict: false });
- var thing = new Thing({ iAmNotInTheSchema: true });
- thing.save() // iAmNotInTheSchema is now saved to the db!!
-
- :markdown
- This value can be overridden at the model instance level by passing a second boolean argument:
-
- :js
- var Thing = db.model('Thing');
- var thing = new Thing(doc, true); // enables strict mode
- var thing = new Thing(doc, false); // disables strict mode
-
- :markdown
- The `strict` option may also be set to `"throw"` which will cause errors to be produced instead of ignoring the bad data.
-
- :markdown
- _NOTE: in mongoose v2 the default was false._
-
- h4#shardkey option: shardKey
- :markdown
- The `shardKey` option is used when we have a [sharded MongoDB architecture](http://www.mongodb.org/display/DOCS/Sharding+Introduction). Each sharded collection is given a shard key which must be present in all insert/update operations. We just need to set this schema option to the same shard key and we’ll be all set.
-
- :js
- new Schema({ .. }, { shardkey: { tag: 1, name: 1 }})
-
- :markdown
- _Note that Mongoose does not send the `shardcollection` command for you. You must configure your shards yourself._
-
- h4#capped option: capped
- :markdown
- Mongoose supports MongoDBs [capped](http://www.mongodb.org/display/DOCS/Capped+Collections) collections. To specify the underlying MongoDB collection be `capped`, set the `capped` option to the maximum size of the collection in [bytes](http://www.mongodb.org/display/DOCS/Capped+Collections#CappedCollections-size.).
- :js
- new Schema({..}, { capped: 1024 })
- :markdown
- The `capped` option may also be set to an object if you want to pass additional options like [max](http://www.mongodb.org/display/DOCS/Capped+Collections#CappedCollections-max) or [autoIndexId](http://www.mongodb.org/display/DOCS/Capped+Collections#CappedCollections-autoIndexId). In this case you must explicitly pass the `size` option which is required.
- :js
- new Schema({..}, { capped: { size: 1024, max: 1000, autoIndexId: true })
-
- h4#versionKey option: versionKey
- :markdown
- The `versionKey` is a property set on each document when first created by Mongoose. This keys value contains the internal [revision](http://aaronheckmann.posterous.com/mongoose-v3-part-1-versioning) of the document. The name of this document property is configurable. The default is `__v`. If this conflicts with your application you can configure as such:
- :js
- var schema = new Schema({ name: 'string' });
- var Thing = db.model('Thing', schema);
- var thing = new Thing({ name: 'mongoose v3' });
- thing.save(); // { __v: 0, name: 'mongoose v3' }
-
- // customized versionKey
- new Schema({..}, { versionKey: '_somethingElse' })
- var Thing = db.model('Thing', schema);
- var thing = new Thing({ name: 'mongoose v3' });
- thing.save(); // { _somethingElse: 0, name: 'mongoose v3' }
-
- :markdown
- Document versioning can also be disabled by setting the `versionKey` to false. _DO NOT disable versioning unless you [know what you are doing](http://aaronheckmann.posterous.com/mongoose-v3-part-1-versioning)._
- :js
- new Schema({..}, { versionKey: false })
- var Thing = db.model('Thing', schema);
- var thing = new Thing({ name: 'no versioning please' });
- thing.save(); // { name: 'no versioning please' }
- h4#autoIndex option: autoIndex
- :markdown
- At application startup, Mongoose sends an `ensureIndex` command for each index declared in your `Schema`. As of Mongoose v3, indexes are created in the `background` by default. If you wish to disable the auto-creation feature and manually handle when indexes are created, set your `Schema`s `autoIndex` option to `false` and use the [ensureIndexes](./api.html#model_Model-ensureIndexes) method on your model.
- :js
- var schema = new Schema({..}, { autoIndex: false })
- var Clock = db.model('Clock', schema);
- Clock.ensureIndexes(callback);
-
- script.
- document.body.className = 'load';
- include includes/googleanalytics
+extends layout
+
+block content
+ h2 Schemas
+ p
+ | If you haven't yet done so, please take a minute to read the
+ a(href="./index.html") quickstart
+ | to get an idea of how Mongoose works.
+ :markdown
+ This page covers `Schema` [definition](#definition), [plugins](#plugins), instance [methods](#methods), [statics](#statics), [indexes](#indexes), [virtuals](#virtuals) and [options](#options). Let's start with `Schema` definition.
+ h3#definition Defining your schema
+ p
+ | Everything in Mongoose starts with a Schema. Each schema maps to a MongoDB collection and defines the shape of the documents within that collection.
+ :js
+ var blogSchema = new Schema({
+ title: String,
+ author: String,
+ body: String,
+ comments: [{ body: String, date: Date }],
+ date: { type: Date, default: Date.now },
+ hidden: Boolean,
+ meta: {
+ votes: Number,
+ favs: Number
+ }
+ })
+ p
+ em
+ | If you want to add additional keys later, use the
+ a(href="./api.html#schema_Schema-add") Schema#add
+ | method.
+ p
+ | Each key in our
+ code blogSchema
+ | defines a property in our documents which will be cast to its associated
+ a(href="./api.html#schematype_SchemaType") SchemaType
+ |. Keys may also be assigned nested objects containing further key/type definitions
+ em (e.g. the `meta` property above).
+ | For example, we've defined a
+ code title
+ | which will be cast to the
+ a(href="./api.html#schema-string-js") String
+ | SchemaType and
+ code date
+ | which will be cast to a
+ code Date
+ | SchemaType.
+ p
+ | The permitted SchemaTypes are
+ ul
+ li String
+ li Number
+ li Date
+ li Buffer
+ li Boolean
+ li Mixed
+ li ObjectId
+ li Array
+ | Read more about them
+ a(href="./schematypes.html") here
+ | .
+ p
+ | Schemas not only define the structure of your document and casting of properties, they also define document
+ a(href="#methods") instance methods
+ |, static
+ a(href="#statics") Model methods
+ |,
+ a(href="#indexes") compound indexes
+ | and document lifecycle hooks called
+ a(href="./middleware.html") middleware
+ |.
+ h3#plugins Pluggable
+ p
+ | Schemas are
+ a(href="./plugins.html") pluggable
+ | which allows us to package up reusable features into
+ a(href="http://plugins.mongoosejs.com") plugins
+ | that can be shared with the community or just between your projects.
+ h3#methods Instance methods
+ p
+ a(href="./models.html") Models
+ | are just fancy
+ code constructor
+ | functions. As such they can have prototype methods inherited by their instances. In the case of Mongoose, instances are
+ a(href="./documents.html") documents
+ |.
+ p
+ | Defining an instance method is easy.
+ :js
+ var animalSchema = new Schema({ name: String, type: String });
+
+ animalSchema.methods.findSimilarTypes = function (cb) {
+ return this.model('Animal').find({ type: this.type }, cb);
+ }
+ p
+ | Now all of our
+ code animal
+ | instances have a
+ code findSimilarTypes
+ | method available to it.
+ :js
+ var Animal = mongoose.model('Animal', animalSchema);
+ var dog = new Animal({ type: 'dog' })
+
+ dog.findSimilarTypes(function (err, dogs) {
+ console.log(dogs) // woof
+ })
+ h3#statics Statics
+ p
+ | Adding static constructor methods to Models is simple as well. Continuing with our
+ code animalSchema
+ |:
+ :js
+ animalSchema.statics.findByName = function (name, cb) {
+ this.find({ name: new RegExp(name, 'i'), cb);
+ }
+
+ var Animal = mongoose.model('Animal', animalSchema);
+ Animal.findByName('fido', function (err, animals) {
+ console.log(animals);
+ })
+ h3#indexes Indexes
+ p
+ a(href="http://www.mongodb.org/display/DOCS/Indexes") Indexes
+ | can be defined
+ a(href="./api.html#schematype_SchemaType-index") at
+ |
+ a(href="./api.html#schematype_SchemaType-unique") the
+ |
+ a(href="./api.html#schematype_SchemaType-sparse") path
+ |
+ a(href="./api.html#schematype_SchemaType-expires") level
+ | or the
+ code schema
+ | level. Defining indexes at the schema level is necessary when defining
+ a(href="http://www.mongodb.org/display/DOCS/Indexes#Indexes-CompoundKeys", target="_blank") compound indexes
+ |.
+ :js
+ animalSchema.index({ name: 1, type: -1 });
+ p
+ | When your application starts up, Mongoose automatically calls
+ code ensureIndex
+ | for each defined index. This behavior can be disabled by setting the
+ code autoIndex
+ | option of your schema to false.
+ :js
+ animalSchema.set('autoIndex', false)
+ // or
+ new Schema({..}, { autoIndex: false })
+ p
+ | See also the
+ a(href="./api.html#model_Model-ensureIndexes")
+ code Model#ensureIndexes
+ | method.
+
+ h3#virtuals Virtuals
+ :markdown
+ [Virtual](./api.html#schema_Schema-virtual) attributes are attributes that are convenient to have around but that do not get persisted to MongoDB.
+ :js
+ var personSchema = new Schema({
+ name: {
+ first: String,
+ last: String
+ }
+ });
+
+ var Person = mongoose.model('Person', personSchema);
+
+ var bad = new Person({
+ name: { first: 'Walter', last: 'White' }
+ });
+ :markdown
+ Suppose we want to log the full name of `bad`. We could do this manually like so:
+ :js
+ console.log(bad.name.first + ' ' + bad.name.last); // Walter White
+ :markdown
+ Or we could add a `virtual` attribute [getter](./api.html#virtualtype_VirtualType-get) to our `personSchema` so we don't need to write out this string concatenation mess each time:
+ :js
+ personSchema.virtual('name.full').get(function () {
+ return this.name.first + ' ' + this.name.last;
+ })
+ :markdown
+ Now, when we access our virtual full name property, our getter function will be invoked and the value returned:
+ :js
+ console.log('%s is insane', bad.name.full) // Walter White is insane
+ :markdown
+ It would also be nice to be able to set `this.name.first` and `this.name.last` by setting `this.name.full`. For example, if we wanted to change `bad`'s `name.first` and `name.last` to 'Breaking' and 'Bad' respectively, it'd be nice to just:
+ :js
+ bad.name.full = 'Breaking Bad';
+ :markdown
+ Mongoose let's you do this as well through its virtual attribute [setters](./api.html#virtualtype_VirtualType-set):
+ :js
+ personSchema.virtual('name.full').set(function (name) {
+ var split = name.split(' ');
+ this.name.first = split[0];
+ this.name.last = split[1];
+ })
+
+ ...
+
+ mad.name.full = 'Breaking Bad';
+ console.log(mad.name.first) // Breaking
+ :markdown
+ If you need attributes that you can get and set but that are not themselves persisted to MongoDB, virtual attributes is the Mongoose feature for you.
+
+ h3#options Options
+ :markdown
+ `Schema`s have a few configurable options which can be passed to the constructor or `set` directly:
+ :js
+ new Schema({..}, options);
+
+ // or
+
+ var schema = new Schema({..});
+ schema.set(option, value);
+
+ :markdown
+ Valid options:
+
+ - [safe](#safe)
+ - [strict](#strict)
+ - [capped](#capped)
+ - [versionKey](#versionKey)
+ - [autoIndex](#autoIndex)
+
+ h4#safe option: safe
+ :markdown
+ This option is passed to MongoDB with all operations and let's us specify if errors should be returned to our callbacks as well as tune write behavior.
+
+ :js
+ var safe = true;
+ new Schema({ .. }, { safe: safe })
+
+ :markdown
+ By default this is set to `true` for all schemas which guarentees that any occurring error gets passed back to our callback.
+ By setting `safe` to something else like `{ j: 1, w: 2, wtimeout: 10000 }` we can guarantee the write was committed to the MongoDB journal (j: 1), at least 2 replicas (w: 2), and that the write will timeout if it takes longer than 10 seconds (wtimeout: 10000). Errors will still be passed to our callback.
+
+ There are other write concerns like `{ w: "majority" }` too. See the MongoDB [docs](http://www.mongodb.org/display/DOCS/getLastError+Command) for more details.
+
+ :js
+ var safe = { w: "majority", wtimeout: 10000 };
+ new Schema({ .. }, { safe: safe })
+
+ h4#strict option: strict
+ :markdown
+ The strict option, (enabled by default), ensures that values added to our model instance that were not specified in our schema do not get saved to the db.
+ _NOTE: do not set to false unless you have good reason._
+
+ :js
+ var thingSchema = new Schema({..})
+ var Thing = db.model('Thing', schemaSchema);
+ var thing = new Thing({ iAmNotInTheSchema: true });
+ thing.save() // iAmNotInTheSchema is not saved to the db
+
+ // set to false..
+ var thingSchema = new Schema({..}, { strict: false });
+ var thing = new Thing({ iAmNotInTheSchema: true });
+ thing.save() // iAmNotInTheSchema is now saved to the db!!
+
+ :markdown
+ This value can be overridden at the model instance level by passing a second boolean argument:
+
+ :js
+ var Thing = db.model('Thing');
+ var thing = new Thing(doc, true); // enables strict mode
+ var thing = new Thing(doc, false); // disables strict mode
+
+ :markdown
+ The `strict` option may also be set to `"throw"` which will cause errors to be produced instead of ignoring the bad data.
+
+ :markdown
+ _NOTE: in mongoose v2 the default was false._
+
+ h4#shardkey option: shardKey
+ :markdown
+ The `shardKey` option is used when we have a [sharded MongoDB architecture](http://www.mongodb.org/display/DOCS/Sharding+Introduction). Each sharded collection is given a shard key which must be present in all insert/update operations. We just need to set this schema option to the same shard key and we’ll be all set.
+
+ :js
+ new Schema({ .. }, { shardkey: { tag: 1, name: 1 }})
+
+ :markdown
+ _Note that Mongoose does not send the `shardcollection` command for you. You must configure your shards yourself._
+
+ h4#capped option: capped
+ :markdown
+ Mongoose supports MongoDBs [capped](http://www.mongodb.org/display/DOCS/Capped+Collections) collections. To specify the underlying MongoDB collection be `capped`, set the `capped` option to the maximum size of the collection in [bytes](http://www.mongodb.org/display/DOCS/Capped+Collections#CappedCollections-size.).
+ :js
+ new Schema({..}, { capped: 1024 })
+ :markdown
+ The `capped` option may also be set to an object if you want to pass additional options like [max](http://www.mongodb.org/display/DOCS/Capped+Collections#CappedCollections-max) or [autoIndexId](http://www.mongodb.org/display/DOCS/Capped+Collections#CappedCollections-autoIndexId). In this case you must explicitly pass the `size` option which is required.
+ :js
+ new Schema({..}, { capped: { size: 1024, max: 1000, autoIndexId: true })
+
+ h4#versionKey option: versionKey
+ :markdown
+ The `versionKey` is a property set on each document when first created by Mongoose. This keys value contains the internal [revision](http://aaronheckmann.posterous.com/mongoose-v3-part-1-versioning) of the document. The name of this document property is configurable. The default is `__v`. If this conflicts with your application you can configure as such:
+ :js
+ var schema = new Schema({ name: 'string' });
+ var Thing = db.model('Thing', schema);
+ var thing = new Thing({ name: 'mongoose v3' });
+ thing.save(); // { __v: 0, name: 'mongoose v3' }
+
+ // customized versionKey
+ new Schema({..}, { versionKey: '_somethingElse' })
+ var Thing = db.model('Thing', schema);
+ var thing = new Thing({ name: 'mongoose v3' });
+ thing.save(); // { _somethingElse: 0, name: 'mongoose v3' }
+
+ :markdown
+ Document versioning can also be disabled by setting the `versionKey` to false. _DO NOT disable versioning unless you [know what you are doing](http://aaronheckmann.posterous.com/mongoose-v3-part-1-versioning)._
+ :js
+ new Schema({..}, { versionKey: false })
+ var Thing = db.model('Thing', schema);
+ var thing = new Thing({ name: 'no versioning please' });
+ thing.save(); // { name: 'no versioning please' }
+ h4#autoIndex option: autoIndex
+ :markdown
+ At application startup, Mongoose sends an `ensureIndex` command for each index declared in your `Schema`. As of Mongoose v3, indexes are created in the `background` by default. If you wish to disable the auto-creation feature and manually handle when indexes are created, set your `Schema`s `autoIndex` option to `false` and use the [ensureIndexes](./api.html#model_Model-ensureIndexes) method on your model.
+ :js
+ var schema = new Schema({..}, { autoIndex: false })
+ var Clock = db.model('Clock', schema);
+ Clock.ensureIndexes(callback);
+
+script.
+document.body.className = 'load';
+include includes/googleanalytics
View
25 docs/layout.jade
@@ -0,0 +1,25 @@
+doctype html
+html(lang='en')
+ head
+ meta(charset="utf-8")
+ meta(name="viewport", content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no")
+ title Mongoose #{title} v#{package.version}
+ block style
+ link(href='http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700', rel='stylesheet', type='text/css')
+ link(href='/docs/css/default.css', rel='stylesheet', type='text/css')
+ link(href='/docs/css/guide.css', rel='stylesheet', type='text/css')
+ body
+ a#forkbanner(href="http://github.com/learnboost/mongoose")
+ img(style="position: absolute; top: 0; right: 0; border: 0;", src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png", alt="Fork me on GitHub")
+ #links
+ #header
+ h1
+ a(href="../index.html")
+ .mongoose Mongoose
+ include includes/nav
+ #content
+ .module
+ block content
+ script.
+ document.body.className = 'load';
+ include includes/googleanalytics
View
12 docs/middleware.html
@@ -1,4 +1,4 @@
-<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"><title>Mongoose Quick Start v3.0.0</title><link href="http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700" rel="stylesheet" type="text/css"><link href="/docs/css/default.css" rel="stylesheet" type="text/css"><link href="/docs/css/guide.css" rel="stylesheet" type="text/css"></head><body><a id="forkbanner" href="http://github.com/learnboost/mongoose"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" alt="Fork me on GitHub"></a><div id="links"><div id="header"><h1><a href="../index.html"><div class="mongoose">Mongoose</div></a></h1></div><ul><li class="home"><a href="../index.html">home</a></li><li class="plugins"><a href="http://plugins.mongoosejs.com">plugins</a></li><li class="changelog"><a href="http://github.com/learnboost/mongoose/tree/master/History.md">change log</a></li><li class="support"><a href="../index.html#support">support</a></li><li class="fork"><a href="http://github.com/learnboost/mongoose">fork</a></li><li class="guide"><a href="./guide.html">guide</a><ul><li class="double"><a href="./guide.html">schemas</a><ul><li class="schematypes"><a href="./schematypes.html"><span>schema</span>types</a></li></ul></li><li class="double"><a href="./documents.html">documents</a><ul><li class="subdocs"><a href="./subdocs.html">sub docs</a></li></ul></li><li><a href="./models.html">models</a></li><li><a href="./queries.html">queries</a></li><li><a href="./plugins.html">plugins</a></li><li><a href="./middleware.html">middleware</a></li><li><a href="./validation.html">validation</a></li><li><a href="./populate.html">populate</a></li><li><a href="./migration.html">migrating from 2.x</a></li><li><a href="./contributing.html">contributing</a></li></ul></li><li class="api"><a href="./api.html">api docs</a></li><li class="quickstart"><a href="./index.html">quick start</a></li><li class="contrib"><a href="http://github.com/learnboost/mongoose/contributors">contributors</a></li><li class="prior"><a href="./prior.html">prior releases</a></li></ul></div><div id="content"><div class="module"><h2>Middleware</h2><p>Middleware are functions which are passed control of flow during execution of <a href="./api.html#document_Document-init">init</a>, <a href="./api.html#document_Document-validate">validate</a>, <a href="./api.html#model_Model-save">save</a> and <a href="./api.html#model_Model-remove">remove</a> methods.</p><p>
+<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"><title>Mongoose Middleware v3.0.0</title><link href="http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700" rel="stylesheet" type="text/css"><link href="/docs/css/default.css" rel="stylesheet" type="text/css"><link href="/docs/css/guide.css" rel="stylesheet" type="text/css"></head><body><a id="forkbanner" href="http://github.com/learnboost/mongoose"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" alt="Fork me on GitHub"></a><div id="links"><div id="header"><h1><a href="../index.html"><div class="mongoose">Mongoose</div></a></h1></div><ul><li class="home"><a href="../index.html">home</a></li><li class="plugins"><a href="http://plugins.mongoosejs.com">plugins</a></li><li class="changelog"><a href="http://github.com/learnboost/mongoose/tree/master/History.md">change log</a></li><li class="support"><a href="../index.html#support">support</a></li><li class="fork"><a href="http://github.com/learnboost/mongoose">fork</a></li><li class="guide"><a href="./guide.html">guide</a><ul><li class="double"><a href="./guide.html">schemas</a><ul><li class="schematypes"><a href="./schematypes.html"><span>schema</span>types</a></li></ul></li><li class="double"><a href="./documents.html">documents</a><ul><li class="subdocs"><a href="./subdocs.html">sub docs</a></li></ul></li><li><a href="./models.html">models</a></li><li><a href="./queries.html">queries</a></li><li><a href="./plugins.html">plugins</a></li><li><a href="./middleware.html">middleware</a></li><li><a href="./validation.html">validation</a></li><li><a href="./populate.html">populate</a></li><li><a href="./migration.html">migrating from 2.x</a></li><li><a href="./contributing.html">contributing</a></li></ul></li><li class="api"><a href="./api.html">api docs</a></li><li class="quickstart"><a href="./index.html">quick start</a></li><li class="contrib"><a href="http://github.com/learnboost/mongoose/contributors">contributors</a></li><li class="prior"><a href="./prior.html">prior releases</a></li></ul></div><div id="content"><div class="module"><h2>Middleware</h2><p>Middleware are functions which are passed control of flow during execution of <a href="./api.html#document_Document-init">init</a>, <a href="./api.html#document_Document-validate">validate</a>, <a href="./api.html#model_Model-save">save</a> and <a href="./api.html#model_Model-remove">remove</a> methods.</p><p>
There are two types of middleware, serial and parallel.</p><h4>Serial</h4><p>Serial middleware are executed one after another, when each middleware calls <code>next</code></p><pre><code class="javascript"><span class="keyword">var</span> schema = <span class="keyword">new</span> Schema(..);
schema.pre(<span class="string">'save'</span>, <span class="function"><span class="keyword">function</span> <span class="params">(next)</span> {</span>
<span class="comment">// do stuff</span>
@@ -18,4 +18,12 @@
myModel.save(<span class="function"><span class="keyword">function</span> <span class="params">(err)</span> {</span>
console.log(err.message) <span class="comment">// something went wrong</span>
});
-</code></pre></div></div></body></html>
+</code></pre></div></div><script>document.body.className = 'load';</script><script>var _gaq = _gaq || [];
+_gaq.push(['_setAccount', 'UA-1122274-9']);
+_gaq.push(['_trackPageview']);
+
+(function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+})();</script></body></html>
View
153 docs/middleware.jade
@@ -1,88 +1,71 @@
-doctype html
-html(lang='en')
- head
- meta(charset="utf-8")
- meta(name="viewport", content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no")
- title Mongoose Quick Start v#{package.version}
- link(href='http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700', rel='stylesheet', type='text/css')
- link(href='/docs/css/default.css', rel='stylesheet', type='text/css')
- link(href='/docs/css/guide.css', rel='stylesheet', type='text/css')
- body
- a#forkbanner(href="http://github.com/learnboost/mongoose")
- img(style="position: absolute; top: 0; right: 0; border: 0;", src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png", alt="Fork me on GitHub")
- #links
- #header
- h1
- a(href="../index.html")
- .mongoose Mongoose
- include includes/nav
- #content
- .module
- h2 Middleware
- p
- | Middleware are functions which are passed control of flow during execution of
- a(href="./api.html#document_Document-init") init
- |,
- a(href="./api.html#document_Document-validate") validate
- |,
- a(href="./api.html#model_Model-save") save
- | and
- a(href="./api.html#model_Model-remove") remove
- | methods.
- p
- | There are two types of middleware, serial and parallel.
- h4 Serial
- p
- | Serial middleware are executed one after another, when each middleware calls
- code next
- :js
- var schema = new Schema(..);
- schema.pre('save', function (next) {
- // do stuff
- next();
- });
- h4 Parallel
- p
- | Parallel middleware offer more fine-grained flow control.
- :js
- var schema = new Schema(..);
- schema.pre('save', true, function (next, done) {
- // calling next kicks off the next middleware in parallel
- next();
- doAsync(done);
- });
- p
- | The hooked method, in this case
- code save
- |, will not be executed until
- code done
- | is called by each middleware.
- h4 Use Cases
- p
- | Middleware are useful for atomizing model logic and avoiding nested blocks of async code. Here are some other ideas:
- ul
- li complex validation
- li
- | removing dependent documents
- ul
- li (removing a user removes all his blogposts)
- li asynchronous defaults
- li asynchronous tasks that a certain action triggers
- ul
- li triggering custom events
- li notifications
- h4 Error handling
- :markdown
- If any middleware calls `next` or `done` with an `Error` instance, the flow is interrupted, and the error is passed to the callback.
- :js
- schema.pre('save', function (next) {
- var err = new Error('something went wrong');
- next(err);
- });
+extends layout
- // later...
+block content
+ h2 Middleware
+ p
+ | Middleware are functions which are passed control of flow during execution of
+ a(href="./api.html#document_Document-init") init
+ |,
+ a(href="./api.html#document_Document-validate") validate
+ |,
+ a(href="./api.html#model_Model-save") save
+ | and
+ a(href="./api.html#model_Model-remove") remove
+ | methods.
+ p
+ | There are two types of middleware, serial and parallel.
+ h4 Serial
+ p
+ | Serial middleware are executed one after another, when each middleware calls
+ code next
+ :js
+ var schema = new Schema(..);
+ schema.pre('save', function (next) {
+ // do stuff
+ next();
+ });
+ h4 Parallel
+ p
+ | Parallel middleware offer more fine-grained flow control.
+ :js
+ var schema = new Schema(..);
+ schema.pre('save', true, function (next, done) {
+ // calling next kicks off the next middleware in parallel
+ next();
+ doAsync(done);
+ });
+ p
+ | The hooked method, in this case
+ code save
+ |, will not be executed until
+ code done
+ | is called by each middleware.
+ h4 Use Cases
+ p
+ | Middleware are useful for atomizing model logic and avoiding nested blocks of async code. Here are some other ideas:
+ ul
+ li complex validation
+ li
+ | removing dependent documents
+ ul
+ li (removing a user removes all his blogposts)
+ li asynchronous defaults
+ li asynchronous tasks that a certain action triggers
+ ul
+ li triggering custom events
+ li notifications
+ h4 Error handling
+ :markdown
+ If any middleware calls `next` or `done` with an `Error` instance, the flow is interrupted, and the error is passed to the callback.
+ :js
+ schema.pre('save', function (next) {
+ var err = new Error('something went wrong');
+ next(err);
+ });
- myModel.save(function (err) {
- console.log(err.message) // something went wrong
- });
+ // later...
+
+ myModel.save(function (err) {
+ console.log(err.message) // something went wrong
+ });
View
15 docs/migration.html
@@ -1,6 +1,7 @@
-<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"><title>Mongoose Quick Start v3.0.0</title><link href="http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700" rel="stylesheet" type="text/css"><link href="/docs/css/default.css" rel="stylesheet" type="text/css"><link href="/docs/css/guide.css" rel="stylesheet" type="text/css"><style>table td {
+<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"><title>Mongoose Migration Guide v3.0.0</title><link href="http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700" rel="stylesheet" type="text/css"><link href="/docs/css/default.css" rel="stylesheet" type="text/css"><link href="/docs/css/guide.css" rel="stylesheet" type="text/css"><style>table td {
padding-right: 15px;
-}</style></head><body><a id="forkbanner" href="http://github.com/learnboost/mongoose"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" alt="Fork me on GitHub"></a><div id="links"><div id="header"><h1><a href="../index.html"><div class="mongoose">Mongoose</div></a></h1></div><ul><li class="home"><a href="../index.html">home</a></li><li class="plugins"><a href="http://plugins.mongoosejs.com">plugins</a></li><li class="changelog"><a href="http://github.com/learnboost/mongoose/tree/master/History.md">change log</a></li><li class="support"><a href="../index.html#support">support</a></li><li class="fork"><a href="http://github.com/learnboost/mongoose">fork</a></li><li class="guide"><a href="./guide.html">guide</a><ul><li class="double"><a href="./guide.html">schemas</a><ul><li class="schematypes"><a href="./schematypes.html"><span>schema</span>types</a></li></ul></li><li class="double"><a href="./documents.html">documents</a><ul><li class="subdocs"><a href="./subdocs.html">sub docs</a></li></ul></li><li><a href="./models.html">models</a></li><li><a href="./queries.html">queries</a></li><li><a href="./plugins.html">plugins</a></li><li><a href="./middleware.html">middleware</a></li><li><a href="./validation.html">validation</a></li><li><a href="./populate.html">populate</a></li><li><a href="./migration.html">migrating from 2.x</a></li><li><a href="./contributing.html">contributing</a></li></ul></li><li class="api"><a href="./api.html">api docs</a></li><li class="quickstart"><a href="./index.html">quick start</a></li><li class="contrib"><a href="http://github.com/learnboost/mongoose/contributors">contributors</a></li><li class="prior"><a href="./prior.html">prior releases</a></li></ul></div><div id="content"><div class="module"><h2>Migrating from 2.x to 3.x</h2><p>Migrating from Mongoose 2.x to 3.x brings with it <a href="https://github.com/LearnBoost/mongoose/blob/master/History.md">several changes</a> to be aware of:</p><h3>Query clean-up</h3><p>Many methods of the <a href="./api.html#query-js">Query</a> API were nothing but aliases and have been <a href="https://github.com/LearnBoost/mongoose/commit/1149804c">removed</a> in an effort to keep Mongoose clean and focused on there being as close to <a href="http://www.python.org/dev/peps/pep-0020/">one way</a> of doing things as possible. If you really love all that extra noise, you can bring most of it back with <a href="https://github.com/aheckmann/mongoose-v2-compat">this module</a>.</p>
+}
+</style></head><body><a id="forkbanner" href="http://github.com/learnboost/mongoose"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" alt="Fork me on GitHub"></a><div id="links"><div id="header"><h1><a href="../index.html"><div class="mongoose">Mongoose</div></a></h1></div><ul><li class="home"><a href="../index.html">home</a></li><li class="plugins"><a href="http://plugins.mongoosejs.com">plugins</a></li><li class="changelog"><a href="http://github.com/learnboost/mongoose/tree/master/History.md">change log</a></li><li class="support"><a href="../index.html#support">support</a></li><li class="fork"><a href="http://github.com/learnboost/mongoose">fork</a></li><li class="guide"><a href="./guide.html">guide</a><ul><li class="double"><a href="./guide.html">schemas</a><ul><li class="schematypes"><a href="./schematypes.html"><span>schema</span>types</a></li></ul></li><li class="double"><a href="./documents.html">documents</a><ul><li class="subdocs"><a href="./subdocs.html">sub docs</a></li></ul></li><li><a href="./models.html">models</a></li><li><a href="./queries.html">queries</a></li><li><a href="./plugins.html">plugins</a></li><li><a href="./middleware.html">middleware</a></li><li><a href="./validation.html">validation</a></li><li><a href="./populate.html">populate</a></li><li><a href="./migration.html">migrating from 2.x</a></li><li><a href="./contributing.html">contributing</a></li></ul></li><li class="api"><a href="./api.html">api docs</a></li><li class="quickstart"><a href="./index.html">quick start</a></li><li class="contrib"><a href="http://github.com/learnboost/mongoose/contributors">contributors</a></li><li class="prior"><a href="./prior.html">prior releases</a></li></ul></div><div id="content"><div class="module"><h2>Migrating from 2.x to 3.x</h2><p>Migrating from Mongoose 2.x to 3.x brings with it <a href="https://github.com/LearnBoost/mongoose/blob/master/History.md">several changes</a> to be aware of:</p><h3>Query clean-up</h3><p>Many methods of the <a href="./api.html#query-js">Query</a> API were nothing but aliases and have been <a href="https://github.com/LearnBoost/mongoose/commit/1149804c">removed</a> in an effort to keep Mongoose clean and focused on there being as close to <a href="http://www.python.org/dev/peps/pep-0020/">one way</a> of doing things as possible. If you really love all that extra noise, you can bring most of it back with <a href="https://github.com/aheckmann/mongoose-v2-compat">this module</a>.</p>
<p>Here are the removed methods are their still existing aliases:</p><table><thead><tr style="text-align:left"><th>Removed</th><th>Alternative</th></tr></thead><tbody><tr><td><code>query.run</code></td><td><code>query.exec</code></td></tr><tr><td><code>query.$or</code></td><td><code>query.or</code></td></tr><tr><td><code>query.$nor</code></td><td><code>query.nor</code></td></tr><tr><td><code>query.$gt</code></td><td><code>query.gt</code></td></tr><tr><td><code>query.$gte</code></td><td><code>query.gte</code></td></tr><tr><td><code>query.$lt</code></td><td><code>query.lt</code></td></tr><tr><td><code>query.$lte</code></td><td><code>query.lte</code></td></tr><tr><td><code>query.$ne</code></td><td><code>query.ne</code></td></tr><tr><td><code>query.$in</code></td><td><code>query.in</code></td></tr><tr><td><code>query.$nin</code></td><td><code>query.nin</code></td></tr><tr><td><code>query.$all</code></td><td><code>query.all</code></td></tr><tr><td><code>query.$regex</code></td><td><code>query.regex</code></td></tr><tr><td><code>query.$size</code></td><td><code>query.size</code></td></tr><tr><td><code>query.$maxDistance</code></td><td><code>query.maxDistance</code></td></tr><tr><td><code>query.$mod</code></td><td><code>query.mod</code></td></tr><tr><td><code>query.$near</code></td><td><code>query.near</code></td></tr><tr><td><code>query.$exists</code></td><td><code>query.exists</code></td></tr><tr><td><code>query.$elemMatch</code></td><td><code>query.elemMatch</code></td></tr><tr><td><code>query.$within</code></td><td><code>query.within</code></td></tr><tr><td><code>query.$box</code></td><td><code>query.box</code></td></tr><tr><td><code>query.$center</code></td><td><code>query.center</code></td></tr><tr><td><code>query.$centerSphere</code></td><td><code>query.centerSphere</code></td></tr><tr><td><code>query.$slice</code></td><td><code>query.slice</code></td></tr><tr><td><code>query.notEqualTo</code></td><td><code>query.ne</code></td></tr><tr><td><code>query.wherein</code></td><td><code>query.within</code></td></tr><tr><td><code>query.asc</code></td><td><code>query.sort <a href="#asc">*</a></code></td></tr><tr><td><code>query.desc</code></td><td><code>query.sort <a href="#desc">*</a></code></td></tr><tr><td><code>query.fields</code></td><td><code>query.select <a href="#fields">*</a></code></td></tr></tbody></table><h4 id="asc">query#asc</h4><p>The <code>asc</code> method of <a href="./api.html#query-js">Query</a> has been removed in favor of <a href="./api.html#query_Query-sort">sort</a>. The <code>sort</code> method accepts slightly different arguments so read the <a href="./api.html#query_Query-sort">docs</a> to make sure your application is all set.</p><h4 id="desc">query#desc</h4><p>The <code>desc</code> method of <a href="./api.html#query-js">Query</a> has been removed in favor of <a href="./api.html#query_Query-sort">sort</a>. The <code>sort</code> method accepts slightly different arguments so read the <a href="./api.html#query_Query-sort">docs</a> to make sure your application is all set.</p><h4 id="fields">query#fields</h4><p>The <code>fields</code> method of <a href="./api.html#query-js">Query</a> has been removed, it being mostly an alias for the <a href="./api.html#query_Query-select">select</a> method anyway. The <code>select</code> method has slightly different arguments so read the <a href="./api.html#query_Query-select">docs</a> to make sure your application is all set.</p><h3>Connecting to ReplicaSets</h3><p>To connect to a <a href="http://www.mongodb.org/display/DOCS/Replica+Sets">ReplicaSet</a> you no longer use the separate <code>connectSet</code> or <code>createSetConnection</code> methods. Both <a href="./api.html#index_Mongoose-connect">mongoose.connect</a> and <a href="./api.html#index_Mongoose-createConnection">mongoose.createConnection</a> are now smart enough to just do the right thing with your connection string. If you really want to bring <code>connectSet</code> and <code>createSetConnection</code> back use <a href="https://github.com/aheckmann/mongoose-v2-compat">this module</a>.</p><h3>Schemas</h3><ul><li>are now <a href="./guide.html#strict">strict</a> by default.</li><li>Arrays of <a href="./subdocs.html#altsyntax">object literal</a> now creates document arrays instead of arrays of <a href="./schematypes.html#mixed">Mixed</a>.</li><li>Indexes are now created in <a href="./guide.html#autoIndex">background</a> by default.</li><li>Index errors are now emitted on their model instead of the connection. See issue <a href="https://github.com/LearnBoost/mongoose/issues/984">#984</a>.</li></ul><h3 id="arrays">Arrays</h3><ul><li><a href="./api.html#types_array_MongooseArray-pop">pop</a> is now fixed causing a $set of the entire array.</li><li><a href="./api.html#types_array_MongooseArray-%24pop">$pop</a> is now fixed and behaves just as MongoDB <a href="http://www.mongodb.org/display/DOCS/Updating#Updating-%24pop">$pop</a> does, removing at most the last element of the array.</li><li><a href="./api.html#types_array_MongooseArray-shift">shift</a> is now fixed causing a $set of the entire array.</li><li><a href="./api.html#types_array_MongooseArray-%24shift">$shift</a> is now fixed and behaves just as a <a href="http://www.mongodb.org/display/DOCS/Updating#Updating-%24pop">MongoDB $pop -1</a> does, removing at most the first element of array.</li><li><code>$unshift</code> was removed, use <a href="./api.html#types_array_MongooseArray-unshift">unshift</a> instead.</li><li><code>$addToSet</code> was removed, use <a href="./api.html#types_array_MongooseArray-addToSet">addToSet</a> instead.</li><li><code>$pushAll</code> was removed, use <a href="./api.html#types_array_MongooseArray-push">push</a> instead.</li><li><code>$pull</code> was removed, use <a href="./api.html#types_array_MongooseArray-pull">pull</a> instead.</li><li><code>$pullAll</code> was removed, use <a href="./api.html#types_array_MongooseArray-pull">pull</a> instead.</li><li><code>doAtomics</code> was changed to the <a href="./api.html#types_array_MongooseArray-hasAtomics">hasAtomics</a> private method</li></ul><h3 id="mongoosenumber">Number type</h3><p>The custom subclassed Number type Mongoose used to use for all numbers is now gone. It caused <a href="https://groups.google.com/d/msg/mongoose-orm/syKlN2xL1EE/FfRFhEFj4KcJ">too many problems</a> when doing comparisons and had other bad side-effects.</p>
@@ -24,4 +25,12 @@
});</code></pre><p>With MongooseNumber out of the picture, we&#39;ll instead use the <a href="./api.html#model_Model-findByIdAndUpdate">Account.findByIdAndUpdate</a> helper:</p><pre><code class="javascript">Inventory.findByIdAndUpdate(id, { $inc: { productCount: -<span class="number">7</span> }}, <span class="function"><span class="keyword">function</span> <span class="params">(err, inventory)</span> {</span>
<span class="keyword">if</span> (err) <span class="keyword">return</span> handleError(err);
res.send(inventory.productCount); <span class="comment">// 3</span>
-});</code></pre><p>The <code>findByIdAndUpdate</code> helper not only finds the document but updates it as well before responding with the altered document. The findAndModify helpers are a great addition for many use cases.</p><h3 id="documents">Documents</h3><ul><li><code>doc#commit</code> is now removed, use <a href="./api.html#document_Document-markModified">doc.markModified</a> instead</li><li><a href="./api.html#document_Document-modifiedPaths">doc#modifiedPaths</a> is now a method not a getter</li><li><code>doc.modified</code> is now removed, use <a href="./api.html#document_Document-isModified">doc.isModified</a> instead</li></ul><h4 id="gettercasting">getter casting</h4><p>Getters no longer apply casting. Casting happens at set time. Useful in situations where you desire formatted responses like currency. See issue <a href="https://github.com/LearnBoost/mongoose/issues/820">#820</a> and pull <a href="https://github.com/LearnBoost/mongoose/pull/924">#924</a>.</p><h4 id="setterorder">setter order</h4><p>Values being set no longer cast until <em>after</em> all setters have been applied. Previously the value returned from each setter was cast <em>before</em> passing it on to the next setter. This changes allows more flexible processing of values in setters. See issue <a href="https://github.com/learnboost/mongoose/issues/665">#665</a> and pull <a href="https://github.com/LearnBoost/mongoose/pull/924">#924</a>.</p><h3 id="subdocs">Subdocuments</h3><ul><li><code>subdoc.parent</code> was changed from a property to a <a href="./api.html#types_embedded_EmbeddedDocument-parent">method</a>. See issue <a href="https://github.com/LearnBoost/mongoose/issues/928">#928</a>.</li><li><code>subdoc.parentArray</code> was changed from a property to a <a href="./api.html#types_embedded_EmbeddedDocument-parentArray">method</a>. See issue <a href="https://github.com/LearnBoost/mongoose/issues/928">#928</a>.</li></ul><h3 id="stringmatch">String match validator</h3><p>The String SchemaType <a href="./api.html#schema_string_SchemaString-match">match</a> validator no longer checks against null, undefined, or &#39;&#39;. If you need to validate against these values, enable the <a href="./api.html#schematype_SchemaType-required">required</a> validator as well. See issue <a href="https://github.com/LearnBoost/mongoose/issues/934">#934</a> and pull request <a href="https://github.com/LearnBoost/mongoose/pull/935">#935</a>.</p><h3 id="version">Versioning</h3><p>Documents are now transparently versioned. Read the in depth details <a href="http://aaronheckmann.posterous.com/tag/versioning">here</a>.</p></div></div></body></html>
+});</code></pre><p>The <code>findByIdAndUpdate</code> helper not only finds the document but updates it as well before responding with the altered document. The findAndModify helpers are a great addition for many use cases.</p><h3 id="documents">Documents</h3><ul><li><code>doc#commit</code> is now removed, use <a href="./api.html#document_Document-markModified">doc.markModified</a> instead</li><li><a href="./api.html#document_Document-modifiedPaths">doc#modifiedPaths</a> is now a method not a getter</li><li><code>doc.modified</code> is now removed, use <a href="./api.html#document_Document-isModified">doc.isModified</a> instead</li></ul><h4 id="gettercasting">getter casting</h4><p>Getters no longer apply casting. Casting happens at set time. Useful in situations where you desire formatted responses like currency. See issue <a href="https://github.com/LearnBoost/mongoose/issues/820">#820</a> and pull <a href="https://github.com/LearnBoost/mongoose/pull/924">#924</a>.</p><h4 id="setterorder">setter order</h4><p>Values being set no longer cast until <em>after</em> all setters have been applied. Previously the value returned from each setter was cast <em>before</em> passing it on to the next setter. This changes allows more flexible processing of values in setters. See issue <a href="https://github.com/learnboost/mongoose/issues/665">#665</a> and pull <a href="https://github.com/LearnBoost/mongoose/pull/924">#924</a>.</p><h3 id="subdocs">Subdocuments</h3><ul><li><code>subdoc.parent</code> was changed from a property to a <a href="./api.html#types_embedded_EmbeddedDocument-parent">method</a>. See issue <a href="https://github.com/LearnBoost/mongoose/issues/928">#928</a>.</li><li><code>subdoc.parentArray</code> was changed from a property to a <a href="./api.html#types_embedded_EmbeddedDocument-parentArray">method</a>. See issue <a href="https://github.com/LearnBoost/mongoose/issues/928">#928</a>.</li></ul><h3 id="stringmatch">String match validator</h3><p>The String SchemaType <a href="./api.html#schema_string_SchemaString-match">match</a> validator no longer checks against null, undefined, or &#39;&#39;. If you need to validate against these values, enable the <a href="./api.html#schematype_SchemaType-required">required</a> validator as well. See issue <a href="https://github.com/LearnBoost/mongoose/issues/934">#934</a> and pull request <a href="https://github.com/LearnBoost/mongoose/pull/935">#935</a>.</p><h3 id="version">Versioning</h3><p>Documents are now transparently versioned. Read the in depth details <a href="http://aaronheckmann.posterous.com/tag/versioning">here</a>.</p></div></div><script>document.body.className = 'load';</script><script>var _gaq = _gaq || [];
+_gaq.push(['_setAccount', 'UA-1122274-9']);
+_gaq.push(['_trackPageview']);
+
+(function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+})();</script></body></html>
View
515 docs/migration.jade
@@ -1,283 +1,268 @@
-doctype html
-html(lang='en')
- head
- meta(charset="utf-8")
- meta(name="viewport", content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no")
- title Mongoose Quick Start v#{package.version}
- link(href='http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700', rel='stylesheet', type='text/css')
- link(href='/docs/css/default.css', rel='stylesheet', type='text/css')
- link(href='/docs/css/guide.css', rel='stylesheet', type='text/css')
- style.
- table td {
- padding-right: 15px;
- }
- body
- a#forkbanner(href="http://github.com/learnboost/mongoose")
- img(style="position: absolute; top: 0; right: 0; border: 0;", src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png", alt="Fork me on GitHub")
- #links
- #header
- h1
- a(href="../index.html")
- .mongoose Mongoose
- include includes/nav
- #content
- .module
- h2 Migrating from 2.x to 3.x
- :markdown
- Migrating from Mongoose 2.x to 3.x brings with it [several changes](https://github.com/LearnBoost/mongoose/blob/master/History.md) to be aware of:
+extends layout
- h3 Query clean-up
- :markdown
- Many methods of the [Query](./api.html#query-js) API were nothing but aliases and have been [removed](https://github.com/LearnBoost/mongoose/commit/1149804c) in an effort to keep Mongoose clean and focused on there being as close to [one way](http://www.python.org/dev/peps/pep-0020/) of doing things as possible. If you really love all that extra noise, you can bring most of it back with [this module](https://github.com/aheckmann/mongoose-v2-compat).
+block append style
+ style.
+ table td {
+ padding-right: 15px;
+ }
- Here are the removed methods are their still existing aliases:
- table
- thead
- tr(style='text-align:left')
- th Removed
- th Alternative
- tbody
- tr
- td
- code query.run
- td
- code query.exec
- tr
- td
- code query.$or
- td
- code query.or
- tr
- td
- code query.$nor
- td
- code query.nor
- tr
- td
- code query.$gt
- td
- code query.gt
- tr
- td
- code query.$gte
- td
- code query.gte
- tr
- td
- code query.$lt
- td
- code query.lt
- tr
- td
- code query.$lte
- td
- code query.lte
- tr
- td
- code query.$ne
- td
- code query.ne
- tr
- td
- code query.$in
- td
- code query.in
- tr
- td
- code query.$nin
- td
- code query.nin
- tr
- td
- code query.$all
- td
- code query.all
- tr
- td
- code query.$regex
- td
- code query.regex
- tr
- td
- code query.$size
- td
- code query.size
- tr
- td
- code query.$maxDistance
- td
- code query.maxDistance
- tr
- td
- code query.$mod
- td
- code query.mod
- tr
- td
- code query.$near
- td
- code query.near
- tr
- td
- code query.$exists
- td
- code query.exists
- tr
- td
- code query.$elemMatch
- td
- code query.elemMatch
- tr
- td
- code query.$within
- td
- code query.within
- tr
- td
- code query.$box
- td
- code query.box
- tr
- td
- code query.$center
- td
- code query.center
- tr
- td
- code query.$centerSphere
- td
- code query.centerSphere
- tr
- td
- code query.$slice
- td
- code query.slice
- tr
- td
- code query.notEqualTo
- td
- code query.ne
- tr
- td
- code query.wherein
- td
- code query.within
- tr
- td
- code query.asc
- td
- code
- | query.sort
- a(href="#asc") *
- tr
- td
- code query.desc
- td
- code
- | query.sort
- a(href="#desc") *
- tr
- td
- code query.fields
- td
- code
- | query.select
- a(href="#fields") *
+block content
+ h2 Migrating from 2.x to 3.x
+ :markdown
+ Migrating from Mongoose 2.x to 3.x brings with it [several changes](https://github.com/LearnBoost/mongoose/blob/master/History.md) to be aware of:
- h4#asc query#asc
- :markdown
- The `asc` method of [Query](./api.html#query-js) has been removed in favor of [sort](./api.html#query_Query-sort). The `sort` method accepts slightly different arguments so read the [docs](./api.html#query_Query-sort) to make sure your application is all set.
- h4#desc query#desc
- :markdown
- The `desc` method of [Query](./api.html#query-js) has been removed in favor of [sort](./api.html#query_Query-sort). The `sort` method accepts slightly different arguments so read the [docs](./api.html#query_Query-sort) to make sure your application is all set.
- h4#fields query#fields
- :markdown
- The `fields` method of [Query](./api.html#query-js) has been removed, it being mostly an alias for the [select](./api.html#query_Query-select) method anyway. The `select` method has slightly different arguments so read the [docs](./api.html#query_Query-select) to make sure your application is all set.
+ h3 Query clean-up
+ :markdown
+ Many methods of the [Query](./api.html#query-js) API were nothing but aliases and have been [removed](https://github.com/LearnBoost/mongoose/commit/1149804c) in an effort to keep Mongoose clean and focused on there being as close to [one way](http://www.python.org/dev/peps/pep-0020/) of doing things as possible. If you really love all that extra noise, you can bring most of it back with [this module](https://github.com/aheckmann/mongoose-v2-compat).
+ Here are the removed methods are their still existing aliases:
+ table
+ thead
+ tr(style='text-align:left')
+ th Removed
+ th Alternative
+ tbody
+ tr
+ td
+ code query.run
+ td
+ code query.exec
+ tr
+ td
+ code query.$or
+ td
+ code query.or
+ tr
+ td
+ code query.$nor
+ td
+ code query.nor
+ tr
+ td
+ code query.$gt
+ td
+ code query.gt
+ tr
+ td
+ code query.$gte
+ td
+ code query.gte
+ tr
+ td
+ code query.$lt
+ td
+ code query.lt
+ tr
+ td
+ code query.$lte
+ td
+ code query.lte
+ tr
+ td
+ code query.$ne
+ td
+ code query.ne
+ tr
+ td
+ code query.$in
+ td
+ code query.in
+ tr
+ td
+ code query.$nin
+ td
+ code query.nin
+ tr
+ td
+ code query.$all
+ td
+ code query.all
+ tr
+ td
+ code query.$regex
+ td
+ code query.regex
+ tr
+ td
+ code query.$size
+ td
+ code query.size
+ tr
+ td
+ code query.$maxDistance
+ td
+ code query.maxDistance
+ tr
+ td
+ code query.$mod
+ td
+ code query.mod
+ tr
+ td
+ code query.$near
+ td
+ code query.near
+ tr
+ td
+ code query.$exists
+ td
+ code query.exists
+ tr
+ td
+ code query.$elemMatch
+ td
+ code query.elemMatch
+ tr
+ td
+ code query.$within
+ td
+ code query.within
+ tr
+ td
+ code query.$box
+ td
+ code query.box
+ tr
+ td
+ code query.$center
+ td
+ code query.center
+ tr
+ td
+ code query.$centerSphere
+ td
+ code query.centerSphere
+ tr
+ td
+ code query.$slice
+ td
+ code query.slice
+ tr
+ td
+ code query.notEqualTo
+ td
+ code query.ne
+ tr
+ td
+ code query.wherein
+ td
+ code query.within
+ tr
+ td
+ code query.asc
+ td
+ code
+ | query.sort
+ a(href="#asc") *
+ tr
+ td
+ code query.desc
+ td
+ code
+ | query.sort
+ a(href="#desc") *
+ tr
+ td
+ code query.fields
+ td
+ code
+ | query.select
+ a(href="#fields") *
- h3 Connecting to ReplicaSets
- :markdown
- To connect to a [ReplicaSet](http://www.mongodb.org/display/DOCS/Replica+Sets) you no longer use the separate `connectSet` or `createSetConnection` methods. Both [mongoose.connect](./api.html#index_Mongoose-connect) and [mongoose.createConnection](./api.html#index_Mongoose-createConnection) are now smart enough to just do the right thing with your connection string. If you really want to bring `connectSet` and `createSetConnection` back use [this module](https://github.com/aheckmann/mongoose-v2-compat).
+ h4#asc query#asc
+ :markdown
+ The `asc` method of [Query](./api.html#query-js) has been removed in favor of [sort](./api.html#query_Query-sort). The `sort` method accepts slightly different arguments so read the [docs](./api.html#query_Query-sort) to make sure your application is all set.
+ h4#desc query#desc
+ :markdown
+ The `desc` method of [Query](./api.html#query-js) has been removed in favor of [sort](./api.html#query_Query-sort). The `sort` method accepts slightly different arguments so read the [docs](./api.html#query_Query-sort) to make sure your application is all set.
+ h4#fields query#fields
+ :markdown
+ The `fields` method of [Query](./api.html#query-js) has been removed, it being mostly an alias for the [select](./api.html#query_Query-select) method anyway. The `select` method has slightly different arguments so read the [docs](./api.html#query_Query-select) to make sure your application is all set.
- h3 Schemas
- :markdown
- - are now [strict](./guide.html#strict) by default.
- - Arrays of [object literal](./subdocs.html#altsyntax) now creates document arrays instead of arrays of [Mixed](./schematypes.html#mixed).
- - Indexes are now created in [background](./guide.html#autoIndex) by default.
- - Index errors are now emitted on their model instead of the connection. See issue [#984](https://github.com/LearnBoost/mongoose/issues/984).
- h3#arrays Arrays
- :markdown
- - [pop](./api.html#types_array_MongooseArray-pop) is now fixed causing a $set of the entire array.
- - [$pop](./api.html#types_array_MongooseArray-%24pop) is now fixed and behaves just as MongoDB [$pop](http://www.mongodb.org/display/DOCS/Updating#Updating-%24pop) does, removing at most the last element of the array.
- - [shift](./api.html#types_array_MongooseArray-shift) is now fixed causing a $set of the entire array.
- - [$shift](./api.html#types_array_MongooseArray-%24shift) is now fixed and behaves just as a [MongoDB $pop -1](http://www.mongodb.org/display/DOCS/Updating#Updating-%24pop) does, removing at most the first element of array.
- - `$unshift` was removed, use [unshift](./api.html#types_array_MongooseArray-unshift) instead.
- - `$addToSet` was removed, use [addToSet](./api.html#types_array_MongooseArray-addToSet) instead.
- - `$pushAll` was removed, use [push](./api.html#types_array_MongooseArray-push) instead.
- - `$pull` was removed, use [pull](./api.html#types_array_MongooseArray-pull) instead.
- - `$pullAll` was removed, use [pull](./api.html#types_array_MongooseArray-pull) instead.
- - `doAtomics` was changed to the [hasAtomics](./api.html#types_array_MongooseArray-hasAtomics) private method
+ h3 Connecting to ReplicaSets
+ :markdown
+ To connect to a [ReplicaSet](http://www.mongodb.org/display/DOCS/Replica+Sets) you no longer use the separate `connectSet` or `createSetConnection` methods. Both [mongoose.connect](./api.html#index_Mongoose-connect) and [mongoose.createConnection](./api.html#index_Mongoose-createConnection) are now smart enough to just do the right thing with your connection string. If you really want to bring `connectSet` and `createSetConnection` back use [this module](https://github.com/aheckmann/mongoose-v2-compat).
- h3#mongoosenumber Number type
- :markdown
- The custom subclassed Number type Mongoose used to use for all numbers is now gone. It caused [too many problems](https://groups.google.com/d/msg/mongoose-orm/syKlN2xL1EE/FfRFhEFj4KcJ) when doing comparisons and had other bad side-effects.
+ h3 Schemas
+ :markdown
+ - are now [strict](./guide.html#strict) by default.
+ - Arrays of [object literal](./subdocs.html#altsyntax) now creates document arrays instead of arrays of [Mixed](./schematypes.html#mixed).
+ - Indexes are now created in [background](./guide.html#autoIndex) by default.
+ - Index errors are now emitted on their model instead of the connection. See issue [#984](https://github.com/LearnBoost/mongoose/issues/984).
- With it out of the picture, the following helper methods of MongooseNumbers are now also gone:
+ h3#arrays Arrays
+ :markdown
+ - [pop](./api.html#types_array_MongooseArray-pop) is now fixed causing a $set of the entire array.
+ - [$pop](./api.html#types_array_MongooseArray-%24pop) is now fixed and behaves just as MongoDB [$pop](http://www.mongodb.org/display/DOCS/Updating#Updating-%24pop) does, removing at most the last element of the array.
+ - [shift](./api.html#types_array_MongooseArray-shift) is now fixed causing a $set of the entire array.
+ - [$shift](./api.html#types_array_MongooseArray-%24shift) is now fixed and behaves just as a [MongoDB $pop -1](http://www.mongodb.org/display/DOCS/Updating#Updating-%24pop) does, removing at most the first element of array.
+ - `$unshift` was removed, use [unshift](./api.html#types_array_MongooseArray-unshift) instead.
+ - `$addToSet` was removed, use [addToSet](./api.html#types_array_MongooseArray-addToSet) instead.
+ - `$pushAll` was removed, use [push](./api.html#types_array_MongooseArray-push) instead.
+ - `$pull` was removed, use [pull](./api.html#types_array_MongooseArray-pull) instead.
+ - `$pullAll` was removed, use [pull](./api.html#types_array_MongooseArray-pull) instead.
+ - `doAtomics` was changed to the [hasAtomics](./api.html#types_array_MongooseArray-hasAtomics) private method
- - $inc
- - $increment
- - $decrement
+ h3#mongoosenumber Number type
+ :markdown
+ The custom subclassed Number type Mongoose used to use for all numbers is now gone. It caused [too many problems](https://groups.google.com/d/msg/mongoose-orm/syKlN2xL1EE/FfRFhEFj4KcJ) when doing comparisons and had other bad side-effects.
- If you really want this behavior back, include the [mongoose-number](https://github.com/aheckmann/mongoose-number) module in your project.
+ With it out of the picture, the following helper methods of MongooseNumbers are now also gone:
- A good alternative is to start using the new [findAndModify](./api.html#model_Model-findOneAndUpdate) [helpers](./api.html#model_Model-findOneAndRemove).
- Say we have an inventory of 10 products and a customer purchases 7 of them. In Mongoose v2 you could have depended on MongooseNumber:
- :js
- var inventorySchema = new Schema({ productCount: Number });
- ...
- Inventory.findById(id, function (err, inventory) {
- if (err) return handleError(err);
- inventory.productCount.$decrement(7);
- inventory.save(function (err) {
- // sends Inventory.update({ _id: id }, { $inc: { balance: -7 }}, callback);
- if (err) return handleError(err);
- res.send(inventory.productCount); // 3
- });
- });
- :markdown
- With MongooseNumber out of the picture, we'll instead use the [Account.findByIdAndUpdate](./api.html#model_Model-findByIdAndUpdate) helper:
- :js
- Inventory.findByIdAndUpdate(id, { $inc: { productCount: -7 }}, function (err, inventory) {
- if (err) return handleError(err);
- res.send(inventory.productCount); // 3
- });
- :markdown
- The `findByIdAndUpdate` helper not only finds the document but updates it as well before responding with the altered document. The findAndModify helpers are a great addition for many use cases.
+ - $inc
+ - $increment
+ - $decrement
- h3#documents Documents
- :markdown
- - `doc#commit` is now removed, use [doc.markModified](./api.html#document_Document-markModified) instead
- - [doc#modifiedPaths](./api.html#document_Document-modifiedPaths) is now a method not a getter
- - `doc.modified` is now removed, use [doc.isModified](./api.html#document_Document-isModified) instead
+ If you really want this behavior back, include the [mongoose-number](https://github.com/aheckmann/mongoose-number) module in your project.
- h4#gettercasting getter casting
- :markdown
- Getters no longer apply casting. Casting happens at set time. Useful in situations where you desire formatted responses like currency. See issue [#820](https://github.com/LearnBoost/mongoose/issues/820) and pull [#924](https://github.com/LearnBoost/mongoose/pull/924).
+ A good alternative is to start using the new [findAndModify](./api.html#model_Model-findOneAndUpdate) [helpers](./api.html#model_Model-findOneAndRemove).
+ Say we have an inventory of 10 products and a customer purchases 7 of them. In Mongoose v2 you could have depended on MongooseNumber:
+ :js
+ var inventorySchema = new Schema({ productCount: Number });
+ ...
+ Inventory.findById(id, function (err, inventory) {
+ if (err) return handleError(err);
+ inventory.productCount.$decrement(7);
+ inventory.save(function (err) {
+ // sends Inventory.update({ _id: id }, { $inc: { balance: -7 }}, callback);
+ if (err) return handleError(err);
+ res.send(inventory.productCount); // 3
+ });
+ });
+ :markdown
+ With MongooseNumber out of the picture, we'll instead use the [Account.findByIdAndUpdate](./api.html#model_Model-findByIdAndUpdate) helper:
+ :js
+ Inventory.findByIdAndUpdate(id, { $inc: { productCount: -7 }}, function (err, inventory) {
+ if (err) return handleError(err);
+ res.send(inventory.productCount); // 3
+ });
+ :markdown
+ The `findByIdAndUpdate` helper not only finds the document but updates it as well before responding with the altered document. The findAndModify helpers are a great addition for many use cases.
- h4#setterorder setter order
- :markdown
- Values being set no longer cast until _after_ all setters have been applied. Previously the value returned from each setter was cast _before_ passing it on to the next setter. This changes allows more flexible processing of values in setters. See issue [#665](https://github.com/learnboost/mongoose/issues/665) and pull [#924](https://github.com/LearnBoost/mongoose/pull/924).
+ h3#documents Documents
+ :markdown
+ - `doc#commit` is now removed, use [doc.markModified](./api.html#document_Document-markModified) instead
+ - [doc#modifiedPaths](./api.html#document_Document-modifiedPaths) is now a method not a getter
+ - `doc.modified` is now removed, use [doc.isModified](./api.html#document_Document-isModified) instead
- h3#subdocs Subdocuments
- :markdown
- - `subdoc.parent` was changed from a property to a [method](./api.html#types_embedded_EmbeddedDocument-parent). See issue [#928](https://github.com/LearnBoost/mongoose/issues/928).
- - `subdoc.parentArray` was changed from a property to a [method](./api.html#types_embedded_EmbeddedDocument-parentArray). See issue [#928](https://github.com/LearnBoost/mongoose/issues/928).
+ h4#gettercasting getter casting
+ :markdown
+ Getters no longer apply casting. Casting happens at set time. Useful in situations where you desire formatted responses like currency. See issue [#820](https://github.com/LearnBoost/mongoose/issues/820) and pull [#924](https://github.com/LearnBoost/mongoose/pull/924).
- h3#stringmatch String match validator
- :markdown
- The String SchemaType [match](./api.html#schema_string_SchemaString-match) validator no longer checks against null, undefined, or ''. If you need to validate against these values, enable the [required](./api.html#schematype_SchemaType-required) validator as well. See issue [#934](https://github.com/LearnBoost/mongoose/issues/934) and pull request [#935](https://github.com/LearnBoost/mongoose/pull/935).
+ h4#setterorder setter order
+ :markdown
+ Values being set no longer cast until _after_ all setters have been applied. Previously the value returned from each setter was cast _before_ passing it on to the next setter. This changes allows more flexible processing of values in setters. See issue [#665](https://github.com/learnboost/mongoose/issues/665) and pull [#924](https://github.com/LearnBoost/mongoose/pull/924).
- h3#version Versioning
- :markdown
- Documents are now transparently versioned. Read the in depth details [here](http://aaronheckmann.posterous.com/tag/versioning).
+ h3#subdocs Subdocuments
+ :markdown
+ - `subdoc.parent` was changed from a property to a [method](./api.html#types_embedded_EmbeddedDocument-parent). See issue [#928](https://github.com/LearnBoost/mongoose/issues/928).
+ - `subdoc.parentArray` was changed from a property to a [method](./api.html#types_embedded_EmbeddedDocument-parentArray). See issue [#928](https://github.com/LearnBoost/mongoose/issues/928).
+
+ h3#stringmatch String match validator
+ :markdown
+ The String SchemaType [match](./api.html#schema_string_SchemaString-match) validator no longer checks against null, undefined, or ''. If you need to validate against these values, enable the [required](./api.html#schematype_SchemaType-required) validator as well. See issue [#934](https://github.com/LearnBoost/mongoose/issues/934) and pull request [#935](https://github.com/LearnBoost/mongoose/pull/935).
+
+ h3#version Versioning
+ :markdown
+ Documents are now transparently versioned. Read the in depth details [here](http://aaronheckmann.posterous.com/tag/versioning).
View
12 docs/models.html
@@ -1,4 +1,4 @@
-<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"><title>Mongoose Quick Start v3.0.0</title><link href="http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700" rel="stylesheet" type="text/css"><link href="/docs/css/default.css" rel="stylesheet" type="text/css"><link href="/docs/css/guide.css" rel="stylesheet" type="text/css"></head><body><a id="forkbanner" href="http://github.com/learnboost/mongoose"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" alt="Fork me on GitHub"></a><div id="links"><div id="header"><h1><a href="../index.html"><div class="mongoose">Mongoose</div></a></h1></div><ul><li class="home"><a href="../index.html">home</a></li><li class="plugins"><a href="http://plugins.mongoosejs.com">plugins</a></li><li class="changelog"><a href="http://github.com/learnboost/mongoose/tree/master/History.md">change log</a></li><li class="support"><a href="../index.html#support">support</a></li><li class="fork"><a href="http://github.com/learnboost/mongoose">fork</a></li><li class="guide"><a href="./guide.html">guide</a><ul><li class="double"><a href="./guide.html">schemas</a><ul><li class="schematypes"><a href="./schematypes.html"><span>schema</span>types</a></li></ul></li><li class="double"><a href="./documents.html">documents</a><ul><li class="subdocs"><a href="./subdocs.html">sub docs</a></li></ul></li><li><a href="./models.html">models</a></li><li><a href="./queries.html">queries</a></li><li><a href="./plugins.html">plugins</a></li><li><a href="./middleware.html">middleware</a></li><li><a href="./validation.html">validation</a></li><li><a href="./populate.html">populate</a></li><li><a href="./migration.html">migrating from 2.x</a></li><li><a href="./contributing.html">contributing</a></li></ul></li><li class="api"><a href="./api.html">api docs</a></li><li class="quickstart"><a href="./index.html">quick start</a></li><li class="contrib"><a href="http://github.com/learnboost/mongoose/contributors">contributors</a></li><li class="prior"><a href="./prior.html">prior releases</a></li></ul></div><div id="content"><div class="module"><h2>Models</h2><p><a href="./api.html#model-js">Models</a> are fancy constructors compiled from our <code>Schema</code> definitions. Instances of these models represent <a href="./documents.html">documents</a> which can be saved and retreived from our database. All document creation and retreival from the database is handled by these models.</p><h3>Compiling your first model</h3><pre><code class="javascript"><span class="keyword">var</span> schema = <span class="keyword">new</span> Schema({ name: <span class="string">'string'</span>, size: <span class="string">'string'</span> });
+<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"><title>Mongoose Models v3.0.0</title><link href="http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700" rel="stylesheet" type="text/css"><link href="/docs/css/default.css" rel="stylesheet" type="text/css"><link href="/docs/css/guide.css" rel="stylesheet" type="text/css"></head><body><a id="forkbanner" href="http://github.com/learnboost/mongoose"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" alt="Fork me on GitHub"></a><div id="links"><div id="header"><h1><a href="../index.html"><div class="mongoose">Mongoose</div></a></h1></div><ul><li class="home"><a href="../index.html">home</a></li><li class="plugins"><a href="http://plugins.mongoosejs.com">plugins</a></li><li class="changelog"><a href="http://github.com/learnboost/mongoose/tree/master/History.md">change log</a></li><li class="support"><a href="../index.html#support">support</a></li><li class="fork"><a href="http://github.com/learnboost/mongoose">fork</a></li><li class="guide"><a href="./guide.html">guide</a><ul><li class="double"><a href="./guide.html">schemas</a><ul><li class="schematypes"><a href="./schematypes.html"><span>schema</span>types</a></li></ul></li><li class="double"><a href="./documents.html">documents</a><ul><li class="subdocs"><a href="./subdocs.html">sub docs</a></li></ul></li><li><a href="./models.html">models</a></li><li><a href="./queries.html">queries</a></li><li><a href="./plugins.html">plugins</a></li><li><a href="./middleware.html">middleware</a></li><li><a href="./validation.html">validation</a></li><li><a href="./populate.html">populate</a></li><li><a href="./migration.html">migrating from 2.x</a></li><li><a href="./contributing.html">contributing</a></li></ul></li><li class="api"><a href="./api.html">api docs</a></li><li class="quickstart"><a href="./index.html">quick start</a></li><li class="contrib"><a href="http://github.com/learnboost/mongoose/contributors">contributors</a></li><li class="prior"><a href="./prior.html">prior releases</a></li></ul></div><div id="content"><div class="module"><h2>Models</h2><p><a href="./api.html#model-js">Models</a> are fancy constructors compiled from our <code>Schema</code> definitions. Instances of these models represent <a href="./documents.html">documents</a> which can be saved and retreived from our database. All document creation and retreival from the database is handled by these models.</p><h3>Compiling your first model</h3><pre><code class="javascript"><span class="keyword">var</span> schema = <span class="keyword">new</span> Schema({ name: <span class="string">'string'</span>, size: <span class="string">'string'</span> });
<span class="keyword">var</span> Tank = mongoose.model(<span class="string">'Tank'</span>, schema);
<span class="comment">// or, if you are using separate connections</span>
@@ -21,4 +21,12 @@
</code></pre><h3>Querying</h3><p>Finding documents is easy with Mongoose, which supports the <a href="http://www.mongodb.org/display/DOCS/Advanced+Queries">rich</a> query syntax of MongoDB. Documents can be retreived using each <code>models</code> <a href="./api.html#model_Model-find">find</a>, <a href="./api.html#model_Model-findById">findById</a>, <a href="./api.html#model_Model-findOne">findOne</a>, or <a href="./api.html#model_Model-where">where</a> static methods.</p><pre><code class="javascript">Tank.find({ type: <span class="string">'small'</span> }).where(<span class="string">'createdDate'</span>).gt(oneYearAgo).exec(callback);</code></pre><p>See the chapter on <a href="./queries.html">querying</a> for more details on how to use the <a href="./api.html#query-js">Query</a> api.</p><h3>Removing</h3><p>Models have a static <code>remove</code> method available for removing all documents matching <code>conditions</code>.</p><pre><code class="javascript">Tank.remove({ size: <span class="string">'large'</span> }, <span class="function"><span class="keyword">function</span> <span class="params">(err)</span> {</span>
<span class="keyword">if</span> (err) <span class="keyword">return</span> handleError(err);
<span class="comment">// removed!</span>
-});</code></pre><h3>Updating</h3><p>Each <code>model</code> has its own <code>update</code> method for modifying documents in the database without returning them to your application. See the <a href="./api.html#model_Model-update">API</a> docs for more detail.</p><h3>Yet more</h3><p>The <a href="./api.html#model_Model">API docs</a> cover many additional methods available like <a href="./api.html#model_Model-count">count</a>, <a href="./api.html#model_Model-mapReduce">mapReduce</a>, and more.</p></div></div></body></html>
+});</code></pre><h3>Updating</h3><p>Each <code>model</code> has its own <code>update</code> method for modifying documents in the database without returning them to your application. See the <a href="./api.html#model_Model-update">API</a> docs for more detail.</p><h3>Yet more</h3><p>The <a href="./api.html#model_Model">API docs</a> cover many additional methods available like <a href="./api.html#model_Model-count">count</a>, <a href="./api.html#model_Model-mapReduce">mapReduce</a>, and more.</p></div></div><script>document.body.className = 'load';</script><script>var _gaq = _gaq || [];
+_gaq.push(['_setAccount', 'UA-1122274-9']);
+_gaq.push(['_trackPageview']);
+
+(function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+})();</script></body></html>
View
131 docs/models.jade
@@ -1,74 +1,57 @@
-doctype html
-html(lang='en')
- head
- meta(charset="utf-8")
- meta(name="viewport", content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no")
- title Mongoose Quick Start v#{package.version}
- link(href='http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700', rel='stylesheet', type='text/css')
- link(href='/docs/css/default.css', rel='stylesheet', type='text/css')
- link(href='/docs/css/guide.css', rel='stylesheet', type='text/css')
- body
- a#forkbanner(href="http://github.com/learnboost/mongoose")
- img(style="position: absolute; top: 0; right: 0; border: 0;", src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png", alt="Fork me on GitHub")
- #links
- #header
- h1
- a(href="../index.html")
- .mongoose Mongoose
- include includes/nav
- #content
- .module
- h2 Models
- :markdown
- [Models](./api.html#model-js) are fancy constructors compiled from our `Schema` definitions. Instances of these models represent [documents](./documents.html) which can be saved and retreived from our database. All document creation and retreival from the database is handled by these models.
-
- h3 Compiling your first model
- :js
- var schema = new Schema({ name: 'string', size: 'string' });
- var Tank = mongoose.model('Tank', schema);
-
- // or, if you are using separate connections
- var db = mongoose.createConnection(..);
- var Tank = db.model('Tank', schema);
-
- h3 Constructing documents
- :markdown
- [Documents](./documents.html) are instances of our model. Creating them and saving to the database is easy:
- :js
- var Tank = db.model('Tank', yourSchema);
-
- var small = new Tank({ size: 'small' });
- small.save(function (err) {
- if (err) return handleError(err);
- // saved!
- })
-
- // or
-
- Tank.create({ size: 'small' }, function (err) {
- if (err) return handleError(err);
- // saved!
- })
-
- h3 Querying
- :markdown
- Finding documents is easy with Mongoose, which supports the [rich](http://www.mongodb.org/display/DOCS/Advanced+Queries) query syntax of MongoDB. Documents can be retreived using each `models` [find](./api.html#model_Model-find), [findById](./api.html#model_Model-findById), [findOne](./api.html#model_Model-findOne), or [where](./api.html#model_Model-where) static methods.
-
- :js
- Tank.find({ type: 'small' }).where('createdDate').gt(oneYearAgo).exec(callback);
- :markdown
- See the chapter on [querying](./queries.html) for more details on how to use the [Query](./api.html#query-js) api.
- h3 Removing
- :markdown
- Models have a static `remove` method available for removing all documents matching `conditions`.
- :js
- Tank.remove({ size: 'large' }, function (err) {
- if (err) return handleError(err);
- // removed!
- });
- h3 Updating
- :markdown
- Each `model` has its own `update` method for modifying documents in the database without returning them to your application. See the [API](./api.html#model_Model-update) docs for more detail.
- h3 Yet more
- :markdown
- The [API docs](./api.html#model_Model) cover many additional methods available like [count](./api.html#model_Model-count), [mapReduce](./api.html#model_Model-mapReduce), and more.
+extends layout
+
+block content
+ h2 Models
+ :markdown
+ [Models](./api.html#model-js) are fancy constructors compiled from our `Schema` definitions. Instances of these models represent [documents](./documents.html) which can be saved and retreived from our database. All document creation and retreival from the database is handled by these models.
+
+ h3 Compiling your first model
+ :js
+ var schema = new Schema({ name: 'string', size: 'string' });
+ var Tank = mongoose.model('Tank', schema);
+
+ // or, if you are using separate connections
+ var db = mongoose.createConnection(..);
+ var Tank = db.model('Tank', schema);
+
+ h3 Constructing documents
+ :markdown
+ [Documents](./documents.html) are instances of our model. Creating them and saving to the database is easy:
+ :js
+ var Tank = db.model('Tank', yourSchema);
+
+ var small = new Tank({ size: 'small' });
+ small.save(function (err) {
+ if (err) return handleError(err);
+ // saved!
+ })
+
+ // or
+
+ Tank.create({ size: 'small' }, function (err) {
+ if (err) return handleError(err);
+ // saved!
+ })
+
+ h3 Querying
+ :markdown
+ Finding documents is easy with Mongoose, which supports the [rich](http://www.mongodb.org/display/DOCS/Advanced+Queries) query syntax of MongoDB. Documents can be retreived using each `models` [find](./api.html#model_Model-find), [findById](./api.html#model_Model-findById), [findOne](./api.html#model_Model-findOne), or [where](./api.html#model_Model-where) static methods.
+
+ :js
+ Tank.find({ type: 'small' }).where('createdDate').gt(oneYearAgo).exec(callback);
+ :markdown
+ See the chapter on [querying](./queries.html) for more details on how to use the [Query](./api.html#query-js) api.
+ h3 Removing
+ :markdown
+ Models have a static `remove` method available for removing all documents matching `conditions`.
+ :js
+ Tank.remove({ size: 'large' }, function (err) {
+ if (err) return handleError(err);
+ // removed!
+ });
+ h3 Updating
+ :markdown
+ Each `model` has its own `update` method for modifying documents in the database without returning them to your application. See the [API](./api.html#model_Model-update) docs for more detail.
+ h3 Yet more
+ :markdown
+ The [API docs](./api.html#model_Model) cover many additional methods available like [count](./api.html#model_Model-count), [mapReduce](./api.html#model_Model-mapReduce), and more.
View
12 docs/plugins.html
@@ -1,4 +1,4 @@
-<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"><title>Mongoose Quick Start v3.0.0</title><link href="http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700" rel="stylesheet" type="text/css"><link href="/docs/css/default.css" rel="stylesheet" type="text/css"><link href="/docs/css/guide.css" rel="stylesheet" type="text/css"></head><body><a id="forkbanner" href="http://github.com/learnboost/mongoose"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" alt="Fork me on GitHub"></a><div id="links"><div id="header"><h1><a href="../index.html"><div class="mongoose">Mongoose</div></a></h1></div><ul><li class="home"><a href="../index.html">home</a></li><li class="plugins"><a href="http://plugins.mongoosejs.com">plugins</a></li><li class="changelog"><a href="http://github.com/learnboost/mongoose/tree/master/History.md">change log</a></li><li class="support"><a href="../index.html#support">support</a></li><li class="fork"><a href="http://github.com/learnboost/mongoose">fork</a></li><li class="guide"><a href="./guide.html">guide</a><ul><li class="double"><a href="./guide.html">schemas</a><ul><li class="schematypes"><a href="./schematypes.html"><span>schema</span>types</a></li></ul></li><li class="double"><a href="./documents.html">documents</a><ul><li class="subdocs"><a href="./subdocs.html">sub docs</a></li></ul></li><li><a href="./models.html">models</a></li><li><a href="./queries.html">queries</a></li><li><a href="./plugins.html">plugins</a></li><li><a href="./middleware.html">middleware</a></li><li><a href="./validation.html">validation</a></li><li><a href="./populate.html">populate</a></li><li><a href="./migration.html">migrating from 2.x</a></li><li><a href="./contributing.html">contributing</a></li></ul></li><li class="api"><a href="./api.html">api docs</a></li><li class="quickstart"><a href="./index.html">quick start</a></li><li class="contrib"><a href="http://github.com/learnboost/mongoose/contributors">contributors</a></li><li class="prior"><a href="./prior.html">prior releases</a></li></ul></div><div id="content"><div class="module"><h2>Plugins</h2><p>Schemas are pluggable, that is, they allow for applying pre-packaged capabilities to extend their functionality. This is a very powerful feature.</p>
+<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"><title>Mongoose Plugins v3.0.0</title><link href="http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700" rel="stylesheet" type="text/css"><link href="/docs/css/default.css" rel="stylesheet" type="text/css"><link href="/docs/css/guide.css" rel="stylesheet" type="text/css"></head><body><a id="forkbanner" href="http://github.com/learnboost/mongoose"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" alt="Fork me on GitHub"></a><div id="links"><div id="header"><h1><a href="../index.html"><div class="mongoose">Mongoose</div></a></h1></div><ul><li class="home"><a href="../index.html">home</a></li><li class="plugins"><a href="http://plugins.mongoosejs.com">plugins</a></li><li class="changelog"><a href="http://github.com/learnboost/mongoose/tree/master/History.md">change log</a></li><li class="support"><a href="../index.html#support">support</a></li><li class="fork"><a href="http://github.com/learnboost/mongoose">fork</a></li><li class="guide"><a href="./guide.html">guide</a><ul><li class="double"><a href="./guide.html">schemas</a><ul><li class="schematypes"><a href="./schematypes.html"><span>schema</span>types</a></li></ul></li><li class="double"><a href="./documents.html">documents</a><ul><li class="subdocs"><a href="./subdocs.html">sub docs</a></li></ul></li><li><a href="./models.html">models</a></li><li><a href="./queries.html">queries</a></li><li><a href="./plugins.html">plugins</a></li><li><a href="./middleware.html">middleware</a></li><li><a href="./validation.html">validation</a></li><li><a href="./populate.html">populate</a></li><li><a href="./migration.html">migrating from 2.x</a></li><li><a href="./contributing.html">contributing</a></li></ul></li><li class="api"><a href="./api.html">api docs</a></li><li class="quickstart"><a href="./index.html">quick start</a></li><li class="contrib"><a href="http://github.com/learnboost/mongoose/contributors">contributors</a></li><li class="prior"><a href="./prior.html">prior releases</a></li></ul></div><div id="content"><div class="module"><h2>Plugins</h2><p>Schemas are pluggable, that is, they allow for applying pre-packaged capabilities to extend their functionality. This is a very powerful feature.</p>
<p>Suppose that we have several collections in our database and want to add last-modified functionality to each one. With plugins this is easy. Just create a plugin once and apply it to each <code>Schema</code>:</p><pre><code class="javascript"><span class="comment">// lastMod.js</span>
module.exports = exports = <span class="function"><span class="keyword">function</span> <span class="title">lastModifiedPlugin</span> <span class="params">(schema, options)</span> {</span>
@@ -22,4 +22,12 @@
<span class="comment">// player-schema.js</span>
<span class="keyword">var</span> lastMod = require(<span class="string">'./lastMod'</span>);
<span class="keyword">var</span> Player = <span class="keyword">new</span> Schema({ ... });
-Player.plugin(lastMod);</code></pre><p>We just added last-modified behavior to both our <code>Game</code> and <code>Player</code> schemas and declared an index on the <code>lastMod</code> path of our Games to boot. Not bad for a few lines of code.</p><h3>Community!</h3><p>Not only can you re-use schema functionality in your own projects but you also reap the benefits of the Mongoose community as well. Any plugin published to <a href="https://npmjs.org/">npm</a> and <a href="https://npmjs.org/doc/tag.html">tagged</a> with <code>mongoose</code> will show up on our <a href="http://plugins.mongoosejs.com">search results</a> page.</p></div></div></body></html>
+Player.plugin(lastMod);</code></pre><p>We just added last-modified behavior to both our <code>Game</code> and <code>Player</code> schemas and declared an index on the <code>lastMod</code> path of our Games to boot. Not bad for a few lines of code.</p><h3>Community!</h3><p>Not only can you re-use schema functionality in your own projects but you also reap the benefits of the Mongoose community as well. Any plugin published to <a href="https://npmjs.org/">npm</a> and <a href="https://npmjs.org/doc/tag.html">tagged</a> with <code>mongoose</code> will show up on our <a href="http://plugins.mongoosejs.com">search results</a> page.</p></div></div><script>document.body.className = 'load';</script><script>var _gaq = _gaq || [];
+_gaq.push(['_setAccount', 'UA-1122274-9']);
+_gaq.push(['_trackPageview']);
+
+(function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+})();</script></body></html>
View
81 docs/plugins.jade
@@ -1,55 +1,38 @@
-doctype html
-html(lang='en')
- head
- meta(charset="utf-8")
- meta(name="viewport", content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no")
- title Mongoose Quick Start v#{package.version}
- link(href='http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700', rel='stylesheet', type='text/css')
- link(href='/docs/css/default.css', rel='stylesheet', type='text/css')
- link(href='/docs/css/guide.css', rel='stylesheet', type='text/css')
- body
- a#forkbanner(href="http://github.com/learnboost/mongoose")
- img(style="position: absolute; top: 0; right: 0; border: 0;", src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png", alt="Fork me on GitHub")
- #links
- #header
- h1
- a(href="../index.html")
- .mongoose Mongoose
- include includes/nav
- #content
- .module
- h2 Plugins
- :markdown
- Schemas are pluggable, that is, they allow for applying pre-packaged capabilities to extend their functionality. This is a very powerful feature.
+extends layout
- Suppose that we have several collections in our database and want to add last-modified functionality to each one. With plugins this is easy. Just create a plugin once and apply it to each `Schema`:
+block content
+ h2 Plugins
+ :markdown
+ Schemas are pluggable, that is, they allow for applying pre-packaged capabilities to extend their functionality. This is a very powerful feature.
- :js
- // lastMod.js
- module.exports = exports = function lastModifiedPlugin (schema, options) {
- schema.add({ lastMod: Date })
+ Suppose that we have several collections in our database and want to add last-modified functionality to each one. With plugins this is easy. Just create a plugin once and apply it to each `Schema`:
- schema.pre('save', function (next) {
- this.lastMod = new Date
- next()
- })
+ :js
+ // lastMod.js
+ module.exports = exports = function lastModifiedPlugin (schema, options) {
+ schema.add({ lastMod: Date })
- if (options && options.index) {
- schema.path('lastMod').index(options.index)
- }
- }
+ schema.pre('save', function (next) {
+ this.lastMod = new Date
+ next()
+ })
- // game-schema.js
- var lastMod = require('./lastMod');
- var Game = new Schema({ ... });
- Game.plugin(lastMod, { index: true });
+ if (options && options.index) {
+ schema.path('lastMod').index(options.index)
+ }
+ }
- // player-schema.js
- var lastMod = require('./lastMod');
- var Player = new Schema({ ... });
- Player.plugin(lastMod);
- :markdown
- We just added last-modified behavior to both our `Game` and `Player` schemas and declared an index on the `lastMod` path of our Games to boot. Not bad for a few lines of code.
- h3 Community!
- :markdown
- Not only can you re-use schema functionality in your own projects but you also reap the benefits of the Mongoose community as well. Any plugin published to [npm](https://npmjs.org/) and [tagged](https://npmjs.org/doc/tag.html) with `mongoose` will show up on our [search results](http://plugins.mongoosejs.com) page.
+ // game-schema.js
+ var lastMod = require('./lastMod');
+ var Game = new Schema({ ... });
+ Game.plugin(lastMod, { index: true });
+
+ // player-schema.js
+ var lastMod = require('./lastMod');
+ var Player = new Schema({ ... });
+ Player.plugin(lastMod);
+ :markdown
+ We just added last-modified behavior to both our `Game` and `Player` schemas and declared an index on the `lastMod` path of our Games to boot. Not bad for a few lines of code.
+ h3 Community!
+ :markdown
+ Not only can you re-use schema functionality in your own projects but you also reap the benefits of the Mongoose community as well. Any plugin published to [npm](https://npmjs.org/) and [tagged](https://npmjs.org/doc/tag.html) with `mongoose` will show up on our [search results](http://plugins.mongoosejs.com) page.
View
12 docs/populate.html
@@ -1,4 +1,4 @@
-<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"><title>Mongoose Quick Start v3.0.0</title><link href="http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700" rel="stylesheet" type="text/css"><link href="/docs/css/default.css" rel="stylesheet" type="text/css"><link href="/docs/css/guide.css" rel="stylesheet" type="text/css"></head><body><a id="forkbanner" href="http://github.com/learnboost/mongoose"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" alt="Fork me on GitHub"></a><div id="links"><div id="header"><h1><a href="../index.html"><div class="mongoose">Mongoose</div></a></h1></div><ul><li class="home"><a href="../index.html">home</a></li><li class="plugins"><a href="http://plugins.mongoosejs.com">plugins</a></li><li class="changelog"><a href="http://github.com/learnboost/mongoose/tree/master/History.md">change log</a></li><li class="support"><a href="../index.html#support">support</a></li><li class="fork"><a href="http://github.com/learnboost/mongoose">fork</a></li><li class="guide"><a href="./guide.html">guide</a><ul><li class="double"><a href="./guide.html">schemas</a><ul><li class="schematypes"><a href="./schematypes.html"><span>schema</span>types</a></li></ul></li><li class="double"><a href="./documents.html">documents</a><ul><li class="subdocs"><a href="./subdocs.html">sub docs</a></li></ul></li><li><a href="./models.html">models</a></li><li><a href="./queries.html">queries</a></li><li><a href="./plugins.html">plugins</a></li><li><a href="./middleware.html">middleware</a></li><li><a href="./validation.html">validation</a></li><li><a href="./populate.html">populate</a></li><li><a href="./migration.html">migrating from 2.x</a></li><li><a href="./contributing.html">contributing</a></li></ul></li><li class="api"><a href="./api.html">api docs</a></li><li class="quickstart"><a href="./index.html">quick start</a></li><li class="contrib"><a href="http://github.com/learnboost/mongoose/contributors">contributors</a></li><li class="prior"><a href="./prior.html">prior releases</a></li></ul></div><div id="content"><div class="module"><h2>Query Population</h2><p>There are no joins in MongoDB but sometimes we still want references to documents in other collections. This is where <a href="./api.html#query_Query-populate">query#populate</a> comes in.</p>
+<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"><title>Mongoose Query Population v3.0.0</title><link href="http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700" rel="stylesheet" type="text/css"><link href="/docs/css/default.css" rel="stylesheet" type="text/css"><link href="/docs/css/guide.css" rel="stylesheet" type="text/css"></head><body><a id="forkbanner" href="http://github.com/learnboost/mongoose"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" alt="Fork me on GitHub"></a><div id="links"><div id="header"><h1><a href="../index.html"><div class="mongoose">Mongoose</div></a></h1></div><ul><li class="home"><a href="../index.html">home</a></li><li class="plugins"><a href="http://plugins.mongoosejs.com">plugins</a></li><li class="changelog"><a href="http://github.com/learnboost/mongoose/tree/master/History.md">change log</a></li><li class="support"><a href="../index.html#support">support</a></li><li class="fork"><a href="http://github.com/learnboost/mongoose">fork</a></li><li class="guide"><a href="./guide.html">guide</a><ul><li class="double"><a href="./guide.html">schemas</a><ul><li class="schematypes"><a href="./schematypes.html"><span>schema</span>types</a></li></ul></li><li class="double"><a href="./documents.html">documents</a><ul><li class="subdocs"><a href="./subdocs.html">sub docs</a></li></ul></li><li><a href="./models.html">models</a></li><li><a href="./queries.html">queries</a></li><li><a href="./plugins.html">plugins</a></li><li><a href="./middleware.html">middleware</a></li><li><a href="./validation.html">validation</a></li><li><a href="./populate.html">populate</a></li><li><a href="./migration.html">migrating from 2.x</a></li><li><a href="./contributing.html">contributing</a></li></ul></li><li class="api"><a href="./api.html">api docs</a></li><li class="quickstart"><a href="./index.html">quick start</a></li><li class="contrib"><a href="http://github.com/learnboost/mongoose/contributors">contributors</a></li><li class="prior"><a href="./prior.html">prior releases</a></li></ul></div><div id="content"><div class="module"><h2>Query Population</h2><p>There are no joins in MongoDB but sometimes we still want references to documents in other collections. This is where <a href="./api.html#query_Query-populate">query#populate</a> comes in.</p>
<p><code>ObjectIds</code> can refer to another document in a collection within our database and be <code>populate()</code>d when querying:</p><pre><code class="javascript"><span class="keyword">var</span> mongoose = require(<span class="string">'mongoose'</span>)
, Schema = mongoose.Schema
@@ -87,4 +87,12 @@
<span class="comment">// prints "The creator is Guillermo"</span>
})
})
-})</code></pre><h4>NOTE:</h4><p>The documents returned from calling <a href="./api.html#query_Query-populate">populate</a> become fully functional, <code>remove</code>able, <code>save</code>able documents. Do not confuse them with <a href="./embedded.html">sub docs</a>. Take caution when calling its remove method because you&#39;ll be removing it from the database, not just the array.</p></div></div></body></html>
+})</code></pre><h4>NOTE:</h4><p>The documents returned from calling <a href="./api.html#query_Query-populate">populate</a> become fully functional, <code>remove</code>able, <code>save</code>able documents. Do not confuse them with <a href="./embedded.html">sub docs</a>. Take caution when calling its remove method because you&#39;ll be removing it from the database, not just the array.</p></div></div><script>document.body.className = 'load';</script><script>var _gaq = _gaq || [];
+_gaq.push(['_setAccount', 'UA-1122274-9']);
+_gaq.push(['_trackPageview']);
+
+(function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+})();</script></body></html>
View
307 docs/populate.jade
@@ -1,162 +1,145 @@
-doctype html
-html(lang='en')
- head
- meta(charset="utf-8")
- meta(name="viewport", content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no")
- title Mongoose Quick Start v#{package.version}
- link(href='http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700', rel='stylesheet', type='text/css')
- link(href='/docs/css/default.css', rel='stylesheet', type='text/css')
- link(href='/docs/css/guide.css', rel='stylesheet', type='text/css')
- body
- a#forkbanner(href="http://github.com/learnboost/mongoose")
- img(style="position: absolute; top: 0; right: 0; border: 0;", src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png", alt="Fork me on GitHub")
- #links
- #header
- h1
- a(href="../index.html")
- .mongoose Mongoose
- include includes/nav
- #content
- .module
- h2 Query Population
- :markdown
- There are no joins in MongoDB but sometimes we still want references to documents in other collections. This is where [query#populate](./api.html#query_Query-populate) comes in.
-
- `ObjectIds` can refer to another document in a collection within our database and be `populate()`d when querying:
- :js
- var mongoose = require('mongoose')
- , Schema = mongoose.Schema
-
- var PersonSchema = new Schema({
- name : String,
- age : Number,
- stories : [{ type: Schema.Types.ObjectId, ref: 'Story' }]
- });
-
- var StorySchema = new Schema({
- _creator : { type: Schema.Types.ObjectId, ref: 'Person' },
- title : String,
- fans : [{ type: Schema.Types.ObjectId, ref: 'Person' }]
- });
-
- var Story = mongoose.model('Story', StorySchema);
- var Person = mongoose.model('Person', PersonSchema);
- :markdown
- So far we've created two `models`. Our `Person` model has it's `stories` field set to an array of `ObjectId`s. The `ref` option is what tells Mongoose in which model to look, in our case the `Story` model. All `_id`s we store here must be document _ids from the `Story` model. We also added a `_creator` `ObjectId` to our `Story` schema which refers to a single `Person`.
- h3 Saving refs
- :markdown
- Saving refs to other documents works the same way you normally save objectids, just assign an `ObjectId`:
- :js
- var aaron = new Person({ name: 'Aaron', age: 100 });
-
- aaron.save(function (err) {
- if (err) return handleError(err);
-
- var story1 = new Story({
- title: "Once upon a timex.",
- _creator: aaron._id // assign an ObjectId
- });
-
- story1.save(function (err) {
- if (err) return handleError(err);
- // thats it!
- });
- })
- h3 Population
- :markdown
- So far we haven't done anything special. We've merely created a `Person` and a `Story`. Now let's take a look at populating our story's `_creator`:
- :js
- Story
- .findOne({ title: /timex/ })
- .populate('_creator')
- .exec(function (err, story) {
- if (err) return handleError(err);
- console.log('The creator is %s', story._creator.name); // prints "The creator is Aaron"
- })
-
- :markdown
- Populated paths are no longer set to their original `ObjectId`s, their value is replaced with the mongoose document returned from the database by performing a separate query before returning the results.
-
- Arrays of `ObjectId` refs work the same way. Just call the [populate](./api.html#query_Query-populate) method on the query and an array of documents will be returned _in place_ of the `ObjectIds`.
-
- h3 Field selection
- :markdown
- What if we only want a few specific fields returned for the query? This can be accomplished by passing the usual [field name syntax](./api.html#query_Query-select) as the second argument to the populate method:
- :js
- Story
- .findOne({ title: /timex/i })
- .populate('_creator', 'name') // only return the Persons name
- .exec(function (err, story) {
- if (err) return handleError(err);
-
- console.log('The creator is %s', story._creator.name);