From c031443cadb8d80070915fb95d79210197c2ab5a Mon Sep 17 00:00:00 2001 From: richard Date: Thu, 12 Sep 2002 02:02:35 +0000 Subject: [PATCH] more documentation, fixed bug in request/description git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@1145 57a73879-2fb5-44c3-a270-3262357dd7e2 --- doc/customizing.txt | 147 ++++++++++++++++++++++++++++++++++++-- roundup/cgi/templating.py | 54 ++++++++++++-- 2 files changed, 191 insertions(+), 10 deletions(-) diff --git a/doc/customizing.txt b/doc/customizing.txt index 223f04a..751afab 100644 --- a/doc/customizing.txt +++ b/doc/customizing.txt @@ -2,7 +2,7 @@ Customising Roundup =================== -:Version: $Revision: 1.28 $ +:Version: $Revision: 1.29 $ .. This document borrows from the ZopeBook section on ZPT. The original is at: http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx @@ -778,9 +778,8 @@ 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). + The current context. This is either None, a + `hyperdb class wrapper`_ or a `hyperdb item wrapper`_ *request* Includes information about the current request, including: - the url @@ -818,6 +817,9 @@ The following variables are available to templates. Hello, World! +*utils* + This variable makes available some utility functions like batching. + The context variable ~~~~~~~~~~~~~~~~~~~~ @@ -825,8 +827,10 @@ 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 +2. if we're looking at a specific hyperdb class, it's a + `hyperdb class wrapper`_. +3. if we're looking at a specific hyperdb item, it's a + `hyperdb item wrapper`_. 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: @@ -838,10 +842,128 @@ The only real difference between cases 2 and 3 above are: 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". +Hyperdb class wrapper +::::::::::::::::::::: + +Note: this is implemented by the roundup.cgi.templating.HTMLClass class. + +This wrapper object provides access to a hyperb class. It is used primarily +in both index view and new item views, but it's also usable anywhere else that +you wish to access information about a class, or the items of a class, when +you don't have a specific item of that class in mind. + +We allow access to properties. There will be no "id" property. The value +accessed through the property will be the current value of the same name from +the CGI form. + +There are several methods available on these wrapper objects: + +=========== ============================================================= +Method Description +=========== ============================================================= +properties return a `hyperdb property wrapper`_ for all of this class' + properties. +list lists all of the active (not retired) items in the class. +csv return the items of this class as a chunk of CSV text. +propnames lists the names of the properties of this class. +filter lists of items from this class, filtered and sorted + by the current *request* filterspec/filter/sort/group args +classhelp display a link to a javascript popup containing this class' + "help" template. +submit generate a submit button (and action hidden element) +renderWith render this class with the given template. +history returns 'New node - no history' :) +=========== ============================================================= + +Note that if you have a property of the same name as one of the above methods, +you'll need to access it using a python "item access" expression. For example:: + + python:context['list'] + +will access the "list" property, rather than the list method. + + +Hyperdb item wrapper +:::::::::::::::::::: + +Note: this is implemented by the roundup.cgi.templating.HTMLItem class. + +This wrapper object provides access to a hyperb item. + +We allow access to properties. There will be no "id" property. The value +accessed through the property will be the current value of the same name from +the CGI form. + +There are several methods available on these wrapper objects: + +=============== ============================================================= +Method Description +=============== ============================================================= +submit generate a submit button (and action hidden element) +journal return the journal of the current item (**not implemented**) +history render the journal of the current item as HTML +renderQueryForm specific to the "query" class - render the search form for + the query +hasPermission specific to the "user" class - determine whether the user + has a Permission +=============== ============================================================= + + +Note that if you have a property of the same name as one of the above methods, +you'll need to access it using a python "item access" expression. For example:: + + python:context['journal'] + +will access the "journal" property, rather than the journal method. + + +Hyperdb property wrapper +:::::::::::::::::::::::: + +Note: this is implemented by subclasses roundup.cgi.templating.HTMLProperty +class (HTMLStringProperty, HTMLNumberProperty, and so on). + +This wrapper object provides access to a single property of a class. Its +value may be either: + +1. if accessed through a `hyperdb item wrapper`_, then it's a value from the + hyperdb +2. if access through a `hyperdb class wrapper`_, then it's a value from the + CGI form + + +The property wrapper has some useful attributes: + +=============== ============================================================= +Attribute Description +=============== ============================================================= +_name the name of the property +_value the value of the property if any +=============== ============================================================= + +There are several methods available on these wrapper objects: + +=========== ============================================================= +Method Description +=========== ============================================================= +plain render a "plain" representation of the property +field render a form edit field for the property +stext specific to String properties - render the value of the + property as StructuredText (requires the StructureText module + to be installed separately) +multiline specific to String properties - render a multiline form edit + field for the property +email specific to String properties - render the value of the + property as an obscured email address +=========== ============================================================= + +XXX do the other properties The request variable ~~~~~~~~~~~~~~~~~~~~ +Note: this is implemented by the roundup.cgi.templating.HTMLRequest class. + The request variable is packed with information about the current request. .. taken from roundup.cgi.templating.HTMLRequest docstring @@ -874,6 +996,19 @@ filterspec values to filter the index on search_text text to perform a full-text search on for an index =========== ================================================================ +The db variable +~~~~~~~~~~~~~~~ + +Note: this is implemented by the roundup.cgi.templating.HTMLDatabase class. + +Allows access to all hyperdb classes as attributes of this variable. If you +want access to the "user" class, for example, you would use:: + + db/user + python:db.user + +The access results in a `hyperdb class wrapper`_. + Displaying Properties --------------------- diff --git a/roundup/cgi/templating.py b/roundup/cgi/templating.py index 11e4983..4a154b9 100644 --- a/roundup/cgi/templating.py +++ b/roundup/cgi/templating.py @@ -277,7 +277,7 @@ class HTMLClass: raise AttributeError, attr def properties(self): - ''' Return HTMLProperty for all props + ''' Return HTMLProperty for all of this class' properties. ''' l = [] for name, prop in self._props.items(): @@ -291,6 +291,8 @@ class HTMLClass: return l def list(self): + ''' List all items in this class. + ''' if self.classname == 'user': klass = HTMLUser else: @@ -635,7 +637,7 @@ class HTMLUser(HTMLItem): class HTMLProperty: ''' String, Number, Date, Interval HTMLProperty - Hase useful attributes: + Has useful attributes: _name the name of the property _value the value of the property if any @@ -660,6 +662,8 @@ class HTMLProperty: class StringHTMLProperty(HTMLProperty): def plain(self, escape=0): + ''' Render a "plain" representation of the property + ''' if self._value is None: return '' if escape: @@ -667,12 +671,18 @@ class StringHTMLProperty(HTMLProperty): return str(self._value) def stext(self, escape=0): + ''' Render the value of the property as StructuredText. + + This requires the StructureText module to be installed separately. + ''' s = self.plain(escape=escape) if not StructuredText: return s return StructuredText(s,level=1,header=0) def field(self, size = 30): + ''' Render a form edit field for the property + ''' if self._value is None: value = '' else: @@ -681,6 +691,8 @@ class StringHTMLProperty(HTMLProperty): return ''%(self._name, value, size) def multiline(self, escape=0, rows=5, cols=40): + ''' Render a multiline form edit field for the property + ''' if self._value is None: value = '' else: @@ -690,7 +702,8 @@ class StringHTMLProperty(HTMLProperty): self._name, rows, cols, value) def email(self, escape=1): - ''' fudge email ''' + ''' Render the value of the property as an obscured email address + ''' if self._value is None: value = '' else: value = str(self._value) value = value.replace('@', ' at ') @@ -701,18 +714,26 @@ class StringHTMLProperty(HTMLProperty): class PasswordHTMLProperty(HTMLProperty): def plain(self): + ''' Render a "plain" representation of the property + ''' if self._value is None: return '' return _('*encrypted*') def field(self, size = 30): + ''' Render a form edit field for the property + ''' return ''%(self._name, size) class NumberHTMLProperty(HTMLProperty): def plain(self): + ''' Render a "plain" representation of the property + ''' return str(self._value) def field(self, size = 30): + ''' Render a form edit field for the property + ''' if self._value is None: value = '' else: @@ -722,11 +743,15 @@ class NumberHTMLProperty(HTMLProperty): class BooleanHTMLProperty(HTMLProperty): def plain(self): + ''' Render a "plain" representation of the property + ''' if self.value is None: return '' return self._value and "Yes" or "No" def field(self): + ''' Render a form edit field for the property + ''' checked = self._value and "checked" or "" s = 'Yes'%(self._name, checked) @@ -740,11 +765,15 @@ class BooleanHTMLProperty(HTMLProperty): class DateHTMLProperty(HTMLProperty): def plain(self): + ''' Render a "plain" representation of the property + ''' if self._value is None: return '' return str(self._value) def field(self, size = 30): + ''' Render a form edit field for the property + ''' if self._value is None: value = '' else: @@ -764,6 +793,8 @@ class DateHTMLProperty(HTMLProperty): class IntervalHTMLProperty(HTMLProperty): def plain(self): + ''' Render a "plain" representation of the property + ''' if self._value is None: return '' return str(self._value) @@ -772,6 +803,8 @@ class IntervalHTMLProperty(HTMLProperty): return self._value.pretty() def field(self, size = 30): + ''' Render a form edit field for the property + ''' if self._value is None: value = '' else: @@ -802,6 +835,8 @@ class LinkHTMLProperty(HTMLProperty): return getattr(i, attr) def plain(self, escape=0): + ''' Render a "plain" representation of the property + ''' if self._value is None: return '' linkcl = self._db.classes[self._prop.classname] @@ -812,6 +847,8 @@ class LinkHTMLProperty(HTMLProperty): return value def field(self): + ''' Render a form edit field for the property + ''' linkcl = self._db.getclass(self._prop.classname) if linkcl.getprops().has_key('order'): sort_on = 'order' @@ -928,6 +965,8 @@ class MultilinkHTMLProperty(HTMLProperty): return [klass(self._client, self._prop.classname, value) for value in l] def plain(self, escape=0): + ''' Render a "plain" representation of the property + ''' linkcl = self._db.classes[self._prop.classname] k = linkcl.labelprop(1) labels = [] @@ -939,6 +978,8 @@ class MultilinkHTMLProperty(HTMLProperty): return value def field(self, size=30, showid=0): + ''' Render a form edit field for the property + ''' sortfunc = make_sort_function(self._db, self._prop.classname) linkcl = self._db.getclass(self._prop.classname) value = self._value[:] @@ -1168,7 +1209,12 @@ class HTMLRequest: if self.client.nodeid: s.append('- %s%s'%(self.classname, self.client.nodeid)) else: - s.append('- index of '+self.classname) + if self.template == 'item': + s.append('- new %s'%self.classname) + elif self.template == 'index': + s.append('- %s index'%self.classname) + else: + s.append('- %s %s'%(self.classname, self.template)) else: s.append('- home') return ' '.join(s) -- 2.30.2