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

comparison doc/customizing.txt @ 1125:3c1533be3822

more doc

author	Richard Jones <richard@users.sourceforge.net>
date	Thu, 12 Sep 2002 03:57:09 +0000
parents	1fc1f92c5f31
children	36ec30d286ea

comparison

equal deleted inserted replaced

-:1fc1f92c5f31
+:3c1533be3822
 ===================
 Customising Roundup
 ===================
-:Version: $Revision: 1.30 $
+:Version: $Revision: 1.31 $
 .. This document borrows from the ZopeBook section on ZPT. The original is at:
 http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
 .. contents::
+:depth: 1
 What You Can Do
 ===============
 Customisation of Roundup can take one of five forms:
 XXX example
 Web Interface
 =============
+.. contents::
+:local:
+:depth: 1
 The web is provided by the roundup.cgi.client module and is used by
 roundup.cgi, roundup-server and ZRoundup.
 In all cases, we determine which tracker is being accessed
 (the first part of the URL path inside the scope of the CGI handler) and pass
 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
+**login**
 Attempt to log a user in.
-logout
+**logout**
 Log the user out - make them "anonymous".
-register
+**register**
 Attempt to create a new user based on the contents of the form and then log
 them in.
-edit
+**edit**
 Perform an edit of an item in the database. There are some special form
 elements you may use:
 :link=designator:property and :multilink=designator:property
 The value specifies an item designator and the property on that
 "files" property. Attach the file to the message created from
 the :note if it's supplied.
 :required=property,property,...
 The named properties are required to be filled in the form.
-new
+**new**
 Add a new item to the database. You may use the same special form elements
 as in the "edit" action.
-editCSV
+**editCSV**
 Performs an edit of all of a class' items in one go. See also the
 *class*.csv templating method which generates the CSV data to be edited, and
 the "_generic.index" template which uses both of these features.
-search
+**search**
 Mangle some of the form variables.
 Set the form ":filter" variable based on the values of the
 filter variables - if they're set to anything other than
 "dontcare" then add them to :filter.
 Each action also has a corresponding *actionPermission* (where
 "action" is the name of the action) method which determines
 whether the action is permissible given the current user. The base permission
 checks are:
-login
+**login**
 Determine whether the user has permission to log in.
 Base behaviour is to check the user has "Web Access".
-logout
+**logout**
 No permission checks are made.
-register
+**register**
 Determine whether the user has permission to register
 Base behaviour is to check the user has "Web Registration".
-edit
+**edit**
 Determine whether the user has permission to edit this item.
 Base behaviour is to check the user can edit this class. If we're
 editing the "user" class, users are allowed to edit their own
 details. Unless it's the "roles" property, which requires the
 special Permission "Web Roles".
-new
+**new**
 Determine whether the user has permission to create (edit) this item.
 Base behaviour is to check the user can edit this class. No
 additional property checks are made. Additionally, new user items
 may be created if the user has the "Web Registration" Permission.
-editCSV
+**editCSV**
 Determine whether the user has permission to edit this class.
 Base behaviour is to check the user can edit this class.
-search
+**search**
 Determine whether the user has permission to search this class.
 Base behaviour is to check the user can view this class.
 Default templates
 -----------------
 Most customisation of the web view can be done by modifying the templates in
 the tracker **html** directory. There are several types of files in there:
-page
+**page**
 This template defines the overall look of your tracker. When you
 view an issue, it appears inside this template. When you view an index, it
 also appears inside this template. It will have a ``tal:content`` or
 ``tal:replace`` command with the expression ``structure content`` which
 will show the issue, list of issues or whatever.
-home
+**home**
 the default page displayed when no other page is indicated by the user
-home.classlist
+**home.classlist**
 a special version of the default page that lists the classes in the tracker
-*classname*.item
+**classname.item**
 displays an item of the *classname* class
-*classname*.index
+**classname.index**
 displays a list of *classname* items
-*classname*.search
+**classname.search**
 displays a search page for *classname* items
-_generic.index
+**_generic.index**
 used to display a list of items where there is no *classname*.index available
-_generic.help
+**_generic.help**
 used to display a "class help" page where there is no *classname*.help
-user.register
+**user.register**
 a special page just for the user class that renders the registration page
-style.css
+**style.css**
 a static file that is served up as-is
 How the templates work
 ----------------------
 Roundup's templates consist of special attributes on your template tags. These
 attributes form the Template Attribute Language, or TAL. The commands are:
-tal:define="variable expression; variable expression; ..."
+**tal:define="variable expression; variable expression; ..."**
 Define a new variable that is local to this tag and its contents. For
 example::
 <html tal:define="title request/description">
 <head><title tal:content="title"></title></head>
 In the example, the variable "title" is defined as being the result of the
 expression "request/description". The tal:content command inside the <html>
 tag may then use the "title" variable.
