rename bfgwiki to wiki

1 files changed, 137 insertions, 0 deletions

diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst
new file mode 100644
index 000000000..2649a345f
--- /dev/null
+++ b/docs/tutorials/wiki/basiclayout.rst
@@ -0,0 +1,137 @@
+============
+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.
+