From ca37eabef95e76e0815301fdcd5f6334ca4f8101 Mon Sep 17 00:00:00 2001 From: richard Date: Wed, 25 Sep 2002 06:20:09 +0000 Subject: [PATCH] added doc for METAL git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@1235 57a73879-2fb5-44c3-a270-3262357dd7e2 --- TODO.txt | 3 + doc/customizing.txt | 169 +++++++++++++++++++++++++++++--------- roundup/cgi/templating.py | 6 +- 3 files changed, 139 insertions(+), 39 deletions(-) diff --git a/TODO.txt b/TODO.txt index fb10104..304a7c9 100644 --- a/TODO.txt +++ b/TODO.txt @@ -28,6 +28,8 @@ pending mailgw Allow multiple email addresses at one gw with different roundup: "|roundup-mailgw /instances/dev" vmbugs: "|roundup-mailgw /instances/dev component=voicemail" +pending mailgw Identification of users should have a configurable degree of + strictness (ie. turn off username==address matching) pending project switch to a Roundup instance for Roundup bug/feature tracking pending security an LDAP user database implementation pending security authenticate over a secure connection @@ -48,6 +50,7 @@ pending web search "refinement" - pre-fill the search page with the pending web UNIX init.d script for roundup-server pending web allow multilink selections to select a "none" element to allow people with broken browsers to select nothing? +pending web automagically link designators bug mailgw some f*ked mailers QUOTE their Re; "Re: "[issue1] bla blah"" bug docs need to mention somewhere how sorting works diff --git a/doc/customizing.txt b/doc/customizing.txt index 62f03f6..fe2d2a8 100644 --- a/doc/customizing.txt +++ b/doc/customizing.txt @@ -2,7 +2,7 @@ Customising Roundup =================== -:Version: $Revision: 1.43 $ +:Version: $Revision: 1.44 $ .. This document borrows from the ZopeBook section on ZPT. The original is at: http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx @@ -473,7 +473,7 @@ 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" 3. handle any requested action (item edit, search, ...) -4. render a template, resulting in HTML output +4. render the template requested by the context, resulting in HTML output In some situations, exceptions occur: @@ -632,11 +632,12 @@ 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** - This template defines the overall look of your tracker. When you + This template usually 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. + also appears inside this template. This template defines a macro which is + used by almost all other templates as a wrapper for their content, using its + "content" slot. It will also define the "head_title" and "body_title" slots + to allow setting of the page title. **home** the default page displayed when no other page is indicated by the user **home.classlist** @@ -670,8 +671,8 @@ 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: - +attributes form the Template Attribute Language, or TAL. The basic tag +commands are: **tal:define="variable expression; variable expression; ..."** Define a new variable that is local to this tag and its contents. For @@ -788,6 +789,51 @@ three forms: equivalent to ``item/status/checklist``, assuming that ``checklist`` is a method. +Tag macros, which are used in forming the basic structure of your pages, +are handled with the following commands: + +**metal:define-macro="macro name"** + Define that the tag and its contents are now a macro that may be inserted + into other templates using the *use-macro* command. For example:: + + + ... + + + defines a macro called "page" using the ```` tag and its contents. + Once defined, macros are stored on the template they're defined on in the + ``macros`` attribute. You can access them later on through the ``templates`` + variable, eg. the most common ``templates/page/macros/page`` to access the + "page" macro of the "page" template. + +**metal:use-macro="path expression"** + Use a macro, which is identified by the path expression (see above). This + will replace the current tag with the identified macro contents. For + example:: + + + ... + + + will replace the tag and its contents with the "page" macro of the "page" + template. + +**metal:define-slot="slot name"** and **metal:fill-slot="slot name"** + To define *dynamic* parts of the macro, you define "slots" which may be + filled when the macro is used with a *use-macro* command. For example, the + ``templates/page/macros/page`` macro defines a slot like so:: + + title goes here + + In your *use-macro* command, you may now use a *fill-slot* command like + this:: + + My Title + + where the tag that fills the slot completely replaces the one defined as + the slot in the macro. + + Information available to templates ---------------------------------- @@ -812,6 +858,11 @@ The following variables are available to templates. The current tracker **db** The current database, through which db.config may be reached. +**templates** + Access to all the tracker templates by name. Used mainly in *use-macro* + commands. +**utils** + This variable makes available some utility functions like batching. **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 @@ -835,9 +886,6 @@ The following variables are available to templates. Hello, World! -**utils** - This variable makes available some utility functions like batching. - The context variable ~~~~~~~~~~~~~~~~~~~~ @@ -1078,9 +1126,34 @@ want access to the "user" class, for example, you would use:: The access results in a `hyperdb class wrapper`_. +The templates variable +~~~~~~~~~~~~~~~~~~~~~~ + +Note: this is implemented by the roundup.cgi.templating.Templates class. + +This variable doesn't have any useful methods defined. It supports being +used in expressions to access the templates, and subsequently the template +macros. You may access the templates using the following path expression:: -The util variable -~~~~~~~~~~~~~~~~~ + templates/name + +or the python expression:: + + templates[name] + +where "name" is the name of the template you wish to access. The template you +get access to has one useful attribute, "macros". To access a specific macro +(called "macro_name"), use the path expression:: + + templates/name/macros/macro_name + +or the python expression:: + + templates[name].macros[macro_name] + + +The utils variable +~~~~~~~~~~~~~~~~~~ Note: this is implemented by the roundup.cgi.templating.TemplatingUtils class. @@ -1546,13 +1619,22 @@ The link was for the item template for the category object. This translates into the system looking for a file called ``category.item`` in the ``html`` tracker directory. This is the file that we are going to write now. -First we add an id tag in a comment which doesn't affect the outcome -of the code at all but is essential for managing the changes to this -file. It is useful for debugging however, if you load a page in a +First we add an info tag in a comment which doesn't affect the outcome +of the code at all but is useful for debugging. If you load a page in a browser and look at the page source, you can see which sections come from which files by looking for these comments:: - + + +Next we need to add in the METAL macro stuff so we get the normal page +trappings:: + + + Category editing + +

