![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
summary | shortlog | log | commit | commitdiff | tree
raw | patch | inline | side by side (parent: 9eb6bee)
raw | patch | inline | side by side (parent: 9eb6bee)
| author | richard <richard@57a73879-2fb5-44c3-a270-3262357dd7e2> | |
| Mon, 9 Sep 2002 07:55:24 +0000 (07:55 +0000) | ||
| committer | richard <richard@57a73879-2fb5-44c3-a270-3262357dd7e2> | |
| Mon, 9 Sep 2002 07:55:24 +0000 (07:55 +0000) |
git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@1102 57a73879-2fb5-44c3-a270-3262357dd7e2
| doc/customizing.txt | patch | blob | history |
diff --git a/doc/customizing.txt b/doc/customizing.txt
index 1f4d65e3b0dc4466d8b63b110282de2072302140..076e9ceb09611898b0c7f396978671df2533b2a3 100644 (file)
--- a/doc/customizing.txt
+++ b/doc/customizing.txt
Customising Roundup
===================
-:Version: $Revision: 1.21 $
+:Version: $Revision: 1.22 $
.. This document borrows from the ZopeBook section on ZPT. The original is at:
http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
MAIL_DEFAULT_CLASS = 'issue' # use "issue" class by default
#MAIL_DEFAULT_CLASS = '' # disable (or just comment the var out)
- # Define what index links are available in the header, and what their
- # labels are. Each key is used to look up one of the index specifications
- # below - so 'DEFAULT' will use 'DEFAULT_INDEX'.
- # Where the FILTERSPEC has 'assignedto' with a value of None, it will be
- # replaced by the id of the logged-in user.
- HEADER_INDEX_LINKS = ['DEFAULT', 'UNASSIGNED', 'USER']
-
- # list the classes that users are able to add nodes to
- HEADER_ADD_LINKS = ['issue']
-
- # list the classes that users can search
- HEADER_SEARCH_LINKS = ['issue']
-
- # list search filters per class
- SEARCH_FILTERS = ['ISSUE_FILTER', 'SUPPORT_FILTER']
-
- # Now the DEFAULT display specification. TODO: describe format
- DEFAULT_INDEX = {
- 'LABEL': 'All Issues',
- 'CLASS': 'issue',
- 'SORT': ['-activity'],
- 'GROUP': ['priority'],
- 'FILTER': ['status'],
- 'COLUMNS': ['id','activity','title','creator','assignedto'],
- 'FILTERSPEC': {
- 'status': ['-1', '1', '2', '3', '4', '5', '6', '7'],
- },
- }
-
- # The "unsassigned issues" index
- UNASSIGNED_INDEX = {
- 'LABEL': 'Unassigned Issues',
- 'CLASS': 'issue',
- 'SORT': ['-activity'],
- 'GROUP': ['priority'],
- 'FILTER': ['status', 'assignedto'],
- 'COLUMNS': ['id','activity','title','creator','status'],
- 'FILTERSPEC': {
- 'status': ['-1', '1', '2', '3', '4', '5', '6', '7'],
- 'assignedto': ['-1'],
- },
- }
-
- # The "my issues" index -- note that the user's id will replace the
- # 'CURRENT USER' value of the "assignedto" filterspec
- USER_INDEX = {
- 'LABEL': 'My Issues',
- 'CLASS': 'issue',
- 'SORT': ['-activity'],
- 'GROUP': ['priority'],
- 'FILTER': ['status', 'assignedto'],
- 'COLUMNS': ['id','activity','title','creator','status'],
- 'FILTERSPEC': {
- 'status': ['-1', '1', '2', '3', '4', '5', '6', '7'],
- 'assignedto': 'CURRENT USER',
- },
- }
-
- ISSUE_FILTER = {
- 'CLASS': 'issue',
- 'FILTER': ['status', 'priority', 'assignedto', 'creator']
- }
-
- SUPPORT_FILTER = {
- 'CLASS': 'issue',
- 'FILTER': ['status', 'priority', 'assignedto', 'creator']
- }
-
-
Instance Schema
---------------
("status"))
issue.setkey('title')
+XXX security definitions
+
Classes and Properties - creating a new information store
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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:
displays a search page for *classname* items
_generic.index
used to display a list of items where there is no *classname*.index available
+_generic.help
+ used to display a "class help" page where there is no *classname*.help
user.register
a special page just for the user class that renders the registration page
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:
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
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
How the templates work
~~~~~~~~~~~~~~~~~~~~~~
-Roundup's templates consist of two core technologies:
+Roundup's templates consist of special attributes on your template tags. These
+attributes form the Template Attribute Language, or TAL. The commands are:
-TAL - Template Attribute Language
- This is the syntax which is woven into the HTML using the ``tal:`` tag
- attributes. A TAL parser pulls out the TAL commands from the attributes
- runs them using some expression engine. TAL gives us the following commands:
- 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::
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')">
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::
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>
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::
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>
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::
Hello, world!
- Note that the commands on a given tag are evaulated in the order above, so
- *define* comes before *condition*, and so on.
+Note that the commands on a given tag are evaulated in the order above, so
+*define* comes before *condition*, and so on.
- Additionally, a tag is defined, tal:block, which is removed from output. Its
- content is not, but the tag itself is (so don't go using any tal:attributes
- commands on it). This is useful for making arbitrary blocks of HTML
- conditional or repeatable (very handy for repeating multiple table rows,
- which would othewise require an illegal tag placement to effect the repeat).
+Additionally, a tag is defined, tal:block, which is removed from output. Its
+content is not, but the tag itself is (so don't go using any tal:attributes
+commands on it). This is useful for making arbitrary blocks of HTML
+conditional or repeatable (very handy for repeating multiple table rows,
+which would othewise require an illegal tag placement to effect the repeat).
-TALES - TAL Expression Syntax
- The expression engine used in this case is TALES, which runs the expressions
- that form the tag attribute values. TALES expressions come in three
- flavours:
+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.
they are the default expression type, so it's not necessary.
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
The current instance
*db*
The current database, through which db.config may be reached.
+*nothing*
+ XXX a special variable
+*default*
+ XXX a special variable
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):
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)**
+=========== ================================================================
+
+**Index page specific variables (indexing arguments)**
+
+=========== ================================================================
+Variable Holds
+=========== ================================================================
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
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