Updating docs for 3.1.0

mongoid · Feb 13, 2013 · 694c5eb · 694c5eb
1 parent 29a1435
commit 694c5eb
Show file tree

Hide file tree

Showing 13 changed files with 393 additions and 31 deletions.
diff --git a/en/mongoid/docs/callbacks.html b/en/mongoid/docs/callbacks.html
@@ -89,13 +89,14 @@ <h1>Callbacks</h1>
 <div class='page-nav'>
   <div class='container'>
     <ul class='nav nav-pills'>
-      <li><a href="#callbacks">Callbacks</a></li>
+      <li><a href="#callbacks">Document Callbacks</a></li>
+      <li><a href="#relation_callbacks">Relation Callbacks</a></li>
       <li><a href="#observers">Observers</a></li>
     </ul>
   </div>
 </div>
 <section id='callbacks'>
-  <h2>Callbacks</h2>
+  <h2>Document Callbacks</h2>
   <p>
     Mongoid supports the following callbacks:
     <ul>
@@ -106,6 +107,7 @@ <h2>Callbacks</h2>
       <li><code>before_create</code></li>
       <li><code>around_create</code></li>
       <li><code>after_create</code></li>
+      <li><code>after_find</code> <span class="label label-info">Since 3.1.0</span></li>
       <li><code>before_update</code></li>
       <li><code>around_update</code></li>
       <li><code>after_update</code></li>
@@ -154,6 +156,24 @@ <h2>Callbacks</h2>
     <div class="code"><pre><span class="keyword">class</span> <span class="class">Article</span>&#x000A;  include <span class="constant">Mongoid</span>::<span class="constant">Document</span>&#x000A;  field <span class="symbol">:name</span>, type: <span class="constant">String</span>&#x000A;&#x000A;  set_callback(<span class="symbol">:create</span>, <span class="symbol">:before</span>) <span class="keyword">do</span> |document|&#x000A;    <span class="comment"># Message sending code here.</span>&#x000A;  <span class="keyword">end</span>&#x000A;<span class="keyword">end</span>&#x000A;</pre></div>
   </div>
 </section>
+<section id='relation_callbacks'>
+  <h2>
+    Relation Callbacks
+  </h2>
+  <span class='label label-info'>Since 3.1.0</span>
+  <p>
+    Mongoid has a set of callbacks that are specific to collection based relations - these are:
+    <ul>
+      <li><code>after_add</code></li>
+      <li><code>after_remove</code></li>
+      <li><code>before_add</code></li>
+      <li><code>before_remove</code></li>
+    </ul>
+    Each time a document is added or removed from any of the following relations,
+    the respective callbacks are fired: <code>embeds_many</code>,
+    <code>has_many</code>, and <code>has_and_belongs_to_many</code>.
+  </p>
+</section>
 <section id='observers'>
   <h2>Observers</h2>
   <p>

diff --git a/en/mongoid/docs/documents.html b/en/mongoid/docs/documents.html
@@ -140,6 +140,13 @@ <h2>Storage</h2>
   <div class="CodeRay">
     <div class="code"><pre><span class="keyword">class</span> <span class="class">Person</span>&#x000A;  include <span class="constant">Mongoid</span>::<span class="constant">Document</span>&#x000A;  store_in collection: <span class="string"><span class="delimiter">&quot;</span><span class="content">citizens</span><span class="delimiter">&quot;</span></span>, database: <span class="string"><span class="delimiter">&quot;</span><span class="content">other</span><span class="delimiter">&quot;</span></span>, session: <span class="string"><span class="delimiter">&quot;</span><span class="content">secondary</span><span class="delimiter">&quot;</span></span>&#x000A;<span class="keyword">end</span>&#x000A;</pre></div>
   </div>
+  <p>
+    The <code>store_in</code> macro can also take lambdas - a common case for this
+    is multi-tenant applications.
+  </p>
+  <div class="CodeRay">
+    <div class="code"><pre><span class="keyword">class</span> <span class="class">Band</span>&#x000A;  include <span class="constant">Mongoid</span>::<span class="constant">Document</span>&#x000A;  store_in database: -&gt;{ <span class="constant">Thread</span>.current[<span class="symbol">:database</span>] }&#x000A;<span class="keyword">end</span>&#x000A;</pre></div>
+  </div>
   <p>
     When a document is stored in the database the ruby object will get
     serialized into BSON and have a structure like so:
