Updated the Active Record documentation to reflect new publicly visible Active Record methods: get_compiled_select(), get_compiled_delete(), get_compiled_insert(), get_compiled_update(), and reset_query().

1 files changed, 100 insertions, 13 deletions

diff --git a/user_guide/database/active_record.html b/user_guide/database/active_record.html
index 92d9614d5..d53630402 100644
--- a/user_guide/database/active_record.html
+++ b/user_guide/database/active_record.html
@@ -73,6 +73,7 @@ is generated by each database adapter.  It also allows for safer queries, since
 <li><a href="#delete">Deleting Data</a></li>
 <li><a href="#chaining">Method Chaining</a></li>
 <li><a href="#caching">Active Record Caching</a></li>
+<li><a href="#resetting">Reset Active Record</a></li>
 </ul>
 
 <h1><a name="select">&nbsp;</a>Selecting Data</h1>
@@ -107,6 +108,27 @@ foreach ($query->result() as $row)<br />
 
 <p>Please visit the <a href="results.html">result functions</a> page for a full discussion regarding result generation.</p>
 
+<h2>$this->db->get_compiled_select();</h2>
+
+<p>Compiles the selection query just like <kbd>$this->db->get()</kbd> but does not <em>run</em> the query. This method simply returns the SQL query as a string. </p>
+
+<code>$sql = $this->db->get_compiled_select('mytable');<br />
+echo $sql;<br />
+<br />
+// Produces string: SELECT * FROM mytable</code>
+
+<p>The second parameter enables you to set whether or not the active record query will be reset (by default it will be&mdash;just like <kbd>$this->db->get()</kbd>):</p>
+
+<code>echo $this->db->limit(10,20)->get_compiled_select('mytable', FALSE);<br />
+<br />
+// Produces string: SELECT * FROM mytable LIMIT 20, 10 (in MySQL. Other databases have slightly different syntax)<br />
+<br />
+echo $this->db->select('title, content, date')->get_compiled_select();<br />
+<br />
+// Produces string: SELECT title, content, date FROM mytable </code>
+
+<p>The key thing to notice in the above example is that the second query did not utlize <kbd>$this->db->from()</kbd> and did not pass a table name into the first parameter. The reason for this outcome is because the query has not been executed using <kbd>$this->db->get()</kbd> which resets values or reset directly using <kbd>$this-db->reset_query()</kbd>.</p>
+
 
 <h2>$this->db->get_where();</h2>
 
@@ -334,13 +356,6 @@ $this->db->or_where('id >', $id);
 	$this-&gt;db-&gt;like('title', 'match', 'both'); <br />
 // Produces: WHERE title LIKE '%match%' </code>	</li>
 
-If you do not want to use the wildcard (%) you can pass to the optional third argument the option 'none'.
-
-<code>
-	$this-&gt;db-&gt;like('title', 'match', 'none'); <br />
-// Produces: WHERE title LIKE 'match'
-</code>
-
 	<li><strong>Associative array method:</strong>
 
 	<code>
@@ -528,11 +543,41 @@ $this->db->insert('mytable', $object);
 
 <p class="important"><strong>Note:</strong> All values are escaped automatically producing safer queries.</p>
 
+<a name="compiled_insert">&nbsp;</a>
+<h2>$this->db->get_compiled_insert();</h2>
+
+<p>Compiles the insertion query just like <kbd>$this->db->insert()</kbd> but does not <em>run</em> the query. This method simply returns the SQL query as a string. </p>
+
+<code>
+$data = array(<br />
+&nbsp;&nbsp;&nbsp;'title' => 'My title' ,<br />
+&nbsp;&nbsp;&nbsp;'name' => 'My Name' ,<br />
+&nbsp;&nbsp;&nbsp;'date' => 'My date'<br />
+);<br />
+<br />
+$sql = $this->db->set($data)->get_compiled_insert('mytable');<br />
+echo $sql;<br />
+<br />
+// Produces string: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date')</code>
+
+<p>The second parameter enables you to set whether or not the active record query will be reset (by default it will be&mdash;just like <kbd>$this->db->insert()</kbd>):</p>
+
+<code>echo $this->db->set('title', 'My Title')->get_compiled_insert('mytable', FALSE);<br />
+<br />
+// Produces string: INSERT INTO mytable (title) VALUES ('My Title')<br />
+<br />
+echo $this->db->set('content', 'My Content')->get_compiled_insert();<br />
+<br />
+// Produces string: INSERT INTO mytable (title, content) VALUES ('My Title', 'My Content')</code>
+
+<p>The key thing to notice in the above example is that the second query did not utlize <kbd>$this->db->from()</kbd> nor did it pass a table name into the first parameter. The reason this worked is because the query has not been executed using <kbd>$this->db->insert()</kbd> which resets values or reset directly using <kbd>$this-db->reset_query()</kbd>.</p>
+
+
 <h2>$this->db->insert_batch();</h2>
 <p>Generates an insert string based on the data you supply, and runs the query. You can either pass an
 <strong>array</strong> or an <strong>object</strong> to the function.  Here is an example using an array:</p>
 
