From bbdc74fc81ac9b7710a41d0adea639baf6cac551 Mon Sep 17 00:00:00 2001 From: richard Date: Mon, 9 Sep 2002 00:45:06 +0000 Subject: [PATCH] More documentation. Simplified the "klass", "item" and "*classname*" variables into "context. git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@1092 57a73879-2fb5-44c3-a270-3262357dd7e2 --- TODO.txt | 2 +- doc/customizing.txt | 112 ++++++++++++++++-- roundup/cgi/client.py | 4 +- roundup/cgi/templating.py | 54 +++------ roundup/templates/classic/html/_generic.index | 2 +- roundup/templates/classic/html/file.index | 2 +- roundup/templates/classic/html/issue.index | 4 +- roundup/templates/classic/html/issue.item | 34 +++--- roundup/templates/classic/html/msg.index | 2 +- roundup/templates/classic/html/msg.item | 12 +- roundup/templates/classic/html/user.index | 16 +-- roundup/templates/classic/html/user.item | 42 +++---- roundup/templates/classic/html/user.register | 16 +-- 13 files changed, 187 insertions(+), 115 deletions(-) diff --git a/TODO.txt b/TODO.txt index 91ab448..014f1eb 100644 --- a/TODO.txt +++ b/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 diff --git a/doc/customizing.txt b/doc/customizing.txt index 7a1279c..6a8b28b 100644 --- a/doc/customizing.txt +++ b/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 :::::::::::::::::::: diff --git a/roundup/cgi/client.py b/roundup/cgi/client.py index 58a9cff..3dac133 100644 --- a/roundup/cgi/client.py +++ b/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: diff --git a/roundup/cgi/templating.py b/roundup/cgi/templating.py index 64f8716..d8a4f69 100644 --- a/roundup/cgi/templating.py +++ b/roundup/cgi/templating.py @@ -123,26 +123,13 @@ 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 @@ -150,20 +137,14 @@ class RoundupPageTemplate(PageTemplate.PageTemplate): ``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 @@ class RoundupPageTemplate(PageTemplate.PageTemplate): } # 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 @@ class HTMLClass: ''' 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 @@ class HTMLItem: #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 diff --git a/roundup/templates/classic/html/_generic.index b/roundup/templates/classic/html/_generic.index index 298a282..951dafd 100644 --- a/roundup/templates/classic/html/_generic.index +++ b/roundup/templates/classic/html/_generic.index @@ -19,7 +19,7 @@

- +
diff --git a/roundup/templates/classic/html/file.index b/roundup/templates/classic/html/file.index index fcbca1f..689e207 100644 --- a/roundup/templates/classic/html/file.index +++ b/roundup/templates/classic/html/file.index @@ -1,5 +1,5 @@ - + dld link diff --git a/roundup/templates/classic/html/issue.index b/roundup/templates/classic/html/issue.index index 7474192..a1f41f6 100644 --- a/roundup/templates/classic/html/issue.index +++ b/roundup/templates/classic/html/issue.index @@ -59,7 +59,7 @@ - diff --git a/roundup/templates/classic/html/issue.item b/roundup/templates/classic/html/issue.item index 7a04bf5..70ff043 100644 --- a/roundup/templates/classic/html/issue.item +++ b/roundup/templates/classic/html/issue.item @@ -7,35 +7,35 @@ - + - + - + - @@ -58,18 +58,20 @@ -
Titletitletitle
Priorityprioritypriority Statusstatusstatus
Superseder - + - -
View: + +
View: 		Nosy List - +
Assigned To + assignedto menu  
  + submit button will go here
-activity info +activity info - - + +
- + @@ -80,10 +82,10 @@
Messages
author date
- +
- + - + - - - - + + + +
Files
File nameUploaded
dld link @@ -97,7 +99,7 @@ - +
History
history
history
diff --git a/roundup/templates/classic/html/msg.index b/roundup/templates/classic/html/msg.index index 03fc70b..f2a8348 100644 --- a/roundup/templates/classic/html/msg.index +++ b/roundup/templates/classic/html/msg.index @@ -1,6 +1,6 @@ - + diff --git a/roundup/templates/classic/html/msg.item b/roundup/templates/classic/html/msg.item index d1405ed..abf69d8 100644 --- a/roundup/templates/classic/html/msg.item +++ b/roundup/templates/classic/html/msg.item @@ -3,28 +3,28 @@ - + - + - + - + - +
Messages
author date
Author
Recipients
Date
- 

+  

  		
 

 
 
Files

  
   dld link
@@ -37,6 +37,6 @@
 
 
 
History
history
history

 
 

diff --git a/roundup/templates/classic/html/user.index b/roundup/templates/classic/html/user.index
index 67fbea3..d553f39 100644
--- a/roundup/templates/classic/html/user.index
+++ b/roundup/templates/classic/html/user.index
@@ -7,15 +7,15 @@
  		Email address
  Phone number
 

  
-  username
+  username
  realnameorganisationaddressphonerealnameorganisationaddressphone
 

 

diff --git a/roundup/templates/classic/html/user.item b/roundup/templates/classic/html/user.item
index 7e528b8..2968d78 100644
--- a/roundup/templates/classic/html/user.item
+++ b/roundup/templates/classic/html/user.item
@@ -1,7 +1,7 @@
 
 
 
 
@@ -16,52 +16,52 @@ You are not allowed to view this page.
 
-  
+  
-  
+  
-  
+  
-  
-  
+  
-  
+  
-  
+  
-  
+  
-  
+  
-  
+  

  

   Namerealnamerealname
  

  

   Login Nameusernameusername
  

  

   Login Passwordpasswordpassword
  

  

   Rolesroles
+  roles
    
   
  

  

   Phonephonephone
  

  

   Organisationorganisationorganisation
  

  

   E-mail addressaddressaddress
  

  

   Alternate E-mail addresses
One address per line		alternate_addressesalternate_addresses
  

 
  

    submit button heresubmit button here
  

 

 
 
-
- 
+
+ 

-  
+  

   
Queries

    query
   

  

@@ -69,7 +69,7 @@ You are not allowed to view this page.
  
-   
+   

   
History

   
historyhistory
   

  

 
@@ -78,23 +78,23 @@ You are not allowed to view this page.
 
 
-  
+  
-  
+  
-  
+  
-  
+  
-  
+  

  
realnamerealname
  

  

   Login Nameusernameusername
  

  

   Phonephonephone
  

  

   Organisationorganisationorganisation
  

  

   E-mail addressaddressaddress
  

 

 
diff --git a/roundup/templates/classic/html/user.register b/roundup/templates/classic/html/user.register
index 0b18f81..5033d43 100644
--- a/roundup/templates/classic/html/user.register
+++ b/roundup/templates/classic/html/user.register
@@ -12,39 +12,39 @@ You are not allowed to view this page.
 
-  
+  
-  
+  
-  
+  
+      tal:content="structure context/roles/field">roles
-  
+  
-  
+  
-  
+  
-  
+  
-- 
2.30.2



  

   Namerealnamerealname
  

  

   Login Nameusernameusername
  

  

   Login Passwordpasswordpassword
  

  

   Roles
   roles
   
    
   
  

  

   Phonephonephone
  

  

   Organisationorganisationorganisation
  

  

   E-mail addressaddressaddress
  

  

   Alternate E-mail addresses
One address per line		alternate_addressesalternate_addresses