@@ -328,6 +335,19 @@ <h3>Custom field serialization</h3>
   <div class="CodeRay">
     <div class="code"><pre>point = <span class="constant">Point</span>.new(<span class="integer">12</span>, <span class="integer">24</span>)&#x000A;<span class="constant">Venue</span>.where(location: point)&#x000A;</pre></div>
   </div>
+  <div class='well'>
+    <table>
+      <tr>
+        <td class='achtung'><img src="/images/achtung.png" /></td>
+        <td class='note'>
+          When accessing custom fields from the document, you will get a new
+          instance of that object with each call to the getter. This is
+          because Mongoid is generating a new object from the object from the
+          raw attributes on each access.
+        </td>
+      </tr>
+    </table>
+  </div>
   <p>
     We need the point object in the criteria to be transformed to a Mongo
     friendly value when it is not as well, and <code>evolve</code> is the method

diff --git a/en/mongoid/docs/extras.html b/en/mongoid/docs/extras.html
@@ -116,7 +116,10 @@ <h2>Caching</h2>
   </div>
 </section>
 <section id='paranoia'>
-  <h2>Paranoid Documents</h2>
+  <h2>
+    Paranoid Documents
+    <span class="label label-info">Removing in 4.0.0</span>
+  </h2>
   <p>
     There may be times when you don't want documents to actually get deleted
     from the database, but "flagged" as deleted. Mongoid provides a Paranoia
@@ -135,7 +138,10 @@ <h2>Paranoid Documents</h2>
   </div>
 </section>
 <section id='versioning'>
-  <h2>Versioning</h2>
+  <h2>
+    Versioning
+    <span class="label label-info">Removing in 4.0.0</span>
+  </h2>
   <p>
     Mongoid supports simple versioning through inclusion of the
     <code>Mongoid::Versioning</code> module. Including this module will create a
@@ -183,7 +189,14 @@ <h2>Timestamping</h2>
     method:
   </p>
   <div class="CodeRay">
-    <div class="code"><pre>person.timeless.save&#x000A;<span class="constant">Person</span>.timeless.create!</pre></div>
+    <div class="code"><pre>person.timeless.save&#x000A;<span class="constant">Person</span>.timeless.create!&#x000A;</pre></div>
+  </div>
+  <p>
+    If you'd like shorter timestamp fields with aliases on them to save space,
+    you can include the short versions of the modules.
+  </p>
+  <div class="CodeRay">
+    <div class="code"><pre><span class="keyword">class</span> <span class="class">Band</span>&#x000A;  include <span class="constant">Mongoid</span>::<span class="constant">Document</span>&#x000A;  include <span class="constant">Mongoid</span>::<span class="constant">Timestamps</span>::<span class="constant">Short</span> <span class="comment"># For c_at and u_at.</span>&#x000A;<span class="keyword">end</span>&#x000A;&#x000A;<span class="keyword">class</span> <span class="class">Band</span>&#x000A;  include <span class="constant">Mongoid</span>::<span class="constant">Document</span>&#x000A;  include <span class="constant">Mongoid</span>::<span class="constant">Timestamps</span>::<span class="constant">Created</span>::<span class="constant">Short</span> <span class="comment"># For c_at only.</span>&#x000A;<span class="keyword">end</span>&#x000A;&#x000A;<span class="keyword">class</span> <span class="class">Band</span>&#x000A;  include <span class="constant">Mongoid</span>::<span class="constant">Document</span>&#x000A;  include <span class="constant">Mongoid</span>::<span class="constant">Timestamps</span>::<span class="constant">Updated</span>::<span class="constant">Short</span> <span class="comment"># For u_at only.</span>&#x000A;<span class="keyword">end</span></pre></div>
   </div>
 </section>
       </div>

diff --git a/en/mongoid/docs/indexing.html b/en/mongoid/docs/indexing.html
@@ -116,14 +116,20 @@ <h1>Indexing</h1>
   Indexes can be run in the background in cases where they may take some time:
 </p>
 <div class="CodeRay">
