Mercurial Repository: p/roundup/code: doc/design.txt comparison

comparison doc/design.txt @ 1244:8dd4f736370b

merge from maintenance branch

author	Richard Jones <richard@users.sourceforge.net>
date	Thu, 03 Oct 2002 06:56:30 +0000
parents	d870139aeb5c
children	6fede2aa6a12

comparison

equal deleted inserted replaced

-:3a028d2f7830
+:8dd4f736370b
 Displaying Properties
 ~~~~~~~~~~~~~~~~~~~~~
 Properties appear in the user interface in three contexts:
-in indices, in editors, and as filters.  For each type of
+in indices, in editors, and as search filters.  For each type of
 property, there are several display possibilities.  For example,
 in an index view, a string property may just be printed as
 a plain string, but in an editor view, that property should
 be displayed in an editable field.
 The display of a property is handled by functions in
-a displayers module.  Each function accepts at
+the ``cgi.templating`` module.
-least three standard arguments -- the database, class name,
-and item id -- and returns a chunk of HTML.
+Displayer functions are triggered by ``tal:content`` or ``tal:replace``
+tag attributes in templates.  The value of the attribute
-Displayer functions are triggered by <display>
+provides an expression for calling the displayer function.
-tags in templates.  The call attribute of the tag
+For example, the occurrence of::
-provides a Python expression for calling the displayer
-function.  The three standard arguments are inserted in
+tal:content="context/status/plain"
-front of the arguments given.  For example, the occurrence of::
-<display call="plain('status', max=30)">
 in a template triggers a call to::
-plain(db, "issue", 13, "status", max=30)
+context['status'].plain()
+where the context would be an item of the "issue" class.  The displayer
-when displaying issue 13 in the "issue" class.  The displayer
 functions can accept extra arguments to further specify
-details about the widgets that should be generated.  By defining new
+details about the widgets that should be generated.
-displayer functions, the user interface can be highly customized.
 Some of the standard displayer functions include:
 ========= ====================================================================
 Function  Description
 plain     display a String property directly;
 display a Date property in a specified time zone with an option
 to omit the time from the date stamp; for a Link or Multilink
 property, display the key strings of the linked items (or the
 ids if the linked class has no key property)
-field     display a property like the
+field     display a property like the plain displayer above, but in a text
-plain displayer above, but in a text field
+field to be edited
-to be edited
+menu      for a Link property, display a menu of the available choices
-menu      for a Link property, display
-a menu of the available choices
-link      for a Link or Multilink property,
-display the names of the linked items, hyperlinked to the
-issue views on those items
-count     for a Multilink property, display
-a count of the number of links in the list
-reldate   display a Date property in terms
-of an interval relative to the current date (e.g. "+ 3w", "- 2d").
-download  show a Link("file") or Multilink("file")
-property using links that allow you to download files
-checklist for a Link or Multilink property,
-display checkboxes for the available choices to permit filtering
 ========= ====================================================================
-TODO: See the htmltemplate pydoc for a complete list of the functions
+See the `customisation`_ documentation for the complete list.
 Index Views
 ~~~~~~~~~~~
