From: richard Date: Sat, 7 Sep 2002 02:41:11 +0000 (+0000) Subject: *** empty log message *** X-Git-Url: https://git.tokkee.org/?a=commitdiff_plain;h=9dbeaf66e8f73f440e4ccd58f2fdee47fa023d27;p=roundup.git *** empty log message *** git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@1089 57a73879-2fb5-44c3-a270-3262357dd7e2 --- diff --git a/doc/customizing.txt b/doc/customizing.txt index cf75193..7a1279c 100644 --- a/doc/customizing.txt +++ b/doc/customizing.txt @@ -2,7 +2,10 @@ Customising Roundup =================== -:Version: $Revision: 1.18 $ +:Version: $Revision: 1.19 $ + +.. This document borrows from the ZopeBook section on ZPT. The original is at: + http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx .. contents:: @@ -620,6 +623,7 @@ The basic processing of a web request proceeds as follows: 4. render a template, resulting in HTML output In some situations, exceptions occur: + - HTTP Redirect (generally raised by an action) - SendFile (generally raised by determine_context) here we serve up a FileClass "content" property @@ -721,17 +725,20 @@ search Also handle the ":queryname" variable and save off the query to the user's query list. -Each of the actions is implemented by a corresponding *name*Action method on +Each of the actions is implemented by a corresponding *actionAction* (where +"action" is the name of the action) method on the roundup.cgi.Client class, which also happens to be in your instance as interfaces.Client. So if you need to define new actions, you may add them there (see `definining new web actions`_). -Each action also has a corresponding *name*Permission method which determines +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 - XXX TODO + Determine whether the user has permission to log in. + Base behaviour is to check the user has "Web Access". logout No permission checks are made. register @@ -777,21 +784,95 @@ footer with your own code. This allows you to use a sidebar navigation scheme, for example. -PageTemplates in a Nutshell -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +How the templates work +~~~~~~~~~~~~~~~~~~~~~~ -PageTemplates consist of two core technologies: +Roundup's templates consist of two core technologies: 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: + 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:: + + + + + + In the example, the variable "title" is defined as being the result of the + expression "request/description". The tal:content command inside the + tag may then use the "title" variable. + + tal:condition="expression" + Only keep this tag and its contents if the expression is true. For example:: + +

+ Display some issue information. +

+ + In the example, the

tag and its contents are only displayed if the + 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:: + + + + + + + + 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:: + + + + The example would replace the 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:: + + user's name appears here - tal:define - tal:replace - tal:content - tal:repeat - tal:attributes + The example would replace the contents of the tag with the user's + realname. If the user's realname was "Bruce" then the resultant output + would be "Bruce". + + tal:attributes="attribute expression; attribute expression; ..." + Set attributes on this tag to the results of expressions. For example:: + + My Details + + In the example, the "href" attribute of the 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:: + + Hello, world! + + 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 @@ -815,6 +896,9 @@ TALES - TAL Expression Syntax 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