-  <div class="code"><pre><span class="keyword">class</span> <span class="class">Person</span>&#x000A;  include <span class="constant">Mongoid</span>::<span class="constant">Document</span>&#x000A;  field <span class="symbol">:ssn</span>&#x000A;&#x000A;  index({ ssn: <span class="integer">1</span> }, { unique: <span class="predefined-constant">true</span>, background: <span class="predefined-constant">true</span> })&#x000A;<span class="keyword">end</span>&#x000A;</pre></div>
+  <div class="code"><pre><span class="keyword">class</span> <span class="class">Person</span>&#x000A;  include <span class="constant">Mongoid</span>::<span class="constant">Document</span>&#x000A;  field <span class="symbol">:ssn</span>&#x000A;  index({ ssn: <span class="integer">1</span> }, { unique: <span class="predefined-constant">true</span>, background: <span class="predefined-constant">true</span> })&#x000A;<span class="keyword">end</span>&#x000A;</pre></div>
 </div>
 <p>
   For geospacial indexes, make sure the field you are indexing is an <tt>Array</tt>.
 </p>
 <div class="CodeRay">
   <div class="code"><pre><span class="keyword">class</span> <span class="class">Person</span>&#x000A;  include <span class="constant">Mongoid</span>::<span class="constant">Document</span>&#x000A;  field <span class="symbol">:location</span>, type: <span class="constant">Array</span>&#x000A;&#x000A;  index({ location: <span class="string"><span class="delimiter">&quot;</span><span class="content">2d</span><span class="delimiter">&quot;</span></span> }, { min: <span class="integer">-200</span>, max: <span class="integer">200</span> })&#x000A;<span class="keyword">end</span>&#x000A;</pre></div>
 </div>
+<p>
+  Indexes can be scoped to a specific database.
+</p>
+<div class="CodeRay">
+  <div class="code"><pre><span class="keyword">class</span> <span class="class">Person</span>&#x000A;  include <span class="constant">Mongoid</span>::<span class="constant">Document</span>&#x000A;  field <span class="symbol">:ssn</span>&#x000A;  index({ ssn: <span class="integer">1</span> }, { database: <span class="string"><span class="delimiter">&quot;</span><span class="content">users</span><span class="delimiter">&quot;</span></span>, unique: <span class="predefined-constant">true</span>, background: <span class="predefined-constant">true</span> })&#x000A;<span class="keyword">end</span>&#x000A;</pre></div>
+</div>
 <p>
   You can have Mongoid define indexes for you on "foreign key" fields for
   relational associations. This only works on the relation macro that the

diff --git a/en/mongoid/docs/installation.html b/en/mongoid/docs/installation.html
@@ -160,8 +160,8 @@ <h2>Installation</h2>
       <tr>
         <td class='achtung'><img src="/images/achtung.png" /></td>
         <td class='note'>
-          The minimum version of MongoDB that is required for you to run Mongoid 3
-          is <code>2.0.0</code>.
+          The minimum version of MongoDB that is required for you to run Mongoid
+          is <code>2.0.0</code> for 3.0.x and <code>2.2.0</code> for 3.1.x.
         </td>
       </tr>
     </table>
@@ -342,7 +342,7 @@ <h2>Logging</h2>
     logger to have a different level. Logging is turned off by default.
   </p>
   <div class="CodeRay">
-    <div class="code"><pre><span class="keyword">module</span> <span class="class">MyApplication</span>&#x000A;  <span class="keyword">class</span> <span class="class">Application</span> &lt;&lt; <span class="constant">Rails</span>::<span class="constant">Application</span>&#x000A;    <span class="constant">Mongoid</span>.logger.level = <span class="constant">Logger</span>::<span class="constant">DEBUG</span>&#x000A;    <span class="constant">Moped</span>.logger.level = <span class="constant">Logger</span>::<span class="constant">DEBUG</span>&#x000A;  <span class="keyword">end</span>&#x000A;<span class="keyword">end</span>&#x000A;</pre></div>
+    <div class="code"><pre><span class="keyword">module</span> <span class="class">MyApplication</span>&#x000A;  <span class="keyword">class</span> <span class="class">Application</span> &lt; <span class="constant">Rails</span>::<span class="constant">Application</span>&#x000A;    <span class="constant">Mongoid</span>.logger.level = <span class="constant">Logger</span>::<span class="constant">DEBUG</span>&#x000A;    <span class="constant">Moped</span>.logger.level = <span class="constant">Logger</span>::<span class="constant">DEBUG</span>&#x000A;  <span class="keyword">end</span>&#x000A;<span class="keyword">end</span>&#x000A;</pre></div>
   </div>
   <p>
     If you want to change the logger instance, you can simply just set a

diff --git a/en/mongoid/docs/persistence.html b/en/mongoid/docs/persistence.html
@@ -142,17 +142,17 @@ <h2>Standard</h2>
         <td class='doc'>
           <code>Model.create</code>
           <p class='doc'>
