From 837916cfe47223dad034fe8c6dccce60d9836d68 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 24 Jul 2008 18:57:17 +0000 Subject: Get rid of duplicate info in lxmlgraph tutorial. --- docs/tutorials/lxmlgraph/background.rst | 8 +- docs/tutorials/lxmlgraph/index.rst | 16 +- docs/tutorials/lxmlgraph/installation.rst | 22 -- docs/tutorials/lxmlgraph/oxygen.xpr | 509 ------------------------------ docs/tutorials/lxmlgraph/step01.rst | 195 +----------- docs/tutorials/lxmlgraph/step02.rst | 29 +- docs/tutorials/lxmlgraph/step03.rst | 6 +- 7 files changed, 34 insertions(+), 751 deletions(-) delete mode 100644 docs/tutorials/lxmlgraph/installation.rst delete mode 100644 docs/tutorials/lxmlgraph/oxygen.xpr (limited to 'docs/tutorials/lxmlgraph') diff --git a/docs/tutorials/lxmlgraph/background.rst b/docs/tutorials/lxmlgraph/background.rst index 975c23a1d..79579d342 100644 --- a/docs/tutorials/lxmlgraph/background.rst +++ b/docs/tutorials/lxmlgraph/background.rst @@ -2,10 +2,10 @@ Background ==================== This demo application presumes that you have an interest in XML -technologies and might want to leverage them for a fast-as-hell, 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. +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.) diff --git a/docs/tutorials/lxmlgraph/index.rst b/docs/tutorials/lxmlgraph/index.rst index 42c8ec503..f08076fc9 100644 --- a/docs/tutorials/lxmlgraph/index.rst +++ b/docs/tutorials/lxmlgraph/index.rst @@ -1,20 +1,14 @@ -Publishing XML with repoze.bfg -========================================== +``lxmlgraph``: Publishing XML with ``repoze.bfg`` +================================================= -``repoze.bfg`` is, well, fun. It brings back the good old days of -Bobo, but with the good new days of WSGI. With ``repoze.bfg``, -hierarchical websites are a cinch to develop. - -XML is also hierarchical. ``repoze.lxmlgraph`` is a demo application -for ``repoze.bfg`` that shows publishing a tree of XML as a -hierarchical website, while leveraging the facilities the gun gives -you. +Hierarchical websites are easy to develop with ``repoze.bfg``. +``repoze.lxmlgraph`` is a demo application for ``repoze.bfg`` that +describes publishing an XML document as a hierarchical website. .. toctree:: :maxdepth: 2 background - installation step01 step02 step03 diff --git a/docs/tutorials/lxmlgraph/installation.rst b/docs/tutorials/lxmlgraph/installation.rst deleted file mode 100644 index b30c058b8..000000000 --- a/docs/tutorials/lxmlgraph/installation.rst +++ /dev/null @@ -1,22 +0,0 @@ -Installation -===================== - -You can get the final form of the demo application, along with all the -steps along the way, via the miracles of virtualenv, easy_install and Paster -templates:: - - $ virtualenv --no-site-packages myapp - $ cd myapp - $ source bin/activate - $ easy_install repoze.lxmlgraph - $ paster create -t lxmlgraph_project - -Answer the questions, then run the demo: - - cd <> - python run.py - -At that point a URL such as ``http://localhost:5432/folder2/query1`` -should work. - - \ No newline at end of file diff --git a/docs/tutorials/lxmlgraph/oxygen.xpr b/docs/tutorials/lxmlgraph/oxygen.xpr deleted file mode 100644 index 6b42af9e1..000000000 --- a/docs/tutorials/lxmlgraph/oxygen.xpr +++ /dev/null @@ -1,509 +0,0 @@ - - - - - - - - - scenario.associations - - - - xsltview - - - XML - - - step04/myapp/xsltview.xsl - - - - - debugui-entryviewer - - - XML - - - ../../../repoze.debug/trunk/repoze/debug/static/debugui-entryviewer.xsl - - - - - Docbook PDF modified - - - XSL - - - ../../../../playground/paul/psu2008/themes/Untitled5.xml - - - - - docbook/docbook5.framework/DocBook 5/Docbook HTML - - - XSL - - - ../../../../../guidetoec2.xml - - - - - - scenarios - - - - Execute DDXQuery - - - - - - - - - - - - - - - - - - ${currentFileURL} - - - - - - false - - - false - - - DD_XQUERY - - - true - - - false - - - - - - false - - - - - - false - - - false - - - true - - - false - - - true - - - - - - - - - DataDirect - - - - - - - - Execute SQL - - - - - - - - - - - - - - - - - - ${currentFileURL} - - - - - - false - - - false - - - SQL - - - true - - - false - - - - - - false - - - - - - false - - - false - - - false - - - false - - - true - - - - - - - - - JDBC - - - - - - - - Execute XQuery - - - - - - - - - - - - - - - - - - ${currentFileURL} - - - - - - false - - - false - - - XQUERY - - - true - - - false - - - - - - false - - - - - - false - - - false - - - true - - - false - - - true - - - - - - - - - Saxon9B XQuery - - - - - - - - Docbook PDF modified - - - - - - - - - pdf - - - Built-in (Apache FOP) - - - - - - ${frameworks}/docbook/xsl/fo/docbook.xsl - - - ${currentFileURL} - - - false - - - true - - - XSL - - - true - - - true - - - ${cfd}/${cfn}.pdf - - - false - - - - - - false - - - false - - - false - - - false - - - true - - - - - - draft.mode - - - no - - - - - fop.extensions - - - 0 - - - - - fop1.extensions - - - 1 - - - - - linenumbering.extension - - - 1 - - - - - paper.type - - - A4 - - - - - use.extensions - - - 1 - - - - - - - - - Saxon6.5.5 - - - - - - - - xsltview - - - - - - - - - pdf - - - Built-in (Apache FOP) - - - - - - ${currentFileURL} - - - file:/Users/paul/projects/repozesvn/repoze.lxmlgraph/trunk/docs/step04/myapp/samplemodel.xml - - - false - - - false - - - XML - - - true - - - false - - - - - - true - - - - - - false - - - true - - - false - - - false - - - true - - - - - - - - - Xsltproc - - - - - - - - - scenarios.load.from.project - true - - - - - - - - - - diff --git a/docs/tutorials/lxmlgraph/step01.rst b/docs/tutorials/lxmlgraph/step01.rst index f44f48db9..d86c5bc8f 100644 --- a/docs/tutorials/lxmlgraph/step01.rst +++ b/docs/tutorials/lxmlgraph/step01.rst @@ -1,188 +1,17 @@ -================================================ -Step 01: Non-XML Hello World for ``repoze.bfg`` -================================================ +======================= +Step 1: Getting Started +======================= -Before we work on implementing an XML graph, we need a simple starting -point for a basic ``repoze.bfg`` application. In this step we'll do -the least amount possible to run a ``repoze.bfg`` sample application. +To get started, run ``paster create -t bfg`` as described in +:ref:_project_narr to create your lxmlgraph project:: -.. note:: - All steps in this writeup presume that you have a virtualenv setup - as shown in the Installation step. More specifically: *make sure - you are using that virtualenv's Python* !! + $ paster create -t bfg + Selected and implied templates: + repoze.bfg#bfg repoze.bfg starter project -Directory Layout -==================== + Enter project name: lxmlgraph + ... + $ + -Each step in this writeup has a subdirectory for the working -application described in that step. Thus, starting at this docs -directory, we have:: - - docs/ - step01/ - myapp/ - __init__.py - configure.zcml - models.py - views.py - run.py - step02/ - step03/ - -Below we discuss each file in the ``step01``, then show how to run and -use the demo application. - - -Directory ``myapp`` ---------------------- - -This directory contains the *package* to be published. That's right, -I said *package*. ``repoze.bfg``, as we will see in a moment, uses -Python packages as the unit of publishing. - - -Module ``myapp/__init__.py`` ------------------------------- - -This is (usually-empty) file that makes a directory into a Python -"package." For ``repoze.bfg`` this is particularly important - - -Module ``myapp/configure.zcml`` --------------------------------- - -Unlike other frameworks, ``repoze.bfg`` doesn't try to hide -configuration. Instead, configuration using ZCML is the central -wiring point. At the same time, ZCML is used in a very basic way, to -avoid confusion it can cause. - -.. literalinclude:: step01/myapp/configure.zcml - :linenos: - :language: xml - -#. Lines 1-3 provide the root node and namespaces for the - configuration language. ``bfg`` is the namespace for - ``repoze.bfg``-specific configuration directives. - -#. Line 5 initializes those ``repoze.bfg``-specific configuration - directives. - -#. Lines 8-11 register a single view for model objects that support - the IMyModel interface. In this case we made a default view, which - means going to ``/a`` triggers the default view of instance ``a``. - Finally, the ``view`` attribute points at a Python function that - does all the work for this view. - - -Module ``myapp/models.py`` ------------------------------ - -In our sample app, the ``models.py`` module provides the model data. -We create an interface ``IMyModel`` that gives us the "type system" -for our data. We then write a class ``MyModel`` that provides the -behavior for instances of the ``IMyModel`` type. - -.. literalinclude:: step01/myapp/models.py - :linenos: - -#. Lines 5-6 define the interface. - -#. Lines 8-11 provide a class for that interface. - -#. Lines 13-15 make a small tree of sample data (``/a`` and ``/b`` for - URLs.) - -#. Line 17 is a function that will be grabbed by the server when it - wants to find the top of the model. - - -Module ``myapp/views.py`` ---------------------------- - -Much of the heavy liftin in a ``repoze.bfg`` application comes in the -views. These are the bridge between the content in the model, and the -HTML given back to the browser. Since ``repoze.bfg`` is very -type-centric, URLs grab information of a certain type. Once we have -the information and its type, we can grab a view that is registered -for that type. - -.. note:: - - This "Step 01" doesn't use a template. The "view" we define is done - in Python, which generates the HTML. Most applications will use - templates to generate markup. - -.. literalinclude:: step01/myapp/models.py - :linenos: - -#. Lines 3 provide the ``my_hello_view`` that was registered as the - view. ``configure.zcml``, on Line 10, said that the default URL - for IMyModel content should run this ``my_hello_view`` function. - - The function is handed two pieces of information: the ``context`` - and the ``request``. The ``context`` is the data at the current - hop in the URL. (That data comes from the model.) The request is - an instance of a WebOb request. - -#. Lines 4-7 generate a WebOb Response object and return it. - - -Module ``run.py`` ---------------------- - -We need a small Python module that sets everything, fires up a web -server, and handles incoming requests. Later we'll see how to use a -Paste configuration file to do this work for us. - -.. literalinclude:: step01/run.py - :linenos: - -#. Line 1 uses the web server from the Paste project. - -#. Line 3 imports the big gun from ``repoze.bfg``. - -#. Line 4 grabs the function that hands back the top of the - application's model data. - -#. Line 5 imports the package that we want to "publish". - -#. Line 7 loads the big gun with the data and the package. - -#. And finally, line 8 starts the web server on port 5432. - - -Running and Browsing the Application ---------------------------------------- - -We have our minimal application now in place. We can run the -application as follows:: - - cd docs/step01 - python run.py - -.. note:: - - Just to say it AGAIN: make sure the Python you are using is the - Python from your virtual environment. One way to ensure you always - get the right scripts is to do ``source bin/activate`` from the top - of your virtualenv. This will modify your PATH to look first in the - virtual env. - -You should then see:: - - $ python ./run.py - serving on 0.0.0.0:5432 view at http://127.0.0.1:5432 - -If you connect in a web browser to ``http://localhost:5432/a`` you -will see:: - - Hello from a @ /a - -This also works for ``http://localhost:5432/b``. However, if you -connect to ``http://localhost:5432/c`` you will get:: - - 404 Not Found - The resource could not be found. - - http://localhost:5432/c \ No newline at end of file diff --git a/docs/tutorials/lxmlgraph/step02.rst b/docs/tutorials/lxmlgraph/step02.rst index d4b6b261b..b4987df28 100644 --- a/docs/tutorials/lxmlgraph/step02.rst +++ b/docs/tutorials/lxmlgraph/step02.rst @@ -2,31 +2,27 @@ Step 02: Hello World as XML ================================================ -We now have a website with ``/a`` and ``/b`` URLs. Each has a default -view that returns a teensy weensy response. +We now have a default project. -In this step we will do the exact some scope, but using an XML -document as our model data. We will leverage the same ``repoze.bfg`` -machinery: +In this step we will add an XML document as our model data. We will +leverage the following ``repoze.bfg`` machinery: - Model data with interfaces that define "types" - ZCML configuration to provide type-specific views -We do, however, need to do some things differently: +Our application will need to do these things: - Our model class needs to use lxml to inject itelf into the XML nodes - That model class needs to implement the "handshake" -Let's look at what changed. - File ``myapp/samplemodel.xml`` -------------------------------- -Our hierarchy in Step 01 was very simple. Mimicking it in XML is, -thus, also very simple: +We're going to add an XML document that will serve as a source for +model data named ``samplemodel.xml``. .. literalinclude:: step02/myapp/samplemodel.xml :linenos: @@ -52,9 +48,6 @@ with an attribute matching the next hop. Also, the value of the Module ``myapp/models.py`` ------------------------------ -Here is the serious change: we have made an XML-aware model. Or is it -a model-aware XML document? Such questions, harrumph. - At a high level, we make write a class that "extends" lxml Element nodes, create an lxml parser, and register the custom class with the parser. @@ -87,11 +80,10 @@ parser. the custom Python class registered. We then load some XML and return the top of the tree. - Module `myapp/views.py`` -------------------------- -We only made two changes here. +Our ``views.py`` module does the following: .. literalinclude:: step02/myapp/views.py :linenos: @@ -102,17 +94,14 @@ We only made two changes here. #. Line 6 uses the special property we defined in our custom Python class to get the ``__name__`` of the context. - Browsing the Model ------------------------ -We can use the same URLs from Step 01 to browser the model and see -results:: +We can use these URLs to browse the model graph and see results:: http://localhost:5432/a http://localhost:5432/b http://localhost:5432/c (Not Found) In this case, each request grabs a node in the XML and uses it as the -data for the view. ``repoze.bfg`` doesn't really know that, unlike -Step 01, we no longer have "real" Python data. \ No newline at end of file +data for the view. diff --git a/docs/tutorials/lxmlgraph/step03.rst b/docs/tutorials/lxmlgraph/step03.rst index c7298e41d..6a585e37d 100644 --- a/docs/tutorials/lxmlgraph/step03.rst +++ b/docs/tutorials/lxmlgraph/step03.rst @@ -52,8 +52,10 @@ This function is relatively simple: (context). The second is the XML node object for that hop (context). -In Step 01 and 02, we returned a WebOb Response object that we -created. ``render_template_to_response`` makes a Response itself. +In Step 02, we returned a WebOb Response object that we created. +``render_template_to_response`` makes a Response itself. The +response's status is always ``200 OK`` if you use this shortcut +function. Here's what the ZPT looks like: -- cgit v1.2.3