![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
summary | shortlog | log | commit | commitdiff | tree
raw | patch | inline | side by side (parent: ca37eab)
raw | patch | inline | side by side (parent: ca37eab)
| author | richard <richard@57a73879-2fb5-44c3-a270-3262357dd7e2> | |
| Wed, 25 Sep 2002 06:38:25 +0000 (06:38 +0000) | ||
| committer | richard <richard@57a73879-2fb5-44c3-a270-3262357dd7e2> | |
| Wed, 25 Sep 2002 06:38:25 +0000 (06:38 +0000) |
git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@1237 57a73879-2fb5-44c3-a270-3262357dd7e2
| doc/customizing.txt | patch | blob | history |
diff --git a/doc/customizing.txt b/doc/customizing.txt
index fe2d2a860b357b716f779a0617731829d173f29e..8f3c845d3e425f8c14e4305483d1f054a24e5b97 100644 (file)
--- a/doc/customizing.txt
+++ b/doc/customizing.txt
-===================
+icing
Customising Roundup
===================
-:Version: $Revision: 1.44 $
+:Version: $Revision: 1.45 $
.. This document borrows from the ZopeBook section on ZPT. The original is at:
http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
**page**
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. 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.
+ also appears inside this template. This template defines a macro called
+ "icing" which is used by almost all other templates as a coating 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**
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 basic tag
+Basic Templating Actions
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Roundup's templates consist of special attributes on your template tags.
+These attributes form the Template Attribute Language, or TAL. The basic tag
commands are:
**tal:define="variable expression; variable expression; ..."**
conditional or repeatable (very handy for repeating multiple table rows,
which would othewise require an illegal tag placement to effect the repeat).
+
+Templating Expressions
+~~~~~~~~~~~~~~~~~~~~~~
+
The expressions you may use in the attibute values may be one of the following
-three forms:
+forms:
**Path Expressions** - eg. ``item/status/checklist``
These are object attribute / item accesses. Roughly speaking, the path
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:
+Template Macros
+~~~~~~~~~~~~~~~
+
+Macros are used in Roundup to save us from repeating the same common page
+stuctures over and over. The most common (and probably only) macro you'll use
+is the "icing" macro defined in the "page" template.
+
+Macros are generated and used inside your templates using special attributes
+similar to the `basic templating actions`_. In this case though, the
+attributes belong to the Macro Expansion Template Attribute Language, or
+METAL. The macro commands are:
**metal:define-macro="macro name"**
Define that the tag and its contents are now a macro that may be inserted
defines a macro called "page" using the ``<html>`` 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
+ variable, eg. the most common ``templates/page/macros/icing`` to access the
"page" macro of the "page" template.
**metal:use-macro="path expression"**
will replace the current tag with the identified macro contents. For
example::
- <tal:block metal:use-macro="templates/page/macros/page">
+ <tal:block metal:use-macro="templates/page/macros/icing">
...
</tal:block>
**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::
+ ``templates/page/macros/icing`` macro defines a slot like so::
<title metal:define-slot="head_title">title goes here</title>
where the tag that fills the slot completely replaces the one defined as
the slot in the macro.
+Note that you may not mix METAL and TAL commands on the same tag, but TAL
+commands may be used freely inside METAL-using tags (so your *fill-slots*
+tags may have all manner of TAL inside them).
+
Information available to templates
----------------------------------
Next we need to add in the METAL macro stuff so we get the normal page
trappings::
- <tal:block metal:use-macro="templates/page/macros/page">
+ <tal:block metal:use-macro="templates/page/macros/icing">
<title metal:fill-slot="head_title">Category editing</title>
<td class="page-header-top" metal:fill-slot="body_title">
<h2>Category editing</h2>
So putting it all together, and closing the table and form we get::
<!-- category.item -->
- <tal:block metal:use-macro="templates/page/macros/page">
+ <tal:block metal:use-macro="templates/page/macros/icing">
<title metal:fill-slot="head_title">Category editing</title>
<td class="page-header-top" metal:fill-slot="body_title">
<h2>Category editing</h2>