Category editing

+ + Next we need to setup up a standard HTML form, which is the whole purpose of this file. We link to some handy javascript which sends the form @@ -1587,7 +1669,7 @@ will be created with that name:: name -Finally a submit button so that the user can submit the new category:: +Then a submit button so that the user can submit the new category::   @@ -1596,31 +1678,43 @@ Finally a submit button so that the user can submit the new category:: -So putting it all together, and closing the table and form we get:: +Finally we finish off the tags we used at the start to do the METAL stuff:: - + + -
+So putting it all together, and closing the table and form we get:: - + + + Category editing + +

Category editing

+ + + - - + - - - - +
Category
Namename
+ - - - - -
Category
  - submit button will go here -
- + + Name + name + + + +   + + submit button will go here + + + + + +
This is quite a lot to just ask the user one simple question, but there is a lot of setup for basically one line (the form line) to do @@ -1898,7 +1992,6 @@ Setting up a "wizard" (or "druid") for controlled adding of issues The next page has the usual issue entry information, with the addition of the following form fragments:: -
diff --git a/roundup/cgi/templating.py b/roundup/cgi/templating.py index a9757fa..63c23b4 100644 --- a/roundup/cgi/templating.py +++ b/roundup/cgi/templating.py @@ -206,7 +206,11 @@ def lookupIds(db, prop, ids, num_re=re.compile('-?\d+')): if num_re.match(entry): l.append(entry) else: - l.append(cl.lookup(entry)) + try: + l.append(cl.lookup(entry)) + except KeyError: + # ignore invalid keys + pass return l class HTMLPermissions: -- 2.30.2