Mercurial > p > roundup > code

comparison doc/customizing.txt @ 1070:af0abadfda3a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
*** empty log message ***
author Richard Jones <richard@users.sourceforge.net>
date Sat, 07 Sep 2002 02:41:11 +0000
parents a55ef5a98fd3
children cf30c6cdca02
comparison
equal deleted inserted replaced
1069:b3a2b6d2a142 1070:af0abadfda3a
1 =================== 1 ===================
2 Customising Roundup 2 Customising Roundup
3 =================== 3 ===================
4 4
5 :Version: $Revision: 1.18 $ 5 :Version: $Revision: 1.19 $
6
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
6 9
7 .. contents:: 10 .. contents::
8 11
9 12
10 What You Can Do 13 What You Can Do
618 2. figure out what the request is for - we call this the "context" 621 2. figure out what the request is for - we call this the "context"
619 3. handle any requested action (item edit, search, ...) 622 3. handle any requested action (item edit, search, ...)
620 4. render a template, resulting in HTML output 623 4. render a template, resulting in HTML output
621 624
622 In some situations, exceptions occur: 625 In some situations, exceptions occur:
626
623 - HTTP Redirect (generally raised by an action) 627 - HTTP Redirect (generally raised by an action)
624 - SendFile (generally raised by determine_context) 628 - SendFile (generally raised by determine_context)
625 here we serve up a FileClass "content" property 629 here we serve up a FileClass "content" property
626 - SendStaticFile (generally raised by determine_context) 630 - SendStaticFile (generally raised by determine_context)
627 here we serve up a file from the tracker "html" directory 631 here we serve up a file from the tracker "html" directory
719 "dontcare" then add them to :filter. 723 "dontcare" then add them to :filter.
720 724
721 Also handle the ":queryname" variable and save off the query to 725 Also handle the ":queryname" variable and save off the query to
722 the user's query list. 726 the user's query list.
723 727
724 Each of the actions is implemented by a corresponding *name*Action method on 728 Each of the actions is implemented by a corresponding *actionAction* (where
729 "action" is the name of the action) method on
725 the roundup.cgi.Client class, which also happens to be in your instance as 730 the roundup.cgi.Client class, which also happens to be in your instance as
726 interfaces.Client. So if you need to define new actions, you may add them 731 interfaces.Client. So if you need to define new actions, you may add them
727 there (see `definining new web actions`_). 732 there (see `definining new web actions`_).
728 733
729 Each action also has a corresponding *name*Permission method which determines 734 Each action also has a corresponding *actionPermission* (where
735 "action" is the name of the action) method which determines
730 whether the action is permissible given the current user. The base permission 736 whether the action is permissible given the current user. The base permission
731 checks are: 737 checks are:
732 738
733 login 739 login
734 XXX TODO 740 Determine whether the user has permission to log in.
741 Base behaviour is to check the user has "Web Access".
735 logout 742 logout
736 No permission checks are made. 743 No permission checks are made.
737 register 744 register
738 Determine whether the user has permission to register 745 Determine whether the user has permission to register
739 Base behaviour is to check the user has "Web Registration". 746 Base behaviour is to check the user has "Web Registration".
775 instance's interfaces module. This means you can override the header and 782 instance's interfaces module. This means you can override the header and
776 footer with your own code. This allows you to use a sidebar navigation scheme, 783 footer with your own code. This allows you to use a sidebar navigation scheme,
777 for example. 784 for example.
778 785
779 786
780 PageTemplates in a Nutshell 787 How the templates work
781 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 788 ~~~~~~~~~~~~~~~~~~~~~~
782 789
783 PageTemplates consist of two core technologies: 790 Roundup's templates consist of two core technologies:
784 791
785 TAL - Template Attribute Language 792 TAL - Template Attribute Language
786 This is the syntax which is woven into the HTML using the ``tal:`` tag 793 This is the syntax which is woven into the HTML using the ``tal:`` tag
787 attributes. A TAL parser pulls out the TAL commands from the attributes 794 attributes. A TAL parser pulls out the TAL commands from the attributes
788 runs them using some expression engine. TAL gives: 795 runs them using some expression engine. TAL gives us the following commands:
789 796
790 tal:define 797 tal:define="variable expression; variable expression; ..."
791 tal:replace 798 Define a new variable that is local to this tag and its contents. For
792 tal:content 799 example::
793 tal:repeat 800
794 tal:attributes 801 <html tal:define="title request/description">
802 <head><title tal:content="title"></title></head>
803 </html>
804
805 In the example, the variable "title" is defined as being the result of the
806 expression "request/description". The tal:content command inside the <html>
807 tag may then use the "title" variable.
808
809 tal:condition="expression"
810 Only keep this tag and its contents if the expression is true. For example::
811
812 <p tal:condition="python:request.user.hasPermission('View', 'issue')">
813 Display some issue information.
814 </p>
815
816 In the example, the <p> tag and its contents are only displayed if the
817 user has the View permission for issues. We consider the number zero, a
818 blank string, an empty list, and the built-in variable nothing to be false
819 values. Nearly every other value is true, including non-zero numbers, and
820 strings with anything in them (even spaces!).
821
822 tal:repeat="variable expression"
823 Repeat this tag and its contents for each element of the sequence that the
824 expression returns, defining a new local variable and a special "repeat"
825 variable for each element. For example::
826
827 <tr tal:repeat="u user/list">
828 <td tal:content="u/id"></td>
829 <td tal:content="u/username"></td>
830 <td tal:content="u/realname"></td>
831 </tr>
832
833 The example would iterate over the sequence of users returned by
834 "user/list" and define the local variable "u" for each entry.
835
836 tal:replace="expression"
837 Replace this tag with the result of the expression. For example::
838
839 <span tal:replace="request/user/realname"></span>
840
841 The example would replace the <span> tag and its contents with the user's
842 realname. If the user's realname was "Bruce" then the resultant output
843 would be "Bruce".
844
845 tal:content="expression"
846 Replace the contents of this tag with the result of the expression. For
847 example::
848
849 <span tal:content="request/user/realname">user's name appears here</span>
850
851 The example would replace the contents of the <span> tag with the user's
852 realname. If the user's realname was "Bruce" then the resultant output
853 would be "<span>Bruce</span>".
854
855 tal:attributes="attribute expression; attribute expression; ..."
856 Set attributes on this tag to the results of expressions. For example::
857
858 <a tal:attributes="href string:user${request/user/id}">My Details</a>
859
860 In the example, the "href" attribute of the <a> tag is set to the value of
861 the "string:user${request/user/id}" expression, which will be something
862 like "user123".
863
864 tal:omit-tag="expression"
865 Remove this tag (but not its contents) if the expression is true. For
866 example::
867
868 <span tal:omit-tag="python:1">Hello, world!</span>
869
870 would result in output of::
871
872 Hello, world!
873
874 Note that the commands on a given tag are evaulated in the order above, so
875 *define* comes before *condition*, and so on.
795 876
796 Additionally, a tag is defined, tal:block, which is removed from output. Its 877 Additionally, a tag is defined, tal:block, which is removed from output. Its
797 content is not, but the tag itself is (so don't go using any tal:attributes 878 content is not, but the tag itself is (so don't go using any tal:attributes
798 commands on it). This is useful for making arbitrary blocks of HTML 879 commands on it). This is useful for making arbitrary blocks of HTML
799 conditional or repeatable (very handy for repeating multiple table rows, 880 conditional or repeatable (very handy for repeating multiple table rows,
812 ``status`` item (as in ``item['status']``). If that 893 ``status`` item (as in ``item['status']``). If that
813 fails, the path expression fails. When we get to the end, the object we're 894 fails, the path expression fails. When we get to the end, the object we're
814 left with is evaluated to get a string - methods are called, objects are 895 left with is evaluated to get a string - methods are called, objects are
815 stringified. Path expressions may have an optional ``path:`` prefix, though 896 stringified. Path expressions may have an optional ``path:`` prefix, though
816 they are the default expression type, so it's not necessary. 897 they are the default expression type, so it's not necessary.
898
899 XXX | components of expressions
900 XXX "nothing" and "default"
817 901
818 String Expressions - eg. ``string:hello ${user/name}`` 902 String Expressions - eg. ``string:hello ${user/name}``
819 These expressions are simple string interpolations (though they can be just 903 These expressions are simple string interpolations (though they can be just
820 plain strings with no interpolation if you want. The expression in the 904 plain strings with no interpolation if you want. The expression in the
821 ``${ ... }`` is just a path expression as above. 905 ``${ ... }`` is just a path expression as above.
Roundup Issue Tracker: http://roundup-tracker.org/