-            <i>Insert a document into the database</i>
+            <i>Insert a document or multiple documents into the database</i>
           </p>
         </td>
         <td>
           <div class="CodeRay">
-            <div class="code"><pre><span class="constant">Person</span>.create(&#x000A;  first_name: <span class="string"><span class="delimiter">&quot;</span><span class="content">Heinrich</span><span class="delimiter">&quot;</span></span>,&#x000A;  last_name: <span class="string"><span class="delimiter">&quot;</span><span class="content">Heine</span><span class="delimiter">&quot;</span></span>&#x000A;)&#x000A;&#x000A;<span class="constant">Person</span>.create(first_name: <span class="string"><span class="delimiter">&quot;</span><span class="content">Heinrich</span><span class="delimiter">&quot;</span></span>) <span class="keyword">do</span> |doc|&#x000A;  doc.last_name = <span class="string"><span class="delimiter">&quot;</span><span class="content">Heine</span><span class="delimiter">&quot;</span></span>&#x000A;<span class="keyword">end</span></pre></div>
+            <div class="code"><pre><span class="constant">Person</span>.create(&#x000A;  first_name: <span class="string"><span class="delimiter">&quot;</span><span class="content">Heinrich</span><span class="delimiter">&quot;</span></span>,&#x000A;  last_name: <span class="string"><span class="delimiter">&quot;</span><span class="content">Heine</span><span class="delimiter">&quot;</span></span>&#x000A;)&#x000A;&#x000A;<span class="constant">Person</span>.create([&#x000A;  { first_name: <span class="string"><span class="delimiter">&quot;</span><span class="content">Heinrich</span><span class="delimiter">&quot;</span></span>, last_name: <span class="string"><span class="delimiter">&quot;</span><span class="content">Heine</span><span class="delimiter">&quot;</span></span> },&#x000A;  { first_name: <span class="string"><span class="delimiter">&quot;</span><span class="content">Willy</span><span class="delimiter">&quot;</span></span>, last_name: <span class="string"><span class="delimiter">&quot;</span><span class="content">Brandt</span><span class="delimiter">&quot;</span></span> }&#x000A;])&#x000A;&#x000A;<span class="constant">Person</span>.create(first_name: <span class="string"><span class="delimiter">&quot;</span><span class="content">Heinrich</span><span class="delimiter">&quot;</span></span>) <span class="keyword">do</span> |doc|&#x000A;  doc.last_name = <span class="string"><span class="delimiter">&quot;</span><span class="content">Heine</span><span class="delimiter">&quot;</span></span>&#x000A;<span class="keyword">end</span></pre></div>
           </div>
         </td>
         <td>
           <div class="CodeRay">
-            <div class="code"><pre>collections[<span class="symbol">:people</span>].insert({&#x000A;  first_name: <span class="string"><span class="delimiter">&quot;</span><span class="content">Heinrich</span><span class="delimiter">&quot;</span></span>,&#x000A;  last_name: <span class="string"><span class="delimiter">&quot;</span><span class="content">Heine</span><span class="delimiter">&quot;</span></span>&#x000A;})</pre></div>
+            <div class="code"><pre>collections[<span class="symbol">:people</span>].insert({&#x000A;  first_name: <span class="string"><span class="delimiter">&quot;</span><span class="content">Heinrich</span><span class="delimiter">&quot;</span></span>,&#x000A;  last_name: <span class="string"><span class="delimiter">&quot;</span><span class="content">Heine</span><span class="delimiter">&quot;</span></span>&#x000A;})&#x000A;collections[<span class="symbol">:people</span>].insert([&#x000A;  { first_name: <span class="string"><span class="delimiter">&quot;</span><span class="content">Heinrich</span><span class="delimiter">&quot;</span></span>, last_name: <span class="string"><span class="delimiter">&quot;</span><span class="content">Heine</span><span class="delimiter">&quot;</span></span> },&#x000A;  { first_name: <span class="string"><span class="delimiter">&quot;</span><span class="content">Willy</span><span class="delimiter">&quot;</span></span>, last_name: <span class="string"><span class="delimiter">&quot;</span><span class="content">Brandt</span><span class="delimiter">&quot;</span></span> }&#x000A;])</pre></div>
           </div>
         </td>
       </tr>
@@ -161,7 +161,7 @@ <h2>Standard</h2>
           <code>Model.create!</code>
           <p class='doc'>
             <i>
-              Insert a document into the database,
+              Insert a document or multiple documents into the database,
               raising an error if a validation error occurs.
             </i>
           </p>