[Repoze-checkins] r1378 - repoze.lxmlgraph/trunk/docs

[Paul Everitt]

Author: Paul Everitt <paul at agendaless.com>
Date: Fri Jul 18 15:07:22 2008
New Revision: 1378

Log:
Added some more background information on what it does, how it works.


Modified:
   repoze.lxmlgraph/trunk/docs/background.rst

Modified: repoze.lxmlgraph/trunk/docs/background.rst
==============================================================================
--- repoze.lxmlgraph/trunk/docs/background.rst	(original)
+++ repoze.lxmlgraph/trunk/docs/background.rst	Fri Jul 18 15:07:22 2008
@@ -10,3 +10,97 @@
 In fact, the real purpose of this demo app is to teach its author how
 to use the stack (repoze.bfg, Paster, eggs, etc.)
 
+In summary:
+
+  - Represent a hierarchical site as hierarchical XML
+
+  - Inject ``repoze.bfg`` semantics into elements using ``lxml``
+
+  - Support flexible-but-fast rendering with XSLT
+
+.. warning::
+
+  If you dislike XML and related technologies such as XPath and XSLT,
+  you'll thoroughly detest this sample application.  Just to be
+  stupendously clear, ``repoze.bfg`` is in no way dependent on XML.
+  On the other hand, ``repoze.bfg`` happens to make XML publishing
+  kind fun.
+
+What It Does
+-------------------
+
+Imagine you have a website that looks like this::
+
+  /
+    folder1/
+      doc1
+      doc2
+      image1
+    folder2/
+      doc2
+
+Meaning, a heterogenous, nested folder structure, just like your hard
+drive.  (Unless you're one of those folks that uses your Windows
+Desktop as a flat filing system.)  How might I get that information
+into a website?
+
+Using ``repoze.bfg``, of course.  More specifically, with an XML file
+that models that hierarchy:
+
+.. literalinclude:: step00/simplemodel.xml
+	:language: xml
+
+How It Works
+-------------------
+
+To coerce ``repoze.bfg`` into publishing this model, I just need to
+sprinkle in some Python behavior.  For example, ``repoze.bfg`` uses
+``__getitem__`` to traverse the model.  I need my XML data to support
+this method.  Moreover, I want some specific behavior: run an XPath
+express on the node to get the child with the ``@id`` attribute
+matching the URL hop.
+
+Fortunately ``lxml`` makes this easy.  I can inject my nodes with a
+class that I write, thus providing my own ``__getitem__`` behavior.
+
+That class can also assert that my XML nodes provide an interface.
+The interface then lets me glue back into the standard ``repoze.bfg``
+machinery, such as associating views and permissions into the model.
+
+Neato torpedo.  And stinking fast.
+
+Next up, I need to provide views for the elements in the model.  I
+could, for example, use ZPT and manipulate the XML data using Python
+expressions against the lxml API.  Or, I could use XSLT.
+
+For the latter, I could register a different XSLT for every "view" on
+every interface.  Or, I could write one big XSLT, and let its template
+matching machinery decide who to render in a certain context.
+
+And finally, I could pass in just a single node and render it, or pass
+in the entire tree with a parameter identifying the context node.
+
+What It Might Do
+--------------------
+
+This demo application has the potential to show some other interesting
+investigations:
+
+1) Authorization.  By hooking up support for an ``__acl__`` property,
+I can store ACL information on a single node, on an ancestor, on the
+root, on the Python class, or any combination thereof.  Additionally,
+I can wire up the ``__parent__`` attribute as a property that makes an
+lxml ``node.getparent()`` call.
+
+2) Multiple views.  Instead of just having a single default view on a
+node, I can allow other view names, all pointing at the same factory
+and XSLT.  I simple grab that name and pass it in as a paramter to the
+XSLT, which will run a different rule for rendering.
+
+3) Forms.  To edit data in the model, I need to render a form, then
+handle post data on the way back in.  For the former, it's *really*
+easy in XSLT to make a very powerful, flexible, and extensisible form
+rendering system.  For the latter, I'll have to learn more about POST
+handlers in ``repoze.bfg``.
+
+