Add some subroutine docs. Must write another test so that I can understand all ins...

[dbsrgits/DBIx-Class-ResultSource-MultipleTableInheritance.git] / README.html

diff --git a/README.html b/README.html
index a25e75b..6506fd7 100644 (file)
--- a/README.html
+++ b/README.html
@@ -16,10 +16,10 @@
 
 <ul>
 
-       <li><a href="#name">NAME</a></li>
        <li><a href="#synopsis">SYNOPSIS</a></li>
        <li><a href="#why">WHY?</a></li>
        <li><a href="#how">HOW?</a></li>
+       <li><a href="#methods">METHODS</a></li>
        <li><a href="#author">AUTHOR</a></li>
        <ul>
 
@@ -36,12 +36,6 @@
 
 <p>
 </p>
-<hr />
-<h1><a name="name">NAME</a></h1>
-<p>DBIx::Class::ResultSource::MultipleTableInheritance -- Use multiple tables to define your classes</p>
-<p>
-</p>
-<hr />
 <h1><a name="synopsis">SYNOPSIS</a></h1>
 <pre>
     {
@@ -101,8 +95,8 @@
         $VAR1 = 'id';
         $VAR2 = 'flavor';
         $VAR3 = 'aroma';</pre>
-<p>Inherit from this package and you can make a resultset class from a view, but that's more than a little bit misleading: the result is <strong>writable</strong> and updateable--transparently.</p>
-<p>This is accomplished through the use of stored functions that map changes written to the view to changes to the underlying concrete tables.</p>
+<p>Inherit from this package and you can make a resultset class from a view, but that's more than a little bit misleading: the result is <strong>transparently writable</strong>.</p>
+<p>This is accomplished through the use of stored procedures that map changes written to the view to changes to the underlying concrete tables.</p>
 <p>
 </p>
 <hr />
@@ -131,7 +125,7 @@
             has password
     }</pre>
 <pre>
-    class Investor isa User {
+    class Investor extends User {
         has dollars
     }</pre>
 <p>Good idea, but how to put this into code?</p>
@@ -177,7 +171,7 @@
 </p>
 <hr />
 <h1><a name="how">HOW?</a></h1>
-<p>There is a third strategy implemented here. Make the database do more of the work. It'll save us some typing and it'll make for more expressive code. What if we could do this:</p>
+<p>There is a third strategy implemented here. Make the database do more of the work: hide the nasty bits so we don't have to handle them unless we really want to. It'll save us some typing and it'll make for more expressive code. What if we could do this:</p>
 <pre>
     my $new_investor = $schema-&gt;resultset('Investor')-&gt;create(
         name =&gt; $args-&gt;{name},
@@ -185,7 +179,13 @@
         dollars =&gt; $args-&gt;{dollars},
     );
     
-And have it Just Work? The user ( {name =&gt; $args-&gt;{name}, password =&gt; $args-&gt;{password} } ) should be created transparently, and the use of either user or investor in your code should require no special handling. Deleting and updating $new_investor should also delete or update the user row.</pre>
+And have it Just Work? The user...</pre>
+<pre>
+    {
+        name =&gt; $args-&gt;{name},
+        password =&gt; $args-&gt;{password},
+    }</pre>
+<p>should be created behind the scenes, and the use of either user or investor in your code should require no special handling. Deleting and updating $new_investor should also delete or update the user row.</p>
 <p>It does. User and investor are both views, their concrete tables abstracted away behind a set of rules and triggers. You would expect the above DBIC create statement to look like this in SQL:</p>
 <pre>
     INSERT INTO investor (&quot;name&quot;,&quot;password&quot;,&quot;dollars&quot;) VALUES (...);</pre>
@@ -201,7 +201,60 @@ And have it Just Work? The user ( {name =&gt; $args-&gt;{name}, password =&gt; $
 <pre>
     DELETE FROM _investor_table WHERE (&quot;id&quot; = ?);
     DELETE FROM _user_table WHERE (&quot;id&quot; = ?);</pre>
-<p></p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<dl>
+<dt><strong><a name="new" class="item">new</a></strong></dt>
+
+<dd>
+<p>MTI find the parents, if any, of your resultset class and adds them to the list of parent_sources for the table.</p>
+</dd>
+<dt><strong><a name="add_additional_parents" class="item">add_additional_parents</a></strong></dt>
+
+<dd>
+<p>Continuing with coffee:</p>
+<pre>
+    __PACKAGE__-&gt;result_source_instance-&gt;add_additional_parents(
+        qw/
+            MyApp::Schema::Result::Beverage
+            MyApp::Schema::Result::Liquid
+        /
+    );</pre>
+<p>This just lets you manually add additional parents beyond the ones MTI finds.</p>
+</dd>
+<dt><strong><a name="add_additional_parent" class="item">add_additional_parent</a></strong></dt>
+
+<dd>
+<pre>
+    __PACKAGE__-&gt;result_source_instance-&gt;add_additional_parent(
+            MyApp::Schema::Result::Beverage
+    );</pre>
+<p>You can also add just one.</p>
+</dd>
+<dt><strong><a name="attach_additional_sources" class="item">attach_additional_sources</a></strong></dt>
+
+<dd>
+<p>MTI takes the parents' sources and relationships, creates new DBIx::Class:Table object from them, and registers this as a new, raw, source in the schema, e.g.,</p>
+<pre>
+    use MyApp::Schema;</pre>
+<pre>
+    print STDERR map { &quot;$_\n&quot; } MyApp::Schema-&gt;sources;</pre>
+<pre>
+    # Coffee 
+    # Beverage
+    # Liquid
+    # Sumatra
+    # Raw::Sumatra</pre>
+<p>Raw::Sumatra will be used to generate the view.</p>
+</dd>
+<dt><strong><a name="view_definition" class="item">view_definition</a></strong></dt>
+
+<dd>
+<p>This takes the raw table and generates the view (and stored procedures) you will use.</p>
+</dd>
+</dl>
 <p>
 </p>
 <hr />