Yup.

1 files changed, 61 insertions, 0 deletions

diff --git a/docs/narr/models.rst b/docs/narr/models.rst
new file mode 100644
index 000000000..c56d8e2f5
--- /dev/null
+++ b/docs/narr/models.rst
@@ -0,0 +1,61 @@
+Models
+======
+
+*Models* are typically simple Python classes defined in a module.
+ Model *instances* make up the graph that ``repoze.bfg`` is willing to
+ traverse.
+
+Defining a Model
+----------------
+
+An example of a model describing a blog entry::
+
+  import datetime
+  from zope.interface import implements
+  from zope.interface import Interface
+
+  class IBlogEntry(Interface):
+      pass
+
+  class BlogEntry(object):
+      implements(IBlogEntry)
+      def __init__(self, title, body, author):
+          self.title = title
+          self.body =  body
+          self.author = author
+          self.created = datetime.datetime.now()
+
+A model consists of basically two things: the object which defines the
+model (above as the class ``IBlogEntry``), and an *interface* attached
+to the model object.  An interface simply tags the model object with a
+"type" that can be referred to within view configuration.  A model
+object can implement zero or more interfaces.
+
+Defining a Graph of Model Instances
+-----------------------------------
+
+``repoze.bfg`` expects to be able to traverse a graph of model
+instances.  ``repoze.bfg`` imposes the following policy on model
+instance nodes in the graph:
+
+ - Nodes which contain other nodes (aka "container" nodes) must supply
+   a ``__getitem__`` method which is willing to resolve a string or
+   unicode name to a subobject.  If a subobject by that name does not
+   exist in the container, ``__getitem__`` must raise a KeyError.  If
+   a subobject by that name *does* exist, the container should return
+   the subobject (another model instance).  
+
+ - Nodes which do not contain other nodes (aka "leaf" nodes) must not
+   implement ``__getitem__``.
+
+Location-Aware Model Instances
+------------------------------
+
+ - For ``repoze.bfg`` security and convenience URL-generation
+   functions to work properly against a model instance graph, all
+   nodes in the graph should have two attributes:: ``__parent__`` and
+   ``__name__``.  The ``__parent__`` attribute should be a reference
+   to the node's parent model instance in the graph.  The ``__name__``
+   attribute should be the name that a node's parent refers to the
+   node by via ``__getitem__``.
+