More documentation.

Simplified the "klass", "item" and "*classname*" variables into "context.

Author: Richard Jones

TODO.txt

@@ -53,7 +53,7 @@ pending admin: have roundup-admin "set" command be applicable to all items
                in a class
 
 bug: request.url is incorrect in cgi-bin environments
-
+bug: query editing not translated to new templating
 
 done web: Re-enable link backrefs from messages (feature request #568714)
 done web: have the page layout (header/footer) be templatable

doc/customizing.txt

@@ -2,7 +2,7 @@
 Customising Roundup
 ===================
 
-:Version: $Revision: 1.19 $
+:Version: $Revision: 1.20 $
 
 .. This document borrows from the ZopeBook section on ZPT. The original is at:
    http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
@@ -591,6 +591,9 @@ control on to the instance interfaces.Client class which handles the rest of
 the access through its main() method. This means that you can do pretty much
 anything you want as a web interface to your instance.
 
+Figuring out what is displayed
+::::::::::::::::::::::::::::::
+
 Most customisation of the web view can be done by modifying the templates in
 the instance **html** directory. There are several types of files in there:
 
@@ -615,6 +618,9 @@ user.register
 style.css
   a static file that is served up as-is
 
+How requests are processed
+::::::::::::::::::::::::::
+
 The basic processing of a web request proceeds as follows:
 
 1. figure out who we are, defaulting to the "anonymous" user
@@ -636,6 +642,9 @@ In some situations, exceptions occur:
 - NotFound       (raised wherever it needs to be)
   this exception percolates up to the CGI interface that called the client
 
+Determining web context
+:::::::::::::::::::::::
+
 To determine the "context" of a request, we look at the URL and the special
 request variable ``:template``. The URL path after the instance identifier
 is examined. Typical URL paths look like:
@@ -679,8 +688,14 @@ which defaults to:
 - only classname suplied:          "index"
 - full item designator supplied:   "item"
 
-Actions are triggered by using a ``:action`` CGI variable, where the value is
-one of:
+
+Performing actions in web requests
+::::::::::::::::::::::::::::::::::
+
+When a user requests a web page, they may optionally also request for an
+action to take place. As described in `how requests are processed`_, the
+action is performed before the requested page is generated. Actions are
+triggered by using a ``:action`` CGI variable, where the value is one of:
 
 login
  Attempt to log a user in.
@@ -910,6 +925,83 @@ TALES - TAL Expression Syntax
    equivalent to ``item/status/checklist``, assuming that ``checklist`` is
    a method.
 
+Information available to templates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following variables are available to templates.
+
+.. taken from roundup.cgi.templating.RoundupPageTemplate docstring
+
+*context*
+  The current context. This is either None, a wrapper around a
+  hyperdb class (an HTMLClass) or a wrapper around a hyperdb item (an
+  HTMLItem).
+*request*
+  Includes information about the current request, including:
+   - the url
+   - the current index information (``filterspec``, ``filter`` args,
+     ``properties``, etc) parsed out of the form. 
+   - methods for easy filterspec link generation
+   - *user*, the current user node as an HTMLItem instance
+   - *form*
+     The current CGI form information as a mapping of form argument
+     name to value
+*instance*
+  The current instance
+*db*
+  The current database, through which db.config may be reached.
+
+The context variable
+::::::::::::::::::
+
+The *context* variable is one of three things based on the current context
+(see `determining web context`_ for how we figure this out):
+
+1. if we're looking at a "home" page, then it's None
+2. if we're looking at a specific hyperdb class, it's an HTMLClass instance
+3. if we're looking at a specific hyperdb item, it's an HTMLItem instance
+
+If the context is not None, we can access the properties of the class or item.
+The only real difference between cases 2 and 3 above are:
+
+1. the properties may have a real value behind them, and this will appear if
+   the property is displayed through ``context/property`` or
+   ``context/property/field``.
+2. the context's "id" property will be a false value in the second case, but
+   a real, or true value in the third. Thus we can determine whether we're
+   looking at a real item from the hyperdb by testing "context/id".
+
+
+The request variable
+::::::::::::::::::::
+
+The request variable is packed with information about the current request.
+
+.. taken from roundup.cgi.templating.HTMLRequest docstring
+
+=========== ================================================================
+Variable    Holds
+=========== ================================================================
+form        the CGI form as a cgi.FieldStorage
+env         the CGI environment variables
+url         the current URL path for this request
+base        the base URL for this instance
+user        a HTMLUser instance for this user
+classname   the current classname (possibly None)
+template    the current template (suffix, also possibly None)
+form        the current CGI form variables in a FieldStorage
+**Index  page specific variables (indexing arguments)**
+columns     dictionary of the columns to display in an index page
+show        a convenience access to columns - request/show/colname will
+              be true if the columns should be displayed, false otherwise
+sort        index sort column (direction, column name)
+group       index grouping property (direction, column name)
+filter      properties to filter the index on
+filterspec  values to filter the index on
+search_text text to perform a full-text search on for an index
+----------- ----------------------------------------------------------------
+
+
 Displaying Properties
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -931,11 +1023,11 @@ An index view specifier (URL fragment) looks like this (whitespace has been
 added for clarity)::
 
      /issue?status=unread,in-progress,resolved&
-             topic=security,ui&
-             :group=+priority&
-             :sort=-activity&
-             :filters=status,topic&
-             :columns=title,status,fixer
+            topic=security,ui&
+            :group=+priority&
+            :sort=-activity&
+            :filters=status,topic&
+            :columns=title,status,fixer
 
 The index view is determined by two parts of the specifier: the layout part and
 the filter part. The layout part consists of the query parameters that begin
@@ -958,10 +1050,6 @@ by activity, arranged in descending order. The filter section shows filters for
 the "status" and "topic" properties, and the table includes columns for the
 "title", "status", and "fixer" properties.
 
-Associated with each item class is a default layout specifier. The layout
-specifier in the above example is the default layout to be provided with the
-default bug-tracker schema described above in section 4.4.
-
 Filtering of indexes
 ::::::::::::::::::::
 

roundup/cgi/client.py

@@ -1,4 +1,4 @@
-# $Id: client.py,v 1.20 2002-09-06 22:54:51 richard Exp $
+# $Id: client.py,v 1.21 2002-09-09 00:45:06 richard Exp $
 
 __doc__ = """
 WWW request handler (also used in the stand-alone server).
@@ -1069,10 +1069,8 @@ def parsePropsFromForm(db, cl, form, nodeid=0, num_re=re.compile('^\d+$')):
         must be supplied or a ValueError will be raised.
     '''
     required = []
-    print form.keys()
     if form.has_key(':required'):
         value = form[':required']
-        print 'required', value
         if isinstance(value, type([])):
             required = [i.value.strip() for i in value]
         else:

roundup/cgi/templating.py

@@ -123,47 +123,28 @@ class RoundupPageTemplate(PageTemplate.PageTemplate):
         Interrogate the client to set up the various template variables to
         be available:
 
-        *class*
-          The current class of node being displayed as an HTMLClass
-          instance.
-        *item*
-          The current node from the database, if we're viewing a specific
-          node, as an HTMLItem instance. If it doesn't exist, then we're
-          on a new item page.
-        (*classname*)
-          this is one of two things:
-
-          1. the *item* is also available under its classname, so a *user*
-             node would also be available under the name *user*. This is
-             also an HTMLItem instance.
-          2. if there's no *item* then the current class is available
-             through this name, thus "user/name" and "user/name/menu" will
-             still work - the latter will pull information from the form
-             if it can.
-        *form*
-          The current CGI form information as a mapping of form argument
-          name to value
+        *context*
+         this is one of three things:
+         1. None - we're viewing a "home" page
+         2. The current class of item being displayed. This is an HTMLClass
+            instance.
+         3. The current item from the database, if we're viewing a specific
+            item, as an HTMLItem instance.
         *request*
           Includes information about the current request, including:
            - the url
            - the current index information (``filterspec``, ``filter`` args,
              ``properties``, etc) parsed out of the form. 
            - methods for easy filterspec link generation
            - *user*, the current user node as an HTMLItem instance
+           - *form*, the current CGI form information as a FieldStorage
         *instance*
           The current instance
         *db*
           The current database, through which db.config may be reached.
-
-        Maybe also:
-
-        *modules*
-          python modules made available (XXX: not sure what's actually in
-          there tho)
     '''
     def getContext(self, client, classname, request):
         c = {
-             'klass': HTMLClass(client, classname),
              'options': {},
              'nothing': None,
              'request': request,
@@ -173,10 +154,9 @@ def getContext(self, client, classname, request):
         }
         # add in the item if there is one
         if client.nodeid:
-            c['item'] = HTMLItem(client, classname, client.nodeid)
-            c[classname] = c['item']
+            c['context'] = HTMLItem(client, classname, client.nodeid)
         else:
-            c[classname] = c['klass']
+            c['context'] = HTMLClass(client, classname)
         return c
 
     def render(self, client, classname, request, **options):
@@ -237,11 +217,15 @@ def __getitem__(self, item):
         ''' return an HTMLProperty instance
         '''
         #print 'getitem', (self, item)
+
+        # we don't exist
+        if item == 'id':
+            return None
         if item == 'creator':
-            return HTMLUser(self.client, 'user', client.userid)
+            # but we will be created by this user...
+            return HTMLUser(self.client, 'user', self.client.userid)
 
-        if not self.props.has_key(item):
-            raise KeyError, item
+        # get the property
         prop = self.props[item]
 
         # look up the correct HTMLProperty class
@@ -398,8 +382,8 @@ def __getitem__(self, item):
         #print 'getitem', (self, item)
         if item == 'id':
             return self.nodeid
-        if not self.props.has_key(item):
-            raise KeyError, item
+
+        # get the property
         prop = self.props[item]
 
         # get the value, handling missing values

roundup/templates/classic/html/_generic.index

@@ -19,7 +19,7 @@
 </p>
 
 <form onSubmit="return submit_once()" method="POST">
-<textarea rows="15" cols="60" name="rows" tal:content="klass/csv"></textarea>
+<textarea rows="15" cols="60" name="rows" tal:content="context/csv"></textarea>
 <br>
 <input type="hidden" name=":action" value="editCSV">
 <input type="submit" value="Edit Items">

roundup/templates/classic/html/file.index

@@ -1,5 +1,5 @@
 <!-- dollarId: file.index,v 1.4 2002/01/23 05:10:27 richard Exp dollar-->
-<tr tal:repeat="file class/list">
+<tr tal:repeat="file context/list">
  <td tal:condition="display/properties/name">
   <a href="" tal:attributes="href string:file${file/id}/${file/name}">dld link</a>
  </td>

roundup/templates/classic/html/issue.index

@@ -59,7 +59,7 @@
    <td>
     <select name=":sort">
      <option value="">- nothing -</option>
-     <option tal:repeat="col klass/properties"
+     <option tal:repeat="col context/properties"
              tal:attributes="value col/name;
                              selected python:col.name == request.sort[1]"
              tal:content="col/name">column</option>
@@ -75,7 +75,7 @@
    <td>
     <select name=":group">
      <option value="">- nothing -</option>
-     <option tal:repeat="col klass/properties"
+     <option tal:repeat="col context/properties"
              tal:attributes="value col/name;
                              selected python:col.name == request.group[1]"
              tal:content="col/name">column</option>