============
Basic Layout
============

The starter files generated by the ``pyramid_zodb`` template are basic,
but they provide a good orientation for the high-level patterns common
to most :term:`traversal` -based :mod:`pyramid` (and :term:`ZODB`
based) projects.

The source code for this tutorial stage can be browsed via
`http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/basiclayout/
<http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/basiclayout/>`_.

``__init__.py``
---------------

A directory on disk can be turned into a Python :term:`package` by
containing an ``__init__.py`` file.  Even if empty, this marks a
directory as a Python package.

Configuration With ``configure.zcml``
--------------------------------------

The ``pyramid_zodb`` template uses :term:`ZCML` to perform system
configuration.  The ZCML file generated by the template looks like the
following:

   .. literalinclude:: src/basiclayout/tutorial/configure.zcml
      :linenos:
      :language: xml

#. *Line 1*.  The root ``<configure>`` element.

#. *Line 4*. Boilerplate, the comment explains.

#. *Lines 6-10*.  Register a ``<view>`` that names a ``context`` type
   that is a class.  ``.views.my_view`` is a *function* we write
   (generated by the ``pyramid_zodb`` template) that is given a
   ``context`` object and a ``request`` and which returns a
   dictionary.  The ``renderer`` tag indicates that the
   ``templates/mytemplate.pt`` template should be used to turn the
   dictionary returned by the view into a response.
   ``templates/mytemplate.pt`` is a *relative* path: it names the
   ``mytemplate.pt`` file which lives in the ``templates``
   subdirectory of the directory in which this ``configure.zcml``
   lives in.  In this case, it means it lives in the ``tutorial``
   package's ``templates`` directory as ``mytemplate.pt``

   Since this ``<view>`` doesn't have a ``name`` attribute, it is the
   "default" view for that class.

#. *Lines 12-15*.  Register a ``static`` view which answers requests
   which start with ``/static``.  This is a view that will serve up
   static resources for us, in this case, at
   ``http://localhost:6543/static/`` and below.  The ``path`` element
   of this tag is a relative directory name, so it finds the resources
   it should serve within the ``templates/static`` directory inside
   the ``tutorial`` package.

Content Models with ``models.py``
---------------------------------

:mod:`pyramid` often uses the word :term:`model` when talking about
content resources arranged in the hierarchical *object graph*
consulted by :term:`traversal`.  The ``models.py`` file is where the
``pyramid_zodb`` Paster template put the classes that implement our
model objects.

Here is the source for ``models.py``:

   .. literalinclude:: src/basiclayout/tutorial/models.py
      :linenos:
      :language: py

#. *Lines 3-4*.  The ``MyModel`` class we referred to in the ZCML file
   named ``configure.zcml`` is implemented here.  Instances of this
   class will be capable of being persisted in :term:`ZODB` because
   the class inherits from the
   :class:`persistent.mapping.PersistentMapping` class.  The
   ``__parent__`` and ``__name__`` are important parts of the
   :term:`traversal` protocol.  By default, have these as ``None``
   indicating that this is the :term:`root` object.

#. *Lines 6-12*.  ``appmaker`` is used to return the *application
   root* object.  It is called on *every request* to the
   :mod:`pyramid` application.  It also performs bootstrapping by
   *creating* an application root (inside the ZODB root object) if one
   does not already exist.
 
   We do so by first seeing if the database has the persistent
   application root.  If not, we make an instance, store it, and
   commit the transaction.  We then return the application root
   object.

App Startup with ``run.py``
---------------------------

When you run the application using the ``paster`` command using the
``tutorial.ini`` generated config file, the application configuration
points at an Setuptools *entry point* described as
``egg:tutorial#app``.  In our application, because the application's
``setup.py`` file says so, this entry point happens to be the ``app``
function within the file named ``run.py``:

   .. literalinclude:: src/basiclayout/tutorial/run.py
      :linenos:
      :language: py

#. *Lines 1-2*.  Perform some dependency imports.

#. *Line 12*. Get the ZODB configuration from the ``tutorial.ini``
   file's ``[app:main]`` section represented by the ``settings``
   dictionary passed to our ``app`` function.  This will be a URI
   (something like ``file:///path/to/Data.fs``).

#. *Line 15*. We create a "finder" object using the
   ``PersistentApplicationFinder`` helper class, passing it the ZODB
   URI and the "appmaker" we've imported from ``models.py``.

#. *Lines 16 - 17*.  We create a :term:`root factory` which uses the
   finder to return a ZODB root object.

#. *Line 18*.  We construct a :term:`Configurator` with a :term:`root
   factory` and the settings keywords parsed by PasteDeploy.  The root
   factory is named ``get_root``.

#. *Lines 19-21*.  Begin configuration using the ``begin`` method of
   the :meth:`pyramid.configuration.Configurator` class, load the
   ``configure.zcml`` file from our package using the
   :meth:`pyramid.configuration.Configurator.load_zcml` method, and
   end configuration using the
   :meth:`pyramid.configuration.Configurator.end` method.

#. *Line 22*.  Use the
   :meth:`pyramid.configuration.Configurator.make_wsgi_app` method
   to return a :term:`WSGI` application.