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

comparison doc/customizing.txt @ 1083:40fc5f8cd55c

more doc

author	Richard Jones <richard@users.sourceforge.net>
date	Mon, 09 Sep 2002 07:55:24 +0000
parents	954ad22eb7d9
children	43ab730ee194

comparison

equal deleted inserted replaced

-:38b3a28b9e72
+:40fc5f8cd55c
 ===================
 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
 .. contents::
 # subjects. To disable, comment out the variable below or leave it blank.
 # Examples:
 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
 ---------------
 Note: if you modify the schema, you'll most likely need to edit the
 `web interface`_ HTML template files and `detectors`_ to reflect
 issue = IssueClass(db, "issue", assignedto=Link("user"),
 topic=Multilink("keyword"), priority=Link("priority"), status=Link
 ("status"))
 issue.setkey('title')
+XXX security definitions
 Classes and Properties - creating a new information store
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 In the instance above, we've defined 7 classes of information:
 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:
 page
 displays a list of *classname* items
 *classname*.search
 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:
 1. figure out who we are, defaulting to the "anonymous" user
 2. figure out what the request is for - we call this the "context"
 granted for the action to take place
 - 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:
 - only classname suplied:          "index"
 - full item designator supplied:   "item"
 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:
 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
+tal:define="variable expression; variable expression; ..."
-runs them using some expression engine. TAL gives us the following commands:
-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"
 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"
 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"
 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"
 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; ..."
 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"
 Remove this tag (but not its contents) if the expression is true. For
 example::
 <span tal:omit-tag="python:1">Hello, world!</span>
 would result in output of::
 Hello, world!
 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).
-TALES - TAL Expression Syntax
+The expressions you may use in the attibute values may be one of the following
-The expression engine used in this case is TALES, which runs the expressions
+three forms:
-that form the tag attribute values. TALES expressions come in three
-flavours:
+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
 left with is evaluated to get a string - methods are called, objects are
 stringified. Path expressions may have an optional ``path:`` prefix, though
 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}``
 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``
 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.
 name to value
 *instance*
 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):
 1. if we're looking at a "home" page, then it's None
 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)**
+=========== ================================================================
+**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
 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
 ~~~~~~~~~~~~~~~~~~~~~

Mercurial > p > roundup > code

comparison doc/customizing.txt @ 1083:40fc5f8cd55c