+XXX The following needs to be clearer
 An index view contains two sections: a filter section
 and an index section.
 The filter section provides some widgets for selecting
 which issues appear in the index.  The index section is
 """""""""""""""""""""
 An index view specifier looks like this (whitespace
 has been added for clarity)::
-/issue?status=unread,in-progress,resolved&amp;
+/issue?status=unread,in-progress,resolved&
-topic=security,ui&amp;
+topic=security,ui&
-:group=priority&amp;
+:group=priority&
-:sort=-activity&amp;
+:sort=-activity&
-:filters=status,topic&amp;
+: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.
 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.
-Filter Section
-""""""""""""""
-The template for a filter section provides the
-filtering widgets at the top of the index view.
-Fragments enclosed in ``<property>...</property>``
-tags are included or omitted depending on whether the
-view specifier requests a filter for a particular property.
-Here's a simple example of a filter template::
-<property name=status>
-<display call="checklist('status')">
-</property>
-<br>
-<property name=priority>
-<display call="checklist('priority')">
-</property>
-<br>
-<property name=fixer>
-<display call="menu('fixer')">
-</property>
 Index Section
 """""""""""""
 The template for an index section describes one row of
 the index table.
 to display the values of the issue's properties.
 Here's a simple example of an index template::
 <tr>
-<property name=title>
+<td tal:condition="request/show/title" tal:content="contex/title"></td>
-<td><display call="plain('title', max=50)"></td>
+<td tal:condition="request/show/status" tal:content="contex/status"></td>
-</property>
+<td tal:condition="request/show/fixer" tal:content="contex/fixer"></td>
-<property name=status>
-<td><display call="plain('status')"></td>
-</property>
-<property name=fixer>
-<td><display call="plain('fixer')"></td>
-</property>
 </tr>
 Sorting
 """""""
 Here's an example of a basic editor template::
 <table>
 <tr>
-<td colspan=2>
+<td colspan=2 tal:content="python:context.title.field(size='60')"></td>
-<display call="field('title', size=60)">
-</td>
 </tr>
 <tr>
-<td>
+<td tal:content="context/fixer/field"></td>
-<display call="field('fixer', size=30)">
+<td tal:content="context/status/menu"></td>
-</td>
-<td>
-<display call="menu('status')>
-</td>
 </tr>
 <tr>
-<td>
+<td tal:content="context/nosy/field"></td>
-<display call="field('nosy', size=30)">
+<td tal:content="context/priority/menu"></td>
-</td>
-<td>
-<display call="menu('priority')>
-</td>
 </tr>
 <tr>
 <td colspan=2>
-<display call="note()">
+<textarea name=":note" rows=5 cols=60></textarea>
 </td>
 </tr>
 </table>
-As shown in the example, the editor template can also
+As shown in the example, the editor template can also include a ":note" field,
-request the display of a "note" field, which is a
+which is a text area for entering a note to go along with a change.
-text area for entering a note to go along with a change.
 When a change is submitted, the system automatically
 generates a message describing the changed properties.
 The message displays all of the property values on the
 issue and indicates which ones have changed.
 priority: critical
 status: unread -> in-progress
 fixer: (none)
 keywords: parrot,plumage,perch,nailed,dead
-If a note is given in the "note" field, the note is
+If a note is given in the ":note" field, the note is
 appended to the description.  The message is then added
 to the issue's message spool (thus triggering the standard
 detector to react by sending out this message to the nosy list).
 Spool Section
 if db.security.hasItemPermission('issue', itemid, assignedto=userid):
 # all ok
 Code in the core will make use of these methods, as should code in auditors in
-custom templates. The htmltemplate will implement a new tag, ``<require>``
+custom templates. The HTML templating may access the access controls through
-which has the form::
+the *user* attribute of the *request* variable. It exposes a ``hasPermission()``
+method::
-<require permission="name,name,name" assignedto="$userid" status="open">
-HTML to display if the user has the permission.
+tal:condition="python:request.user.hasPermission('Edit', 'issue')"
-<else>
-HTML to display if the user does not have the permission.
+or, if the *context* is *issue*, then the following is the same::
-</require>
+tal:condition="python:request.user.hasPermission('Edit')"
-where:
-- the permission attribute gives a comma-separated list of permission names.
-These are checked in turn using ``hasPermission`` and requires one to
-be OK.
-- the other attributes are lookups on the item using ``hasItemPermission``. If
-the attribute value is "$userid" then the current user's userid is tested.
-Any of these tests must pass or the ``<require>`` check will fail. The section
-of html within the side of the ``<else>`` that fails is remove from processing.
 Authentication of Users
 ~~~~~~~~~~~~~~~~~~~~~~~
 Users must be authenticated correctly for the above controls to work. This is
 A combination of existing and new Roles, Permissions and auditors could
 be used here.
 privacy - issues that are only visible to some users
 A new property is added to the issue which marks the user or group of
 users who are allowed to view and edit the issue. An auditor will check
-for edit access, and the htmltemplate <require> tag can check for view
+for edit access, and the template user object can check for view access.
-access.
 Deployment Scenarios
 --------------------
 - Added Boolean and Number types
 - Added section Hyperdatabase Implementations
 - "Item" has been renamed to "Issue" to account for the more specific nature
 of the Class.
+- New Templating
+- Access Controls
+------------------
+Back to `Table of Contents`_
+.. _`Table of Contents`: index.html
+.. _customisation: customizing.html

Mercurial > p > roundup > code

comparison doc/design.txt @ 1244:8dd4f736370b