-tal:condition="expression"
+**tal:condition="expression"**
 Only keep this tag and its contents if the expression is true. For example::
 <p tal:condition="python:request.user.hasPermission('View', 'issue')">
 Display some issue information.
 </p>
 user has the View permission for issues. We consider the number zero, a
 blank string, an empty list, and the built-in variable nothing to be false
 values. Nearly every other value is true, including non-zero numbers, and
 strings with anything in them (even spaces!).
-tal:repeat="variable expression"
+**tal:repeat="variable expression"**
 Repeat this tag and its contents for each element of the sequence that the
 expression returns, defining a new local variable and a special "repeat"
 variable for each element. For example::
 <tr tal:repeat="u user/list">
 </tr>
 The example would iterate over the sequence of users returned by
 "user/list" and define the local variable "u" for each entry.
-tal:replace="expression"
+**tal:replace="expression"**
 Replace this tag with the result of the expression. For example::
 <span tal:replace="request/user/realname"></span>
 The example would replace the <span> tag and its contents with the user's
 realname. If the user's realname was "Bruce" then the resultant output
 would be "Bruce".
-tal:content="expression"
+**tal:content="expression"**
 Replace the contents of this tag with the result of the expression. For
 example::
 <span tal:content="request/user/realname">user's name appears here</span>
 The example would replace the contents of the <span> tag with the user's
 realname. If the user's realname was "Bruce" then the resultant output
 would be "<span>Bruce</span>".
-tal:attributes="attribute expression; attribute expression; ..."
+**tal:attributes="attribute expression; attribute expression; ..."**
 Set attributes on this tag to the results of expressions. For example::
 <a tal:attributes="href string:user${request/user/id}">My Details</a>
 In the example, the "href" attribute of the <a> tag is set to the value of
 the "string:user${request/user/id}" expression, which will be something
 like "user123".
-tal:omit-tag="expression"
+**tal:omit-tag="expression"**
 Remove this tag (but not its contents) if the expression is true. For
 example::
 <span tal:omit-tag="python:1">Hello, world!</span>
 which would othewise require an illegal tag placement to effect the repeat).
 The expressions you may use in the attibute values may be one of the following
 three forms:
-Path Expressions - eg. ``item/status/checklist``
+**Path Expressions** - eg. ``item/status/checklist``
 These are object attribute / item accesses. Roughly speaking, the path
 ``item/status/checklist`` is broken into parts ``item``, ``status``
 and ``checklist``. The ``item`` part is the root of the expression.
 We then look for a ``status`` attribute on ``item``, or failing that, a
 ``status`` item (as in ``item['status']``). If that
 XXX | components of expressions
 XXX "nothing" and "default"
-String Expressions - eg. ``string:hello ${user/name}``
+**String Expressions** - eg. ``string:hello ${user/name}``
 These expressions are simple string interpolations (though they can be just
 plain strings with no interpolation if you want. The expression in the
 ``${ ... }`` is just a path expression as above.
-Python Expressions - eg. ``python: 1+1``
+**Python Expressions** - eg. ``python: 1+1``
 These expressions give the full power of Python. All the "root level"
 variables are available, so ``python:item.status.checklist()`` would be
 equivalent to ``item/status/checklist``, assuming that ``checklist`` is
 a method.
 Information available to templates
 ----------------------------------
+Note: this is implemented by roundup.cgi.templating.RoundupPageTemplate
 The following variables are available to templates.
-.. taken from roundup.cgi.templating.RoundupPageTemplate docstring
+**context**
-*context*
 The current context. This is either None, a
 `hyperdb class wrapper`_ or a `hyperdb item wrapper`_
-*request*
+**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 item as an HTMLItem instance
 - *form*
 The current CGI form information as a mapping of form argument
 name to value
-*tracker*
+**tracker**
 The current tracker
-*db*
+**db**
 The current database, through which db.config may be reached.
-*nothing*
+**nothing**
 This is a special variable - if an expression evaluates to this, then the
 tag (in the case of a tal:replace), its contents (in the case of
 tal:content) or some attributes (in the case of tal:attributes) will not
 appear in the the output. So for example::
 would result in::
 <span>Hello, World!</span>
-*default*
+**default**
 Also a special variable - if an expression evaluates to this, then the
 existing HTML in the template will not be replaced or removed, it will
 remain. So::
 <span tal:replace="default">Hello, World!</span>
 would result in::
 <span>Hello, World!</span>
-*utils*
+**utils**
 This variable makes available some utility functions like batching.
 The context variable
 ~~~~~~~~~~~~~~~~~~~~
 <tr tal:define="keywords db/keyword/list"
 tal:repeat="start python:range(0, len(keywords), 4)">
 <td tal:define="batch python:utils.Batch(keywords, 4, start)"
 tal:repeat="keyword batch" tal:content="keyword/name">keyword here</td>
 </tr>
-<tr><td colspan="4" style="border-top: 1px solid gray">&nbsp;</td></tr>
 </table>
 ... which will produce a table with four columns containing the items of the
 "keyword" class (well, their "name" anyway).

Mercurial > p > roundup > code

comparison doc/customizing.txt @ 1125:3c1533be3822