-<code> 
+<code>
 $data = array(<br/>
 &nbsp;&nbsp;&nbsp;array(<br />
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'title' => 'My title' ,<br />
@@ -544,7 +589,7 @@ $data = array(<br/>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'name' => 'Another Name' ,<br />
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'date' => 'Another date'<br />
 &nbsp;&nbsp;&nbsp;)<br/>
-);<br /> 
+);<br />
 <br />
 $this->db->update_batch('mytable', $data);
 <br /><br />
@@ -670,6 +715,14 @@ You can optionally pass this information directly into the update function as a
 <p>You may also use the <dfn>$this->db->set()</dfn> function described above when performing updates.</p>
 
 
+
+<h2>$this->db->get_compiled_update();</h2>
+
+<p>This works exactly the same way as <kbd>$this->db->get_compiled_insert()</kbd> except that it produces an UPDATE SQL string instead of an INSERT SQL string.</p>
+
+<p>For more information view documentation for <a href="#compiled_insert">get_compiled_insert()</a>.</p>
+
+
 <a name="delete">&nbsp;</a>
 <h1>Deleting Data</h1>
 
@@ -699,11 +752,22 @@ the data to the second parameter of the function:</p>
 $this-&gt;db-&gt;where('id', '5');<br />
 $this-&gt;db-&gt;delete($tables);</code></p>
 <p>If you want to delete all data from a table, you can use the <dfn>truncate()</dfn> function, or <dfn>empty_table()</dfn>.</p>
+
+
+<h2>$this->db->get_compiled_delete();</h2>
+<p>This works exactly the same way as <kbd>$this->db->get_compiled_insert()</kbd> except that it produces a DELETE SQL string instead of an INSERT SQL string.</p>
+<p>For more information view documentation for <a href="#compiled_insert">get_compiled_insert()</a>.</p>
+
+
+
 <h2>$this-&gt;db-&gt;empty_table();</h2>
 <p>Generates a delete SQL string and runs the query.<code>	$this-&gt;db-&gt;empty_table('mytable'); <br />
 	<br />
 // Produces<br />
 // DELETE FROM mytable</code></p>
+
+
+
 <h2>$this-&gt;db-&gt;truncate();</h2>
 <p>Generates a truncate SQL string and runs the query.</p>
 <code> $this-&gt;db-&gt;from('mytable'); <br />
@@ -716,7 +780,9 @@ $this-&gt;db-&gt;truncate('mytable'); <br />
 </code>
 <p class="important"><strong>Note:</strong> If the TRUNCATE command isn't available, truncate() will execute as &quot;DELETE FROM table&quot;.</p>
 
-<h1><a name="chaining">&nbsp;</a>Method Chaining</h1>
+
+<a name="chaining">&nbsp;</a>
+<h1>Method Chaining</h1>
 
 <p>Method chaining allows you to simplify your syntax by connecting multiple functions.  Consider this example:</p>
 
@@ -727,9 +793,9 @@ $query = $this->db->get();</code>
 
 <p class="important"><strong>Note:</strong> Method chaining only works with PHP 5.</p>
 
-<p>&nbsp;</p>
+<a name="caching">&nbsp;</a>
 
-<h1><a name="caching">&nbsp;</a>Active Record Caching</h1>
+<h1>Active Record Caching</h1>
 
 <p>While not &quot;true&quot; caching, Active Record enables you to save (or &quot;cache&quot;) certain parts of your queries for reuse at a later point in your script's execution. Normally, when an Active Record call is completed, all stored information is reset for the next call. With caching, you can prevent this reset, and reuse information easily.</p>
 
@@ -769,7 +835,28 @@ $this-&gt;db-&gt;get('tablename');<br />
 //Generates:  SELECT `field2` FROM (`tablename`)</code></p>
 
 <p class="important"> <strong>Note:</strong> The following statements can be cached: select, from, join, where, like, group_by, having, order_by, set</p>
-<p>&nbsp;</p>
+
+
+<a name="resetting">&nbsp;</a>
+<h1>Reset Active Record</h1>
+
+<p>Resetting Active Record allows you to start fresh with your query without executing it first using a method like <kbd>$this->db->get()</kbd> or <kbd>$this->db->insert()</kbd>. Just like the methods that execute a query, this will <em>not</em> reset items you've cached using <a href="#caching">Active Record Caching</a>.</p>
+<p>This is useful in situations where you are using Active Record to generate SQL (ex. <kbd>$this->db->get_compiled_select()</kbd>) but then choose to, for instance, run the query:</p>
+
+<code>
+// Note that the second parameter of the get_compiled_select method is FALSE<br />
+$sql = $this->db->select(array('field1','field2'))->where('field3',5)->get_compiled_select('mytable', FALSE);<br />
+<br />
+// ...<br />
+// Do something crazy with the SQL code... like add it to a cron script for later execution or something...<br />
+// ...<br />
+<br />
+$data = $this->db->get()->result_array();<br />
+<br />
+// Would execute and return an array of results of the following query:<br />
+// SELECT field1, field1 from mytable where field3 = 5;<br />
+</code>
+
 </div>
 <!-- END CONTENT -->