Mercurial > p > roundup > code
comparison doc/customizing.txt @ 1073:cf30c6cdca02
More documentation.
Simplified the "klass", "item" and "*classname*" variables into "context.
| author | Richard Jones <richard@users.sourceforge.net> |
|---|---|
| date | Mon, 09 Sep 2002 00:45:06 +0000 |
| parents | af0abadfda3a |
| children | 954ad22eb7d9 |
comparison
equal
deleted
inserted
replaced
| 1072:88ded00fa0e0 | 1073:cf30c6cdca02 |
|---|---|
| 1 =================== | 1 =================== |
| 2 Customising Roundup | 2 Customising Roundup |
| 3 =================== | 3 =================== |
| 4 | 4 |
| 5 :Version: $Revision: 1.19 $ | 5 :Version: $Revision: 1.20 $ |
| 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:: |
| 588 scripts. In both cases, the scripts determine which instance is being accessed | 588 scripts. In both cases, the scripts determine which instance is being accessed |
| 589 (the first part of the URL path inside the scope of the CGI handler) and pass | 589 (the first part of the URL path inside the scope of the CGI handler) and pass |
| 590 control on to the instance interfaces.Client class which handles the rest of | 590 control on to the instance interfaces.Client class which handles the rest of |
| 591 the access through its main() method. This means that you can do pretty much | 591 the access through its main() method. This means that you can do pretty much |
| 592 anything you want as a web interface to your instance. | 592 anything you want as a web interface to your instance. |
| 593 | |
| 594 Figuring out what is displayed | |
| 595 :::::::::::::::::::::::::::::: | |
| 593 | 596 |
| 594 Most customisation of the web view can be done by modifying the templates in | 597 Most customisation of the web view can be done by modifying the templates in |
| 595 the instance **html** directory. There are several types of files in there: | 598 the instance **html** directory. There are several types of files in there: |
| 596 | 599 |
| 597 page | 600 page |
| 613 user.register | 616 user.register |
| 614 a special page just for the user class that renders the registration page | 617 a special page just for the user class that renders the registration page |
| 615 style.css | 618 style.css |
| 616 a static file that is served up as-is | 619 a static file that is served up as-is |
| 617 | 620 |
| 621 How requests are processed | |
| 622 :::::::::::::::::::::::::: | |
| 623 | |
| 618 The basic processing of a web request proceeds as follows: | 624 The basic processing of a web request proceeds as follows: |
| 619 | 625 |
| 620 1. figure out who we are, defaulting to the "anonymous" user | 626 1. figure out who we are, defaulting to the "anonymous" user |
| 621 2. figure out what the request is for - we call this the "context" | 627 2. figure out what the request is for - we call this the "context" |
| 622 3. handle any requested action (item edit, search, ...) | 628 3. handle any requested action (item edit, search, ...) |
| 633 here the action is cancelled, the request is rendered and an error | 639 here the action is cancelled, the request is rendered and an error |
| 634 message is displayed indicating that permission was not | 640 message is displayed indicating that permission was not |
| 635 granted for the action to take place | 641 granted for the action to take place |
| 636 - NotFound (raised wherever it needs to be) | 642 - NotFound (raised wherever it needs to be) |
| 637 this exception percolates up to the CGI interface that called the client | 643 this exception percolates up to the CGI interface that called the client |
| 644 | |
| 645 Determining web context | |
| 646 ::::::::::::::::::::::: | |
| 638 | 647 |
| 639 To determine the "context" of a request, we look at the URL and the special | 648 To determine the "context" of a request, we look at the URL and the special |
| 640 request variable ``:template``. The URL path after the instance identifier | 649 request variable ``:template``. The URL path after the instance identifier |
| 641 is examined. Typical URL paths look like: | 650 is examined. Typical URL paths look like: |
| 642 | 651 |
| 677 which defaults to: | 686 which defaults to: |
| 678 | 687 |
| 679 - only classname suplied: "index" | 688 - only classname suplied: "index" |
| 680 - full item designator supplied: "item" | 689 - full item designator supplied: "item" |
| 681 | 690 |
| 682 Actions are triggered by using a ``:action`` CGI variable, where the value is | 691 |
| 683 one of: | 692 Performing actions in web requests |
| 693 :::::::::::::::::::::::::::::::::: | |
| 694 | |
| 695 When a user requests a web page, they may optionally also request for an | |
| 696 action to take place. As described in `how requests are processed`_, the | |
| 697 action is performed before the requested page is generated. Actions are | |
| 698 triggered by using a ``:action`` CGI variable, where the value is one of: | |
| 684 | 699 |
| 685 login | 700 login |
| 686 Attempt to log a user in. | 701 Attempt to log a user in. |
| 687 logout | 702 logout |
| 688 Log the user out - make them "anonymous". | 703 Log the user out - make them "anonymous". |
| 908 These expressions give the full power of Python. All the "root level" | 923 These expressions give the full power of Python. All the "root level" |
| 909 variables are available, so ``python:item.status.checklist()`` would be | 924 variables are available, so ``python:item.status.checklist()`` would be |
| 910 equivalent to ``item/status/checklist``, assuming that ``checklist`` is | 925 equivalent to ``item/status/checklist``, assuming that ``checklist`` is |
| 911 a method. | 926 a method. |
| 912 | 927 |
| 928 Information available to templates | |
| 929 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 930 | |
| 931 The following variables are available to templates. | |
| 932 | |
| 933 .. taken from roundup.cgi.templating.RoundupPageTemplate docstring | |
| 934 | |
| 935 *context* | |
| 936 The current context. This is either None, a wrapper around a | |
| 937 hyperdb class (an HTMLClass) or a wrapper around a hyperdb item (an | |
| 938 HTMLItem). | |
| 939 *request* | |
| 940 Includes information about the current request, including: | |
| 941 - the url | |
| 942 - the current index information (``filterspec``, ``filter`` args, | |
| 943 ``properties``, etc) parsed out of the form. | |
| 944 - methods for easy filterspec link generation | |
| 945 - *user*, the current user node as an HTMLItem instance | |
| 946 - *form* | |
| 947 The current CGI form information as a mapping of form argument | |
| 948 name to value | |
| 949 *instance* | |
| 950 The current instance | |
| 951 *db* | |
| 952 The current database, through which db.config may be reached. | |
| 953 | |
| 954 The context variable | |
| 955 :::::::::::::::::: | |
| 956 | |
| 957 The *context* variable is one of three things based on the current context | |
| 958 (see `determining web context`_ for how we figure this out): | |
| 959 | |
| 960 1. if we're looking at a "home" page, then it's None | |
| 961 2. if we're looking at a specific hyperdb class, it's an HTMLClass instance | |
| 962 3. if we're looking at a specific hyperdb item, it's an HTMLItem instance | |
| 963 | |
| 964 If the context is not None, we can access the properties of the class or item. | |
| 965 The only real difference between cases 2 and 3 above are: | |
| 966 | |
| 967 1. the properties may have a real value behind them, and this will appear if | |
| 968 the property is displayed through ``context/property`` or | |
| 969 ``context/property/field``. | |
| 970 2. the context's "id" property will be a false value in the second case, but | |
| 971 a real, or true value in the third. Thus we can determine whether we're | |
| 972 looking at a real item from the hyperdb by testing "context/id". | |
| 973 | |
| 974 | |
| 975 The request variable | |
| 976 :::::::::::::::::::: | |
| 977 | |
| 978 The request variable is packed with information about the current request. | |
| 979 | |
| 980 .. taken from roundup.cgi.templating.HTMLRequest docstring | |
| 981 | |
| 982 =========== ================================================================ | |
| 983 Variable Holds | |
| 984 =========== ================================================================ | |
| 985 form the CGI form as a cgi.FieldStorage | |
| 986 env the CGI environment variables | |
| 987 url the current URL path for this request | |
| 988 base the base URL for this instance | |
| 989 user a HTMLUser instance for this user | |
| 990 classname the current classname (possibly None) | |
| 991 template the current template (suffix, also possibly None) | |
| 992 form the current CGI form variables in a FieldStorage | |
| 993 **Index page specific variables (indexing arguments)** | |
| 994 columns dictionary of the columns to display in an index page | |
| 995 show a convenience access to columns - request/show/colname will | |
| 996 be true if the columns should be displayed, false otherwise | |
| 997 sort index sort column (direction, column name) | |
| 998 group index grouping property (direction, column name) | |
| 999 filter properties to filter the index on | |
| 1000 filterspec values to filter the index on | |
| 1001 search_text text to perform a full-text search on for an index | |
| 1002 ----------- ---------------------------------------------------------------- | |
| 1003 | |
| 1004 | |
| 913 Displaying Properties | 1005 Displaying Properties |
| 914 ~~~~~~~~~~~~~~~~~~~~~ | 1006 ~~~~~~~~~~~~~~~~~~~~~ |
| 915 | 1007 |
| 916 Properties appear in the user interface in three contexts: in indices, in | 1008 Properties appear in the user interface in three contexts: in indices, in |
| 917 editors, and as search arguments. | 1009 editors, and as search arguments. |
| 929 | 1021 |
| 930 An index view specifier (URL fragment) looks like this (whitespace has been | 1022 An index view specifier (URL fragment) looks like this (whitespace has been |
| 931 added for clarity):: | 1023 added for clarity):: |
| 932 | 1024 |
| 933 /issue?status=unread,in-progress,resolved& | 1025 /issue?status=unread,in-progress,resolved& |
| 934 topic=security,ui& | 1026 topic=security,ui& |
| 935 :group=+priority& | 1027 :group=+priority& |
| 936 :sort=-activity& | 1028 :sort=-activity& |
| 937 :filters=status,topic& | 1029 :filters=status,topic& |
| 938 :columns=title,status,fixer | 1030 :columns=title,status,fixer |
| 939 | 1031 |
| 940 The index view is determined by two parts of the specifier: the layout part and | 1032 The index view is determined by two parts of the specifier: the layout part and |
| 941 the filter part. The layout part consists of the query parameters that begin | 1033 the filter part. The layout part consists of the query parameters that begin |
| 942 with colons, and it determines the way that the properties of selected nodes | 1034 with colons, and it determines the way that the properties of selected nodes |
| 943 are displayed. The filter part consists of all the other query parameters, and | 1035 are displayed. The filter part consists of all the other query parameters, and |
| 955 with "topic" values including both "security" and "ui" are displayed. The items | 1047 with "topic" values including both "security" and "ui" are displayed. The items |
| 956 are grouped by priority, arranged in ascending order; and within groups, sorted | 1048 are grouped by priority, arranged in ascending order; and within groups, sorted |
| 957 by activity, arranged in descending order. The filter section shows filters for | 1049 by activity, arranged in descending order. The filter section shows filters for |
| 958 the "status" and "topic" properties, and the table includes columns for the | 1050 the "status" and "topic" properties, and the table includes columns for the |
| 959 "title", "status", and "fixer" properties. | 1051 "title", "status", and "fixer" properties. |
| 960 | |
| 961 Associated with each item class is a default layout specifier. The layout | |
| 962 specifier in the above example is the default layout to be provided with the | |
| 963 default bug-tracker schema described above in section 4.4. | |
| 964 | 1052 |
| 965 Filtering of indexes | 1053 Filtering of indexes |
| 966 :::::::::::::::::::: | 1054 :::::::::::::::::::: |
| 967 | 1055 |
| 968 TODO | 1056 TODO |