Mercurial > p > roundup > code

comparison doc/customizing.txt @ 1214:3ed25834f33c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
more doc
author Richard Jones <richard@users.sourceforge.net>
date Wed, 25 Sep 2002 06:38:25 +0000
parents 3a5e05edcd87
children f83efa574177
comparison
equal deleted inserted replaced
1213:3a5e05edcd87 1214:3ed25834f33c
1 =================== 1 icing
2 Customising Roundup 2 Customising Roundup
3 =================== 3 ===================
4 4
5 :Version: $Revision: 1.44 $ 5 :Version: $Revision: 1.45 $
6 6
7 .. This document borrows from the ZopeBook section on ZPT. The original is at: 7 .. This document borrows from the ZopeBook section on ZPT. The original is at:
8 http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx 8 http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
9 9
10 .. contents:: 10 .. contents::
632 the tracker **html** directory. There are several types of files in there: 632 the tracker **html** directory. There are several types of files in there:
633 633
634 **page** 634 **page**
635 This template usually defines the overall look of your tracker. When you 635 This template usually defines the overall look of your tracker. When you
636 view an issue, it appears inside this template. When you view an index, it 636 view an issue, it appears inside this template. When you view an index, it
637 also appears inside this template. This template defines a macro which is 637 also appears inside this template. This template defines a macro called
638 used by almost all other templates as a wrapper for their content, using its 638 "icing" which is used by almost all other templates as a coating for their
639 "content" slot. It will also define the "head_title" and "body_title" slots 639 content, using its "content" slot. It will also define the "head_title"
640 to allow setting of the page title. 640 and "body_title" slots to allow setting of the page title.
641 **home** 641 **home**
642 the default page displayed when no other page is indicated by the user 642 the default page displayed when no other page is indicated by the user
643 **home.classlist** 643 **home.classlist**
644 a special version of the default page that lists the classes in the tracker 644 a special version of the default page that lists the classes in the tracker
645 **classname.item** 645 **classname.item**
668 668
669 669
670 How the templates work 670 How the templates work
671 ---------------------- 671 ----------------------
672 672
673 Roundup's templates consist of special attributes on your template tags. These 673 Basic Templating Actions
674 attributes form the Template Attribute Language, or TAL. The basic tag 674 ~~~~~~~~~~~~~~~~~~~~~~~~
675
676 Roundup's templates consist of special attributes on your template tags.
677 These attributes form the Template Attribute Language, or TAL. The basic tag
675 commands are: 678 commands are:
676 679
677 **tal:define="variable expression; variable expression; ..."** 680 **tal:define="variable expression; variable expression; ..."**
678 Define a new variable that is local to this tag and its contents. For 681 Define a new variable that is local to this tag and its contents. For
679 example:: 682 example::
758 content is not, but the tag itself is (so don't go using any tal:attributes 761 content is not, but the tag itself is (so don't go using any tal:attributes
759 commands on it). This is useful for making arbitrary blocks of HTML 762 commands on it). This is useful for making arbitrary blocks of HTML
760 conditional or repeatable (very handy for repeating multiple table rows, 763 conditional or repeatable (very handy for repeating multiple table rows,
761 which would othewise require an illegal tag placement to effect the repeat). 764 which would othewise require an illegal tag placement to effect the repeat).
762 765
766
767 Templating Expressions
768 ~~~~~~~~~~~~~~~~~~~~~~
769
763 The expressions you may use in the attibute values may be one of the following 770 The expressions you may use in the attibute values may be one of the following
764 three forms: 771 forms:
765 772
766 **Path Expressions** - eg. ``item/status/checklist`` 773 **Path Expressions** - eg. ``item/status/checklist``
767 These are object attribute / item accesses. Roughly speaking, the path 774 These are object attribute / item accesses. Roughly speaking, the path
768 ``item/status/checklist`` is broken into parts ``item``, ``status`` 775 ``item/status/checklist`` is broken into parts ``item``, ``status``
769 and ``checklist``. The ``item`` part is the root of the expression. 776 and ``checklist``. The ``item`` part is the root of the expression.
787 These expressions give the full power of Python. All the "root level" 794 These expressions give the full power of Python. All the "root level"
788 variables are available, so ``python:item.status.checklist()`` would be 795 variables are available, so ``python:item.status.checklist()`` would be
789 equivalent to ``item/status/checklist``, assuming that ``checklist`` is 796 equivalent to ``item/status/checklist``, assuming that ``checklist`` is
790 a method. 797 a method.
791 798
792 Tag macros, which are used in forming the basic structure of your pages, 799 Template Macros
793 are handled with the following commands: 800 ~~~~~~~~~~~~~~~
801
802 Macros are used in Roundup to save us from repeating the same common page
803 stuctures over and over. The most common (and probably only) macro you'll use
804 is the "icing" macro defined in the "page" template.
805
806 Macros are generated and used inside your templates using special attributes
807 similar to the `basic templating actions`_. In this case though, the
808 attributes belong to the Macro Expansion Template Attribute Language, or
809 METAL. The macro commands are:
794 810
795 **metal:define-macro="macro name"** 811 **metal:define-macro="macro name"**
796 Define that the tag and its contents are now a macro that may be inserted 812 Define that the tag and its contents are now a macro that may be inserted
797 into other templates using the *use-macro* command. For example:: 813 into other templates using the *use-macro* command. For example::
798 814
801 </html> 817 </html>
802 818
803 defines a macro called "page" using the ``<html>`` tag and its contents. 819 defines a macro called "page" using the ``<html>`` tag and its contents.
804 Once defined, macros are stored on the template they're defined on in the 820 Once defined, macros are stored on the template they're defined on in the
805 ``macros`` attribute. You can access them later on through the ``templates`` 821 ``macros`` attribute. You can access them later on through the ``templates``
806 variable, eg. the most common ``templates/page/macros/page`` to access the 822 variable, eg. the most common ``templates/page/macros/icing`` to access the
807 "page" macro of the "page" template. 823 "page" macro of the "page" template.
808 824
809 **metal:use-macro="path expression"** 825 **metal:use-macro="path expression"**
810 Use a macro, which is identified by the path expression (see above). This 826 Use a macro, which is identified by the path expression (see above). This
811 will replace the current tag with the identified macro contents. For 827 will replace the current tag with the identified macro contents. For
812 example:: 828 example::
813 829
814 <tal:block metal:use-macro="templates/page/macros/page"> 830 <tal:block metal:use-macro="templates/page/macros/icing">
815 ... 831 ...
816 </tal:block> 832 </tal:block>
817 833
818 will replace the tag and its contents with the "page" macro of the "page" 834 will replace the tag and its contents with the "page" macro of the "page"
819 template. 835 template.
820 836
821 **metal:define-slot="slot name"** and **metal:fill-slot="slot name"** 837 **metal:define-slot="slot name"** and **metal:fill-slot="slot name"**
822 To define *dynamic* parts of the macro, you define "slots" which may be 838 To define *dynamic* parts of the macro, you define "slots" which may be
823 filled when the macro is used with a *use-macro* command. For example, the 839 filled when the macro is used with a *use-macro* command. For example, the
824 ``templates/page/macros/page`` macro defines a slot like so:: 840 ``templates/page/macros/icing`` macro defines a slot like so::
825 841
826 <title metal:define-slot="head_title">title goes here</title> 842 <title metal:define-slot="head_title">title goes here</title>
827 843
828 In your *use-macro* command, you may now use a *fill-slot* command like 844 In your *use-macro* command, you may now use a *fill-slot* command like
829 this:: 845 this::
830 846
831 <title metal:fill-slot="head_title">My Title</title> 847 <title metal:fill-slot="head_title">My Title</title>
832 848
833 where the tag that fills the slot completely replaces the one defined as 849 where the tag that fills the slot completely replaces the one defined as
834 the slot in the macro. 850 the slot in the macro.
851
852 Note that you may not mix METAL and TAL commands on the same tag, but TAL
853 commands may be used freely inside METAL-using tags (so your *fill-slots*
854 tags may have all manner of TAL inside them).
835 855
836 856
837 Information available to templates 857 Information available to templates
838 ---------------------------------- 858 ----------------------------------
839 859
1627 <!-- category.item --> 1647 <!-- category.item -->
1628 1648
1629 Next we need to add in the METAL macro stuff so we get the normal page 1649 Next we need to add in the METAL macro stuff so we get the normal page
1630 trappings:: 1650 trappings::
1631 1651
1632 <tal:block metal:use-macro="templates/page/macros/page"> 1652 <tal:block metal:use-macro="templates/page/macros/icing">
1633 <title metal:fill-slot="head_title">Category editing</title> 1653 <title metal:fill-slot="head_title">Category editing</title>
1634 <td class="page-header-top" metal:fill-slot="body_title"> 1654 <td class="page-header-top" metal:fill-slot="body_title">
1635 <h2>Category editing</h2> 1655 <h2>Category editing</h2>
1636 </td> 1656 </td>
1637 <td class="content" metal:fill-slot="content"> 1657 <td class="content" metal:fill-slot="content">
1684 </tal:block> 1704 </tal:block>
1685 1705
1686 So putting it all together, and closing the table and form we get:: 1706 So putting it all together, and closing the table and form we get::
1687 1707
1688 <!-- category.item --> 1708 <!-- category.item -->
1689 <tal:block metal:use-macro="templates/page/macros/page"> 1709 <tal:block metal:use-macro="templates/page/macros/icing">
1690 <title metal:fill-slot="head_title">Category editing</title> 1710 <title metal:fill-slot="head_title">Category editing</title>
1691 <td class="page-header-top" metal:fill-slot="body_title"> 1711 <td class="page-header-top" metal:fill-slot="body_title">
1692 <h2>Category editing</h2> 1712 <h2>Category editing</h2>
1693 </td> 1713 </td>
1694 <td class="content" metal:fill-slot="content"> 1714 <td class="content" metal:fill-slot="content">
Roundup Issue Tracker: http://roundup-tracker.org/