diff options
Diffstat (limited to 'docs/tutorials')
| -rw-r--r-- | docs/tutorials/lxmlgraph/background.rst | 69 | ||||
| -rw-r--r-- | docs/tutorials/lxmlgraph/index.rst | 12 | ||||
| -rw-r--r-- | docs/tutorials/lxmlgraph/step01.rst | 7 | ||||
| -rw-r--r-- | docs/tutorials/lxmlgraph/step02.rst | 39 | ||||
| -rw-r--r-- | docs/tutorials/lxmlgraph/step03.rst | 17 |
5 files changed, 58 insertions, 86 deletions
diff --git a/docs/tutorials/lxmlgraph/background.rst b/docs/tutorials/lxmlgraph/background.rst index e4fdc5034..aec4cda26 100644 --- a/docs/tutorials/lxmlgraph/background.rst +++ b/docs/tutorials/lxmlgraph/background.rst @@ -1,31 +1,29 @@ Background ==================== -This demo application presumes that you have an interest in XML -technologies and might want to leverage them for a fast, but rich and -dynamic, website. In this demo application, we build up, bit-by-bit, -the functionality. Thus, you don't have to know squatola about XML to -follow along. - -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 :term:`lxml` - - - Support flexible-but-fast rendering with XSLT +In this demo application, we build up, bit-by-bit, the functionality +for a website based on a single XML document. You don't have to know +much about XML to follow along. In fact, the real purpose of this +demo app is to teach its author how to use the stack +(:mod:`repoze.bfg`, ``paster``, eggs, etc.) .. 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 + stupendously clear, :mod:`repoze.bfg` is in no way dependent on XML. + On the other hand, :mod:`repoze.bfg` happens to make XML publishing kinda fun. +In summary: + + - Represent a hierarchical website as an XML document + + - Inject :mod:`repoze.bfg` semantics into elements using + :term:`lxml` + + - Support rendering with :term:`XSLT` + What It Does ------------------- @@ -44,7 +42,7 @@ 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 +Using :mod:`repoze.bfg`, of course. More specifically, with an XML file that models that hierarchy: .. literalinclude:: step00/simplemodel.xml @@ -53,8 +51,8 @@ that models that hierarchy: 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 +To coerce :mod:`repoze.bfg` into publishing this model, I just need to +sprinkle in some Python behavior. For example, :mod:`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 ``@name`` attribute @@ -64,11 +62,9 @@ Fortunately :term:`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`` +The interface then lets me glue back into the standard :mod:`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 :term:`lxml` API. Or, I could use XSLT. @@ -85,28 +81,3 @@ step-by-step, starting with no XML. Each of those decisions will be analyzed an implemented. At the end, you'll see both the resulting demo application, plus the thought process that went along with it. -What It Might Do --------------------- - -This demo application has the potential to show some other interesting -investigations: - -#. **Authorization**. By hooking up support for an ``__acl__`` - property, I can store ACL information on a single node, on an - ancestor, on the ``<site>`` root, on the Python class, or any - combination thereof. Additionally, I can wire up the - ``__parent__`` attribute as a property that makes an :term:`lxml` - ``node.getparent()`` call. - -#. **Multiple views**. Instead of just having a single default view - on a node, I can allow other view names, all pointing at the same - view function 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. Adding a view would no longer required editing ZCML and - adding a function. - -#. **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``. diff --git a/docs/tutorials/lxmlgraph/index.rst b/docs/tutorials/lxmlgraph/index.rst index a4d0016cc..cc79f7e73 100644 --- a/docs/tutorials/lxmlgraph/index.rst +++ b/docs/tutorials/lxmlgraph/index.rst @@ -1,10 +1,10 @@ -``lxmlgraph``: Publishing An XML Tree with ``repoze.bfg`` -========================================================== +``lxmlgraph``: Publishing An XML Tree with :mod:`repoze.bfg` +============================================================ -Hierarchical websites are easy to develop with ``repoze.bfg``. That -hierarchy doesn't need to be defined by any particular sort of graph -or databsase system. To demonstrate this, we present -``repoze.lxmlgraph``, a demo application for ``repoze.bfg`` that +Hierarchical websites are easy to develop with :mod:`repoze.bfg`. +That hierarchy doesn't need to be defined by any particular sort of +graph or databsase system. To demonstrate this, we present +``repoze.lxmlgraph``, a demo application for :mod:`repoze.bfg` that describes publishing an XML document as a hierarchical website. .. toctree:: diff --git a/docs/tutorials/lxmlgraph/step01.rst b/docs/tutorials/lxmlgraph/step01.rst index 6c6f93191..578f13608 100644 --- a/docs/tutorials/lxmlgraph/step01.rst +++ b/docs/tutorials/lxmlgraph/step01.rst @@ -3,10 +3,9 @@ Step 1: Getting Started ======================= To get started, using the ``paster`` command from a :term:`virtualenv` -you've created that has ``repoze.bfg`` installed, run ``paster create --t bfg`` as described in :ref:`project_narr` to create your lxmlgraph -project:: - +you've created that has :mod:`repoze.bfg` installed, run ``paster +create -t bfg`` as described in :ref:`project_narr` to create your +``lxmlgraph`` project:: $ paster create -t bfg Selected and implied templates: repoze.bfg#bfg repoze.bfg starter project diff --git a/docs/tutorials/lxmlgraph/step02.rst b/docs/tutorials/lxmlgraph/step02.rst index 94aca07e4..1dc1ebcd3 100644 --- a/docs/tutorials/lxmlgraph/step02.rst +++ b/docs/tutorials/lxmlgraph/step02.rst @@ -6,7 +6,7 @@ We now have a project named ``lxmlgraph``. It contains a *package* (also) named ``lxmlgraph``. In this step we will add an XML document to the *package* as our model -data. We will leverage the following ``repoze.bfg`` machinery: +data. We will leverage the following :mod:`repoze.bfg` machinery: - Model data with interfaces that define "types" @@ -14,11 +14,11 @@ data. We will leverage the following ``repoze.bfg`` machinery: Our application will need to do these things: - - Use :term:`lxml` Element classes to inject ``repoze.bfg`` behavior into - ``lxml`` nodes + - Use :term:`lxml` Element classes to inject :mod:`repoze.bfg` + behavior into ``lxml`` nodes - - That model class needs to implement the ``repoze.bfg`` publishing - contract + - That model class needs to implement the :mod:`repoze.bfg` + publishing contract All of the below filenames are relative to the ``lxmlgraph`` *package* rather than the *project*. @@ -40,18 +40,17 @@ your package: #. In lines 3-4, the ``<site>`` contains 2 top-level children: a and b. These are provided as an element name ``<document>``. This, - also, is meaningless as far as ``repoze.bfg`` is concerned. + also, is meaningless as far as :mod:`repoze.bfg` is concerned. However, this is where you compose the information model you are publishing. The only special constraint is that an XML node that wants to be -"found" by ``repoze.bfg`` in during traversal *must* have a ``name`` -attribute. (The use of ``@name`` corresponds to ``__name__`` in the -``repoze.bfg`` sense of ``repoze.bfg`` :term:`location` ). Each hop -in the URL tries to grab a child with an attribute matching the next -hop. Also, the value of the ``@name`` should be unique in its -containing node. - +"found" by :mod:`repoze.bfg` in during traversal *must* have a +``name`` attribute. (The use of ``@name`` corresponds to ``__name__`` +in the :mod:`repoze.bfg` sense of :term:`location` ). Each hop in the +URL tries to grab a child with an attribute matching the next hop. +Also, the value of the ``@name`` should be unique in its containing +node. Module ``models.py`` ------------------------------ @@ -64,7 +63,7 @@ class with the parser. Replace the contents of the autogenerated .. literalinclude:: step02/myapp/models.py :linenos: -#. Line 4 imports ``lxml``. +#. Line 4 imports :term:`lxml`. #. Line 9 creates the custom class we are going to use to extend etree.ElementBase. The `<lxml website @@ -75,20 +74,20 @@ class with the parser. Replace the contents of the autogenerated certain content type (interface.) In our case, instances will be XML nodes. -#. ``repoze.bfg`` has a "protocol" where model data should have an +#. :mod:`repoze.bfg` has a protocol where model data should have an ``__name__`` attribute. Lines 14-16 implement this by grabbing the ``@name`` attribute of the current node. -#. URL traversal in ``repoze.bfg`` works via the ``__getitem__`` +#. URL traversal in :mod:`repoze.bfg` works via the ``__getitem__`` protocol. Thus, we need a method that implements this. Lines 18-26 use XPath to look for a direct child that has an ``@name`` matching the item name that's being traversed to. If it finds it, return it. If not, or if more than one is found, raise an error. #. As before, ``get_root`` is the function that is expected to return - the top of the model. In lines 30+ we do the ``lxml`` magic to get the - custom Python class registered. We then load some XML and return - the top of the tree. + the top of the model. In lines 30+ we do the :term:`lxml` magic to + get the custom Python class registered. We then load some XML and + return the top of the tree. Module ``views.py`` ----------------------------- @@ -124,7 +123,9 @@ It will listen on port 5432. We can use these URLs to browse the model graph and see results:: http://localhost:5432/a (Hello to document from a @ /a) + http://localhost:5432/b (Hello to document from b @ /b) + http://localhost:5432/c (Not Found) In this case, each request grabs a node in the XML and uses it as the diff --git a/docs/tutorials/lxmlgraph/step03.rst b/docs/tutorials/lxmlgraph/step03.rst index 5e7911889..9edc77af3 100644 --- a/docs/tutorials/lxmlgraph/step03.rst +++ b/docs/tutorials/lxmlgraph/step03.rst @@ -60,8 +60,9 @@ Also add a function in ``views.py`` that looks like the following: This function is relatively simple: -#. Line 1 imports a ``repoze.bfg`` function that renders ZPT templates - to a response. ``repoze.bfg`` uses the ``z3c.pt`` ZPT engine. +#. Line 1 imports a :mod:`repoze.bfg` function that renders ZPT + templates to a response. :mod:`repoze.bfg` uses the ``z3c.pt`` ZPT + engine. #. Line 2, like our other view functions, gets passed a ``context`` (the current hop in the URL) and WebOb ``request`` object. @@ -160,11 +161,12 @@ to your ``views.py`` file: #. Line 10 implements the difference. We call ``render_transform_to_response`` instead of - ``render_template_to_response``. This tells ``repoze.bfg`` to make - an XSLT processor for this template, instead of a ZPT. The second - argument passes in ``context`` to the XSLT transform. ``context``` - is an instance of an Element node. Namely, a node from the XML - document that corresponds to the current hop in the URL. + ``render_template_to_response``. This tells :mod:`repoze.bfg` to + make an XSLT processor for this template, instead of a ZPT. The + second argument passes in ``context`` to the XSLT transform. + ``context``` is an instance of an Element node. Namely, a node + from the XML document that corresponds to the current hop in the + URL. ``xsltview.xsl`` @@ -190,7 +192,6 @@ directory and give it the following contents: #. Line 8 shows the element name of the current node. - Viewing the XSLT -------------------- |