Add defining models chapter.

1 files changed, 63 insertions, 0 deletions

diff --git a/docs/tutorials/bfgwiki2/definingmodels.rst b/docs/tutorials/bfgwiki2/definingmodels.rst
new file mode 100644
index 000000000..334f87890
--- /dev/null
+++ b/docs/tutorials/bfgwiki2/definingmodels.rst
@@ -0,0 +1,63 @@
+===============
+Defining Models
+===============
+
+The first change we'll make to our bone-stock paster-generated
+application will be to define a:term:`model` constructor representing
+a wiki page.   We'll do this inside our ``models.py`` file.
+
+Making Edits to ``models.py``
+-----------------------------
+
+.. note::
+
+  There is nothing automagically special about the filename
+  ``models.py``.  A project may have many models throughout its
+  codebase in arbitrarily-named files.  Files implementing models
+  often have ``model`` in their filenames (or they may live in a
+  Python subpackage of your application package named ``models``) ,
+  but this is only by convention.
+
+The first thing we want to do is remove the stock ``Model`` class from
+the generated ``models.py`` file.  The ``Model`` class is only a
+sample and we're not going to use it.
+
+Then, we'll add a ``Page`` class.  Because this is a SQLAlchemy
+application, this class should inherit from an instance of
+``sqlalchemy.ext.declarative.declarative_base``.  Declarative
+SQLAlchemy models are easier to use than directly-mapped ones.  The
+code generated by our ``routesalchemy`` paster template does not use
+declarative SQLAlchemy syntax, so we'll need to chage various things to
+begin to use declarative syntax.
+
+Our ``Page`` class will have a class level attributes
+``__tablename__`` which equals the string ``pages``.  This means that
+SQLAlchemy will store our wiki data in a SQL table named ``pages``.
+Our Page class will also have class-level attributes named ``id``,
+``pagename`` and ``data`` (all instances of ``sqlalchemy.Column``).
+These will map to columns in the ``pages`` table.  The ``id``
+attribute will be the primary key in the table.  The ``name``
+attribute will be a text attribute, each value of which needs to be
+unique within the column.  The ``data`` attribute is a text attribute
+that will hold the body of each page.
+
+We'll also remove our ``populate`` function.  We'll inline the
+populate step into ``initialize_sql``, changing our ``initialize_sql``
+function to add a FrontPage object to our database at startup time.
+We're also going to use slightly different binding syntax.  It will
+will otherwise largely be the same as the ``initialize_sql`` in the
+paster-generated ``models.py``.
+
+Our DBSession assignment stays the same as the original generated
+``models.py``.
+
+Looking at the Result of Our Edits to ``models.py``
+---------------------------------------------------
+
+The result of all of our edits to ``models.py`` will end up looking
+something like this:
+
+.. literalinclude:: src/models/tutorial/models.py
+   :linenos:
+   :language: python
+