annotate doc/customizing.txt @ 5161:12190efa30d4

I realized that the __came_from and __redirect_to url parameters I added to handle issues with the LoginAction and NewItemAction could be used for XSS or other purposes. So I check them using a new clean_url(url) function. This tries to validate that the url is under the tracker's base url and that the components of the url are properly url encoded. If it thinks something is wrong with the url, it will raise a ValueError. I decided to not attempt to fix the url's if there is an issue, better to bring it to the tracker admin's attention. Changed the code paths in NewItemAction and LoginAction that deal with the form parameters to use the clean_url function on the form input first.
author John Rouillard <rouilj@ieee.org>
date Sat, 23 Jul 2016 14:00:49 -0400
parents 63294ed25e84
children e1e40674a0bc
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
4033
bca7c59ac400 Enhance documentation generation.
Stefan Seefeld <stefan@seefeld.name>
parents: 3968
diff changeset
1 :tocdepth: 2
bca7c59ac400 Enhance documentation generation.
Stefan Seefeld <stefan@seefeld.name>
parents: 3968
diff changeset
2
1215
f83efa574177 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1214
diff changeset
3 ===================
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
4 Customising Roundup
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
5 ===================
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
6
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
7 .. This document borrows from the ZopeBook section on ZPT. The original is at:
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
8 http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 684
diff changeset
9
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 684
diff changeset
10 .. contents::
4888
b07014d6a7aa docs: Fix table of contents on customizing page
anatoly techtonik <techtonik@gmail.com>
parents: 4880
diff changeset
11 :depth: 2
b07014d6a7aa docs: Fix table of contents on customizing page
anatoly techtonik <techtonik@gmail.com>
parents: 4880
diff changeset
12 :local:
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 684
diff changeset
13
898
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
14 What You Can Do
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
15 ===============
898
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
16
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
17 Before you get too far, it's probably worth having a quick read of the Roundup
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
18 `design documentation`_.
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
19
1850
6e80f8f760a4 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1832
diff changeset
20 Customisation of Roundup can take one of six forms:
898
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
21
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
22 1. `tracker configuration`_ changes
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1083
diff changeset
23 2. database, or `tracker schema`_ changes
898
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
24 3. "definition" class `database content`_ changes
4921
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
25 4. behavioural changes, through detectors_ and extensions_
2003
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents: 1998
diff changeset
26 5. `security / access controls`_
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
27 6. change the `web interface`_
898
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
28
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
29 The third case is special because it takes two distinctly different forms
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1083
diff changeset
30 depending upon whether the tracker has been initialised or not. The other two
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1083
diff changeset
31 may be done at any time, before or after tracker initialisation. Yes, this
898
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
32 includes adding or removing properties from classes.
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
33
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
34
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1083
diff changeset
35 Trackers in a Nutshell
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
36 ======================
898
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
37
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1083
diff changeset
38 Trackers have the following structure:
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
39
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
40 =================== ========================================================
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
41 Tracker File Description
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
42 =================== ========================================================
2921
ad4fb8a14a97 more doc updates, not so many TODOs any more
Richard Jones <richard@users.sourceforge.net>
parents: 2915
diff changeset
43 config.ini Holds the basic `tracker configuration`_
ad4fb8a14a97 more doc updates, not so many TODOs any more
Richard Jones <richard@users.sourceforge.net>
parents: 2915
diff changeset
44 schema.py Holds the `tracker schema`_
ad4fb8a14a97 more doc updates, not so many TODOs any more
Richard Jones <richard@users.sourceforge.net>
parents: 2915
diff changeset
45 initial_data.py Holds any data to be entered into the database when the
ad4fb8a14a97 more doc updates, not so many TODOs any more
Richard Jones <richard@users.sourceforge.net>
parents: 2915
diff changeset
46 tracker is initialised.
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
47 db/ Holds the tracker's database
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
48 db/files/ Holds the tracker's upload files and messages
2921
ad4fb8a14a97 more doc updates, not so many TODOs any more
Richard Jones <richard@users.sourceforge.net>
parents: 2915
diff changeset
49 db/backend_name Names the database back-end for the tracker
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
50 detectors/ Auditors and reactors for this tracker
4921
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
51 extensions/ Additional actions and `templating utilities`_
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
52 html/ Web interface templates, images and style sheets
3772
13e8825da493 Documentation update for common lib directory
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3769
diff changeset
53 lib/ optional common imports for detectors and extensions
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
54 =================== ========================================================
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
55
3117
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
56
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1083
diff changeset
57 Tracker Configuration
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
58 =====================
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
59
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
60 The ``config.ini`` located in your tracker home contains the basic
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
61 configuration for the web and e-mail components of roundup's interfaces.
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
62
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
63 Changes to the data captured by your tracker is controlled by the `tracker
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
64 schema`_. Some configuration is also performed using permissions - see the
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
65 `security / access controls`_ section. For example, to allow users to
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
66 automatically register through the email interface, you must grant the
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
67 "Anonymous" Role the "Email Access" Permission.
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
68
2911
ca6206cc74d9 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2910
diff changeset
69 The following is taken from the `Python Library Reference`__ (May 20, 2004)
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
70 section "ConfigParser -- Configuration file parser":
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
71
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
72 The configuration file consists of sections, led by a "[section]" header
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
73 and followed by "name = value" entries, with line continuations on a
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
74 newline with leading whitespace. Note that leading whitespace is removed
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
75 from values. The optional values can contain format strings which
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
76 refer to other values in the same section. Lines beginning with "#" or ";"
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
77 are ignored and may be used to provide comments.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
78
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
79 For example::
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
80
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
81 [My Section]
2911
ca6206cc74d9 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2910
diff changeset
82 foodir = %(dir)s/whatever
ca6206cc74d9 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2910
diff changeset
83 dir = frob
ca6206cc74d9 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2910
diff changeset
84
ca6206cc74d9 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2910
diff changeset
85 would resolve the "%(dir)s" to the value of "dir" ("frob" in this case)
ca6206cc74d9 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2910
diff changeset
86 resulting in "foodir" being "frob/whatever".
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
87
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
88 __ http://docs.python.org/lib/module-ConfigParser.html
1245
d8c98af869ff merge from maint-0-5
Richard Jones <richard@users.sourceforge.net>
parents: 1244
diff changeset
89
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
90 Section **main**
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
91 database -- ``db``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
92 Database directory path. The path may be either absolute or relative
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
93 to the directory containig this config file.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
94
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
95 templates -- ``html``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
96 Path to the HTML templates directory. The path may be either absolute
5154
f608eeecf638 issue2550891: Allow subdir in template value. Anthony (antmail)
John Rouillard <rouilj@ieee.org>
parents: 5135
diff changeset
97 or relative to the directory containing this config file.
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
98
3922
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
99 static_files -- default *blank*
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
100 Path to directory holding additional static files available via Web
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
101 UI. This directory may contain sitewide images, CSS stylesheets etc.
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
102 and is searched for these files prior to the TEMPLATES directory
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
103 specified above. If this option is not set, all static files are
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
104 taken from the TEMPLATES directory The path may be either absolute or
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
105 relative to the directory containig this config file.
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
106
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
107 admin_email -- ``roundup-admin``
2914
c75a19894d3e alex's feedback
Richard Jones <richard@users.sourceforge.net>
parents: 2911
diff changeset
108 Email address that roundup will complain to if it runs into trouble. If
c75a19894d3e alex's feedback
Richard Jones <richard@users.sourceforge.net>
parents: 2911
diff changeset
109 the email address doesn't contain an ``@`` part, the MAIL_DOMAIN defined
c75a19894d3e alex's feedback
Richard Jones <richard@users.sourceforge.net>
parents: 2911
diff changeset
110 below is used.
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
111
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
112 dispatcher_email -- ``roundup-admin``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
113 The 'dispatcher' is a role that can get notified of new items to the
2914
c75a19894d3e alex's feedback
Richard Jones <richard@users.sourceforge.net>
parents: 2911
diff changeset
114 database. It is used by the ERROR_MESSAGES_TO config setting. If the
c75a19894d3e alex's feedback
Richard Jones <richard@users.sourceforge.net>
parents: 2911
diff changeset
115 email address doesn't contain an ``@`` part, the MAIL_DOMAIN defined
c75a19894d3e alex's feedback
Richard Jones <richard@users.sourceforge.net>
parents: 2911
diff changeset
116 below is used.
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
117
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
118 email_from_tag -- default *blank*
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
119 Additional text to include in the "name" part of the From: address used
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
120 in nosy messages. If the sending user is "Foo Bar", the From: line
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
121 is usually: ``"Foo Bar" <issue_tracker@tracker.example>``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
122 the EMAIL_FROM_TAG goes inside the "Foo Bar" quotes like so:
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
123 ``"Foo Bar EMAIL_FROM_TAG" <issue_tracker@tracker.example>``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
124
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
125 new_web_user_roles -- ``User``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
126 Roles that a user gets when they register with Web User Interface.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
127 This is a comma-separated list of role names (e.g. ``Admin,User``).
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
128
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
129 new_email_user_roles -- ``User``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
130 Roles that a user gets when they register with Email Gateway.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
131 This is a comma-separated string of role names (e.g. ``Admin,User``).
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
132
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
133 error_messages_to -- ``user``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
134 Send error message emails to the ``dispatcher``, ``user``, or ``both``?
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
135 The dispatcher is configured using the DISPATCHER_EMAIL setting.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
136 Allowed values: ``dispatcher``, ``user``, or ``both``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
137
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
138 html_version -- ``html4``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
139 HTML version to generate. The templates are ``html4`` by default.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
140 If you wish to make them xhtml, then you'll need to change this
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
141 var to ``xhtml`` too so all auto-generated HTML is compliant.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
142 Allowed values: ``html4``, ``xhtml``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
143
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
144 timezone -- ``0``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
145 Numeric timezone offset used when users do not choose their own
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
146 in their settings.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
147
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
148 instant_registration -- ``yes``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
149 Register new users instantly, or require confirmation via
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
150 email?
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
151 Allowed values: ``yes``, ``no``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
152
3544
5cd1c83dea50 Features and fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 3535
diff changeset
153 email_registration_confirmation -- ``yes``
5cd1c83dea50 Features and fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 3535
diff changeset
154 Offer registration confirmation by email or only through the web?
5cd1c83dea50 Features and fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 3535
diff changeset
155 Allowed values: ``yes``, ``no``
5cd1c83dea50 Features and fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 3535
diff changeset
156
5cd1c83dea50 Features and fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 3535
diff changeset
157 indexer_stopwords -- default *blank*
5cd1c83dea50 Features and fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 3535
diff changeset
158 Additional stop-words for the full-text indexer specific to
5cd1c83dea50 Features and fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 3535
diff changeset
159 your tracker. See the indexer source for the default list of
5cd1c83dea50 Features and fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 3535
diff changeset
160 stop-words (e.g. ``A,AND,ARE,AS,AT,BE,BUT,BY, ...``).
5cd1c83dea50 Features and fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 3535
diff changeset
161
3922
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
162 umask -- ``02``
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
163 Defines the file creation mode mask.
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
164
5047
b8a04cce88ff Adding documentation for csv_field_size to the customizing tracker section issue2550669
John Rouillard <rouilj@ieee.org>
parents: 5004
diff changeset
165 csv_field_size -- ``131072``
b8a04cce88ff Adding documentation for csv_field_size to the customizing tracker section issue2550669
John Rouillard <rouilj@ieee.org>
parents: 5004
diff changeset
166 Maximum size of a csv-field during import. Roundups export
b8a04cce88ff Adding documentation for csv_field_size to the customizing tracker section issue2550669
John Rouillard <rouilj@ieee.org>
parents: 5004
diff changeset
167 format is a csv (comma separated values) variant. The csv
b8a04cce88ff Adding documentation for csv_field_size to the customizing tracker section issue2550669
John Rouillard <rouilj@ieee.org>
parents: 5004
diff changeset
168 reader has a limit on the size of individual fields
b8a04cce88ff Adding documentation for csv_field_size to the customizing tracker section issue2550669
John Rouillard <rouilj@ieee.org>
parents: 5004
diff changeset
169 starting with python 2.5. Set this to a higher value if you
b8a04cce88ff Adding documentation for csv_field_size to the customizing tracker section issue2550669
John Rouillard <rouilj@ieee.org>
parents: 5004
diff changeset
170 get the error 'Error: field larger than field limit' during
b8a04cce88ff Adding documentation for csv_field_size to the customizing tracker section issue2550669
John Rouillard <rouilj@ieee.org>
parents: 5004
diff changeset
171 import.
b8a04cce88ff Adding documentation for csv_field_size to the customizing tracker section issue2550669
John Rouillard <rouilj@ieee.org>
parents: 5004
diff changeset
172
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
173 Section **tracker**
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
174 name -- ``Roundup issue tracker``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
175 A descriptive name for your roundup instance.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
176
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
177 web -- ``http://host.example/demo/``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
178 The web address that the tracker is viewable at.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
179 This will be included in information sent to users of the tracker.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
180 The URL MUST include the cgi-bin part or anything else
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
181 that is required to get to the home page of the tracker.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
182 You MUST include a trailing '/' in the URL.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
183
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
184 email -- ``issue_tracker``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
185 Email address that mail to roundup should go to.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
186
3922
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
187 language -- default *blank*
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
188 Default locale name for this tracker. If this option is not set, the
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
189 language is determined by the environment variable LANGUAGE, LC_ALL,
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
190 LC_MESSAGES, or LANG, in that order of preference.
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
191
3548
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
192 Section **web**
4088
34434785f308 Plug a number of security holes:
Richard Jones <richard@users.sourceforge.net>
parents: 4036
diff changeset
193 allow_html_file -- ``no``
34434785f308 Plug a number of security holes:
Richard Jones <richard@users.sourceforge.net>
parents: 4036
diff changeset
194 Setting this option enables Roundup to serve uploaded HTML
34434785f308 Plug a number of security holes:
Richard Jones <richard@users.sourceforge.net>
parents: 4036
diff changeset
195 file content *as HTML*. This is a potential security risk
34434785f308 Plug a number of security holes:
Richard Jones <richard@users.sourceforge.net>
parents: 4036
diff changeset
196 and is therefore disabled by default. Set to 'yes' if you
34434785f308 Plug a number of security holes:
Richard Jones <richard@users.sourceforge.net>
parents: 4036
diff changeset
197 trust *all* users uploading content to your tracker.
34434785f308 Plug a number of security holes:
Richard Jones <richard@users.sourceforge.net>
parents: 4036
diff changeset
198
3548
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
199 http_auth -- ``yes``
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
200 Whether to use HTTP Basic Authentication, if present.
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
201 Roundup will use either the REMOTE_USER or HTTP_AUTHORIZATION
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
202 variables supplied by your web server (in that order).
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
203 Set this option to 'no' if you do not wish to use HTTP Basic
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
204 Authentication in your web interface.
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
205
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
206 use_browser_language -- ``yes``
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
207 Whether to use HTTP Accept-Language, if present.
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
208 Browsers send a language-region preference list.
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
209 It's usually set in the client's browser or in their
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
210 Operating System.
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
211 Set this option to 'no' if you want to ignore it.
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
212
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
213 debug -- ``no``
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
214 Setting this option makes Roundup display error tracebacks
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
215 in the user's browser rather than emailing them to the
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
216 tracker admin."),
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
217
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
218 Section **rdbms**
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
219 Settings in this section are used by Postgresql and MySQL backends only
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
220
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
221 name -- ``roundup``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
222 Name of the database to use.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
223
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
224 host -- ``localhost``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
225 Database server host.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
226
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
227 port -- default *blank*
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
228 TCP port number of the database server. Postgresql usually resides on
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
229 port 5432 (if any), for MySQL default port number is 3306. Leave this
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
230 option empty to use backend default.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
231
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
232 user -- ``roundup``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
233 Database user name that Roundup should use.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
234
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
235 password -- ``roundup``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
236 Database user password.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
237
3922
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
238 read_default_file -- ``~/.my.cnf``
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
239 Name of the MySQL defaults file. Only used in MySQL connections.
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
240
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
241 read_default_group -- ``roundup``
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
242 Name of the group to use in the MySQL defaults file. Only used in
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
243 MySQL connections.
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
244
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
245 Section **logging**
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
246 config -- default *blank*
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
247 Path to configuration file for standard Python logging module. If this
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
248 option is set, logging configuration is loaded from specified file;
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
249 options 'filename' and 'level' in this section are ignored. The path may
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
250 be either absolute or relative to the directory containig this config file.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
251
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
252 filename -- default *blank*
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
253 Log file name for minimal logging facility built into Roundup. If no file
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
254 name specified, log messages are written on stderr. If above 'config'
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
255 option is set, this option has no effect. The path may be either absolute
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
256 or relative to the directory containig this config file.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
257
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
258 level -- ``ERROR``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
259 Minimal severity level of messages written to log file. If above 'config'
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
260 option is set, this option has no effect.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
261 Allowed values: ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
262
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
263 Section **mail**
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
264 Outgoing email options. Used for nosy messages, password reset and
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
265 registration approval requests.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
266
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
267 domain -- ``localhost``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
268 Domain name used for email addresses.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
269
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
270 host -- default *blank*
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
271 SMTP mail host that roundup will use to send mail
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
272
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
273 username -- default *blank*
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
274 SMTP login name. Set this if your mail host requires authenticated access.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
275 If username is not empty, password (below) MUST be set!
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
276
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
277 password -- default *blank*
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
278 SMTP login password.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
279 Set this if your mail host requires authenticated access.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
280
3878
6d14a3b4e295 allow admin to specify port and local hostname for SMTP connections
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3830
diff changeset
281 port -- default *25*
6d14a3b4e295 allow admin to specify port and local hostname for SMTP connections
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3830
diff changeset
282 SMTP port on mail host.
6d14a3b4e295 allow admin to specify port and local hostname for SMTP connections
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3830
diff changeset
283 Set this if your mail host runs on a different port.
6d14a3b4e295 allow admin to specify port and local hostname for SMTP connections
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3830
diff changeset
284
6d14a3b4e295 allow admin to specify port and local hostname for SMTP connections
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3830
diff changeset
285 local_hostname -- default *blank*
6d14a3b4e295 allow admin to specify port and local hostname for SMTP connections
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3830
diff changeset
286 The fully qualified domain name (FQDN) to use during SMTP sessions. If left
6d14a3b4e295 allow admin to specify port and local hostname for SMTP connections
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3830
diff changeset
287 blank, the underlying SMTP library will attempt to detect your FQDN. If your
6d14a3b4e295 allow admin to specify port and local hostname for SMTP connections
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3830
diff changeset
288 mail host requires something specific, specify the FQDN to use.
6d14a3b4e295 allow admin to specify port and local hostname for SMTP connections
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3830
diff changeset
289
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
290 tls -- ``no``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
291 If your SMTP mail host provides or requires TLS (Transport Layer Security)
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
292 then you may set this option to 'yes'.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
293 Allowed values: ``yes``, ``no``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
294
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
295 tls_keyfile -- default *blank*
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
296 If TLS is used, you may set this option to the name of a PEM formatted
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
297 file that contains your private key. The path may be either absolute or
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
298 relative to the directory containig this config file.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
299
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
300 tls_certfile -- default *blank*
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
301 If TLS is used, you may set this option to the name of a PEM formatted
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
302 certificate chain file. The path may be either absolute or relative
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
303 to the directory containig this config file.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
304
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
305 charset -- utf-8
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
306 Character set to encode email headers with. We use utf-8 by default, as
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
307 it's the most flexible. Some mail readers (eg. Eudora) can't cope with
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
308 that, so you might need to specify a more limited character set
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
309 (eg. iso-8859-1).
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
310
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
311 debug -- default *blank*
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
312 Setting this option makes Roundup to write all outgoing email messages
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
313 to this file *instead* of sending them. This option has the same effect
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
314 as environment variable SENDMAILDEBUG. Environment variable takes
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
315 precedence. The path may be either absolute or relative to the directory
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
316 containig this config file.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
317
3922
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
318 add_authorinfo -- ``yes``
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
319 Add a line with author information at top of all messages send by
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
320 roundup.
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
321
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
322 add_authoremail -- ``yes``
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
323 Add the mail address of the author to the author information at the
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
324 top of all messages. If this is false but add_authorinfo is true,
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
325 only the name of the actor is added which protects the mail address
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
326 of the actor from being exposed at mail archives, etc.
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
327
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
328 Section **mailgw**
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
329 Roundup Mail Gateway options
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
330
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
331 keep_quoted_text -- ``yes``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
332 Keep email citations when accepting messages. Setting this to ``no`` strips
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
333 out "quoted" text from the message. Signatures are also stripped.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
334 Allowed values: ``yes``, ``no``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
335
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
336 leave_body_unchanged -- ``no``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
337 Preserve the email body as is - that is, keep the citations *and*
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
338 signatures.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
339 Allowed values: ``yes``, ``no``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
340
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
341 default_class -- ``issue``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
342 Default class to use in the mailgw if one isn't supplied in email subjects.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
343 To disable, leave the value blank.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
344
3922
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
345 language -- default *blank*
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
346 Default locale name for the tracker mail gateway. If this option is
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
347 not set, mail gateway will use the language of the tracker instance.
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
348
3417
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
349 subject_prefix_parsing -- ``strict``
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
350 Controls the parsing of the [prefix] on subject lines in incoming emails.
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
351 ``strict`` will return an error to the sender if the [prefix] is not
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
352 recognised. ``loose`` will attempt to parse the [prefix] but just
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
353 pass it through as part of the issue title if not recognised. ``none``
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
354 will always pass any [prefix] through as part of the issue title.
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
355
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
356 subject_suffix_parsing -- ``strict``
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
357 Controls the parsing of the [suffix] on subject lines in incoming emails.
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
358 ``strict`` will return an error to the sender if the [suffix] is not
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
359 recognised. ``loose`` will attempt to parse the [suffix] but just
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
360 pass it through as part of the issue title if not recognised. ``none``
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
361 will always pass any [suffix] through as part of the issue title.
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
362
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
363 subject_suffix_delimiters -- ``[]``
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
364 Defines the brackets used for delimiting the commands suffix in a subject
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
365 line.
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
366
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
367 subject_content_match -- ``always``
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
368 Controls matching of the incoming email subject line against issue titles
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
369 in the case where there is no designator [prefix]. ``never`` turns off
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
370 matching. ``creation + interval`` or ``activity + interval`` will match
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
371 an issue for the interval after the issue's creation or last activity.
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
372 The interval is a standard Roundup interval.
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
373
4406
3a0395583de5 add missing config options
Richard Jones <richard@users.sourceforge.net>
parents: 4325
diff changeset
374 subject_updates_title -- ``yes``
3a0395583de5 add missing config options
Richard Jones <richard@users.sourceforge.net>
parents: 4325
diff changeset
375 Update issue title if incoming subject of email is different.
3a0395583de5 add missing config options
Richard Jones <richard@users.sourceforge.net>
parents: 4325
diff changeset
376 Setting this to ``no`` will ignore the title part of
3a0395583de5 add missing config options
Richard Jones <richard@users.sourceforge.net>
parents: 4325
diff changeset
377 the subject of incoming email messages.
3a0395583de5 add missing config options
Richard Jones <richard@users.sourceforge.net>
parents: 4325
diff changeset
378
3922
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
379 refwd_re -- ``(\s*\W?\s*(fw|fwd|re|aw|sv|ang)\W)+``
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
380 Regular expression matching a single reply or forward prefix
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
381 prepended by the mailer. This is explicitly stripped from the
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
382 subject during parsing. Value is Python Regular Expression
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
383 (UTF8-encoded).
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
384
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
385 origmsg_re -- `` ^[>|\s]*-----\s?Original Message\s?-----$``
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
386 Regular expression matching start of an original message if quoted
4656
bce631d8f24d issue2550738: Fixes for various documentation typos, thanks Nathan Russell
John Kristensen <john@jerrykan.com>
parents: 4619
diff changeset
387 in the body. Value is Python Regular Expression (UTF8-encoded).
3922
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
388
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
389 sign_re -- ``^[>|\s]*-- ?$``
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
390 Regular expression matching the start of a signature in the message
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
391 body. Value is Python Regular Expression (UTF8-encoded).
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
392
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
393 eol_re -- ``[\r\n]+``
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
394 Regular expression matching end of line. Value is Python Regular
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
395 Expression (UTF8-encoded).
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
396
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
397 blankline_re -- ``[\r\n]+\s*[\r\n]+``
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
398 Regular expression matching a blank line. Value is Python Regular
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
399 Expression (UTF8-encoded).
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
400
4406
3a0395583de5 add missing config options
Richard Jones <richard@users.sourceforge.net>
parents: 4325
diff changeset
401 ignore_alternatives -- ``no``
3a0395583de5 add missing config options
Richard Jones <richard@users.sourceforge.net>
parents: 4325
diff changeset
402 When parsing incoming mails, roundup uses the first
3a0395583de5 add missing config options
Richard Jones <richard@users.sourceforge.net>
parents: 4325
diff changeset
403 text/plain part it finds. If this part is inside a
3a0395583de5 add missing config options
Richard Jones <richard@users.sourceforge.net>
parents: 4325
diff changeset
404 multipart/alternative, and this option is set, all other
3a0395583de5 add missing config options
Richard Jones <richard@users.sourceforge.net>
parents: 4325
diff changeset
405 parts of the multipart/alternative are ignored. The default
3a0395583de5 add missing config options
Richard Jones <richard@users.sourceforge.net>
parents: 4325
diff changeset
406 is to keep all parts and attach them to the issue.
3a0395583de5 add missing config options
Richard Jones <richard@users.sourceforge.net>
parents: 4325
diff changeset
407
3922
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
408 Section **pgp**
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
409 OpenPGP mail processing options
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
410
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
411 enable -- ``no``
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
412 Enable PGP processing. Requires pyme.
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
413
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
414 roles -- default *blank*
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
415 If specified, a comma-separated list of roles to perform PGP
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
416 processing on. If not specified, it happens for all users.
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
417
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
418 homedir -- default *blank*
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
419 Location of PGP directory. Defaults to $HOME/.gnupg if not
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
420 specified.
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
421
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
422 Section **nosy**
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
423 Nosy messages sending
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
424
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
425 messages_to_author -- ``no``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
426 Send nosy messages to the author of the message.
4975
2fce201a2b47 Documentation: configuration messages_to_author value "nosy" now documented.
Bernhard Reiter <bernhard@intevation.de>
parents: 4941
diff changeset
427 If ``yes`` is used, then messages are sent to the author
2fce201a2b47 Documentation: configuration messages_to_author value "nosy" now documented.
Bernhard Reiter <bernhard@intevation.de>
parents: 4941
diff changeset
428 even if not on the nosy list, same for ``new`` (but only for new messages).
2fce201a2b47 Documentation: configuration messages_to_author value "nosy" now documented.
Bernhard Reiter <bernhard@intevation.de>
parents: 4941
diff changeset
429 When set to ``nosy``, the nosy list controls sending messages to the author.
2fce201a2b47 Documentation: configuration messages_to_author value "nosy" now documented.
Bernhard Reiter <bernhard@intevation.de>
parents: 4941
diff changeset
430 Allowed values: ``yes``, ``no``, ``new``, ``nosy``
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
431
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
432 signature_position -- ``bottom``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
433 Where to place the email signature.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
434 Allowed values: ``top``, ``bottom``, ``none``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
435
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
436 add_author -- ``new``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
437 Does the author of a message get placed on the nosy list automatically?
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
438 If ``new`` is used, then the author will only be added when a message
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
439 creates a new issue. If ``yes``, then the author will be added on
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
440 followups too. If ``no``, they're never added to the nosy.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
441 Allowed values: ``yes``, ``no``, ``new``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
442
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
443 add_recipients -- ``new``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
444 Do the recipients (``To:``, ``Cc:``) of a message get placed on the nosy
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
445 list? If ``new`` is used, then the recipients will only be added when a
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
446 message creates a new issue. If ``yes``, then the recipients will be added
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
447 on followups too. If ``no``, they're never added to the nosy.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
448 Allowed values: ``yes``, ``no``, ``new``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
449
3417
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
450 email_sending -- ``single``
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
451 Controls the email sending from the nosy reactor. If ``multiple`` then
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
452 a separate email is sent to each recipient. If ``single`` then a single
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
453 email is sent with each recipient as a CC address.
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
454
3922
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
455 max_attachment_size -- ``2147483647``
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
456 Attachments larger than the given number of bytes won't be attached
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
457 to nosy mails. They will be replaced by a link to the tracker's
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
458 download page for the file.
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
459
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
460
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
461 You may generate a new default config file using the ``roundup-admin
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
462 genconfig`` command.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
463
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
464 Configuration variables may be referred to in lower or upper case. In code,
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
465 variables not in the "main" section are referred to using their section and
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
466 name, so "domain" in the section "mail" becomes MAIL_DOMAIN. The
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
467 configuration variables available are:
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
468
3768
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
469 Extending the configuration file
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
470 --------------------------------
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
471
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
472 You can't add new variables to the config.ini file in the tracker home but
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
473 you can add two new config.ini files:
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
474
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
475 - a config.ini in the ``extensions`` directory will be loaded and attached
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
476 to the config variable as "ext".
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
477 - a config.ini in the ``detectors`` directory will be loaded and attached
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
478 to the config variable as "detectors".
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
479
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
480 For example, the following in ``detectors/config.ini``::
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
481
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
482 [main]
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
483 qa_recipients = email@example.com
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
484
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
485 is accessible as::
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
486
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
487 db.config.detectors['QA_RECIPIENTS']
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
488
3772
13e8825da493 Documentation update for common lib directory
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3769
diff changeset
489 Note that the name grouping applied to the main configuration file is
3769
d41ee0fdae71 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3768
diff changeset
490 applied to the extension config files, so if you instead have::
d41ee0fdae71 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3768
diff changeset
491
d41ee0fdae71 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3768
diff changeset
492 [qa]
d41ee0fdae71 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3768
diff changeset
493 recipients = email@example.com
d41ee0fdae71 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3768
diff changeset
494
d41ee0fdae71 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3768
diff changeset
495 then the above ``db.config.detectors['QA_RECIPIENTS']`` will still work.
d41ee0fdae71 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3768
diff changeset
496
1360
aa7e4e8b14be allow additional control over the roundupdb email sending...
Richard Jones <richard@users.sourceforge.net>
parents: 1335
diff changeset
497
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1083
diff changeset
498 Tracker Schema
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
499 ==============
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
500
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
501 .. note::
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
502 if you modify the schema, you'll most likely need to edit the
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
503 `web interface`_ HTML template files and `detectors`_ to reflect
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
504 your changes.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
505
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
506 A tracker schema defines what data is stored in the tracker's database.
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
507 Schemas are defined using Python code in the ``schema.py`` module of your
2153
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
508 tracker.
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
509
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
510 The ``schema.py`` module
2153
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
511 ------------------------
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
512
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
513 The ``schema.py`` module contains two functions:
2153
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
514
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
515 **open**
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
516 This function defines what your tracker looks like on the inside, the
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
517 **schema** of the tracker. It defines the **Classes** and **properties**
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
518 on each class. It also defines the **security** for those Classes. The
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
519 next few sections describe how schemas work and what you can do with
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
520 them.
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
521 **init**
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
522 This function is responsible for setting up the initial state of your
4435
386200d0c929 Some minor typos fixed in doc/customizing.txt (Thanks Ralf Hemmecke).
Bernhard Reiter <Bernhard.Reiter@intevation.de>
parents: 4406
diff changeset
523 tracker. It's called exactly once - by the ``roundup-admin initialise``
2153
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
524 command. See the start of the section on `database content`_ for more
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
525 info about how this works.
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
526
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
527
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
528 The "classic" schema
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
529 --------------------
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
530
3476
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
531 The "classic" schema looks like this (see section `setkey(property)`_
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
532 below for the meaning of ``'setkey'`` -- you may also want to look into
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
533 the sections `setlabelprop(property)`_ and `setorderprop(property)`_ for
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
534 specifying (default) labelling and ordering of classes.)::
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
535
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
536 pri = Class(db, "priority", name=String(), order=String())
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
537 pri.setkey("name")
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
538
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
539 stat = Class(db, "status", name=String(), order=String())
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
540 stat.setkey("name")
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
541
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
542 keyword = Class(db, "keyword", name=String())
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
543 keyword.setkey("name")
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
544
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
545 user = Class(db, "user", username=String(), organisation=String(),
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
546 password=String(), address=String(), realname=String(),
3754
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3747
diff changeset
547 phone=String(), alternate_addresses=String(),
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3747
diff changeset
548 queries=Multilink('query'), roles=String(), timezone=String())
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
549 user.setkey("username")
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
550
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
551 msg = FileClass(db, "msg", author=Link("user"), summary=String(),
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
552 date=Date(), recipients=Multilink("user"),
3754
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3747
diff changeset
553 files=Multilink("file"), messageid=String(), inreplyto=String())
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3747
diff changeset
554
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3747
diff changeset
555 file = FileClass(db, "file", name=String())
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
556
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
557 issue = IssueClass(db, "issue", keyword=Multilink("keyword"),
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
558 status=Link("status"), assignedto=Link("user"),
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
559 priority=Link("priority"))
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
560 issue.setkey('title')
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
561
1832
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
562
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
563 What you can't do to the schema
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
564 -------------------------------
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
565
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
566 You must never:
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
567
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
568 **Remove the users class**
2739
deb298529c2b doc clarification
Richard Jones <richard@users.sourceforge.net>
parents: 2726
diff changeset
569 This class is the only *required* class in Roundup.
deb298529c2b doc clarification
Richard Jones <richard@users.sourceforge.net>
parents: 2726
diff changeset
570
deb298529c2b doc clarification
Richard Jones <richard@users.sourceforge.net>
parents: 2726
diff changeset
571 **Remove the "username", "address", "password" or "realname" user properties**
deb298529c2b doc clarification
Richard Jones <richard@users.sourceforge.net>
parents: 2726
diff changeset
572 Various parts of Roundup require these properties. Don't remove them.
1832
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
573
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
574 **Change the type of a property**
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
575 Property types must *never* be changed - the database simply doesn't take
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
576 this kind of action into account. Note that you can't just remove a
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
577 property and re-add it as a new type either. If you wanted to make the
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
578 assignedto property a Multilink, you'd need to create a new property
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
579 assignedto_list and remove the old assignedto property.
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
580
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
581
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
582 What you can do to the schema
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
583 -----------------------------
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
584
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
585 Your schema may be changed at any time before or after the tracker has been
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
586 initialised (or used). You may:
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
587
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
588 **Add new properties to classes, or add whole new classes**
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
589 This is painless and easy to do - there are generally no repurcussions
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
590 from adding new information to a tracker's schema.
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
591
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
592 **Remove properties**
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
593 Removing properties is a little more tricky - you need to make sure that
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
594 the property is no longer used in the `web interface`_ *or* by the
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
595 detectors_.
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
596
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
597
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
598
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
599 Classes and Properties - creating a new information store
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
600 ---------------------------------------------------------
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
601
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1083
diff changeset
602 In the tracker above, we've defined 7 classes of information:
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
603
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
604 priority
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
605 Defines the possible levels of urgency for issues.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
606
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
607 status
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
608 Defines the possible states of processing the issue may be in.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
609
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
610 keyword
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
611 Initially empty, will hold keywords useful for searching issues.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
612
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
613 user
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
614 Initially holding the "admin" user, will eventually have an entry
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
615 for all users using roundup.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
616
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
617 msg
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
618 Initially empty, will hold all e-mail messages sent to or
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
619 generated by roundup.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
620
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
621 file
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
622 Initially empty, will hold all files attached to issues.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
623
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
624 issue
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
625 Initially empty, this is where the issue information is stored.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
626
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
627 We define the "priority" and "status" classes to allow two things:
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
628 reduction in the amount of information stored on the issue and more
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
629 powerful, accurate searching of issues by priority and status. By only
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
630 requiring a link on the issue (which is stored as a single number) we
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
631 reduce the chance that someone mis-types a priority or status - or
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
632 simply makes a new one up.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
633
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
634
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
635 Class and Items
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
636 ~~~~~~~~~~~~~~~
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
637
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
638 A Class defines a particular class (or type) of data that will be stored
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
639 in the database. A class comprises one or more properties, which gives
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
640 the information about the class items.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
641
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
642 The actual data entered into the database, using ``class.create()``, are
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
643 called items. They have a special immutable property called ``'id'``. We
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
644 sometimes refer to this as the *itemid*.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
645
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
646
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
647 Properties
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
648 ~~~~~~~~~~
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
649
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
650 A Class is comprised of one or more properties of the following types:
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
651
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
652 * String properties are for storing arbitrary-length strings.
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
653 * Password properties are for storing encoded arbitrary-length strings.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
654 The default encoding is defined on the ``roundup.password.Password``
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
655 class.
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
656 * Date properties store date-and-time stamps. Their values are Timestamp
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
657 objects.
5067
e424987d294a Add support for an integer type to join the existing number type.
John Rouillard <rouilj@ieee.org>
parents: 5064
diff changeset
658 * Integer properties store integer values. (Number can store real/float values.)
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
659 * Number properties store numeric values.
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
660 * Boolean properties store on/off, yes/no, true/false values.
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
661 * A Link property refers to a single other item selected from a
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
662 specified class. The class is part of the property; the value is an
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
663 integer, the id of the chosen item.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
664 * A Multilink property refers to possibly many items in a specified
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
665 class. The value is a list of integers.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
666
5064
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
667 Properties can have additional attributes to change the default
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
668 behaviour:
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
669
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
670 * String properties can have an ``indexme`` attribute that defines if the
5114
f74300d1494e issue2550854: including new field in All text* search.
John Rouillard <rouilj@ieee.org>
parents: 5067
diff changeset
671 property should be part of the full text index. The default is 'no' but this
f74300d1494e issue2550854: including new field in All text* search.
John Rouillard <rouilj@ieee.org>
parents: 5067
diff changeset
672 can be set to 'yes' to allow a property's contents to be in the full
f74300d1494e issue2550854: including new field in All text* search.
John Rouillard <rouilj@ieee.org>
parents: 5067
diff changeset
673 text index.
5064
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
674 * Link and Multilink properties can have several attributes:
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
675
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
676 - ``do_journal``: By default, every change of a link property is
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
677 recorded in the item being linked to (or being unlinked). A typical
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
678 use-case for setting ``do_journal='no'`` would be to turn off
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
679 journalling of nosy list, message author and message recipient link
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
680 and unlink events to prevent the journal from clogged with these
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
681 events.
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
682 - ``try_id_parsing`` is turned on by default. If entering a number
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
683 into a Link or Multilink field, roundup interprets this number as an
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
684 ID of the item to link to. Sometimes items can have numeric names
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
685 (like, e.g., product codes). For these roundup needs to match the
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
686 numeric name and should never match an ID. In this case you can set
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
687 ``try_id_parsing='no'``.
5131
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
688 - The ``msg_header_property`` is used by the mail gateway when sending
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
689 out messages. When a link or multilink property of an issue changes,
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
690 roundup creates email headers of the form::
5064
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
691
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
692 X-Roundup-issue-prop: value
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
693
5131
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
694 where ``value`` is the ``name`` property for the linked item(s).
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
695 For example, if you have a multilink for attached_files in your
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
696 issue, you will see a header::
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
697
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
698 X-Roundup-issue-attached_files: MySpecialFile.doc, HisResume.txt
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
699
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
700 when the class for attached files is defined as::
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
701
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
702 file = FileClass(db, "file",
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
703 name=String())
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
704
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
705 ``MySpecialFile.doc`` is the name for the file object.
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
706
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
707 If you have an ``assigned_to`` property in your issue class that
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
708 links to the user class and you want to add a header::
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
709
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
710 X-Roundup-issue-assigned_to: ...
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
711
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
712 so that the mail recipients can filter emails where
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
713 ``X-Roundup-issue-assigned_to: name`` that contains their
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
714 username. The user class is defined as::
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
715
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
716 user = Class(db, "user",
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
717 username=String(),
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
718 password=Password(),
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
719 address=String(),
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
720 realname=String(),
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
721 phone=String(),
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
722 organisation=String(),
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
723 alternate_addresses=String(),
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
724 queries=Multilink('query'),
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
725 roles=String(), # comma-separated string of Role names
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
726 timezone=String())
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
727
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
728 Because there is no ``name`` parameter for the user class, there
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
729 will be no header. However setting::
5135
9e8d8cd49f40 removing unneeded whitespace
John Rouillard <rouilj@ieee.org>
parents: 5131
diff changeset
730
9e8d8cd49f40 removing unneeded whitespace
John Rouillard <rouilj@ieee.org>
parents: 5131
diff changeset
731 assigned_to=Link("user", msg_header_property="username")
5131
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
732
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
733 will make the mail gateway generate an ``X-Roundup-issue-assigned_to``
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
734 using the username property of the linked user.
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
735
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
736 Assume assigned_to for an issue is linked to the user with
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
737 username=joe_user, setting::
5064
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
738
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
739 msg_header_property="username"
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
740
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
741 for the assigned_to property will generated message headers of the
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
742 form::
5131
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
743
5064
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
744 X-Roundup-issue-assigned_to: joe_user
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
745
5131
513803cade0a from mailing list spurce up the documentation om msg_header_property. We may rename it, but that'a an easy patch
John Rouillard <rouilj@ieee.org>
parents: 5124
diff changeset
746 for emails sent on issues where joe_user has been assigned to the issue.
5124
a927f9549af0 Fix issue2550751: Email Header Issue.
John Rouillard <rouilj@ieee.org>
parents: 5114
diff changeset
747
a927f9549af0 Fix issue2550751: Email Header Issue.
John Rouillard <rouilj@ieee.org>
parents: 5114
diff changeset
748 If this property is set to the empty string "", it will prevent
a927f9549af0 Fix issue2550751: Email Header Issue.
John Rouillard <rouilj@ieee.org>
parents: 5114
diff changeset
749 the header from being generated on outgoing mail.
5064
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
750
3097
Richard Jones <richard@users.sourceforge.net>
parents: 3079
diff changeset
751 All Classes automatically have a number of properties by default:
Richard Jones <richard@users.sourceforge.net>
parents: 3079
diff changeset
752
Richard Jones <richard@users.sourceforge.net>
parents: 3079
diff changeset
753 *creator*
Richard Jones <richard@users.sourceforge.net>
parents: 3079
diff changeset
754 Link to the user that created the item.
Richard Jones <richard@users.sourceforge.net>
parents: 3079
diff changeset
755 *creation*
Richard Jones <richard@users.sourceforge.net>
parents: 3079
diff changeset
756 Date the item was created.
Richard Jones <richard@users.sourceforge.net>
parents: 3079
diff changeset
757 *actor*
Richard Jones <richard@users.sourceforge.net>
parents: 3079
diff changeset
758 Link to the user that last modified the item.
Richard Jones <richard@users.sourceforge.net>
parents: 3079
diff changeset
759 *activity*
Richard Jones <richard@users.sourceforge.net>
parents: 3079
diff changeset
760 Date the item was last modified.
Richard Jones <richard@users.sourceforge.net>
parents: 3079
diff changeset
761
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
762
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
763 FileClass
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
764 ~~~~~~~~~
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
765
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
766 FileClasses save their "content" attribute off in a separate file from
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
767 the rest of the database. This reduces the number of large entries in
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
768 the database, which generally makes databases more efficient, and also
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
769 allows us to use command-line tools to operate on the files. They are
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
770 stored in the files sub-directory of the ``'db'`` directory in your
3754
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3747
diff changeset
771 tracker. FileClasses also have a "type" attribute to store the MIME
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3747
diff changeset
772 type of the file.
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
773
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
774
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
775 IssueClass
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
776 ~~~~~~~~~~
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
777
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
778 IssueClasses automatically include the "messages", "files", "nosy", and
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
779 "superseder" properties.
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
780
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
781 The messages and files properties list the links to the messages and
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
782 files related to the issue. The nosy property is a list of links to
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
783 users who wish to be informed of changes to the issue - they get "CC'ed"
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
784 e-mails when messages are sent to or generated by the issue. The nosy
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
785 reactor (in the ``'detectors'`` directory) handles this action. The
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
786 superseder link indicates an issue which has superseded this one.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
787
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
788 They also have the dynamically generated "creation", "activity" and
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
789 "creator" properties.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
790
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
791 The value of the "creation" property is the date when an item was
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
792 created, and the value of the "activity" property is the date when any
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
793 property on the item was last edited (equivalently, these are the dates
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
794 on the first and last records in the item's journal). The "creator"
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
795 property holds a link to the user that created the issue.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
796
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
797
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
798 setkey(property)
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
799 ~~~~~~~~~~~~~~~~
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
800
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
801 Select a String property of the class to be the key property. The key
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
802 property must be unique, and allows references to the items in the class
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
803 by the content of the key property. That is, we can refer to users by
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
804 their username: for example, let's say that there's an issue in roundup,
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
805 issue 23. There's also a user, richard, who happens to be user 2. To
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
806 assign an issue to him, we could do either of::
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
807
1570
93e0a565cee5 fix the "set" command usage statement
Richard Jones <richard@users.sourceforge.net>
parents: 1568
diff changeset
808 roundup-admin set issue23 assignedto=2
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
809
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
810 or::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
811
1570
93e0a565cee5 fix the "set" command usage statement
Richard Jones <richard@users.sourceforge.net>
parents: 1568
diff changeset
812 roundup-admin set issue23 assignedto=richard
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
813
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
814 Note, the same thing can be done in the web and e-mail interfaces.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
815
3476
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
816 setlabelprop(property)
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
817 ~~~~~~~~~~~~~~~~~~~~~~
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
818
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
819 Select a property of the class to be the label property. The label
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
820 property is used whereever an item should be uniquely identified, e.g.,
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
821 when displaying a link to an item. If setlabelprop is not specified for
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
822 a class, the following values are tried for the label:
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
823
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
824 * the key of the class (see the `setkey(property)`_ section above)
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
825 * the "name" property
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
826 * the "title" property
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
827 * the first property from the sorted property name list
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
828
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
829 So in most cases you can get away without specifying setlabelprop
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
830 explicitly.
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
831
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
832 setorderprop(property)
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
833 ~~~~~~~~~~~~~~~~~~~~~~
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
834
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
835 Select a property of the class to be the order property. The order
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
836 property is used whenever using a default sort order for the class,
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
837 e.g., when grouping or sorting class A by a link to class B in the user
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
838 interface, the order property of class B is used for sorting. If
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
839 setorderprop is not specified for a class, the following values are tried
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
840 for the order property:
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
841
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
842 * the property named "order"
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
843 * the label property (see `setlabelprop(property)`_ above)
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
844
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
845 So in most cases you can get away without specifying setorderprop
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
846 explicitly.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
847
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
848 create(information)
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
849 ~~~~~~~~~~~~~~~~~~~
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
850
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
851 Create an item in the database. This is generally used to create items
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
852 in the "definitional" classes like "priority" and "status".
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
853
684
5b23ff865f3a added a "detectors" directory...
Richard Jones <richard@users.sourceforge.net>
parents: 673
diff changeset
854
2897
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
855 A note about ordering
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
856 ~~~~~~~~~~~~~~~~~~~~~
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
857
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
858 When we sort items in the hyperdb, we use one of a number of methods,
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
859 depending on the properties being sorted on:
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
860
5067
e424987d294a Add support for an integer type to join the existing number type.
John Rouillard <rouilj@ieee.org>
parents: 5064
diff changeset
861 1. If it's a String, Integer, Number, Date or Interval property, we
e424987d294a Add support for an integer type to join the existing number type.
John Rouillard <rouilj@ieee.org>
parents: 5064
diff changeset
862 just sort the scalar value of the property. Strings are sorted
e424987d294a Add support for an integer type to join the existing number type.
John Rouillard <rouilj@ieee.org>
parents: 5064
diff changeset
863 case-sensitively.
2897
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
864 2. If it's a Link property, we sort by either the linked item's "order"
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
865 property (if it has one) or the linked item's "id".
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
866 3. Mulitlinks sort similar to #2, but we start with the first Multilink
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
867 list item, and if they're the same, we sort by the second item, and
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
868 so on.
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
869
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
870 Note that if an "order" property is defined on a Class that is used for
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
871 sorting, all items of that Class *must* have a value against the "order"
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
872 property, or sorting will result in random ordering.
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
873
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
874
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
875 Examples of adding to your schema
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
876 ---------------------------------
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
877
3754
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3747
diff changeset
878 The Roundup wiki has examples of how schemas can be customised to add
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3747
diff changeset
879 new functionality.
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
880
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
881
684
5b23ff865f3a added a "detectors" directory...
Richard Jones <richard@users.sourceforge.net>
parents: 673
diff changeset
882 Detectors - adding behaviour to your tracker
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
883 ============================================
909
ef9c759c243e Fix to hasPermission, thanks Stefan Seefeld.
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
884 .. _detectors:
684
5b23ff865f3a added a "detectors" directory...
Richard Jones <richard@users.sourceforge.net>
parents: 673
diff changeset
885
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
886 Detectors are initialised every time you open your tracker database, so
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
887 you're free to add and remove them any time, even after the database is
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
888 initialised via the ``roundup-admin initialise`` command.
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
889
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
890 The detectors in your tracker fire *before* (**auditors**) and *after*
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
891 (**reactors**) changes to the contents of your database. They are Python
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
892 modules that sit in your tracker's ``detectors`` directory. You will
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
893 have some installed by default - have a look. You can write new
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
894 detectors or modify the existing ones. The existing detectors installed
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
895 for you are:
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
896
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
897 **nosyreaction.py**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
898 This provides the automatic nosy list maintenance and email sending.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
899 The nosy reactor (``nosyreaction``) fires when new messages are added
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
900 to issues. The nosy auditor (``updatenosy``) fires when issues are
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
901 changed, and figures out what changes need to be made to the nosy list
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
902 (such as adding new authors, etc.)
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
903 **statusauditor.py**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
904 This provides the ``chatty`` auditor which changes the issue status
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
905 from ``unread`` or ``closed`` to ``chatting`` if new messages appear.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
906 It also provides the ``presetunread`` auditor which pre-sets the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
907 status to ``unread`` on new items if the status isn't explicitly
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
908 defined.
1777
fbe08359511a customisation doc update
Richard Jones <richard@users.sourceforge.net>
parents: 1773
diff changeset
909 **messagesummary.py**
fbe08359511a customisation doc update
Richard Jones <richard@users.sourceforge.net>
parents: 1773
diff changeset
910 Generates the ``summary`` property for new messages based on the message
fbe08359511a customisation doc update
Richard Jones <richard@users.sourceforge.net>
parents: 1773
diff changeset
911 content.
fbe08359511a customisation doc update
Richard Jones <richard@users.sourceforge.net>
parents: 1773
diff changeset
912 **userauditor.py**
fbe08359511a customisation doc update
Richard Jones <richard@users.sourceforge.net>
parents: 1773
diff changeset
913 Verifies the content of some of the user fields (email addresses and
fbe08359511a customisation doc update
Richard Jones <richard@users.sourceforge.net>
parents: 1773
diff changeset
914 roles lists).
fbe08359511a customisation doc update
Richard Jones <richard@users.sourceforge.net>
parents: 1773
diff changeset
915
fbe08359511a customisation doc update
Richard Jones <richard@users.sourceforge.net>
parents: 1773
diff changeset
916 If you don't want this default behaviour, you're completely free to change
fbe08359511a customisation doc update
Richard Jones <richard@users.sourceforge.net>
parents: 1773
diff changeset
917 or remove these detectors.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
918
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
919 See the detectors section in the `design document`__ for details of the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
920 interface for detectors.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
921
909
ef9c759c243e Fix to hasPermission, thanks Stefan Seefeld.
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
922 __ design.html
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
923
2209
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
924
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
925 Detector API
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
926 ------------
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
927
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
928 Auditors are called with the arguments::
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
929
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
930 audit(db, cl, itemid, newdata)
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
931
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
932 where ``db`` is the database, ``cl`` is an instance of Class or
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
933 IssueClass within the database, and ``newdata`` is a dictionary mapping
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
934 property names to values.
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
935
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
936 For a ``create()`` operation, the ``itemid`` argument is None and
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
937 newdata contains all of the initial property values with which the item
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
938 is about to be created.
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
939
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
940 For a ``set()`` operation, newdata contains only the names and values of
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
941 properties that are about to be changed.
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
942
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
943 For a ``retire()`` or ``restore()`` operation, newdata is None.
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
944
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
945 Reactors are called with the arguments::
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
946
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
947 react(db, cl, itemid, olddata)
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
948
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
949 where ``db`` is the database, ``cl`` is an instance of Class or
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
950 IssueClass within the database, and ``olddata`` is a dictionary mapping
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
951 property names to values.
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
952
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
953 For a ``create()`` operation, the ``itemid`` argument is the id of the
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
954 newly-created item and ``olddata`` is None.
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
955
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
956 For a ``set()`` operation, ``olddata`` contains the names and previous
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
957 values of properties that were changed.
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
958
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
959 For a ``retire()`` or ``restore()`` operation, ``itemid`` is the id of
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
960 the retired or restored item and ``olddata`` is None.
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
961
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
962
2193
b1a29edd6214 added another sample detector
Richard Jones <richard@users.sourceforge.net>
parents: 2180
diff changeset
963 Additional Detectors Ready For Use
b1a29edd6214 added another sample detector
Richard Jones <richard@users.sourceforge.net>
parents: 2180
diff changeset
964 ----------------------------------
b1a29edd6214 added another sample detector
Richard Jones <richard@users.sourceforge.net>
parents: 2180
diff changeset
965
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
966 Sample additional detectors that have been found useful will appear in
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
967 the ``'detectors'`` directory of the Roundup distribution. If you want
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
968 to use one, copy it to the ``'detectors'`` of your tracker instance:
684
5b23ff865f3a added a "detectors" directory...
Richard Jones <richard@users.sourceforge.net>
parents: 673
diff changeset
969
4695
132650f4700a #2550782: Added a new irker detector to send notifications on IRC when an issue is created or messages are added.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 4656
diff changeset
970 **irker.py**
132650f4700a #2550782: Added a new irker detector to send notifications on IRC when an issue is created or messages are added.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 4656
diff changeset
971 This detector sends notification on IRC through an irker daemon
132650f4700a #2550782: Added a new irker detector to send notifications on IRC when an issue is created or messages are added.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 4656
diff changeset
972 (http://www.catb.org/esr/irker/) when issues are created or messages
132650f4700a #2550782: Added a new irker detector to send notifications on IRC when an issue is created or messages are added.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 4656
diff changeset
973 are added. In order to use it you need to install irker, start the
132650f4700a #2550782: Added a new irker detector to send notifications on IRC when an issue is created or messages are added.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 4656
diff changeset
974 irkerd daemon, and add an ``[irker]`` section in ``detectors/config.ini``
132650f4700a #2550782: Added a new irker detector to send notifications on IRC when an issue is created or messages are added.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 4656
diff changeset
975 that contains a comma-separated list of channels where the messages should
132650f4700a #2550782: Added a new irker detector to send notifications on IRC when an issue is created or messages are added.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 4656
diff changeset
976 be sent, e.g. ``channels = irc://chat.freenode.net/channelname``.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
977 **newissuecopy.py**
684
5b23ff865f3a added a "detectors" directory...
Richard Jones <richard@users.sourceforge.net>
parents: 673
diff changeset
978 This detector sends an email to a team address whenever a new issue is
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
979 created. The address is hard-coded into the detector, so edit it
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
980 before you use it (look for the text 'team@team.host') or you'll get
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
981 email errors!
2193
b1a29edd6214 added another sample detector
Richard Jones <richard@users.sourceforge.net>
parents: 2180
diff changeset
982 **creator_resolution.py**
b1a29edd6214 added another sample detector
Richard Jones <richard@users.sourceforge.net>
parents: 2180
diff changeset
983 Catch attempts to set the status to "resolved" - if the assignedto
b1a29edd6214 added another sample detector
Richard Jones <richard@users.sourceforge.net>
parents: 2180
diff changeset
984 user isn't the creator, then set the status to "confirm-done". Note that
b1a29edd6214 added another sample detector
Richard Jones <richard@users.sourceforge.net>
parents: 2180
diff changeset
985 "classic" Roundup doesn't have that status, so you'll have to add it. If
b1a29edd6214 added another sample detector
Richard Jones <richard@users.sourceforge.net>
parents: 2180
diff changeset
986 you don't want to though, it'll just use "in-progress" instead.
b1a29edd6214 added another sample detector
Richard Jones <richard@users.sourceforge.net>
parents: 2180
diff changeset
987 **email_auditor.py**
b1a29edd6214 added another sample detector
Richard Jones <richard@users.sourceforge.net>
parents: 2180
diff changeset
988 If a file added to an issue is of type message/rfc822, we tack on the
b1a29edd6214 added another sample detector
Richard Jones <richard@users.sourceforge.net>
parents: 2180
diff changeset
989 extension .eml.
b1a29edd6214 added another sample detector
Richard Jones <richard@users.sourceforge.net>
parents: 2180
diff changeset
990 The reason for this is that Microsoft Internet Explorer will not open
b1a29edd6214 added another sample detector
Richard Jones <richard@users.sourceforge.net>
parents: 2180
diff changeset
991 things with a .eml attachment, as they deem it 'unsafe'. Worse yet,
b1a29edd6214 added another sample detector
Richard Jones <richard@users.sourceforge.net>
parents: 2180
diff changeset
992 they'll just give you an incomprehensible error message. For more
b1a29edd6214 added another sample detector
Richard Jones <richard@users.sourceforge.net>
parents: 2180
diff changeset
993 information, see the detector code - it has a length explanation.
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
994
684
5b23ff865f3a added a "detectors" directory...
Richard Jones <richard@users.sourceforge.net>
parents: 673
diff changeset
995
2129
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
996 Auditor or Reactor?
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
997 -------------------
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
998
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
999 Generally speaking, the following rules should be observed:
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1000
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1001 **Auditors**
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1002 Are used for `vetoing creation of or changes to items`_. They might
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1003 also make automatic changes to item properties.
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1004 **Reactors**
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1005 Detect changes in the database and react accordingly. They should avoid
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1006 making changes to the database where possible, as this could create
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1007 detector loops.
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1008
2138
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
1009
2129
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1010 Vetoing creation of or changes to items
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1011 ---------------------------------------
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1012
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1013 Auditors may raise the ``Reject`` exception to prevent the creation of
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1014 or changes to items in the database. The mail gateway, for example, will
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1015 not attach files or messages to issues when the creation of those files or
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1016 messages are prevented through the ``Reject`` exception. It'll also not create
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1017 users if that creation is ``Reject``'ed too.
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1018
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1019 To use, simply add at the top of your auditor::
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1020
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1021 from roundup.exceptions import Reject
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1022
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1023 And then when your rejection criteria have been detected, simply::
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1024
5004
494d255043c9 Display errors containing HTML with RejectRaw (issue2550847)
John Kristensen <john@jerrykan.com>
parents: 4975
diff changeset
1025 raise Reject('Description of error')
494d255043c9 Display errors containing HTML with RejectRaw (issue2550847)
John Kristensen <john@jerrykan.com>
parents: 4975
diff changeset
1026
494d255043c9 Display errors containing HTML with RejectRaw (issue2550847)
John Kristensen <john@jerrykan.com>
parents: 4975
diff changeset
1027 Error messages raised with ``Reject`` automatically have any HTML content
494d255043c9 Display errors containing HTML with RejectRaw (issue2550847)
John Kristensen <john@jerrykan.com>
parents: 4975
diff changeset
1028 escaped before being displayed to the user. To display an error message to the
494d255043c9 Display errors containing HTML with RejectRaw (issue2550847)
John Kristensen <john@jerrykan.com>
parents: 4975
diff changeset
1029 user without performing any HTML escaping the ``RejectRaw`` should be used. All
494d255043c9 Display errors containing HTML with RejectRaw (issue2550847)
John Kristensen <john@jerrykan.com>
parents: 4975
diff changeset
1030 security implications should be carefully considering before using
494d255043c9 Display errors containing HTML with RejectRaw (issue2550847)
John Kristensen <john@jerrykan.com>
parents: 4975
diff changeset
1031 ``RejectRaw``.
2129
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1032
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1033
2138
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
1034 Generating email from Roundup
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
1035 -----------------------------
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
1036
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
1037 The module ``roundup.mailer`` contains most of the nuts-n-bolts required
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
1038 to generate email messages from Roundup.
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
1039
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
1040 In addition, the ``IssueClass`` methods ``nosymessage()`` and
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
1041 ``send_message()`` are used to generate nosy messages, and may generate
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
1042 messages which only consist of a change note (ie. the message id parameter
3463
da8fe3566f67 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3429
diff changeset
1043 is not required - this is referred to as a "System Message" because it
da8fe3566f67 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3429
diff changeset
1044 comes from "the system" and not a user).
2138
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
1045
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
1046
4921
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1047 Extensions - adding capabilities to your tracker
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1048 ================================================
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1049 .. _extensions:
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1050
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1051 While detectors_ add new behavior by reacting to changes in tracked
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1052 objects, `extensions` add new actions and utilities to Roundup, which
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1053 are mostly used to enhance web interface.
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1054
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1055 You can create an extension by creating Python file in your tracker
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1056 ``extensions`` directory. All files from this dir are loaded when
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1057 tracker instance is created, at which point it calls ``init(instance)``
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1058 from each file supplying itself as a first argument.
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1059
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1060 Note that at this point web interface is not loaded, but extensions still
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1061 can register actions for in tracker instance. This may be fixed in
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1062 Roundup 1.6 by introducing ``init_web(client)`` callback or a more
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1063 flexible extension point mechanism.
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1064
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1065
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1066 * ``instance.registerUtil`` is used for adding `templating utilities`_
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1067 (see `adding a time log to your issues`_ for an example)
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1068
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1069 * ``instance.registerAction`` is used to add more actions to instance
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1070 and to web interface. See `Defining new web actions`_ for details.
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1071 Generic action can be added by inheriting from ``action.Action``
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1072 instead of ``cgi.action.Action``.
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1073
898
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
1074 Database Content
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
1075 ================
898
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
1076
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
1077 .. note::
3754
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3747
diff changeset
1078 If you modify the content of definitional classes, you'll most
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
1079 likely need to edit the tracker `detectors`_ to reflect your changes.
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1080
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1081 Customisation of the special "definitional" classes (eg. status,
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1082 priority, resolution, ...) may be done either before or after the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1083 tracker is initialised. The actual method of doing so is completely
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1084 different in each case though, so be careful to use the right one.
898
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
1085
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1083
diff changeset
1086 **Changing content before tracker initialisation**
3241
78d2f3ce85f6 filename change
Richard Jones <richard@users.sourceforge.net>
parents: 3228
diff changeset
1087 Edit the initial_data.py module in your tracker to alter the items
78d2f3ce85f6 filename change
Richard Jones <richard@users.sourceforge.net>
parents: 3228
diff changeset
1088 created using the ``create( ... )`` methods.
898
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
1089
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1083
diff changeset
1090 **Changing content after tracker initialisation**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1091 As the "admin" user, click on the "class list" link in the web
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1092 interface to bring up a list of all database classes. Click on the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1093 name of the class you wish to change the content of.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1094
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1095 You may also use the ``roundup-admin`` interface's create, set and
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1096 retire methods to add, alter or remove items from the classes in
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1097 question.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1098
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1099 See "`adding a new field to the classic schema`_" for an example that
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1100 requires database content changes.
898
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
1101
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
1102
2003
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents: 1998
diff changeset
1103 Security / Access Controls
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents: 1998
diff changeset
1104 ==========================
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1105
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1106 A set of Permissions is built into the security module by default:
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1107
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1108 - Create (everything)
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1109 - Edit (everything)
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1110 - View (everything)
4296
72463e22640d fix some more documentation for the Register permission
Richard Jones <richard@users.sourceforge.net>
parents: 4088
diff changeset
1111 - Register (User class only)
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1112
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1113 These are assigned to the "Admin" Role by default, and allow a user to do
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1114 anything. Every Class you define in your `tracker schema`_ also gets an
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1115 Create, Edit and View Permission of its own. The web and email interfaces
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1116 also define:
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1117
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1118 *Email Access*
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1119 If defined, the user may use the email interface. Used by default to deny
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1120 Anonymous users access to the email interface. When granted to the
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1121 Anonymous user, they will be automatically registered by the email
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1122 interface (see also the ``new_email_user_roles`` configuration option).
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1123 *Web Access*
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1124 If defined, the user may use the web interface. All users are able to see
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1125 the login form, regardless of this setting (thus enabling logging in).
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1126 *Web Roles*
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1127 Controls user access to editing the "roles" property of the "user" class.
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1128 TODO: deprecate in favour of a property-based control.
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1129
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1130 These are hooked into the default Roles:
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1131
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1132 - Admin (Create, Edit, View and everything; Web Roles)
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1133 - User (Web Access; Email Access)
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1134 - Anonymous (Web Access)
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1135
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1136 And finally, the "admin" user gets the "Admin" Role, and the "anonymous"
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1137 user gets "Anonymous" assigned when the tracker is installed.
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1138
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1139 For the "User" Role, the "classic" tracker defines:
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1140
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1141 - Create, Edit and View issue, file, msg, query, keyword
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1142 - View priority, status
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1143 - View user
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1144 - Edit their own user record
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1145
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1146 And the "Anonymous" Role is defined as:
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1147
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1148 - Web interface access
4296
72463e22640d fix some more documentation for the Register permission
Richard Jones <richard@users.sourceforge.net>
parents: 4088
diff changeset
1149 - Register user (for registration)
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1150 - View issue, file, msg, query, keyword, priority, status
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1151
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1152 Put together, these settings appear in the tracker's ``schema.py`` file::
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1153
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1154 #
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1155 # TRACKER SECURITY SETTINGS
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1156 #
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1157 # See the configuration and customisation document for information
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1158 # about security setup.
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1159
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1160 #
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1161 # REGULAR USERS
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1162 #
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1163 # Give the regular users access to the web and email interface
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1164 db.security.addPermissionToRole('User', 'Web Access')
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1165 db.security.addPermissionToRole('User', 'Email Access')
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1166
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1167 # Assign the access and edit Permissions for issue, file and message
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1168 # to regular users now
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1169 for cl in 'issue', 'file', 'msg', 'query', 'keyword':
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1170 db.security.addPermissionToRole('User', 'View', cl)
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1171 db.security.addPermissionToRole('User', 'Edit', cl)
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1172 db.security.addPermissionToRole('User', 'Create', cl)
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1173 for cl in 'priority', 'status':
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1174 db.security.addPermissionToRole('User', 'View', cl)
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1175
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1176 # May users view other user information? Comment these lines out
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1177 # if you don't want them to
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1178 db.security.addPermissionToRole('User', 'View', 'user')
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1179
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1180 # Users should be able to edit their own details -- this permission
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1181 # is limited to only the situation where the Viewed or Edited item
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1182 # is their own.
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1183 def own_record(db, userid, itemid):
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1184 '''Determine whether the userid matches the item being accessed.'''
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1185 return userid == itemid
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1186 p = db.security.addPermission(name='View', klass='user', check=own_record,
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1187 description="User is allowed to view their own user details")
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1188 db.security.addPermissionToRole('User', p)
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1189 p = db.security.addPermission(name='Edit', klass='user', check=own_record,
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1190 description="User is allowed to edit their own user details")
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1191 db.security.addPermissionToRole('User', p)
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1192
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1193 #
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1194 # ANONYMOUS USER PERMISSIONS
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1195 #
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1196 # Let anonymous users access the web interface. Note that almost all
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1197 # trackers will need this Permission. The only situation where it's not
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1198 # required is in a tracker that uses an HTTP Basic Authenticated front-end.
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1199 db.security.addPermissionToRole('Anonymous', 'Web Access')
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1200
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1201 # Let anonymous users access the email interface (note that this implies
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1202 # that they will be registered automatically, hence they will need the
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1203 # "Create" user Permission below)
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1204 # This is disabled by default to stop spam from auto-registering users on
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1205 # public trackers.
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1206 #db.security.addPermissionToRole('Anonymous', 'Email Access')
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1207
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1208 # Assign the appropriate permissions to the anonymous user's Anonymous
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1209 # Role. Choices here are:
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1210 # - Allow anonymous users to register
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1211 db.security.addPermissionToRole('Anonymous', 'Create', 'user')
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1212
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1213 # Allow anonymous users access to view issues (and the related, linked
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1214 # information)
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1215 for cl in 'issue', 'file', 'msg', 'keyword', 'priority', 'status':
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1216 db.security.addPermissionToRole('Anonymous', 'View', cl)
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1217
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1218 # [OPTIONAL]
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1219 # Allow anonymous users access to create or edit "issue" items (and the
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1220 # related file and message items)
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1221 #for cl in 'issue', 'file', 'msg':
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1222 # db.security.addPermissionToRole('Anonymous', 'Create', cl)
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1223 # db.security.addPermissionToRole('Anonymous', 'Edit', cl)
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1224
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1225
3117
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1226 Automatic Permission Checks
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1227 ---------------------------
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1228
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1229 Permissions are automatically checked when information is rendered
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1230 through the web. This includes:
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1231
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1232 1. View checks for properties when being rendered via the ``plain()`` or
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1233 similar methods. If the check fails, the text "[hidden]" will be
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1234 displayed.
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1235 2. Edit checks for properties when the edit field is being rendered via
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1236 the ``field()`` or similar methods. If the check fails, the property
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1237 will be rendered via the ``plain()`` method (see point 1. for subsequent
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1238 checking performed)
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1239 3. View checks are performed in index pages for each item being displayed
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1240 such that if the user does not have permission, the row is not rendered.
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1241 4. View checks are performed at the top of item pages for the Item being
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1242 displayed. If the user does not have permission, the text "You are not
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1243 allowed to view this page." will be displayed.
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1244 5. View checks are performed at the top of index pages for the Class being
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1245 displayed. If the user does not have permission, the text "You are not
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1246 allowed to view this page." will be displayed.
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1247
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1248
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1249 New User Roles
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1250 --------------
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1251
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1252 New users are assigned the Roles defined in the config file as:
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1253
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1254 - NEW_WEB_USER_ROLES
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1255 - NEW_EMAIL_USER_ROLES
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1256
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1257 The `users may only edit their issues`_ example shows customisation of
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1258 these parameters.
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1259
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1260
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1261 Changing Access Controls
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1262 ------------------------
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1263
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1264 You may alter the configuration variables to change the Role that new
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1265 web or email users get, for example to not give them access to the web
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1266 interface if they register through email.
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1267
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1268 You may use the ``roundup-admin`` "``security``" command to display the
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1269 current Role and Permission configuration in your tracker.
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1270
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1271
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1272 Adding a new Permission
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1273 ~~~~~~~~~~~~~~~~~~~~~~~
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1274
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1275 When adding a new Permission, you will need to:
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1276
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1277 1. add it to your tracker's ``schema.py`` so it is created, using
2076
2a4309450202 security fixes and doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2069
diff changeset
1278 ``security.addPermission``, for example::
2a4309450202 security fixes and doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2069
diff changeset
1279
2a4309450202 security fixes and doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2069
diff changeset
1280 self.security.addPermission(name="View", klass='frozzle',
2a4309450202 security fixes and doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2069
diff changeset
1281 description="User is allowed to access frozzles")
2a4309450202 security fixes and doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2069
diff changeset
1282
2a4309450202 security fixes and doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2069
diff changeset
1283 will set up a new "View" permission on the Class "frozzle".
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1284 2. enable it for the Roles that should have it (verify with
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1285 "``roundup-admin security``")
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1286 3. add it to the relevant HTML interface templates
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1287 4. add it to the appropriate xxxPermission methods on in your tracker
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1288 interfaces module
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1289
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1290 The ``addPermission`` method takes a couple of optional parameters:
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1291
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1292 **properties**
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1293 A sequence of property names that are the only properties to apply the
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1294 new Permission to (eg. ``... klass='user', properties=('name',
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1295 'email') ...``)
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1296 **check**
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1297 A function to be execute which returns boolean determining whether the
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1298 Permission is allowed. The function has the signature ``check(db, userid,
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1299 itemid)`` where ``db`` is a handle on the open database, ``userid`` is
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1300 the user attempting access and ``itemid`` is the specific item being
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1301 accessed.
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1302
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1303 Example Scenarios
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1304 ~~~~~~~~~~~~~~~~~
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1305
3126
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
1306 See the `examples`_ section for longer examples of customisation.
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
1307
3404
7d48c5b1e8f2 merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3363
diff changeset
1308 **anonymous access through the e-mail gateway**
7d48c5b1e8f2 merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3363
diff changeset
1309 Give the "anonymous" user the "Email Access", ("Edit", "issue") and
7d48c5b1e8f2 merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3363
diff changeset
1310 ("Create", "msg") Permissions but do not not give them the ("Create",
7d48c5b1e8f2 merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3363
diff changeset
1311 "user") Permission. This means that when an unknown user sends email
7d48c5b1e8f2 merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3363
diff changeset
1312 into the tracker, they're automatically logged in as "anonymous".
7d48c5b1e8f2 merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3363
diff changeset
1313 Since they don't have the ("Create", "user") Permission, they won't
7d48c5b1e8f2 merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3363
diff changeset
1314 be automatically registered, but since "anonymous" has permission to
7d48c5b1e8f2 merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3363
diff changeset
1315 use the gateway, they'll still be able to submit issues. Note that
7d48c5b1e8f2 merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3363
diff changeset
1316 the Sender information - their email address - will not be available
7d48c5b1e8f2 merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3363
diff changeset
1317 - they're *anonymous*.
7d48c5b1e8f2 merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3363
diff changeset
1318
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1319 **automatic registration of users in the e-mail gateway**
4296
72463e22640d fix some more documentation for the Register permission
Richard Jones <richard@users.sourceforge.net>
parents: 4088
diff changeset
1320 By giving the "anonymous" user the ("Register", "user") Permission, any
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1321 unidentified user will automatically be registered with the tracker
3404
7d48c5b1e8f2 merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3363
diff changeset
1322 (with no password, so they won't be able to log in through
3744
c07ae92cebbc doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3718
diff changeset
1323 the web until an admin sets their password). By default new Roundup
c07ae92cebbc doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3718
diff changeset
1324 trackers don't allow this as it opens them up to spam. It may be enabled
c07ae92cebbc doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3718
diff changeset
1325 by uncommenting the appropriate addPermissionToRole in your tracker's
c07ae92cebbc doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3718
diff changeset
1326 ``schema.py`` file. The new user is given the Roles list defined in the
3747
c3bba2c81a6f *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3744
diff changeset
1327 "new_email_user_roles" config variable.
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1328
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1329 **only developers may be assigned issues**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1330 Create a new Permission called "Fixer" for the "issue" class. Create a
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1331 new Role "Developer" which has that Permission, and assign that to the
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1332 appropriate users. Filter the list of users available in the assignedto
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1333 list to include only those users. Enforce the Permission with an
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1334 auditor. See the example
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1335 `restricting the list of users that are assignable to a task`_.
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1336
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1337 **only managers may sign off issues as complete**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1338 Create a new Permission called "Closer" for the "issue" class. Create a
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1339 new Role "Manager" which has that Permission, and assign that to the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1340 appropriate users. In your web interface, only display the "resolved"
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1341 issue state option when the user has the "Closer" Permissions. Enforce
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1342 the Permission with an auditor. This is very similar to the previous
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1343 example, except that the web interface check would look like::
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1344
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1345 <option tal:condition="python:request.user.hasPermission('Closer')"
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1346 value="resolved">Resolved</option>
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1347
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1348 **don't give web access to users who register through email**
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1349 Create a new Role called "Email User" which has all the Permissions of
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1350 the normal "User" Role minus the "Web Access" Permission. This will
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1351 allow users to send in emails to the tracker, but not access the web
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1352 interface.
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1353
1317
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1304
diff changeset
1354 **let some users edit the details of all users**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1355 Create a new Role called "User Admin" which has the Permission for
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1356 editing users::
1317
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1304
diff changeset
1357
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1304
diff changeset
1358 db.security.addRole(name='User Admin', description='Managing users')
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1304
diff changeset
1359 p = db.security.getPermission('Edit', 'user')
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1304
diff changeset
1360 db.security.addPermissionToRole('User Admin', p)
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1304
diff changeset
1361
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1304
diff changeset
1362 and assign the Role to the users who need the permission.
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1304
diff changeset
1363
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1364
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1365 Web Interface
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
1366 =============
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1367
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1368 .. contents::
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1369 :local:
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1370
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1371 The web interface is provided by the ``roundup.cgi.client`` module and
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1372 is used by ``roundup.cgi``, ``roundup-server`` and ``ZRoundup``
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1373 (``ZRoundup`` is broken, until further notice). In all cases, we
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1374 determine which tracker is being accessed (the first part of the URL
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1375 path inside the scope of the CGI handler) and pass control on to the
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
1376 ``roundup.cgi.client.Client`` class - which handles the rest of the
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
1377 access through its ``main()`` method. This means that you can do pretty
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
1378 much anything you want as a web interface to your tracker.
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
1379
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1380
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
1381
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1382 Repercussions of changing the tracker schema
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
1383 ---------------------------------------------
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1384
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1385 If you choose to change the `tracker schema`_ you will need to ensure
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1386 the web interface knows about it:
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1387
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1388 1. Index, item and search pages for the relevant classes may need to
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1389 have properties added or removed,
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1390 2. The "page" template may require links to be changed, as might the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1391 "home" page's content arguments.
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1392
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
1393
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
1394 How requests are processed
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
1395 --------------------------
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
1396
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1397 The basic processing of a web request proceeds as follows:
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1398
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1399 1. figure out who we are, defaulting to the "anonymous" user
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1400 2. figure out what the request is for - we call this the "context"
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1401 3. handle any requested action (item edit, search, ...)
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1402 4. render the template requested by the context, resulting in HTML
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1403 output
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1404
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1405 In some situations, exceptions occur:
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1406
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1407 - HTTP Redirect (generally raised by an action)
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1408 - SendFile (generally raised by ``determine_context``)
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1409 here we serve up a FileClass "content" property
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1410 - SendStaticFile (generally raised by ``determine_context``)
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1411 here we serve up a file from the tracker "html" directory
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1412 - Unauthorised (generally raised by an action)
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1413 here the action is cancelled, the request is rendered and an error
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1414 message is displayed indicating that permission was not granted for
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1415 the action to take place
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1416 - NotFound (raised wherever it needs to be)
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1417 this exception percolates up to the CGI interface that called the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1418 client
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1419
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
1420
4725
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1421 Roundup URL design
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1422 ------------------
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1423
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1424 Each tracker has several hardcoded URLs. These three are equivalent and
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1425 lead to the main tracker page:
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1426
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1427 1. ``/``
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1428 2. ``/index``
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1429 3. ``/home``
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1430
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1431 The following prefix is used to access static resources:
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1432
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1433 4. ``/@@file/``
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1434
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1435 All other URLs depend on the classes configured in Roundup database.
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1436 Each class receives two URLs - one for the class itself and another
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1437 for specific items of that class. Example for class URL:
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1438
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1439 5. ``/issue``
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1440
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1441 This is usually used to show listings of class items. The URL for
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1442 for specific object of issue class with id 1 will look like:
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1443
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1444 6. ``/issue1``
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1445
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1446
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
1447 Determining web context
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
1448 -----------------------
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
1449
4725
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1450 To determine the "context" of a request (what request is for), we look at
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1451 the URL path after the tracker root and at ``@template`` request
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1452 parameter. Typical URL paths look like:
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1453
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1454 1. ``/tracker/issue``
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1455 2. ``/tracker/issue1``
2589
809758599cdc oops, double-@
Richard Jones <richard@users.sourceforge.net>
parents: 2588
diff changeset
1456 3. ``/tracker/@@file/style.css``
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1457 4. ``/cgi-bin/roundup.cgi/tracker/file1``
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1458 5. ``/cgi-bin/roundup.cgi/tracker/file1/kitten.png``
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1459
4725
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1460 where tracker root is ``/tracker/`` or ``/cgi-bin/roundup.cgi/tracker/``
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1461 We're looking at "issue", "issue1", "@@file/style.css", "file1" and
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1462 "file1/kitten.png" in the cases above.
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1463
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1464 a. with is no path we are in the "home" context. See `the "home"
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1465 context`_ below for details. "index" or "home" paths may also be used
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1466 to switch into "home" context.
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1467 b. for paths starting with "@@file" the additional path entry ("style.css"
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1468 in the example above) specifies the static file to be served
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1469 from the tracker TEMPLATES directory (or STATIC_FILES, if configured).
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1470 This is usually the tracker's "html" directory. Internally this works
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1471 by raising SendStaticFile exception.
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1472 c. if there is something in the path (as in example 1, "issue"), it
4725
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1473 identifies the tracker class to display.
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1474 d. if the path is an item designator (as in examples 2 and 4, "issue1"
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1475 and "file1"), then we're to display a specific item.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1476 e. if the path starts with an item designator and is longer than one
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1477 entry (as in example 5, "file1/kitten.png"), then we're assumed to be
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1478 handling an item of a ``FileClass``, and the extra path information
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1479 gives the filename that the client is going to label the download
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1480 with (i.e. "file1/kitten.png" is nicer to download than "file1").
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1481 This raises a ``SendFile`` exception.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1482
5154
f608eeecf638 issue2550891: Allow subdir in template value. Anthony (antmail)
John Rouillard <rouilj@ieee.org>
parents: 5135
diff changeset
1483 Neither b. or e. use templates and stop before the template is
f608eeecf638 issue2550891: Allow subdir in template value. Anthony (antmail)
John Rouillard <rouilj@ieee.org>
parents: 5135
diff changeset
1484 determined. For other contexts the template used is specified by the
4725
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1485 ``@template`` variable, which defaults to:
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1486
5154
f608eeecf638 issue2550891: Allow subdir in template value. Anthony (antmail)
John Rouillard <rouilj@ieee.org>
parents: 5135
diff changeset
1487 - only classname supplied: "index"
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1488 - full item designator supplied: "item"
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1489
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
1490
2227
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1491 The "home" Context
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1492 ------------------
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1493
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1494 The "home" context is special because it allows you to add templated
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1495 pages to your tracker that don't rely on a class or item (ie. an issues
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1496 list or specific issue).
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1497
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1498 Let's say you wish to add frames to control the layout of your tracker's
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1499 interface. You'd probably have:
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1500
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1501 - A top-level frameset page. This page probably wouldn't be templated, so
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1502 it could be served as a static file (see `serving static content`_)
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1503 - A sidebar frame that is templated. Let's call this page
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1504 "home.navigation.html" in your tracker's "html" directory. To load that
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1505 page up, you use the URL:
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1506
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1507 <tracker url>/home?@template=navigation
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1508
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1509
2134
00dfd8b50773 doc clarification
Richard Jones <richard@users.sourceforge.net>
parents: 2129
diff changeset
1510 Serving static content
00dfd8b50773 doc clarification
Richard Jones <richard@users.sourceforge.net>
parents: 2129
diff changeset
1511 ----------------------
00dfd8b50773 doc clarification
Richard Jones <richard@users.sourceforge.net>
parents: 2129
diff changeset
1512
00dfd8b50773 doc clarification
Richard Jones <richard@users.sourceforge.net>
parents: 2129
diff changeset
1513 See the previous section `determining web context`_ where it describes
2589
809758599cdc oops, double-@
Richard Jones <richard@users.sourceforge.net>
parents: 2588
diff changeset
1514 ``@@file`` paths.
2134
00dfd8b50773 doc clarification
Richard Jones <richard@users.sourceforge.net>
parents: 2129
diff changeset
1515
00dfd8b50773 doc clarification
Richard Jones <richard@users.sourceforge.net>
parents: 2129
diff changeset
1516
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
1517 Performing actions in web requests
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
1518 ----------------------------------
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
1519
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
1520 When a user requests a web page, they may optionally also request for an
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
1521 action to take place. As described in `how requests are processed`_, the
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
1522 action is performed before the requested page is generated. Actions are
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1523 triggered by using a ``@action`` CGI variable, where the value is one
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1524 of:
1058
a55ef5a98fd3 more docco... and we need to check for web access Permission!
Richard Jones <richard@users.sourceforge.net>
parents: 1057
diff changeset
1525
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1526 **login**
1058
a55ef5a98fd3 more docco... and we need to check for web access Permission!
Richard Jones <richard@users.sourceforge.net>
parents: 1057
diff changeset
1527 Attempt to log a user in.
1278
0c0494deb09f doc for the retire action
Richard Jones <richard@users.sourceforge.net>
parents: 1270
diff changeset
1528
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1529 **logout**
1058
a55ef5a98fd3 more docco... and we need to check for web access Permission!
Richard Jones <richard@users.sourceforge.net>
parents: 1057
diff changeset
1530 Log the user out - make them "anonymous".
1278
0c0494deb09f doc for the retire action
Richard Jones <richard@users.sourceforge.net>
parents: 1270
diff changeset
1531
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1532 **register**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1533 Attempt to create a new user based on the contents of the form and then
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1534 log them in.
1278
0c0494deb09f doc for the retire action
Richard Jones <richard@users.sourceforge.net>
parents: 1270
diff changeset
1535
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1536 **edit**
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1537 Perform an edit of an item in the database. There are some `special form
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1538 variables`_ you may use.
1058
a55ef5a98fd3 more docco... and we need to check for web access Permission!
Richard Jones <richard@users.sourceforge.net>
parents: 1057
diff changeset
1539
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1540 **new**
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1541 Add a new item to the database. You may use the same `special form
5158
63294ed25e84 issue1842687: Keywords: After creating, stay in "Create New" mode.
John Rouillard <rouilj@ieee.org>
parents: 5156
diff changeset
1542 variables`_ as in the "edit" action. Also you can set the
63294ed25e84 issue1842687: Keywords: After creating, stay in "Create New" mode.
John Rouillard <rouilj@ieee.org>
parents: 5156
diff changeset
1543 ``__redirect_to`` form variable to the URL that should be displayed after
63294ed25e84 issue1842687: Keywords: After creating, stay in "Create New" mode.
John Rouillard <rouilj@ieee.org>
parents: 5156
diff changeset
1544 the new item is created. This is useful if you want to create another
63294ed25e84 issue1842687: Keywords: After creating, stay in "Create New" mode.
John Rouillard <rouilj@ieee.org>
parents: 5156
diff changeset
1545 item rather than edit the newly created item.
1058
a55ef5a98fd3 more docco... and we need to check for web access Permission!
Richard Jones <richard@users.sourceforge.net>
parents: 1057
diff changeset
1546
1278
0c0494deb09f doc for the retire action
Richard Jones <richard@users.sourceforge.net>
parents: 1270
diff changeset
1547 **retire**
0c0494deb09f doc for the retire action
Richard Jones <richard@users.sourceforge.net>
parents: 1270
diff changeset
1548 Retire the item in the database.
0c0494deb09f doc for the retire action
Richard Jones <richard@users.sourceforge.net>
parents: 1270
diff changeset
1549
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1550 **editCSV**
1058
a55ef5a98fd3 more docco... and we need to check for web access Permission!
Richard Jones <richard@users.sourceforge.net>
parents: 1057
diff changeset
1551 Performs an edit of all of a class' items in one go. See also the
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1552 *class*.csv templating method which generates the CSV data to be
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1553 edited, and the ``'_generic.index'`` template which uses both of these
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1554 features.
1058
a55ef5a98fd3 more docco... and we need to check for web access Permission!
Richard Jones <richard@users.sourceforge.net>
parents: 1057
diff changeset
1555
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1556 **search**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1557 Mangle some of the form variables:
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1558
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1559 - Set the form ":filter" variable based on the values of the filter
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1560 variables - if they're set to anything other than "dontcare" then add
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1561 them to :filter.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1562
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1563 - Also handle the ":queryname" variable and save off the query to the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1564 user's query list.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1565
2017
31d920b31642 Update customization examples too, expand upgrade notice a bit.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2016
diff changeset
1566 Each of the actions is implemented by a corresponding ``*XxxAction*`` (where
31d920b31642 Update customization examples too, expand upgrade notice a bit.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2016
diff changeset
1567 "Xxx" is the name of the action) class in the ``roundup.cgi.actions`` module.
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
1568 These classes are registered with ``roundup.cgi.client.Client``. If you need
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
1569 to define new actions, you may add them there (see `defining new
2017
31d920b31642 Update customization examples too, expand upgrade notice a bit.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2016
diff changeset
1570 web actions`_).
31d920b31642 Update customization examples too, expand upgrade notice a bit.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2016
diff changeset
1571
31d920b31642 Update customization examples too, expand upgrade notice a bit.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2016
diff changeset
1572 Each action class also has a ``*permission*`` method which determines whether
31d920b31642 Update customization examples too, expand upgrade notice a bit.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2016
diff changeset
1573 the action is permissible given the current user. The base permission checks
2991
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1574 for each action are:
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1575
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1576 **login**
2991
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1577 Determine whether the user has the "Web Access" Permission.
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1578 **logout**
1058
a55ef5a98fd3 more docco... and we need to check for web access Permission!
Richard Jones <richard@users.sourceforge.net>
parents: 1057
diff changeset
1579 No permission checks are made.
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1580 **register**
3404
7d48c5b1e8f2 merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3363
diff changeset
1581 Determine whether the user has the ("Create", "user") Permission.
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1582 **edit**
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1583 Determine whether the user has permission to edit this item. If we're
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1584 editing the "user" class, users are allowed to edit their own details -
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1585 unless they try to edit the "roles" property, which requires the
1058
a55ef5a98fd3 more docco... and we need to check for web access Permission!
Richard Jones <richard@users.sourceforge.net>
parents: 1057
diff changeset
1586 special Permission "Web Roles".
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1587 **new**
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1588 Determine whether the user has permission to create this item. No
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1589 additional property checks are made. Additionally, new user items may
3404
7d48c5b1e8f2 merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3363
diff changeset
1590 be created if the user has the ("Create", "user") Permission.
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1591 **editCSV**
2991
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1592 Determine whether the user has permission to edit this class.
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1593 **search**
2991
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1594 Determine whether the user has permission to view this class.
1058
a55ef5a98fd3 more docco... and we need to check for web access Permission!
Richard Jones <richard@users.sourceforge.net>
parents: 1057
diff changeset
1595
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1596
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1597 Special form variables
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1598 ----------------------
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1599
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1600 Item properties and their values are edited with html FORM
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1601 variables and their values. You can:
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1602
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1603 - Change the value of some property of the current item.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1604 - Create a new item of any class, and edit the new item's
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1605 properties,
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1606 - Attach newly created items to a multilink property of the
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1607 current item.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1608 - Remove items from a multilink property of the current item.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1609 - Specify that some properties are required for the edit
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1610 operation to be successful.
5158
63294ed25e84 issue1842687: Keywords: After creating, stay in "Create New" mode.
John Rouillard <rouilj@ieee.org>
parents: 5156
diff changeset
1611 - Redirect to a different page after creating a new item (new action
63294ed25e84 issue1842687: Keywords: After creating, stay in "Create New" mode.
John Rouillard <rouilj@ieee.org>
parents: 5156
diff changeset
1612 only, not edit action). Usually you end up on the page for the
63294ed25e84 issue1842687: Keywords: After creating, stay in "Create New" mode.
John Rouillard <rouilj@ieee.org>
parents: 5156
diff changeset
1613 created item.
3429
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1614 - Set up user interface locale.
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1615
3293
8897483a9f8b doc tweak
Richard Jones <richard@users.sourceforge.net>
parents: 3292
diff changeset
1616 These operations will only take place if the form action (the
8897483a9f8b doc tweak
Richard Jones <richard@users.sourceforge.net>
parents: 3292
diff changeset
1617 ``@action`` variable) is "edit" or "new".
8897483a9f8b doc tweak
Richard Jones <richard@users.sourceforge.net>
parents: 3292
diff changeset
1618
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1619 In the following, <bracketed> values are variable, "@" may be
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1620 either ":" or "@", and other text "required" is fixed.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1621
3429
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1622 Two special form variables are used to specify user language preferences:
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1623
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1624 ``@language``
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1625 value may be locale name or ``none``. If this variable is set to
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1626 locale name, web interface language is changed to given value
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1627 (provided that appropriate translation is available), the value
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1628 is stored in the browser cookie and will be used for all following
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1629 requests. If value is ``none`` the cookie is removed and the
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1630 language is changed to the tracker default, set up in the tracker
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1631 configuration or OS environment.
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1632
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1633 ``@charset``
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1634 value may be character set name or ``none``. Character set name
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1635 is stored in the browser cookie and sets output encoding for all
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1636 HTML pages generated by Roundup. If value is ``none`` the cookie
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1637 is removed and HTML output is reset to Roundup internal encoding
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1638 (UTF-8).
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1639
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1640 Most properties are specified as form variables:
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1641
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1642 ``<propname>``
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1643 property on the current context item
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1644
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1645 ``<designator>"@"<propname>``
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1646 property on the indicated item (for editing related information)
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1647
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1648 Designators name a specific item of a class.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1649
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1650 ``<classname><N>``
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1651 Name an existing item of class <classname>.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1652
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1653 ``<classname>"-"<N>``
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1654 Name the <N>th new item of class <classname>. If the form
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1655 submission is successful, a new item of <classname> is
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1656 created. Within the submitted form, a particular
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1657 designator of this form always refers to the same new
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1658 item.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1659
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1660 Once we have determined the "propname", we look at it to see
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1661 if it's special:
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1662
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1663 ``@required``
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1664 The associated form value is a comma-separated list of
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1665 property names that must be specified when the form is
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1666 submitted for the edit operation to succeed.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1667
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1668 When the <designator> is missing, the properties are
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1669 for the current context item. When <designator> is
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1670 present, they are for the item specified by
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1671 <designator>.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1672
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1673 The "@required" specifier must come before any of the
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1674 properties it refers to are assigned in the form.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1675
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1676 ``@remove@<propname>=id(s)`` or ``@add@<propname>=id(s)``
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1677 The "@add@" and "@remove@" edit actions apply only to
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1678 Multilink properties. The form value must be a
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1679 comma-separate list of keys for the class specified by
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1680 the simple form variable. The listed items are added
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1681 to (respectively, removed from) the specified
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1682 property.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1683
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1684 ``@link@<propname>=<designator>``
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1685 If the edit action is "@link@", the simple form
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1686 variable must specify a Link or Multilink property.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1687 The form value is a comma-separated list of
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1688 designators. The item corresponding to each
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1689 designator is linked to the property given by simple
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1690 form variable.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1691
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1692 None of the above (ie. just a simple form value)
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1693 The value of the form variable is converted
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1694 appropriately, depending on the type of the property.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1695
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1696 For a Link('klass') property, the form value is a
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1697 single key for 'klass', where the key field is
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1698 specified in schema.py.
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1699
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1700 For a Multilink('klass') property, the form value is a
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1701 comma-separated list of keys for 'klass', where the
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1702 key field is specified in schema.py.
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1703
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1704 Note that for simple-form-variables specifiying Link
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1705 and Multilink properties, the linked-to class must
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1706 have a key field.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1707
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1708 For a String() property specifying a filename, the
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1709 file named by the form value is uploaded. This means we
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1710 try to set additional properties "filename" and "type" (if
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1711 they are valid for the class). Otherwise, the property
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1712 is set to the form value.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1713
5067
e424987d294a Add support for an integer type to join the existing number type.
John Rouillard <rouilj@ieee.org>
parents: 5064
diff changeset
1714 For Date(), Interval(), Boolean(), Integer() and Number()
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1715 properties, the form value is converted to the
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1716 appropriate
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1717
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1718 Any of the form variables may be prefixed with a classname or
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1719 designator.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1720
5161
12190efa30d4 I realized that the __came_from and __redirect_to url parameters I
John Rouillard <rouilj@ieee.org>
parents: 5158
diff changeset
1721 Setting the form variable: ``__redirect_to=`` to a url when
12190efa30d4 I realized that the __came_from and __redirect_to url parameters I
John Rouillard <rouilj@ieee.org>
parents: 5158
diff changeset
1722 @action=new redirects the user to the specified url after successfully
12190efa30d4 I realized that the __came_from and __redirect_to url parameters I
John Rouillard <rouilj@ieee.org>
parents: 5158
diff changeset
1723 creating the new item. This is useful if you want the user to create
12190efa30d4 I realized that the __came_from and __redirect_to url parameters I
John Rouillard <rouilj@ieee.org>
parents: 5158
diff changeset
1724 another item rather than edit the newly created item. Note that the
12190efa30d4 I realized that the __came_from and __redirect_to url parameters I
John Rouillard <rouilj@ieee.org>
parents: 5158
diff changeset
1725 url assigned to ``__redirect_to`` must be url encoded/quoted and be
12190efa30d4 I realized that the __came_from and __redirect_to url parameters I
John Rouillard <rouilj@ieee.org>
parents: 5158
diff changeset
1726 under the tracker's base url. If the base_url uses http, you can set
12190efa30d4 I realized that the __came_from and __redirect_to url parameters I
John Rouillard <rouilj@ieee.org>
parents: 5158
diff changeset
1727 the url to https.
5158
63294ed25e84 issue1842687: Keywords: After creating, stay in "Create New" mode.
John Rouillard <rouilj@ieee.org>
parents: 5156
diff changeset
1728
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1729 Two special form values are supported for backwards compatibility:
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1730
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1731 @note
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1732 This is equivalent to::
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1733
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1734 @link@messages=msg-1
1918
Richard Jones <richard@users.sourceforge.net>
parents: 1850
diff changeset
1735 msg-1@content=value
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1736
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1737 except that in addition, the "author" and "date" properties of
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1738 "msg-1" are set to the userid of the submitter, and the current
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1739 time, respectively.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1740
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1741 @file
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1742 This is equivalent to::
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1743
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1744 @link@files=file-1
1918
Richard Jones <richard@users.sourceforge.net>
parents: 1850
diff changeset
1745 file-1@content=value
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1746
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1747 The String content value is handled as described above for file
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1748 uploads.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1749
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1750 If both the "@note" and "@file" form variables are
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1751 specified, the action::
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1752
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1753 @link@msg-1@files=file-1
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1754
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1755 is also performed.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1756
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1757 We also check that FileClass items have a "content" property with
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1758 actual content, otherwise we remove them from all_props before
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1759 returning.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1760
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1761
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
1762 Default templates
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
1763 -----------------
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
1764
1952
c40ed9113285 Applied Stefan Seefeld's html4/xhtml patch with some changes.
Richard Jones <richard@users.sourceforge.net>
parents: 1918
diff changeset
1765 The default templates are html4 compliant. If you wish to change them to be
2921
ad4fb8a14a97 more doc updates, not so many TODOs any more
Richard Jones <richard@users.sourceforge.net>
parents: 2915
diff changeset
1766 xhtml compliant, you'll need to change the ``html_version`` configuration
ad4fb8a14a97 more doc updates, not so many TODOs any more
Richard Jones <richard@users.sourceforge.net>
parents: 2915
diff changeset
1767 variable in ``config.ini`` to ``'xhtml'`` instead of ``'html4'``.
1952
c40ed9113285 Applied Stefan Seefeld's html4/xhtml patch with some changes.
Richard Jones <richard@users.sourceforge.net>
parents: 1918
diff changeset
1768
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1769 Most customisation of the web view can be done by modifying the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1770 templates in the tracker ``'html'`` directory. There are several types
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1771 of files in there. The *minimal* template includes:
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1772
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1773 **page.html**
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1774 This template usually defines the overall look of your tracker. When
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1775 you view an issue, it appears inside this template. When you view an
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1776 index, it also appears inside this template. This template defines a
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1777 macro called "icing" which is used by almost all other templates as a
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1778 coating for their content, using its "content" slot. It also defines
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1779 the "head_title" and "body_title" slots to allow setting of the page
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1780 title.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1781 **home.html**
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
1782 the default page displayed when no other page is indicated by the user
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1783 **home.classlist.html**
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1784 a special version of the default page that lists the classes in the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1785 tracker
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1786 **classname.item.html**
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
1787 displays an item of the *classname* class
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1788 **classname.index.html**
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
1789 displays a list of *classname* items
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1790 **classname.search.html**
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
1791 displays a search page for *classname* items
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1792 **_generic.index.html**
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1793 used to display a list of items where there is no
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1794 ``*classname*.index`` available
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1795 **_generic.help.html**
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1796 used to display a "class help" page where there is no
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1797 ``*classname*.help``
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1798 **user.register.html**
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1799 a special page just for the user class, that renders the registration
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1800 page
4435
386200d0c929 Some minor typos fixed in doc/customizing.txt (Thanks Ralf Hemmecke).
Bernhard Reiter <Bernhard.Reiter@intevation.de>
parents: 4406
diff changeset
1801 **style.css**
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
1802 a static file that is served up as-is
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1803
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1804 The *classic* template has a number of additional templates.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1805
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
1806 Remember that you can create any template extension you want to,
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1807 so if you just want to play around with the templating for new issues,
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1808 you can copy the current "issue.item" template to "issue.test", and then
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1809 access the test template using the "@template" URL argument::
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1810
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1811 http://your.tracker.example/tracker/issue?@template=test
1147
89b1a8a468e7 more doc, "fixer" example
Richard Jones <richard@users.sourceforge.net>
parents: 1144
diff changeset
1812
89b1a8a468e7 more doc, "fixer" example
Richard Jones <richard@users.sourceforge.net>
parents: 1144
diff changeset
1813 and it won't affect your users using the "issue.item" template.
89b1a8a468e7 more doc, "fixer" example
Richard Jones <richard@users.sourceforge.net>
parents: 1144
diff changeset
1814
5154
f608eeecf638 issue2550891: Allow subdir in template value. Anthony (antmail)
John Rouillard <rouilj@ieee.org>
parents: 5135
diff changeset
1815 You can also put templates into a subdirectory of the template
f608eeecf638 issue2550891: Allow subdir in template value. Anthony (antmail)
John Rouillard <rouilj@ieee.org>
parents: 5135
diff changeset
1816 directory. So if you specify::
f608eeecf638 issue2550891: Allow subdir in template value. Anthony (antmail)
John Rouillard <rouilj@ieee.org>
parents: 5135
diff changeset
1817
f608eeecf638 issue2550891: Allow subdir in template value. Anthony (antmail)
John Rouillard <rouilj@ieee.org>
parents: 5135
diff changeset
1818 http://your.tracker.example/tracker/issue?@template=test/item
f608eeecf638 issue2550891: Allow subdir in template value. Anthony (antmail)
John Rouillard <rouilj@ieee.org>
parents: 5135
diff changeset
1819
f608eeecf638 issue2550891: Allow subdir in template value. Anthony (antmail)
John Rouillard <rouilj@ieee.org>
parents: 5135
diff changeset
1820 you will use the template at: ``test/issue.item.html``. If that
f608eeecf638 issue2550891: Allow subdir in template value. Anthony (antmail)
John Rouillard <rouilj@ieee.org>
parents: 5135
diff changeset
1821 template doesn't exit it will try to use
f608eeecf638 issue2550891: Allow subdir in template value. Anthony (antmail)
John Rouillard <rouilj@ieee.org>
parents: 5135
diff changeset
1822 ``test/_generic.item.html``. If that template doesn't exist
f608eeecf638 issue2550891: Allow subdir in template value. Anthony (antmail)
John Rouillard <rouilj@ieee.org>
parents: 5135
diff changeset
1823 it will return an error.
1147
89b1a8a468e7 more doc, "fixer" example
Richard Jones <richard@users.sourceforge.net>
parents: 1144
diff changeset
1824
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1825 How the templates work
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
1826 ----------------------
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1827
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1828
4619
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1829 Templating engines
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1830 ~~~~~~~~~~~~~~~~~~
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1831
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1832 Since version 1.4.20 Roundup supports two templating engines: the original
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1833 `Template Attribute Language`_ (TAL) engine from Zope and the standalone
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1834 Chameleon templating engine. Chameleon is intended as a replacement for the
4723
42f6c76950a4 Cancel version bump to 1.5.0 - the impact is minimal, so just update
anatoly techtonik <techtonik@gmail.com>
parents: 4695
diff changeset
1835 original TAL engine, and supports the same syntax,
4619
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1836 but they are not 100% compatible. The major (and most likely the only)
4723
42f6c76950a4 Cancel version bump to 1.5.0 - the impact is minimal, so just update
anatoly techtonik <techtonik@gmail.com>
parents: 4695
diff changeset
1837 incompatibility is the default expression type being
4619
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1838 ``python:`` instead of ``path:``. See also "Incompatibilities and
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1839 differences" section of `Chameleon documentation`__.
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1840
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1841 **NOTE1**: For historical reasons, examples given below assumes path
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1842 expression as default expression type. With Chameleon you have to manually
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1843 resolve the path expressions. A Chameleon-based, z3c.pt, that is fully
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1844 compatible with the old TAL implementation, is planned to be included in a
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1845 future release.
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1846
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1847 **NOTE2**: As of 1.4.20 Chameleon support is highly experimental and **not**
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1848 recommended for production use.
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1849
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1850 .. _Chameleon:
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1851 http://chameleon.repoze.org/
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1852 .. _z3c.pt:
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1853 http://pypi.python.org/pypi/z3c.pt
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1854 __ http://chameleon.repoze.org/docs/latest/reference.html#incompatibilities-and-differences
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1855 .. _TAL:
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1856 .. _Template Attribute Language:
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1857 http://dev.zope.org/Wikis/DevSite/Projects/ZPT/TAL%20Specification%201.4
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1858
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1859
1214
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
1860 Basic Templating Actions
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
1861 ~~~~~~~~~~~~~~~~~~~~~~~~
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
1862
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1863 Roundup's templates consist of special attributes on the HTML tags.
4619
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1864 These attributes form the **Template Attribute Language**, or TAL.
2296
5092d44194dd added links to TAL specifications
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2227
diff changeset
1865 The basic TAL commands are:
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1866
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1867 **tal:define="variable expression; variable expression; ..."**
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1868 Define a new variable that is local to this tag and its contents. For
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1869 example::
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1870
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1871 <html tal:define="title request/description">
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1872 <head><title tal:content="title"></title></head>
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1873 </html>
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1874
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1875 In this example, the variable "title" is defined as the result of the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1876 expression "request/description". The "tal:content" command inside the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1877 <html> tag may then use the "title" variable.
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1878
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1879 **tal:condition="expression"**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1880 Only keep this tag and its contents if the expression is true. For
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1881 example::
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1882
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1883 <p tal:condition="python:request.user.hasPermission('View', 'issue')">
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1884 Display some issue information.
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1885 </p>
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1886
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1887 In the example, the <p> tag and its contents are only displayed if
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1888 the user has the "View" permission for issues. We consider the number
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1889 zero, a blank string, an empty list, and the built-in variable
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1890 nothing to be false values. Nearly every other value is true,
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1891 including non-zero numbers, and strings with anything in them (even
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1892 spaces!).
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1893
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1894 **tal:repeat="variable expression"**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1895 Repeat this tag and its contents for each element of the sequence
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1896 that the expression returns, defining a new local variable and a
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1897 special "repeat" variable for each element. For example::
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1898
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1899 <tr tal:repeat="u user/list">
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1900 <td tal:content="u/id"></td>
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1901 <td tal:content="u/username"></td>
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1902 <td tal:content="u/realname"></td>
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1903 </tr>
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1904
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1905 The example would iterate over the sequence of users returned by
2855
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
1906 "user/list" and define the local variable "u" for each entry. Using
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
1907 the repeat command creates a new variable called "repeat" which you
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
1908 may access to gather information about the iteration. See the section
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
1909 below on `the repeat variable`_.
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1910
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1911 **tal:replace="expression"**
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1912 Replace this tag with the result of the expression. For example::
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1913
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1914 <span tal:replace="request/user/realname" />
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1915
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1916 The example would replace the <span> tag and its contents with the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1917 user's realname. If the user's realname was "Bruce", then the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1918 resultant output would be "Bruce".
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1919
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1920 **tal:content="expression"**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1921 Replace the contents of this tag with the result of the expression.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1922 For example::
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1923
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1924 <span tal:content="request/user/realname">user's name appears here
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1925 </span>
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1926
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1927 The example would replace the contents of the <span> tag with the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1928 user's realname. If the user's realname was "Bruce" then the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1929 resultant output would be "<span>Bruce</span>".
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1930
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1931 **tal:attributes="attribute expression; attribute expression; ..."**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1932 Set attributes on this tag to the results of expressions. For
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1933 example::
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1934
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1935 <a tal:attributes="href string:user${request/user/id}">My Details</a>
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1936
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1937 In the example, the "href" attribute of the <a> tag is set to the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1938 value of the "string:user${request/user/id}" expression, which will
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1939 be something like "user123".
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1940
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1941 **tal:omit-tag="expression"**
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1942 Remove this tag (but not its contents) if the expression is true. For
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1943 example::
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1944
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1945 <span tal:omit-tag="python:1">Hello, world!</span>
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1946
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1947 would result in output of::
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1948
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1949 Hello, world!
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1950
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1951 Note that the commands on a given tag are evaulated in the order above,
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1952 so *define* comes before *condition*, and so on.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1953
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1954 Additionally, you may include tags such as <tal:block>, which are
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1955 removed from output. Its content is kept, but the tag itself is not (so
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1956 don't go using any "tal:attributes" commands on it). This is useful for
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1957 making arbitrary blocks of HTML conditional or repeatable (very handy
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1958 for repeating multiple table rows, which would othewise require an
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1959 illegal tag placement to effect the repeat).
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1960
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
1961
1214
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
1962 Templating Expressions
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
1963 ~~~~~~~~~~~~~~~~~~~~~~
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
1964
2296
5092d44194dd added links to TAL specifications
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2227
diff changeset
1965 Templating Expressions are covered by `Template Attribute Language
5092d44194dd added links to TAL specifications
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2227
diff changeset
1966 Expression Syntax`_, or TALES. The expressions you may use in the
5092d44194dd added links to TAL specifications
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2227
diff changeset
1967 attribute values may be one of the following forms:
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1968
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1969 **Path Expressions** - eg. ``item/status/checklist``
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1970 These are object attribute / item accesses. Roughly speaking, the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1971 path ``item/status/checklist`` is broken into parts ``item``,
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1972 ``status`` and ``checklist``. The ``item`` part is the root of the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1973 expression. We then look for a ``status`` attribute on ``item``, or
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1974 failing that, a ``status`` item (as in ``item['status']``). If that
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1975 fails, the path expression fails. When we get to the end, the object
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1976 we're left with is evaluated to get a string - if it is a method, it
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1977 is called; if it is an object, it is stringified. Path expressions
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1978 may have an optional ``path:`` prefix, but they are the default
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1979 expression type, so it's not necessary.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1980
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1981 If an expression evaluates to ``default``, then the expression is
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1982 "cancelled" - whatever HTML already exists in the template will
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1983 remain (tag content in the case of ``tal:content``, attributes in the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1984 case of ``tal:attributes``).
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1985
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1986 If an expression evaluates to ``nothing`` then the target of the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1987 expression is removed (tag content in the case of ``tal:content``,
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1988 attributes in the case of ``tal:attributes`` and the tag itself in
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1989 the case of ``tal:replace``).
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1990
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1991 If an element in the path may not exist, then you can use the ``|``
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1992 operator in the expression to provide an alternative. So, the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1993 expression ``request/form/foo/value | default`` would simply leave
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1994 the current HTML in place if the "foo" form variable doesn't exist.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1995
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1996 You may use the python function ``path``, as in
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1997 ``path("item/status")``, to embed path expressions in Python
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1998 expressions.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1999
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2000 **String Expressions** - eg. ``string:hello ${user/name}``
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2001 These expressions are simple string interpolations - though they can
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2002 be just plain strings with no interpolation if you want. The
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2003 expression in the ``${ ... }`` is just a path expression as above.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2004
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2005 **Python Expressions** - eg. ``python: 1+1``
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
2006 These expressions give the full power of Python. All the "root level"
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2007 variables are available, so ``python:item.status.checklist()`` would
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2008 be equivalent to ``item/status/checklist``, assuming that
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2009 ``checklist`` is a method.
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
2010
1448
bbb1e5f8fc93 added info about structure/not:/path()
Richard Jones <richard@users.sourceforge.net>
parents: 1436
diff changeset
2011 Modifiers:
bbb1e5f8fc93 added info about structure/not:/path()
Richard Jones <richard@users.sourceforge.net>
parents: 1436
diff changeset
2012
bbb1e5f8fc93 added info about structure/not:/path()
Richard Jones <richard@users.sourceforge.net>
parents: 1436
diff changeset
2013 **structure** - eg. ``structure python:msg.content.plain(hyperlink=1)``
bbb1e5f8fc93 added info about structure/not:/path()
Richard Jones <richard@users.sourceforge.net>
parents: 1436
diff changeset
2014 The result of expressions are normally *escaped* to be safe for HTML
bbb1e5f8fc93 added info about structure/not:/path()
Richard Jones <richard@users.sourceforge.net>
parents: 1436
diff changeset
2015 display (all "<", ">" and "&" are turned into special entities). The
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2016 ``structure`` expression modifier turns off this escaping - the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2017 result of the expression is now assumed to be HTML, which is passed
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2018 to the web browser for rendering.
1448
bbb1e5f8fc93 added info about structure/not:/path()
Richard Jones <richard@users.sourceforge.net>
parents: 1436
diff changeset
2019
bbb1e5f8fc93 added info about structure/not:/path()
Richard Jones <richard@users.sourceforge.net>
parents: 1436
diff changeset
2020 **not:** - eg. ``not:python:1=1``
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2021 This simply inverts the logical true/false value of another
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2022 expression.
1448
bbb1e5f8fc93 added info about structure/not:/path()
Richard Jones <richard@users.sourceforge.net>
parents: 1436
diff changeset
2023
2296
5092d44194dd added links to TAL specifications
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2227
diff changeset
2024 .. _TALES:
5092d44194dd added links to TAL specifications
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2227
diff changeset
2025 .. _Template Attribute Language Expression Syntax:
5092d44194dd added links to TAL specifications
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2227
diff changeset
2026 http://dev.zope.org/Wikis/DevSite/Projects/ZPT/TALES%20Specification%201.3
1448
bbb1e5f8fc93 added info about structure/not:/path()
Richard Jones <richard@users.sourceforge.net>
parents: 1436
diff changeset
2027
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
2028
1214
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
2029 Template Macros
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
2030 ~~~~~~~~~~~~~~~
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
2031
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2032 Macros are used in Roundup to save us from repeating the same common
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2033 page stuctures over and over. The most common (and probably only) macro
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2034 you'll use is the "icing" macro defined in the "page" template.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2035
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2036 Macros are generated and used inside your templates using special
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2037 attributes similar to the `basic templating actions`_. In this case,
2296
5092d44194dd added links to TAL specifications
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2227
diff changeset
2038 though, the attributes belong to the `Macro Expansion Template
5092d44194dd added links to TAL specifications
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2227
diff changeset
2039 Attribute Language`_, or METAL. The macro commands are:
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2040
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2041 **metal:define-macro="macro name"**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2042 Define that the tag and its contents are now a macro that may be
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2043 inserted into other templates using the *use-macro* command. For
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2044 example::
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2045
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2046 <html metal:define-macro="page">
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2047 ...
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2048 </html>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2049
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2050 defines a macro called "page" using the ``<html>`` tag and its
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2051 contents. Once defined, macros are stored on the template they're
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2052 defined on in the ``macros`` attribute. You can access them later on
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2053 through the ``templates`` variable, eg. the most common
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2054 ``templates/page/macros/icing`` to access the "page" macro of the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2055 "page" template.
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2056
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2057 **metal:use-macro="path expression"**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2058 Use a macro, which is identified by the path expression (see above).
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2059 This will replace the current tag with the identified macro contents.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2060 For example::
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2061
1214
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
2062 <tal:block metal:use-macro="templates/page/macros/icing">
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2063 ...
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2064 </tal:block>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2065
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2066 will replace the tag and its contents with the "page" macro of the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2067 "page" template.
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2068
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2069 **metal:define-slot="slot name"** and **metal:fill-slot="slot name"**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2070 To define *dynamic* parts of the macro, you define "slots" which may
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2071 be filled when the macro is used with a *use-macro* command. For
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2072 example, the ``templates/page/macros/icing`` macro defines a slot like
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2073 so::
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2074
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2075 <title metal:define-slot="head_title">title goes here</title>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2076
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2077 In your *use-macro* command, you may now use a *fill-slot* command
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2078 like this::
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2079
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2080 <title metal:fill-slot="head_title">My Title</title>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2081
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2082 where the tag that fills the slot completely replaces the one defined
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2083 as the slot in the macro.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2084
2296
5092d44194dd added links to TAL specifications
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2227
diff changeset
2085 Note that you may not mix `METAL`_ and `TAL`_ commands on the same tag, but
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2086 TAL commands may be used freely inside METAL-using tags (so your
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2087 *fill-slots* tags may have all manner of TAL inside them).
1214
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
2088
2296
5092d44194dd added links to TAL specifications
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2227
diff changeset
2089 .. _METAL:
5092d44194dd added links to TAL specifications
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2227
diff changeset
2090 .. _Macro Expansion Template Attribute Language:
5092d44194dd added links to TAL specifications
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2227
diff changeset
2091 http://dev.zope.org/Wikis/DevSite/Projects/ZPT/METAL%20Specification%201.0
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2092
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2093 Information available to templates
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
2094 ----------------------------------
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2095
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
2096 This is implemented by ``roundup.cgi.templating.RoundupPageTemplate``
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
2097
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2098 The following variables are available to templates.
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2099
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
2100 **context**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2101 The current context. This is either None, a `hyperdb class wrapper`_
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2102 or a `hyperdb item wrapper`_
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
2103 **request**
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2104 Includes information about the current request, including:
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2105 - the current index information (``filterspec``, ``filter`` args,
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2106 ``properties``, etc) parsed out of the form.
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2107 - methods for easy filterspec link generation
3968
5857cd1a0db9 add language to the "request" template var
Richard Jones <richard@users.sourceforge.net>
parents: 3922
diff changeset
2108 - "form"
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2109 The current CGI form information as a mapping of form argument name
3968
5857cd1a0db9 add language to the "request" template var
Richard Jones <richard@users.sourceforge.net>
parents: 3922
diff changeset
2110 to value (specifically a cgi.FieldStorage)
5857cd1a0db9 add language to the "request" template var
Richard Jones <richard@users.sourceforge.net>
parents: 3922
diff changeset
2111 - "env" the CGI environment variables
5857cd1a0db9 add language to the "request" template var
Richard Jones <richard@users.sourceforge.net>
parents: 3922
diff changeset
2112 - "base" the base URL for this instance
5857cd1a0db9 add language to the "request" template var
Richard Jones <richard@users.sourceforge.net>
parents: 3922
diff changeset
2113 - "user" a HTMLItem instance for the current user
5857cd1a0db9 add language to the "request" template var
Richard Jones <richard@users.sourceforge.net>
parents: 3922
diff changeset
2114 - "language" as determined by the browser or config
5857cd1a0db9 add language to the "request" template var
Richard Jones <richard@users.sourceforge.net>
parents: 3922
diff changeset
2115 - "classname" the current classname (possibly None)
5857cd1a0db9 add language to the "request" template var
Richard Jones <richard@users.sourceforge.net>
parents: 3922
diff changeset
2116 - "template" the current template (suffix, also possibly None)
1254
77920c42aeb9 Expose the tracker config as a variable for templating
Richard Jones <richard@users.sourceforge.net>
parents: 1252
diff changeset
2117 **config**
2921
ad4fb8a14a97 more doc updates, not so many TODOs any more
Richard Jones <richard@users.sourceforge.net>
parents: 2915
diff changeset
2118 This variable holds all the values defined in the tracker config.ini
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2119 file (eg. TRACKER_NAME, etc.)
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
2120 **db**
1254
77920c42aeb9 Expose the tracker config as a variable for templating
Richard Jones <richard@users.sourceforge.net>
parents: 1252
diff changeset
2121 The current database, used to access arbitrary database items.
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2122 **templates**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2123 Access to all the tracker templates by name. Used mainly in
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2124 *use-macro* commands.
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2125 **utils**
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2126 This variable makes available some utility functions like batching.
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
2127 **nothing**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2128 This is a special variable - if an expression evaluates to this, then
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2129 the tag (in the case of a ``tal:replace``), its contents (in the case
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2130 of ``tal:content``) or some attributes (in the case of
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2131 ``tal:attributes``) will not appear in the the output. So, for
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2132 example::
1100
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2133
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2134 <span tal:attributes="class nothing">Hello, World!</span>
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2135
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2136 would result in::
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2137
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2138 <span>Hello, World!</span>
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2139
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
2140 **default**
1100
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2141 Also a special variable - if an expression evaluates to this, then the
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2142 existing HTML in the template will not be replaced or removed, it will
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2143 remain. So::
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2144
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2145 <span tal:replace="default">Hello, World!</span>
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2146
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2147 would result in::
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2148
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2149 <span>Hello, World!</span>
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2150
2526
dfe0bde4ff7f "Information available to templates": 'true' and 'false' constants
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2511
diff changeset
2151 **true**, **false**
dfe0bde4ff7f "Information available to templates": 'true' and 'false' constants
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2511
diff changeset
2152 Boolean constants that may be used in `templating expressions`_
dfe0bde4ff7f "Information available to templates": 'true' and 'false' constants
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2511
diff changeset
2153 instead of ``python:1`` and ``python:0``.
2540
bad572863a85 "Information available to templates": i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2526
diff changeset
2154 **i18n**
bad572863a85 "Information available to templates": i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2526
diff changeset
2155 Internationalization service, providing two string translation methods:
bad572863a85 "Information available to templates": i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2526
diff changeset
2156
bad572863a85 "Information available to templates": i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2526
diff changeset
2157 **gettext** (*message*)
bad572863a85 "Information available to templates": i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2526
diff changeset
2158 Return the localized translation of message
bad572863a85 "Information available to templates": i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2526
diff changeset
2159 **ngettext** (*singular*, *plural*, *number*)
bad572863a85 "Information available to templates": i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2526
diff changeset
2160 Like ``gettext()``, but consider plural forms. If a translation
bad572863a85 "Information available to templates": i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2526
diff changeset
2161 is found, apply the plural formula to *number*, and return the
bad572863a85 "Information available to templates": i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2526
diff changeset
2162 resulting message (some languages have more than two plural forms).
bad572863a85 "Information available to templates": i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2526
diff changeset
2163 If no translation is found, return singular if *number* is 1;
bad572863a85 "Information available to templates": i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2526
diff changeset
2164 return plural otherwise.
bad572863a85 "Information available to templates": i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2526
diff changeset
2165
bad572863a85 "Information available to templates": i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2526
diff changeset
2166 This function requires python2.3; in earlier python versions
bad572863a85 "Information available to templates": i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2526
diff changeset
2167 may not work as expected.
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2168
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2169 The context variable
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
2170 ~~~~~~~~~~~~~~~~~~~~
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2171
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2172 The *context* variable is one of three things based on the current
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2173 context (see `determining web context`_ for how we figure this out):
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2174
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2175 1. if we're looking at a "home" page, then it's None
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2176 2. if we're looking at a specific hyperdb class, it's a
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2177 `hyperdb class wrapper`_.
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2178 3. if we're looking at a specific hyperdb item, it's a
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2179 `hyperdb item wrapper`_.
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2180
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2181 If the context is not None, we can access the properties of the class or
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2182 item. The only real difference between cases 2 and 3 above are:
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2183
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2184 1. the properties may have a real value behind them, and this will
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2185 appear if the property is displayed through ``context/property`` or
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2186 ``context/property/field``.
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2187 2. the context's "id" property will be a false value in the second case,
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2188 but a real, or true value in the third. Thus we can determine whether
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2189 we're looking at a real item from the hyperdb by testing
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2190 "context/id".
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2191
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2192 Hyperdb class wrapper
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2193 :::::::::::::::::::::
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2194
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
2195 This is implemented by the ``roundup.cgi.templating.HTMLClass``
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2196 class.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2197
4435
386200d0c929 Some minor typos fixed in doc/customizing.txt (Thanks Ralf Hemmecke).
Bernhard Reiter <Bernhard.Reiter@intevation.de>
parents: 4406
diff changeset
2198 This wrapper object provides access to a hyperdb class. It is used
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2199 primarily in both index view and new item views, but it's also usable
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2200 anywhere else that you wish to access information about a class, or the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2201 items of a class, when you don't have a specific item of that class in
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2202 mind.
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2203
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2204 We allow access to properties. There will be no "id" property. The value
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2205 accessed through the property will be the current value of the same name
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2206 from the CGI form.
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2207
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2208 There are several methods available on these wrapper objects:
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2209
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2210 =========== =============================================================
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2211 Method Description
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2212 =========== =============================================================
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2213 properties return a `hyperdb property wrapper`_ for all of this class's
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2214 properties.
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2215 list lists all of the active (not retired) items in the class.
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2216 csv return the items of this class as a chunk of CSV text.
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2217 propnames lists the names of the properties of this class.
2858
0357a9c93933 fix filter() doc
Richard Jones <richard@users.sourceforge.net>
parents: 2855
diff changeset
2218 filter lists of items from this class, filtered and sorted. Two
0357a9c93933 fix filter() doc
Richard Jones <richard@users.sourceforge.net>
parents: 2855
diff changeset
2219 options are avaible for sorting:
0357a9c93933 fix filter() doc
Richard Jones <richard@users.sourceforge.net>
parents: 2855
diff changeset
2220
0357a9c93933 fix filter() doc
Richard Jones <richard@users.sourceforge.net>
parents: 2855
diff changeset
2221 1. by the current *request* filterspec/filter/sort/group args
0357a9c93933 fix filter() doc
Richard Jones <richard@users.sourceforge.net>
parents: 2855
diff changeset
2222 2. by the "filterspec", "sort" and "group" keyword args.
0357a9c93933 fix filter() doc
Richard Jones <richard@users.sourceforge.net>
parents: 2855
diff changeset
2223 "filterspec" is ``{propname: value(s)}``. "sort" and
3696
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2224 "group" are an optionally empty list ``[(dir, prop)]``
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2225 where dir is '+', '-' or None
2858
0357a9c93933 fix filter() doc
Richard Jones <richard@users.sourceforge.net>
parents: 2855
diff changeset
2226 and prop is a prop name or None.
0357a9c93933 fix filter() doc
Richard Jones <richard@users.sourceforge.net>
parents: 2855
diff changeset
2227
3718
0d561b24ceff support sqlite3
Richard Jones <richard@users.sourceforge.net>
parents: 3717
diff changeset
2228 The propname in filterspec and prop in a sort/group spec
0d561b24ceff support sqlite3
Richard Jones <richard@users.sourceforge.net>
parents: 3717
diff changeset
2229 may be transitive, i.e., it may contain properties of
0d561b24ceff support sqlite3
Richard Jones <richard@users.sourceforge.net>
parents: 3717
diff changeset
2230 the form link.link.link.name.
0d561b24ceff support sqlite3
Richard Jones <richard@users.sourceforge.net>
parents: 3717
diff changeset
2231
0d561b24ceff support sqlite3
Richard Jones <richard@users.sourceforge.net>
parents: 3717
diff changeset
2232 eg. All issues with a priority of "1" with messages added in
0d561b24ceff support sqlite3
Richard Jones <richard@users.sourceforge.net>
parents: 3717
diff changeset
2233 the last week, sorted by activity date:
0d561b24ceff support sqlite3
Richard Jones <richard@users.sourceforge.net>
parents: 3717
diff changeset
2234 ``issue.filter(filterspec={"priority": "1",
0d561b24ceff support sqlite3
Richard Jones <richard@users.sourceforge.net>
parents: 3717
diff changeset
2235 'messages.creation' : '.-1w;'}, sort=[('activity', '+')])``
2858
0357a9c93933 fix filter() doc
Richard Jones <richard@users.sourceforge.net>
parents: 2855
diff changeset
2236
3688
722ab52d47fc added filter_sql to SQL backends which takes an arbitrary SQL statement...
Richard Jones <richard@users.sourceforge.net>
parents: 3660
diff changeset
2237 filter_sql **Only in SQL backends**
722ab52d47fc added filter_sql to SQL backends which takes an arbitrary SQL statement...
Richard Jones <richard@users.sourceforge.net>
parents: 3660
diff changeset
2238
722ab52d47fc added filter_sql to SQL backends which takes an arbitrary SQL statement...
Richard Jones <richard@users.sourceforge.net>
parents: 3660
diff changeset
2239 Lists the items that match the SQL provided. The SQL is a
722ab52d47fc added filter_sql to SQL backends which takes an arbitrary SQL statement...
Richard Jones <richard@users.sourceforge.net>
parents: 3660
diff changeset
2240 complete "select" statement.
722ab52d47fc added filter_sql to SQL backends which takes an arbitrary SQL statement...
Richard Jones <richard@users.sourceforge.net>
parents: 3660
diff changeset
2241
722ab52d47fc added filter_sql to SQL backends which takes an arbitrary SQL statement...
Richard Jones <richard@users.sourceforge.net>
parents: 3660
diff changeset
2242 The SQL select must include the item id as the first column.
722ab52d47fc added filter_sql to SQL backends which takes an arbitrary SQL statement...
Richard Jones <richard@users.sourceforge.net>
parents: 3660
diff changeset
2243
722ab52d47fc added filter_sql to SQL backends which takes an arbitrary SQL statement...
Richard Jones <richard@users.sourceforge.net>
parents: 3660
diff changeset
2244 This function **does not** filter out retired items, add
722ab52d47fc added filter_sql to SQL backends which takes an arbitrary SQL statement...
Richard Jones <richard@users.sourceforge.net>
parents: 3660
diff changeset
2245 on a where clause "__retired__ <> 1" if you don't want
722ab52d47fc added filter_sql to SQL backends which takes an arbitrary SQL statement...
Richard Jones <richard@users.sourceforge.net>
parents: 3660
diff changeset
2246 retired nodes.
722ab52d47fc added filter_sql to SQL backends which takes an arbitrary SQL statement...
Richard Jones <richard@users.sourceforge.net>
parents: 3660
diff changeset
2247
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2248 classhelp display a link to a javascript popup containing this class'
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2249 "help" template.
3363
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2250
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2251 This generates a link to a popup window which displays the
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2252 properties indicated by "properties" of the class named by
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2253 "classname". The "properties" should be a comma-separated list
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2254 (eg. 'id,name,description'). Properties defaults to all the
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2255 properties of a class (excluding id, creator, created and
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2256 activity).
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2257
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2258 You may optionally override the "label" displayed, the "width",
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2259 the "height", the number of items per page ("pagesize") and
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2260 the field on which the list is sorted ("sort").
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2261
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2262 With the "filter" arg it is possible to specify a filter for
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2263 which items are supposed to be displayed. It has to be of
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2264 the format "<field>=<values>;<field>=<values>;...".
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2265
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2266 The popup window will be resizable and scrollable.
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2267
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2268 If the "property" arg is given, it's passed through to the
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2269 javascript help_window function. This allows updating of a
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2270 property in the calling HTML page.
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2271
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2272 If the "form" arg is given, it's passed through to the
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2273 javascript help_window function - it's the name of the form
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2274 the "property" belongs to.
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2275
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2276 submit generate a submit button (and action hidden element)
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2277 renderWith render this class with the given template.
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2278 history returns 'New node - no history' :)
1136
7e193bbda38e added generic item editing
Richard Jones <richard@users.sourceforge.net>
parents: 1133
diff changeset
2279 is_edit_ok is the user allowed to Edit the current class?
7e193bbda38e added generic item editing
Richard Jones <richard@users.sourceforge.net>
parents: 1133
diff changeset
2280 is_view_ok is the user allowed to View the current class?
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2281 =========== =============================================================
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2282
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2283 Note that if you have a property of the same name as one of the above
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2284 methods, you'll need to access it using a python "item access"
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2285 expression. For example::
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2286
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2287 python:context['list']
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2288
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2289 will access the "list" property, rather than the list method.
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2290
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2291
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2292 Hyperdb item wrapper
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2293 ::::::::::::::::::::
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2294
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
2295 This is implemented by the ``roundup.cgi.templating.HTMLItem``
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2296 class.
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2297
4435
386200d0c929 Some minor typos fixed in doc/customizing.txt (Thanks Ralf Hemmecke).
Bernhard Reiter <Bernhard.Reiter@intevation.de>
parents: 4406
diff changeset
2298 This wrapper object provides access to a hyperdb item.
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2299
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2300 We allow access to properties. There will be no "id" property. The value
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2301 accessed through the property will be the current value of the same name
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2302 from the CGI form.
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2303
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2304 There are several methods available on these wrapper objects:
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2305
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2306 =============== ========================================================
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2307 Method Description
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2308 =============== ========================================================
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2309 submit generate a submit button (and action hidden element)
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2310 journal return the journal of the current item (**not
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2311 implemented**)
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2312 history render the journal of the current item as HTML
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2313 renderQueryForm specific to the "query" class - render the search form
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2314 for the query
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2315 hasPermission specific to the "user" class - determine whether the
2991
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
2316 user has a Permission. The signature is::
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
2317
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
2318 hasPermission(self, permission, [classname=],
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
2319 [property=], [itemid=])
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
2320
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
2321 where the classname defaults to the current context.
3535
75dc225613cc fix security check for hasPermission(Permission, None)
Richard Jones <richard@users.sourceforge.net>
parents: 3510
diff changeset
2322 hasRole specific to the "user" class - determine whether the
75dc225613cc fix security check for hasPermission(Permission, None)
Richard Jones <richard@users.sourceforge.net>
parents: 3510
diff changeset
2323 user has a Role. The signature is::
75dc225613cc fix security check for hasPermission(Permission, None)
Richard Jones <richard@users.sourceforge.net>
parents: 3510
diff changeset
2324
75dc225613cc fix security check for hasPermission(Permission, None)
Richard Jones <richard@users.sourceforge.net>
parents: 3510
diff changeset
2325 hasRole(self, rolename)
75dc225613cc fix security check for hasPermission(Permission, None)
Richard Jones <richard@users.sourceforge.net>
parents: 3510
diff changeset
2326
1136
7e193bbda38e added generic item editing
Richard Jones <richard@users.sourceforge.net>
parents: 1133
diff changeset
2327 is_edit_ok is the user allowed to Edit the current item?
7e193bbda38e added generic item editing
Richard Jones <richard@users.sourceforge.net>
parents: 1133
diff changeset
2328 is_view_ok is the user allowed to View the current item?
2154
9f6e6bc40a08 fixes and release announcement
Richard Jones <richard@users.sourceforge.net>
parents: 2153
diff changeset
2329 is_retired is the item retired?
3510
ef80a6c02e09 describe copy_url method of hyperdb item wrapper
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3476
diff changeset
2330 download_url generate a url-quoted link for download of FileClass
2180
58b6d1747973 Web interface tweaks.
Richard Jones <richard@users.sourceforge.net>
parents: 2159
diff changeset
2331 item contents (ie. file<id>/<name>)
3510
ef80a6c02e09 describe copy_url method of hyperdb item wrapper
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3476
diff changeset
2332 copy_url generate a url-quoted link for creating a copy
ef80a6c02e09 describe copy_url method of hyperdb item wrapper
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3476
diff changeset
2333 of this item. By default, the copy will acquire
ef80a6c02e09 describe copy_url method of hyperdb item wrapper
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3476
diff changeset
2334 all properties of the current item except for
ef80a6c02e09 describe copy_url method of hyperdb item wrapper
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3476
diff changeset
2335 ``messages`` and ``files``. This can be overridden
ef80a6c02e09 describe copy_url method of hyperdb item wrapper
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3476
diff changeset
2336 by passing ``exclude`` argument which contains a list
ef80a6c02e09 describe copy_url method of hyperdb item wrapper
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3476
diff changeset
2337 (or any iterable) of property names that shall not be
ef80a6c02e09 describe copy_url method of hyperdb item wrapper
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3476
diff changeset
2338 copied. Database-driven properties like ``id`` or
ef80a6c02e09 describe copy_url method of hyperdb item wrapper
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3476
diff changeset
2339 ``activity`` cannot be copied.
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2340 =============== ========================================================
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2341
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2342 Note that if you have a property of the same name as one of the above
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2343 methods, you'll need to access it using a python "item access"
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2344 expression. For example::
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2345
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2346 python:context['journal']
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2347
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2348 will access the "journal" property, rather than the journal method.
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2349
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2350
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2351 Hyperdb property wrapper
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2352 ::::::::::::::::::::::::
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2353
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
2354 This is implemented by subclasses of the
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2355 ``roundup.cgi.templating.HTMLProperty`` class (``HTMLStringProperty``,
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2356 ``HTMLNumberProperty``, and so on).
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2357
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2358 This wrapper object provides access to a single property of a class. Its
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2359 value may be either:
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2360
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2361 1. if accessed through a `hyperdb item wrapper`_, then it's a value from
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2362 the hyperdb
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2363 2. if access through a `hyperdb class wrapper`_, then it's a value from
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2364 the CGI form
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2365
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2366
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2367 The property wrapper has some useful attributes:
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2368
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2369 =============== ========================================================
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2370 Attribute Description
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2371 =============== ========================================================
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2372 _name the name of the property
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2373 _value the value of the property if any - this is the actual
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2374 value retrieved from the hyperdb for this property
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2375 =============== ========================================================
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2376
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2377 There are several methods available on these wrapper objects:
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2378
1773
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2379 =========== ================================================================
1780
d2801a2b0a77 Initial implementation (half-baked) at new Tracker instance.
Richard Jones <richard@users.sourceforge.net>
parents: 1777
diff changeset
2380 Method Description
1773
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2381 =========== ================================================================
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2382 plain render a "plain" representation of the property. This method
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2383 may take two arguments:
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2384
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2385 escape
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2386 If true, escape the text so it is HTML safe (default: no). The
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2387 reason this defaults to off is that text is usually escaped
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2388 at a later stage by the TAL commands, unless the "structure"
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2389 option is used in the template. The following ``tal:content``
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2390 expressions are all equivalent::
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2391
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2392 "structure python:msg.content.plain(escape=1)"
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2393 "python:msg.content.plain()"
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2394 "msg/content/plain"
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2395 "msg/content"
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2396
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2397 Usually you'll only want to use the escape option in a
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2398 complex expression.
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2399
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2400 hyperlink
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2401 If true, turn URLs, email addresses and hyperdb item
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2402 designators in the text into hyperlinks (default: no). Note
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2403 that you'll need to use the "structure" TAL option if you
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2404 want to use this ``tal:content`` expression::
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2405
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2406 "structure python:msg.content.plain(hyperlink=1)"
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2407
2958
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2408 The text is automatically HTML-escaped before the hyperlinking
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2409 transformation done in the plain() method.
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2410
1773
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2411 hyperlinked The same as msg.content.plain(hyperlink=1), but nicer::
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2412
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2413 "structure msg/content/hyperlinked"
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2414
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2415 field render an appropriate form edit field for the property - for
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2416 most types this is a text entry box, but for Booleans it's a
2958
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2417 tri-state yes/no/neither selection. This method may take some
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2418 arguments:
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2419
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2420 size
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2421 Sets the width in characters of the edit field
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2422
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2423 format (Date properties only)
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2424 Sets the format of the date in the field - uses the same
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2425 format string argument as supplied to the ``pretty`` method
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2426 below.
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2427
3649
12633662ff63 include the popcal in Date field editing and search fields by default
Richard Jones <richard@users.sourceforge.net>
parents: 3648
diff changeset
2428 popcal (Date properties only)
12633662ff63 include the popcal in Date field editing and search fields by default
Richard Jones <richard@users.sourceforge.net>
parents: 3648
diff changeset
2429 Include the Javascript-based popup calendar for date
12633662ff63 include the popcal in Date field editing and search fields by default
Richard Jones <richard@users.sourceforge.net>
parents: 3648
diff changeset
2430 selection. Defaults to on.
12633662ff63 include the popcal in Date field editing and search fields by default
Richard Jones <richard@users.sourceforge.net>
parents: 3648
diff changeset
2431
1773
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2432 stext only on String properties - render the value of the property
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2433 as StructuredText (requires the StructureText module to be
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2434 installed separately)
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2435 multiline only on String properties - render a multiline form edit
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2436 field for the property
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2437 email only on String properties - render the value of the property
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2438 as an obscured email address
5156
882fa4d9bead issue2550795: @dispname query args in page.html search links
John Rouillard <rouilj@ieee.org>
parents: 5154
diff changeset
2439 url_quote only on String properties. It quotes any characters in the
882fa4d9bead issue2550795: @dispname query args in page.html search links
John Rouillard <rouilj@ieee.org>
parents: 5154
diff changeset
2440 string so it is safe to use in a url. E.G. a space is
882fa4d9bead issue2550795: @dispname query args in page.html search links
John Rouillard <rouilj@ieee.org>
parents: 5154
diff changeset
2441 replaced with %20.
1773
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2442 confirm only on Password properties - render a second form edit field
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2443 for the property, used for confirmation that the user typed
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2444 the password correctly. Generates a field with name
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2445 "name:confirm".
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2446 now only on Date properties - return the current date as a new
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2447 property
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2448 reldate only on Date properties - render the interval between the date
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2449 and now
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2450 local only on Date properties - return this date as a new property
2007
55046bb7f789 tweaking
Richard Jones <richard@users.sourceforge.net>
parents: 2003
diff changeset
2451 with some timezone offset, for example::
55046bb7f789 tweaking
Richard Jones <richard@users.sourceforge.net>
parents: 2003
diff changeset
2452
55046bb7f789 tweaking
Richard Jones <richard@users.sourceforge.net>
parents: 2003
diff changeset
2453 python:context.creation.local(10)
55046bb7f789 tweaking
Richard Jones <richard@users.sourceforge.net>
parents: 2003
diff changeset
2454
55046bb7f789 tweaking
Richard Jones <richard@users.sourceforge.net>
parents: 2003
diff changeset
2455 will render the date with a +10 hour offset.
2088
90769be53b4b doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 2076
diff changeset
2456 pretty Date properties - render the date as "dd Mon YYYY" (eg. "19
90769be53b4b doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 2076
diff changeset
2457 Mar 2004"). Takes an optional format argument, for example::
90769be53b4b doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 2076
diff changeset
2458
90769be53b4b doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 2076
diff changeset
2459 python:context.activity.pretty('%Y-%m-%d')
90769be53b4b doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 2076
diff changeset
2460
90769be53b4b doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 2076
diff changeset
2461 Will format as "2004-03-19" instead.
90769be53b4b doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 2076
diff changeset
2462
90769be53b4b doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 2076
diff changeset
2463 Interval properties - render the interval in a pretty
2958
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2464 format (eg. "yesterday"). The format arguments are those used
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2465 in the standard ``strftime`` call (see the `Python Library
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2466 Reference: time module`__)
3292
8c7b522dc934 added date selection popup windows (thanks Marcus Priesch)
Richard Jones <richard@users.sourceforge.net>
parents: 3291
diff changeset
2467 popcal Generate a link to a popup calendar which may be used to
8c7b522dc934 added date selection popup windows (thanks Marcus Priesch)
Richard Jones <richard@users.sourceforge.net>
parents: 3291
diff changeset
2468 edit the date field, for example::
8c7b522dc934 added date selection popup windows (thanks Marcus Priesch)
Richard Jones <richard@users.sourceforge.net>
parents: 3291
diff changeset
2469
3597
Richard Jones <richard@users.sourceforge.net>
parents: 3590
diff changeset
2470 <span tal:replace="structure context/due/popcal" />
3292
8c7b522dc934 added date selection popup windows (thanks Marcus Priesch)
Richard Jones <richard@users.sourceforge.net>
parents: 3291
diff changeset
2471
3647
d4112ddfc0bb doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 3597
diff changeset
2472 you still need to include the ``field`` for the property, so
3648
d1b38bde7d5a fix rest
Richard Jones <richard@users.sourceforge.net>
parents: 3647
diff changeset
2473 typically you'd have::
3647
d4112ddfc0bb doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 3597
diff changeset
2474
d4112ddfc0bb doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 3597
diff changeset
2475 <span tal:replace="structure context/due/field" />
d4112ddfc0bb doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 3597
diff changeset
2476 <span tal:replace="structure context/due/popcal" />
d4112ddfc0bb doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 3597
diff changeset
2477
1773
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2478 menu only on Link and Multilink properties - render a form select
3127
021b131bd816 doc fixes, one more fix to the permissions-in-listings fix
Richard Jones <richard@users.sourceforge.net>
parents: 3126
diff changeset
2479 list for this property. Takes a number of optional arguments
021b131bd816 doc fixes, one more fix to the permissions-in-listings fix
Richard Jones <richard@users.sourceforge.net>
parents: 3126
diff changeset
2480
021b131bd816 doc fixes, one more fix to the permissions-in-listings fix
Richard Jones <richard@users.sourceforge.net>
parents: 3126
diff changeset
2481 size
021b131bd816 doc fixes, one more fix to the permissions-in-listings fix
Richard Jones <richard@users.sourceforge.net>
parents: 3126
diff changeset
2482 is used to limit the length of the list labels
021b131bd816 doc fixes, one more fix to the permissions-in-listings fix
Richard Jones <richard@users.sourceforge.net>
parents: 3126
diff changeset
2483 height
021b131bd816 doc fixes, one more fix to the permissions-in-listings fix
Richard Jones <richard@users.sourceforge.net>
parents: 3126
diff changeset
2484 is used to set the <select> tag's "size" attribute
021b131bd816 doc fixes, one more fix to the permissions-in-listings fix
Richard Jones <richard@users.sourceforge.net>
parents: 3126
diff changeset
2485 showid
021b131bd816 doc fixes, one more fix to the permissions-in-listings fix
Richard Jones <richard@users.sourceforge.net>
parents: 3126
diff changeset
2486 includes the item ids in the list labels
021b131bd816 doc fixes, one more fix to the permissions-in-listings fix
Richard Jones <richard@users.sourceforge.net>
parents: 3126
diff changeset
2487 additional
021b131bd816 doc fixes, one more fix to the permissions-in-listings fix
Richard Jones <richard@users.sourceforge.net>
parents: 3126
diff changeset
2488 lists properties which should be included in the label
021b131bd816 doc fixes, one more fix to the permissions-in-listings fix
Richard Jones <richard@users.sourceforge.net>
parents: 3126
diff changeset
2489 sort_on
021b131bd816 doc fixes, one more fix to the permissions-in-listings fix
Richard Jones <richard@users.sourceforge.net>
parents: 3126
diff changeset
2490 indicates the property to sort the list on as (direction,
3363
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2491 (direction, property) where direction is '+' or '-'. A
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2492 single string with the direction prepended may be used.
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2493 For example: ('-', 'order'), '+name'.
3470
fd32170475f5 allow preselection of values in templating menu()s (patch [SF#1396085])
Richard Jones <richard@users.sourceforge.net>
parents: 3463
diff changeset
2494 value
fd32170475f5 allow preselection of values in templating menu()s (patch [SF#1396085])
Richard Jones <richard@users.sourceforge.net>
parents: 3463
diff changeset
2495 gives a default value to preselect in the menu
3127
021b131bd816 doc fixes, one more fix to the permissions-in-listings fix
Richard Jones <richard@users.sourceforge.net>
parents: 3126
diff changeset
2496
021b131bd816 doc fixes, one more fix to the permissions-in-listings fix
Richard Jones <richard@users.sourceforge.net>
parents: 3126
diff changeset
2497 The remaining keyword arguments are used as conditions for
021b131bd816 doc fixes, one more fix to the permissions-in-listings fix
Richard Jones <richard@users.sourceforge.net>
parents: 3126
diff changeset
2498 filtering the items in the list - they're passed as the
3597
Richard Jones <richard@users.sourceforge.net>
parents: 3590
diff changeset
2499 "filterspec" argument to a Class.filter() call. For example::
Richard Jones <richard@users.sourceforge.net>
parents: 3590
diff changeset
2500
Richard Jones <richard@users.sourceforge.net>
parents: 3590
diff changeset
2501 <span tal:replace="structure context/status/menu" />
Richard Jones <richard@users.sourceforge.net>
parents: 3590
diff changeset
2502
Richard Jones <richard@users.sourceforge.net>
parents: 3590
diff changeset
2503 <span tal:replace="python:context.status.menu(order='+name",
Richard Jones <richard@users.sourceforge.net>
parents: 3590
diff changeset
2504 value='chatting',
Richard Jones <richard@users.sourceforge.net>
parents: 3590
diff changeset
2505 filterspec={'status': '1,2,3,4'}" />
3127
021b131bd816 doc fixes, one more fix to the permissions-in-listings fix
Richard Jones <richard@users.sourceforge.net>
parents: 3126
diff changeset
2506
2883
1ca5ebe9b16a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2858
diff changeset
2507 sorted only on Multilink properties - produce a list of the linked
1ca5ebe9b16a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2858
diff changeset
2508 items sorted by some property, for example::
1ca5ebe9b16a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2858
diff changeset
2509
1ca5ebe9b16a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2858
diff changeset
2510 python:context.files.sorted('creation')
1ca5ebe9b16a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2858
diff changeset
2511
1ca5ebe9b16a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2858
diff changeset
2512 Will list the files by upload date.
1773
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2513 reverse only on Multilink properties - produce a list of the linked
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2514 items in reverse order
2180
58b6d1747973 Web interface tweaks.
Richard Jones <richard@users.sourceforge.net>
parents: 2159
diff changeset
2515 isset returns True if the property has been set to a value
1773
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2516 =========== ================================================================
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2517
2958
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2518 __ http://docs.python.org/lib/module-time.html
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2519
2138
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
2520 All of the above functions perform checks for permissions required to
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
2521 display or edit the data they are manipulating. The simplest case is
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
2522 editing an issue title. Including the expression::
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
2523
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
2524 context/title/field
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
2525
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
2526 Will present the user with an edit field, if they have edit permission. If
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
2527 not, then they will be presented with a static display if they have view
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
2528 permission. If they don't even have view permission, then an error message
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
2529 is raised, preventing the display of the page, indicating that they don't
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
2530 have permission to view the information.
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
2531
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2532
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2533 The request variable
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
2534 ~~~~~~~~~~~~~~~~~~~~
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2535
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
2536 This is implemented by the ``roundup.cgi.templating.HTMLRequest``
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2537 class.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2538
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2539 The request variable is packed with information about the current
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2540 request.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2541
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2542 .. taken from ``roundup.cgi.templating.HTMLRequest`` docstring
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2543
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2544 =========== ============================================================
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2545 Variable Holds
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2546 =========== ============================================================
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2547 form the CGI form as a cgi.FieldStorage
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2548 env the CGI environment variables
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1083
diff changeset
2549 base the base URL for this tracker
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2550 user a HTMLUser instance for this user
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2551 classname the current classname (possibly None)
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2552 template the current template (suffix, also possibly None)
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2553 form the current CGI form variables in a FieldStorage
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2554 =========== ============================================================
1083
40fc5f8cd55c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1074
diff changeset
2555
40fc5f8cd55c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1074
diff changeset
2556 **Index page specific variables (indexing arguments)**
40fc5f8cd55c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1074
diff changeset
2557
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2558 =========== ============================================================
1083
40fc5f8cd55c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1074
diff changeset
2559 Variable Holds
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2560 =========== ============================================================
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2561 columns dictionary of the columns to display in an index page
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2562 show a convenience access to columns - request/show/colname will
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
2563 be true if the columns should be displayed, false otherwise
3696
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2564 sort index sort columns [(direction, column name)]
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2565 group index grouping properties [(direction, column name)]
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2566 filter properties to filter the index on
3718
0d561b24ceff support sqlite3
Richard Jones <richard@users.sourceforge.net>
parents: 3717
diff changeset
2567 filterspec values to filter the index on (property=value, eg
0d561b24ceff support sqlite3
Richard Jones <richard@users.sourceforge.net>
parents: 3717
diff changeset
2568 ``priority=1`` or ``messages.author=42``
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2569 search_text text to perform a full-text search on for an index
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2570 =========== ============================================================
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2571
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2572 There are several methods available on the request variable:
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2573
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2574 =============== ========================================================
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2575 Method Description
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2576 =============== ========================================================
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2577 description render a description of the request - handle for the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2578 page title
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2579 indexargs_form render the current index args as form elements
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2580 indexargs_url render the current index args as a URL
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2581 base_javascript render some javascript that is used by other components
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2582 of the templating
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2583 batch run the current index args through a filter and return a
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2584 list of items (see `hyperdb item wrapper`_, and
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2585 `batching`_)
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2586 =============== ========================================================
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2587
1142
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2588 The form variable
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2589 :::::::::::::::::
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2590
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2591 The form variable is a bit special because it's actually a python
1142
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2592 FieldStorage object. That means that you have two ways to access its
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2593 contents. For example, to look up the CGI form value for the variable
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2594 "name", use the path expression::
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2595
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2596 request/form/name/value
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2597
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2598 or the python expression::
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2599
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2600 python:request.form['name'].value
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2601
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2602 Note the "item" access used in the python case, and also note the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2603 explicit "value" attribute we have to access. That's because the form
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2604 variables are stored as MiniFieldStorages. If there's more than one
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2605 "name" value in the form, then the above will break since
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2606 ``request/form/name`` is actually a *list* of MiniFieldStorages. So it's
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2607 best to know beforehand what you're dealing with.
1142
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2608
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2609
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2610 The db variable
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2611 ~~~~~~~~~~~~~~~
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2612
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
2613 This is implemented by the ``roundup.cgi.templating.HTMLDatabase``
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2614 class.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2615
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2616 Allows access to all hyperdb classes as attributes of this variable. If
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2617 you want access to the "user" class, for example, you would use::
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2618
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2619 db/user
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2620 python:db.user
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2621
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1680
diff changeset
2622 Also, the current id of the current user is available as
1800
a3b1b1dcf639 Use getuid(), not figure_curuserid()
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1780
diff changeset
2623 ``db.getuid()``. This isn't so useful in templates (where you have
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1680
diff changeset
2624 ``request/user``), but it can be useful in detectors or interfaces.
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1680
diff changeset
2625
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2626 The access results in a `hyperdb class wrapper`_.
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2627
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2628
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2629 The templates variable
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2630 ~~~~~~~~~~~~~~~~~~~~~~
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2631
4723
42f6c76950a4 Cancel version bump to 1.5.0 - the impact is minimal, so just update
anatoly techtonik <techtonik@gmail.com>
parents: 4695
diff changeset
2632 This was implemented by the ``roundup.cgi.templating.Templates``
42f6c76950a4 Cancel version bump to 1.5.0 - the impact is minimal, so just update
anatoly techtonik <techtonik@gmail.com>
parents: 4695
diff changeset
2633 class before 1.4.20. In later versions it is the instance of appropriate
42f6c76950a4 Cancel version bump to 1.5.0 - the impact is minimal, so just update
anatoly techtonik <techtonik@gmail.com>
parents: 4695
diff changeset
2634 template engine loader class.
42f6c76950a4 Cancel version bump to 1.5.0 - the impact is minimal, so just update
anatoly techtonik <techtonik@gmail.com>
parents: 4695
diff changeset
2635
42f6c76950a4 Cancel version bump to 1.5.0 - the impact is minimal, so just update
anatoly techtonik <techtonik@gmail.com>
parents: 4695
diff changeset
2636 This variable is used to access other templates in expressions and
42f6c76950a4 Cancel version bump to 1.5.0 - the impact is minimal, so just update
anatoly techtonik <techtonik@gmail.com>
parents: 4695
diff changeset
2637 template macros. It doesn't have any useful methods defined. The
42f6c76950a4 Cancel version bump to 1.5.0 - the impact is minimal, so just update
anatoly techtonik <techtonik@gmail.com>
parents: 4695
diff changeset
2638 templates can be accessed using the following path expression::
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2639
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2640 templates/name
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2641
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2642 or the python expression::
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2643
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2644 templates[name]
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2645
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2646 where "name" is the name of the template you wish to access. The
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2647 template has one useful attribute, namely "macros". To access a specific
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2648 macro (called "macro_name"), use the path expression::
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2649
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2650 templates/name/macros/macro_name
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2651
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2652 or the python expression::
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2653
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2654 templates[name].macros[macro_name]
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2655
2855
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2656 The repeat variable
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2657 ~~~~~~~~~~~~~~~~~~~
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2658
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2659 The repeat variable holds an entry for each active iteration. That is, if
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2660 you have a ``tal:repeat="user db/users"`` command, then there will be a
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2661 repeat variable entry called "user". This may be accessed as either::
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2662
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2663 repeat/user
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2664 python:repeat['user']
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2665
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2666 The "user" entry has a number of methods available for information:
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2667
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2668 =============== =========================================================
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2669 Method Description
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2670 =============== =========================================================
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2671 first True if the current item is the first in the sequence.
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2672 last True if the current item is the last in the sequence.
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2673 even True if the current item is an even item in the sequence.
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2674 odd True if the current item is an odd item in the sequence.
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2675 number Current position in the sequence, starting from 1.
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2676 letter Current position in the sequence as a letter, a through
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2677 z, then aa through zz, and so on.
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2678 Letter Same as letter(), except uppercase.
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2679 roman Current position in the sequence as lowercase roman
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2680 numerals.
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2681 Roman Same as roman(), except uppercase.
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2682 =============== =========================================================
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2683
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2684
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2685 The utils variable
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2686 ~~~~~~~~~~~~~~~~~~
4921
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
2687 .. _templating utilities:
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2688
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
2689 This is implemented by the
4921
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
2690 ``roundup.cgi.templating.TemplatingUtils`` class, which may be extended
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
2691 with additional methods by extensions_.
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2692
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2693 =============== ========================================================
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2694 Method Description
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2695 =============== ========================================================
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2696 Batch return a batch object using the supplied list
2180
58b6d1747973 Web interface tweaks.
Richard Jones <richard@users.sourceforge.net>
parents: 2159
diff changeset
2697 url_quote quote some text as safe for a URL (ie. space, %, ...)
58b6d1747973 Web interface tweaks.
Richard Jones <richard@users.sourceforge.net>
parents: 2159
diff changeset
2698 html_quote quote some text as safe in HTML (ie. <, >, ...)
3292
8c7b522dc934 added date selection popup windows (thanks Marcus Priesch)
Richard Jones <richard@users.sourceforge.net>
parents: 3291
diff changeset
2699 html_calendar renders an HTML calendar used by the
8c7b522dc934 added date selection popup windows (thanks Marcus Priesch)
Richard Jones <richard@users.sourceforge.net>
parents: 3291
diff changeset
2700 ``_generic.calendar.html`` template (itself invoked by
8c7b522dc934 added date selection popup windows (thanks Marcus Priesch)
Richard Jones <richard@users.sourceforge.net>
parents: 3291
diff changeset
2701 the popupCalendar DateHTMLProperty method
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2702 =============== ========================================================
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2703
1270
c3424abf7f77 added ability to implement new templating utility methods
Richard Jones <richard@users.sourceforge.net>
parents: 1262
diff changeset
2704
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2705 Batching
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2706 ::::::::
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2707
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2708 Use Batch to turn a list of items, or item ids of a given class, into a
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2709 series of batches. Its usage is::
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2710
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2711 python:utils.Batch(sequence, size, start, end=0, orphan=0,
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2712 overlap=0)
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2713
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2714 or, to get the current index batch::
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2715
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2716 request/batch
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2717
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2718 The parameters are:
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2719
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2720 ========= ==============================================================
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2721 Parameter Usage
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2722 ========= ==============================================================
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2723 sequence a list of HTMLItems
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2724 size how big to make the sequence.
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2725 start where to start (0-indexed) in the sequence.
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2726 end where to end (0-indexed) in the sequence.
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2727 orphan if the next batch would contain less items than this value,
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2728 then it is combined with this batch
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2729 overlap the number of items shared between adjacent batches
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2730 ========= ==============================================================
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2731
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2732 All of the parameters are assigned as attributes on the batch object. In
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2733 addition, it has several more attributes:
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2734
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2735 =============== ========================================================
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2736 Attribute Description
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2737 =============== ========================================================
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
2738 start indicates the start index of the batch. *Unlike
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2739 the argument, is a 1-based index (I know, lame)*
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2740 first indicates the start index of the batch *as a 0-based
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2741 index*
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2742 length the actual number of elements in the batch
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2743 sequence_length the length of the original, unbatched, sequence.
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2744 =============== ========================================================
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2745
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2746 And several methods:
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2747
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2748 =============== ========================================================
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2749 Method Description
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2750 =============== ========================================================
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2751 previous returns a new Batch with the previous batch settings
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2752 next returns a new Batch with the next batch settings
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2753 propchanged detect if the named property changed on the current item
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2754 when compared to the last item
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2755 =============== ========================================================
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2756
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2757 An example of batching::
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2758
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2759 <table class="otherinfo">
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2760 <tr><th colspan="4" class="header">Existing Keywords</th></tr>
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2761 <tr tal:define="keywords db/keyword/list"
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2762 tal:repeat="start python:range(0, len(keywords), 4)">
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2763 <td tal:define="batch python:utils.Batch(keywords, 4, start)"
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2764 tal:repeat="keyword batch" tal:content="keyword/name">
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2765 keyword here</td>
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2766 </tr>
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2767 </table>
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2768
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2769 ... which will produce a table with four columns containing the items of
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2770 the "keyword" class (well, their "name" anyway).
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2771
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
2772
4325
6ec048310de7 add simple doc about translating customised tracker content
Richard Jones <richard@users.sourceforge.net>
parents: 4300
diff changeset
2773 Translations
6ec048310de7 add simple doc about translating customised tracker content
Richard Jones <richard@users.sourceforge.net>
parents: 4300
diff changeset
2774 ~~~~~~~~~~~~
6ec048310de7 add simple doc about translating customised tracker content
Richard Jones <richard@users.sourceforge.net>
parents: 4300
diff changeset
2775
6ec048310de7 add simple doc about translating customised tracker content
Richard Jones <richard@users.sourceforge.net>
parents: 4300
diff changeset
2776 Should you wish to enable multiple languages in template content that you
6ec048310de7 add simple doc about translating customised tracker content
Richard Jones <richard@users.sourceforge.net>
parents: 4300
diff changeset
2777 create you'll need to add new locale files in the tracker home under a
6ec048310de7 add simple doc about translating customised tracker content
Richard Jones <richard@users.sourceforge.net>
parents: 4300
diff changeset
2778 ``locale`` directory. Use the instructions in the ``developer's guide`` to
6ec048310de7 add simple doc about translating customised tracker content
Richard Jones <richard@users.sourceforge.net>
parents: 4300
diff changeset
2779 create the locale files.
6ec048310de7 add simple doc about translating customised tracker content
Richard Jones <richard@users.sourceforge.net>
parents: 4300
diff changeset
2780
6ec048310de7 add simple doc about translating customised tracker content
Richard Jones <richard@users.sourceforge.net>
parents: 4300
diff changeset
2781
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2782 Displaying Properties
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
2783 ---------------------
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2784
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2785 Properties appear in the user interface in three contexts: in indices,
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2786 in editors, and as search arguments. For each type of property, there
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2787 are several display possibilities. For example, in an index view, a
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2788 string property may just be printed as a plain string, but in an editor
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2789 view, that property may be displayed in an editable field.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2790
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2791
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2792 Index Views
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
2793 -----------
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2794
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2795 This is one of the class context views. It is also the default view for
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2796 classes. The template used is "*classname*.index".
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2797
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2798
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2799 Index View Specifiers
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
2800 ~~~~~~~~~~~~~~~~~~~~~
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2801
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2802 An index view specifier (URL fragment) looks like this (whitespace has
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2803 been added for clarity)::
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2804
3036
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2805 /issue?status=unread,in-progress,resolved&
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
2806 keyword=security,ui&
3696
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2807 @group=priority,-status&
3036
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2808 @sort=-activity&
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
2809 @filters=status,keyword&
3036
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2810 @columns=title,status,fixer
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2811
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2812 The index view is determined by two parts of the specifier: the layout
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2813 part and the filter part. The layout part consists of the query
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2814 parameters that begin with colons, and it determines the way that the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2815 properties of selected items are displayed. The filter part consists of
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2816 all the other query parameters, and it determines the criteria by which
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2817 items are selected for display. The filter part is interactively
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2818 manipulated with the form widgets displayed in the filter section. The
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2819 layout part is interactively manipulated by clicking on the column
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2820 headings in the table.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2821
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2822 The filter part selects the union of the sets of items with values
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2823 matching any specified Link properties and the intersection of the sets
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2824 of items with values matching any specified Multilink properties.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2825
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2826 The example specifies an index of "issue" items. Only items with a
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2827 "status" of either "unread" or "in-progress" or "resolved" are
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
2828 displayed, and only items with "keyword" values including both "security"
3696
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2829 and "ui" are displayed. The items are grouped by priority arranged in
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2830 ascending order and in descending order by status; and within
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2831 groups, sorted by activity, arranged in descending order. The filter
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
2832 section shows filters for the "status" and "keyword" properties, and the
3696
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2833 table includes columns for the "title", "status", and "fixer"
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2834 properties.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2835
3036
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2836 ============ =============================================================
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2837 Argument Description
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2838 ============ =============================================================
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2839 @sort sort by prop name, optionally preceeded with '-' to give
3696
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2840 descending or nothing for ascending sorting. Several
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2841 properties can be specified delimited with comma.
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2842 Internally a search-page using several sort properties may
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2843 use @sort0, @sort1 etc. with option @sortdir0, @sortdir1
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2844 etc. for the direction of sorting (a non-empty value of
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2845 sortdir0 specifies reverse order).
3036
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2846 @group group by prop name, optionally preceeded with '-' or to sort
3696
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2847 in descending or nothing for ascending order. Several
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2848 properties can be specified delimited with comma.
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2849 Internally a search-page using several grouping properties may
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2850 use @group0, @group1 etc. with option @groupdir0, @groupdir1
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2851 etc. for the direction of grouping (a non-empty value of
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2852 groupdir0 specifies reverse order).
3036
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2853 @columns selects the columns that should be displayed. Default is
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2854 all.
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2855 @filter indicates which properties are being used in filtering.
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2856 Default is none.
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2857 propname selects the values the item properties given by propname must
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2858 have (very basic search/filter).
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2859 @search_text if supplied, performs a full-text search (message bodies,
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2860 issue titles, etc)
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2861 ============ =============================================================
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2862
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
2863
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
2864 Searching Views
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
2865 ---------------
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2866
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
2867 .. note::
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
2868 if you add a new column to the ``@columns`` form variable potentials
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
2869 then you will need to add the column to the appropriate `index views`_
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
2870 template so that it is actually displayed.
1320
3758a5af985f Lots of little fixes in this update:
Richard Jones <richard@users.sourceforge.net>
parents: 1317
diff changeset
2871
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2872 This is one of the class context views. The template used is typically
1245
d8c98af869ff merge from maint-0-5
Richard Jones <richard@users.sourceforge.net>
parents: 1244
diff changeset
2873 "*classname*.search". The form on this page should have "search" as its
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
2874 ``@action`` variable. The "search" action:
1245
d8c98af869ff merge from maint-0-5
Richard Jones <richard@users.sourceforge.net>
parents: 1244
diff changeset
2875
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2876 - sets up additional filtering, as well as performing indexed text
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2877 searching
3036
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2878 - sets the ``@filter`` variable correctly
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2879 - saves the query off if ``@query_name`` is set.
1245
d8c98af869ff merge from maint-0-5
Richard Jones <richard@users.sourceforge.net>
parents: 1244
diff changeset
2880
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2881 The search page should lay out any fields that you wish to allow the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2882 user to search on. If your schema contains a large number of properties,
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2883 you should be wary of making all of those properties available for
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2884 searching, as this can cause confusion. If the additional properties are
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2885 Strings, consider having their value indexed, and then they will be
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2886 searchable using the full text indexed search. This is both faster, and
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2887 more useful for the end user.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2888
3036
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2889 If the search view does specify the "search" ``@action``, then it may also
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2890 provide an additional argument:
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2891
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2892 ============ =============================================================
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2893 Argument Description
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2894 ============ =============================================================
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2895 @query_name if supplied, the index parameters (including @search_text)
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2896 will be saved off as a the query item and registered against
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2897 the user's queries property. Note that the *classic* template
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2898 schema has this ability, but the *minimal* template schema
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2899 does not.
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2900 ============ =============================================================
1245
d8c98af869ff merge from maint-0-5
Richard Jones <richard@users.sourceforge.net>
parents: 1244
diff changeset
2901
d8c98af869ff merge from maint-0-5
Richard Jones <richard@users.sourceforge.net>
parents: 1244
diff changeset
2902
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2903 Item Views
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
2904 ----------
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2905
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2906 The basic view of a hyperdb item is provided by the "*classname*.item"
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2907 template. It generally has three sections; an "editor", a "spool" and a
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2908 "history" section.
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2909
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2910
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2911 Editor Section
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
2912 ~~~~~~~~~~~~~~
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2913
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2914 The editor section is used to manipulate the item - it may be a static
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2915 display if the user doesn't have permission to edit the item.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2916
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2917 Here's an example of a basic editor template (this is the default
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2918 "classic" template issue item edit form - from the "issue.item.html"
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2919 template)::
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2920
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2921 <table class="form">
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2922 <tr>
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
2923 <th>Title</th>
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2924 <td colspan="3" tal:content="structure python:context.title.field(size=60)">title</td>
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2925 </tr>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2926
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2927 <tr>
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
2928 <th>Priority</th>
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2929 <td tal:content="structure context/priority/menu">priority</td>
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
2930 <th>Status</th>
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2931 <td tal:content="structure context/status/menu">status</td>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2932 </tr>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2933
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2934 <tr>
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
2935 <th>Superseder</th>
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2936 <td>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2937 <span tal:replace="structure python:context.superseder.field(showid=1, size=20)" />
1113
a95428868bf4 Added the missing keyword/topic interface to classic template (blush)
Richard Jones <richard@users.sourceforge.net>
parents: 1100
diff changeset
2938 <span tal:replace="structure python:db.issue.classhelp('id,title')" />
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2939 <span tal:condition="context/superseder">
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2940 <br>View: <span tal:replace="structure python:context.superseder.link(showid=1)" />
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2941 </span>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2942 </td>
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
2943 <th>Nosy List</th>
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2944 <td>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2945 <span tal:replace="structure context/nosy/field" />
1113
a95428868bf4 Added the missing keyword/topic interface to classic template (blush)
Richard Jones <richard@users.sourceforge.net>
parents: 1100
diff changeset
2946 <span tal:replace="structure python:db.user.classhelp('username,realname,address,phone')" />
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2947 </td>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2948 </tr>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2949
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2950 <tr>
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
2951 <th>Assigned To</th>
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2952 <td tal:content="structure context/assignedto/menu">
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2953 assignedto menu
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2954 </td>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2955 <td>&nbsp;</td>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2956 <td>&nbsp;</td>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2957 </tr>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2958
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2959 <tr>
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
2960 <th>Change Note</th>
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2961 <td colspan="3">
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1083
diff changeset
2962 <textarea name=":note" wrap="hard" rows="5" cols="60"></textarea>
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2963 </td>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2964 </tr>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2965
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2966 <tr>
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
2967 <th>File</th>
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2968 <td colspan="3"><input type="file" name=":file" size="40"></td>
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2969 </tr>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2970
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2971 <tr>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2972 <td>&nbsp;</td>
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2973 <td colspan="3" tal:content="structure context/submit">
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2974 submit button will go here
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2975 </td>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2976 </tr>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2977 </table>
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2978
673
604c84696461 link() htmltemplate function now has a "showid" option for links & multilinks.
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
2979
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2980 When a change is submitted, the system automatically generates a message
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2981 describing the changed properties. As shown in the example, the editor
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1083
diff changeset
2982 template can use the ":note" and ":file" fields, which are added to the
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2983 standard changenote message generated by Roundup.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2984
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2985
1638
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
2986 Form values
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
2987 :::::::::::
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
2988
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
2989 We have a number of ways to pull properties out of the form in order to
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
2990 meet the various needs of:
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
2991
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
2992 1. editing the current item (perhaps an issue item)
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
2993 2. editing information related to the current item (eg. messages or
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
2994 attached files)
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
2995 3. creating new information to be linked to the current item (eg. time
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
2996 spent on an issue)
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
2997
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2998 In the following, ``<bracketed>`` values are variable, ":" may be one of
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2999 ":" or "@", and other text ("required") is fixed.
1638
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3000
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3001 Properties are specified as form variables:
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3002
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3003 ``<propname>``
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3004 property on the current context item
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3005
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3006 ``<designator>:<propname>``
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3007 property on the indicated item (for editing related information)
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3008
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3009 ``<classname>-<N>:<propname>``
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3010 property on the Nth new item of classname (generally for creating new
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3011 items to attach to the current item)
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3012
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3013 Once we have determined the "propname", we check to see if it is one of
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3014 the special form values:
1638
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3015
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3016 ``@required``
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3017 The named property values must be supplied or a ValueError will be
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3018 raised.
1638
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3019
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3020 ``@remove@<propname>=id(s)``
1638
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3021 The ids will be removed from the multilink property.
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3022
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3023 ``:add:<propname>=id(s)``
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3024 The ids will be added to the multilink property.
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3025
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3026 ``:link:<propname>=<designator>``
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3027 Used to add a link to new items created during edit. These are
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3028 collected and returned in ``all_links``. This will result in an
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3029 additional linking operation (either Link set or Multilink append)
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3030 after the edit/create is done using ``all_props`` in ``_editnodes``.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3031 The <propname> on the current item will be set/appended the id of the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3032 newly created item of class <designator> (where <designator> must be
1638
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3033 <classname>-<N>).
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3034
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3035 Any of the form variables may be prefixed with a classname or
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3036 designator.
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3037
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3038 Two special form values are supported for backwards compatibility:
1638
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3039
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3040 ``:note``
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3041 create a message (with content, author and date), linked to the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3042 context item. This is ALWAYS designated "msg-1".
1638
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3043 ``:file``
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3044 create a file, attached to the current item and any message created by
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3045 :note. This is ALWAYS designated "file-1".
1638
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3046
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3047
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3048 Spool Section
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3049 ~~~~~~~~~~~~~
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3050
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3051 The spool section lists related information like the messages and files
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3052 of an issue.
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3053
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3054 TODO
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3055
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3056
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3057 History Section
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3058 ~~~~~~~~~~~~~~~
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3059
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3060 The final section displayed is the history of the item - its database
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3061 journal. This is generally generated with the template::
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3062
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3063 <tal:block tal:replace="structure context/history" />
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3064
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3065 *To be done:*
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3066
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3067 *The actual history entries of the item may be accessed for manual
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3068 templating through the "journal" method of the item*::
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3069
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3070 <tal:block tal:repeat="entry context/journal">
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3071 a journal entry
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3072 </tal:block>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3073
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3074 *where each journal entry is an HTMLJournalEntry.*
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3075
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3076
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3077 Defining new web actions
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3078 ------------------------
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3079
2016
2112962f5bb1 Update documentation for the client.py split and add an upgrade notice.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2009
diff changeset
3080 You may define new actions to be triggered by the ``@action`` form variable.
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3081 These are added to the tracker ``extensions`` directory and registered
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3082 using ``instance.registerAction``.
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3083
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3084 All the existing Actions are defined in ``roundup.cgi.actions``.
2016
2112962f5bb1 Update documentation for the client.py split and add an upgrade notice.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2009
diff changeset
3085
2112962f5bb1 Update documentation for the client.py split and add an upgrade notice.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2009
diff changeset
3086 Adding action classes takes three steps; first you `define the new
2112962f5bb1 Update documentation for the client.py split and add an upgrade notice.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2009
diff changeset
3087 action class`_, then you `register the action class`_ with the cgi
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3088 interface so it may be triggered by the ``@action`` form variable.
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3089 Finally you `use the new action`_ in your HTML form.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3090
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3091 See "`setting up a "wizard" (or "druid") for controlled adding of
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3092 issues`_" for an example.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3093
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3094
2016
2112962f5bb1 Update documentation for the client.py split and add an upgrade notice.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2009
diff changeset
3095 Define the new action class
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3096 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3097
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3098 Create a new action class in your tracker's ``extensions`` directory, for
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3099 example ``myaction.py``::
2016
2112962f5bb1 Update documentation for the client.py split and add an upgrade notice.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2009
diff changeset
3100
3291
bb08ffc56967 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3289
diff changeset
3101 from roundup.cgi.actions import Action
bb08ffc56967 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3289
diff changeset
3102
2016
2112962f5bb1 Update documentation for the client.py split and add an upgrade notice.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2009
diff changeset
3103 class MyAction(Action):
2112962f5bb1 Update documentation for the client.py split and add an upgrade notice.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2009
diff changeset
3104 def handle(self):
2112962f5bb1 Update documentation for the client.py split and add an upgrade notice.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2009
diff changeset
3105 ''' Perform some action. No return value is required.
2112962f5bb1 Update documentation for the client.py split and add an upgrade notice.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2009
diff changeset
3106 '''
2112962f5bb1 Update documentation for the client.py split and add an upgrade notice.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2009
diff changeset
3107
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3108 The *self.client* attribute is an instance of ``roundup.cgi.client.Client``.
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3109 See the docstring of that class for details of what it can do.
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3110
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3111 The method will typically check the ``self.form`` variable's contents.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3112 It may then:
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3113
4880
ca692423e401 Different approach to fix XSS in issue2550817
Ralf Schlatterbeck <rsc@runtux.com>
parents: 4790
diff changeset
3114 - add information to ``self.client._ok_message``
ca692423e401 Different approach to fix XSS in issue2550817
Ralf Schlatterbeck <rsc@runtux.com>
parents: 4790
diff changeset
3115 or ``self.client._error_message`` (by using ``self.client.add_ok_message``
ca692423e401 Different approach to fix XSS in issue2550817
Ralf Schlatterbeck <rsc@runtux.com>
parents: 4790
diff changeset
3116 or ``self.client.add_error_message``, respectively)
2016
2112962f5bb1 Update documentation for the client.py split and add an upgrade notice.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2009
diff changeset
3117 - change the ``self.client.template`` variable to alter what the user will see
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3118 next
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3119 - raise Unauthorised, SendStaticFile, SendFile, NotFound or Redirect
2016
2112962f5bb1 Update documentation for the client.py split and add an upgrade notice.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2009
diff changeset
3120 exceptions (import them from roundup.cgi.exceptions)
2112962f5bb1 Update documentation for the client.py split and add an upgrade notice.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2009
diff changeset
3121
2112962f5bb1 Update documentation for the client.py split and add an upgrade notice.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2009
diff changeset
3122
2112962f5bb1 Update documentation for the client.py split and add an upgrade notice.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2009
diff changeset
3123 Register the action class
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3124 ~~~~~~~~~~~~~~~~~~~~~~~~~~
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3125
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3126 The class is now written, but isn't available to the user until you register
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3127 it with the following code appended to your ``myaction.py`` file::
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3128
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3129 def init(instance):
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3130 instance.registerAction('myaction', myActionClass)
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3131
2016
2112962f5bb1 Update documentation for the client.py split and add an upgrade notice.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2009
diff changeset
3132 This maps the action name "myaction" to the action class we defined.
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3133
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3134
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3135 Use the new action
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3136 ~~~~~~~~~~~~~~~~~~
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3137
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3138 In your HTML form, add a hidden form element like so::
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3139
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3140 <input type="hidden" name="@action" value="myaction">
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3141
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3142 where "myaction" is the name you registered in the previous step.
1003
f89b8d32291b Hack hack hack...
Richard Jones <richard@users.sourceforge.net>
parents: 935
diff changeset
3143
2046
f913b6beac35 document and make easier the actions-returning-content idiom
Richard Jones <richard@users.sourceforge.net>
parents: 2034
diff changeset
3144 Actions may return content to the user
f913b6beac35 document and make easier the actions-returning-content idiom
Richard Jones <richard@users.sourceforge.net>
parents: 2034
diff changeset
3145 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
f913b6beac35 document and make easier the actions-returning-content idiom
Richard Jones <richard@users.sourceforge.net>
parents: 2034
diff changeset
3146
f913b6beac35 document and make easier the actions-returning-content idiom
Richard Jones <richard@users.sourceforge.net>
parents: 2034
diff changeset
3147 Actions generally perform some database manipulation and then pass control
f913b6beac35 document and make easier the actions-returning-content idiom
Richard Jones <richard@users.sourceforge.net>
parents: 2034
diff changeset
3148 on to the rendering of a template in the current context (see `Determining
f913b6beac35 document and make easier the actions-returning-content idiom
Richard Jones <richard@users.sourceforge.net>
parents: 2034
diff changeset
3149 web context`_ for how that works.) Some actions will want to generate the
f913b6beac35 document and make easier the actions-returning-content idiom
Richard Jones <richard@users.sourceforge.net>
parents: 2034
diff changeset
3150 actual content returned to the user. Action methods may return their own
f913b6beac35 document and make easier the actions-returning-content idiom
Richard Jones <richard@users.sourceforge.net>
parents: 2034
diff changeset
3151 content string to be displayed to the user, overriding the templating step.
f913b6beac35 document and make easier the actions-returning-content idiom
Richard Jones <richard@users.sourceforge.net>
parents: 2034
diff changeset
3152 In this situation, we assume that the content is HTML by default. You may
f913b6beac35 document and make easier the actions-returning-content idiom
Richard Jones <richard@users.sourceforge.net>
parents: 2034
diff changeset
3153 override the content type indicated to the user by calling ``setHeader``::
f913b6beac35 document and make easier the actions-returning-content idiom
Richard Jones <richard@users.sourceforge.net>
parents: 2034
diff changeset
3154
f913b6beac35 document and make easier the actions-returning-content idiom
Richard Jones <richard@users.sourceforge.net>
parents: 2034
diff changeset
3155 self.client.setHeader('Content-Type', 'text/csv')
f913b6beac35 document and make easier the actions-returning-content idiom
Richard Jones <richard@users.sourceforge.net>
parents: 2034
diff changeset
3156
f913b6beac35 document and make easier the actions-returning-content idiom
Richard Jones <richard@users.sourceforge.net>
parents: 2034
diff changeset
3157 This example indicates that the value sent back to the user is actually
f913b6beac35 document and make easier the actions-returning-content idiom
Richard Jones <richard@users.sourceforge.net>
parents: 2034
diff changeset
3158 comma-separated value content (eg. something to be loaded into a
f913b6beac35 document and make easier the actions-returning-content idiom
Richard Jones <richard@users.sourceforge.net>
parents: 2034
diff changeset
3159 spreadsheet or database).
f913b6beac35 document and make easier the actions-returning-content idiom
Richard Jones <richard@users.sourceforge.net>
parents: 2034
diff changeset
3160
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
3161
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3162 8-bit character set support in Web interface
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3163 --------------------------------------------
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3164
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3165 The web interface uses UTF-8 default. It may be overridden in both forms
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3166 and a browser cookie.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3167
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3168 - In forms, use the ``@charset`` variable.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3169 - To use the cookie override, have the ``roundup_charset`` cookie set.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3170
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3171 In both cases, the value is a valid charset name (eg. ``utf-8`` or
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3172 ``kio8-r``).
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3173
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3174 Inside Roundup, all strings are stored and processed in utf-8.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3175 Unfortunately, some older browsers do not work properly with
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3176 utf-8-encoded pages (e.g. Netscape Navigator 4 displays wrong
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3177 characters in form fields). This version allows one to change
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3178 the character set for http transfers. To do so, you may add
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3179 the following code to your ``page.html`` template::
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3180
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3181 <tal:block define="uri string:${request/base}${request/env/PATH_INFO}">
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3182 <a tal:attributes="href python:request.indexargs_url(uri,
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3183 {'@charset':'utf-8'})">utf-8</a>
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3184 <a tal:attributes="href python:request.indexargs_url(uri,
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3185 {'@charset':'koi8-r'})">koi8-r</a>
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3186 </tal:block>
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3187
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3188 (substitute ``koi8-r`` with appropriate charset for your language).
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3189 Charset preference is kept in the browser cookie ``roundup_charset``.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3190
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3191 ``meta http-equiv`` lines added to the tracker templates in version 0.6.0
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3192 should be changed to include actual character set name::
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3193
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3194 <meta http-equiv="Content-Type"
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3195 tal:attributes="content string:text/html;; charset=${request/client/charset}"
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3196 />
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3197
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3198 The charset is also sent in the http header.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3199
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3200
1100
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
3201 Examples
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
3202 ========
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
3203
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3204 .. contents::
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3205 :local:
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3206 :depth: 2
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3207
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3208
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3209 Changing what's stored in the database
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3210 --------------------------------------
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3211
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3212 The following examples illustrate ways to change the information stored in
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3213 the database.
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3214
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3215
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1215
diff changeset
3216 Adding a new field to the classic schema
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3217 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1100
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
3218
3122
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3219 This example shows how to add a simple field (a due date) to the default
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3220 classic schema. It does not add any additional behaviour, such as enforcing
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3221 the due date, or causing automatic actions to fire if the due date passes.
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3222
3409
80dc8011228e mention schema mutation
Richard Jones <richard@users.sourceforge.net>
parents: 3404
diff changeset
3223 You add new fields by editing the ``schema.py`` file in you tracker's home.
80dc8011228e mention schema mutation
Richard Jones <richard@users.sourceforge.net>
parents: 3404
diff changeset
3224 Schema changes are automatically applied to the database on the next
80dc8011228e mention schema mutation
Richard Jones <richard@users.sourceforge.net>
parents: 3404
diff changeset
3225 tracker access (note that roundup-server would need to be restarted as it
80dc8011228e mention schema mutation
Richard Jones <richard@users.sourceforge.net>
parents: 3404
diff changeset
3226 caches the schema).
3122
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3227
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3228 1. Modify the ``schema.py``::
3122
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3229
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3230 issue = IssueClass(db, "issue",
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
3231 assignedto=Link("user"), keyword=Multilink("keyword"),
3122
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3232 priority=Link("priority"), status=Link("status"),
3127
021b131bd816 doc fixes, one more fix to the permissions-in-listings fix
Richard Jones <richard@users.sourceforge.net>
parents: 3126
diff changeset
3233 due_date=Date())
3122
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3234
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3235 2. Add an edit field to the ``issue.item.html`` template::
3122
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3236
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3237 <tr>
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3238 <th>Due Date</th>
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3239 <td tal:content="structure context/due_date/field" />
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3240 </tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3241
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3242 If you want to show only the date part of due_date then do this instead::
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3243
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3244 <tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3245 <th>Due Date</th>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3246 <td tal:content="structure python:context.due_date.field(format='%Y-%m-%d')" />
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3247 </tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3248
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3249 3. Add the property to the ``issue.index.html`` page::
3122
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3250
3123
5894c7bea8ce *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3122
diff changeset
3251 (in the heading row)
5894c7bea8ce *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3122
diff changeset
3252 <th tal:condition="request/show/due_date">Due Date</th>
5894c7bea8ce *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3122
diff changeset
3253 (in the data row)
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3254 <td tal:condition="request/show/due_date"
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3255 tal:content="i/due_date" />
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3256
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3257 If you want format control of the display of the due date you can
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3258 enter the following in the data row to show only the actual due date::
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3259
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3260 <td tal:condition="request/show/due_date"
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3261 tal:content="python:i.due_date.pretty('%Y-%m-%d')">&nbsp;</td>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3262
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3263 4. Add the property to the ``issue.search.html`` page::
3122
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3264
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3265 <tr tal:define="name string:due_date">
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3266 <th i18n:translate="">Due Date:</th>
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3267 <td metal:use-macro="search_input"></td>
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3268 <td metal:use-macro="column_input"></td>
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3269 <td metal:use-macro="sort_input"></td>
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3270 <td metal:use-macro="group_input"></td>
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3271 </tr>
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3272
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3273 5. If you wish for the due date to appear in the standard views listed
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3274 in the sidebar of the web interface then you'll need to add "due_date"
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3275 to the columns and columns_showall lists in your ``page.html``::
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3276
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3277 columns string:id,activity,due_date,title,creator,status;
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3278 columns_showall string:id,activity,due_date,title,creator,assignedto,status;
3122
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3279
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3280 Adding a new constrained field to the classic schema
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3281 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3282
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3283 This example shows how to add a new constrained property (i.e. a
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3284 selection of distinct values) to your tracker.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3285
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3286
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3287 Introduction
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3288 ::::::::::::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3289
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3290 To make the classic schema of Roundup useful as a TODO tracking system
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3291 for a group of systems administrators, it needs an extra data field per
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3292 issue: a category.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3293
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3294 This would let sysadmins quickly list all TODOs in their particular area
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3295 of interest without having to do complex queries, and without relying on
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3296 the spelling capabilities of other sysadmins (a losing proposition at
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3297 best).
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3298
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3299
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3300 Adding a field to the database
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3301 ::::::::::::::::::::::::::::::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3302
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3303 This is the easiest part of the change. The category would just be a
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3304 plain string, nothing fancy. To change what is in the database you need
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3305 to add some lines to the ``schema.py`` file of your tracker instance.
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3306 Under the comment::
1235
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3307
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3308 # add any additional database schema configuration here
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3309
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3310 add::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3311
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3312 category = Class(db, "category", name=String())
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3313 category.setkey("name")
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3314
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3315 Here we are setting up a chunk of the database which we are calling
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3316 "category". It contains a string, which we are refering to as "name" for
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3317 lack of a more imaginative title. (Since "name" is one of the properties
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3318 that Roundup looks for on items if you do not set a key for them, it's
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3319 probably a good idea to stick with it for new classes if at all
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3320 appropriate.) Then we are setting the key of this chunk of the database
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3321 to be that "name". This is equivalent to an index for database types.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3322 This also means that there can only be one category with a given name.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3323
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3324 Adding the above lines allows us to create categories, but they're not
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3325 tied to the issues that we are going to be creating. It's just a list of
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3326 categories off on its own, which isn't much use. We need to link it in
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3327 with the issues. To do that, find the lines
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
3328 in ``schema.py`` which set up the "issue" class, and then add a link to
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3329 the category::
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3330
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3331 issue = IssueClass(db, "issue", ... ,
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3332 category=Multilink("category"), ... )
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3333
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3334 The ``Multilink()`` means that each issue can have many categories. If
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3335 you were adding something with a one-to-one relationship to issues (such
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3336 as the "assignedto" property), use ``Link()`` instead.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3337
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3338 That is all you need to do to change the schema. The rest of the effort
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3339 is fiddling around so you can actually use the new category.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3340
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3341
1235
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3342 Populating the new category class
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3343 :::::::::::::::::::::::::::::::::
1235
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3344
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3345 If you haven't initialised the database with the ``roundup-admin``
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3346 "initialise" command, then you can add the following to the tracker
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3347 ``initial_data.py`` under the comment::
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3348
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3349 # add any additional database creation steps here - but only if you
1235
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3350 # haven't initialised the database with the admin "initialise" command
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3351
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3352 Add::
1235
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3353
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3354 category = db.getclass('category')
3582
026adc5f1e13 fix "Adding a new constrained field to the classic schema" example in docs
Richard Jones <richard@users.sourceforge.net>
parents: 3580
diff changeset
3355 category.create(name="scipy")
026adc5f1e13 fix "Adding a new constrained field to the classic schema" example in docs
Richard Jones <richard@users.sourceforge.net>
parents: 3580
diff changeset
3356 category.create(name="chaco")
026adc5f1e13 fix "Adding a new constrained field to the classic schema" example in docs
Richard Jones <richard@users.sourceforge.net>
parents: 3580
diff changeset
3357 category.create(name="weave")
1235
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3358
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3359 If the database has already been initalised, then you need to use the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3360 ``roundup-admin`` tool::
1235
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3361
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3362 % roundup-admin -i <tracker home>
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3363 Roundup <version> ready for input.
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3364 Type "help" for help.
3582
026adc5f1e13 fix "Adding a new constrained field to the classic schema" example in docs
Richard Jones <richard@users.sourceforge.net>
parents: 3580
diff changeset
3365 roundup> create category name=scipy
1235
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3366 1
3582
026adc5f1e13 fix "Adding a new constrained field to the classic schema" example in docs
Richard Jones <richard@users.sourceforge.net>
parents: 3580
diff changeset
3367 roundup> create category name=chaco
1235
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3368 2
3582
026adc5f1e13 fix "Adding a new constrained field to the classic schema" example in docs
Richard Jones <richard@users.sourceforge.net>
parents: 3580
diff changeset
3369 roundup> create category name=weave
1235
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3370 3
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3371 roundup> exit...
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3372 There are unsaved changes. Commit them (y/N)? y
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3373
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3374
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3375 Setting up security on the new objects
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3376 ::::::::::::::::::::::::::::::::::::::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3377
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3378 By default only the admin user can look at and change objects. This
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3379 doesn't suit us, as we want any user to be able to create new categories
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3380 as required, and obviously everyone needs to be able to view the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3381 categories of issues for it to be useful.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3382
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3383 We therefore need to change the security of the category objects. This
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3384 is also done in ``schema.py``.
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3385
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3386 There are currently two loops which set up permissions and then assign
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3387 them to various roles. Simply add the new "category" to both lists::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3388
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3389 # Assign the access and edit permissions for issue, file and message
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3390 # to regular users now
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3391 for cl in 'issue', 'file', 'msg', 'category':
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3392 p = db.security.getPermission('View', cl)
2991
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
3393 db.security.addPermissionToRole('User', 'View', cl)
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
3394 db.security.addPermissionToRole('User', 'Edit', cl)
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
3395 db.security.addPermissionToRole('User', 'Create', cl)
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3396
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3397 These lines assign the "View" and "Edit" Permissions to the "User" role,
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3398 so that normal users can view and edit "category" objects.
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3399
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3400 This is all the work that needs to be done for the database. It will
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3401 store categories, and let users view and edit them. Now on to the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3402 interface stuff.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3403
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3404
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3405 Changing the web left hand frame
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3406 ::::::::::::::::::::::::::::::::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3407
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3408 We need to give the users the ability to create new categories, and the
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3409 place to put the link to this functionality is in the left hand function
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3410 bar, under the "Issues" area. The file that defines how this area looks
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3411 is ``html/page.html``, which is what we are going to be editing next.
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3412
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3413 If you look at this file you can see that it contains a lot of
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3414 "classblock" sections which are chunks of HTML that will be included or
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3415 excluded in the output depending on whether the condition in the
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3416 classblock is met. We are going to add the category code at the end of
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3417 the classblock for the *issue* class::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3418
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3419 <p class="classblock"
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3420 tal:condition="python:request.user.hasPermission('View', 'category')">
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3421 <b>Categories</b><br>
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3422 <a tal:condition="python:request.user.hasPermission('Edit', 'category')"
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3423 href="category?@template=item">New Category<br></a>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3424 </p>
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3425
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3426 The first two lines is the classblock definition, which sets up a
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3427 condition that only users who have "View" permission for the "category"
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3428 object will have this section included in their output. Next comes a
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3429 plain "Categories" header in bold. Everyone who can view categories will
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3430 get that.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3431
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3432 Next comes the link to the editing area of categories. This link will
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3433 only appear if the condition - that the user has "Edit" permissions for
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3434 the "category" objects - is matched. If they do have permission then
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3435 they will get a link to another page which will let the user add new
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3436 categories.
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3437
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3438 Note that if you have permission to *view* but not to *edit* categories,
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3439 then all you will see is a "Categories" header with nothing underneath
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3440 it. This is obviously not very good interface design, but will do for
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3441 now. I just claim that it is so I can add more links in this section
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3442 later on. However, to fix the problem you could change the condition in
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3443 the classblock statement, so that only users with "Edit" permission
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3444 would see the "Categories" stuff.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3445
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3446
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3447 Setting up a page to edit categories
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3448 ::::::::::::::::::::::::::::::::::::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3449
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3450 We defined code in the previous section which let users with the
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3451 appropriate permissions see a link to a page which would let them edit
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3452 conditions. Now we have to write that page.
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3453
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3454 The link was for the *item* template of the *category* object. This
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3455 translates into Roundup looking for a file called ``category.item.html``
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3456 in the ``html`` tracker directory. This is the file that we are going to
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3457 write now.
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3458
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3459 First, we add an info tag in a comment which doesn't affect the outcome
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3460 of the code at all, but is useful for debugging. If you load a page in a
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3461 browser and look at the page source, you can see which sections come
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3462 from which files by looking for these comments::
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3463
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3464 <!-- category.item -->
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3465
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3466 Next we need to add in the METAL macro stuff so we get the normal page
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3467 trappings::
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3468
1214
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
3469 <tal:block metal:use-macro="templates/page/macros/icing">
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3470 <title metal:fill-slot="head_title">Category editing</title>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3471 <td class="page-header-top" metal:fill-slot="body_title">
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3472 <h2>Category editing</h2>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3473 </td>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3474 <td class="content" metal:fill-slot="content">
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3475
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3476 Next we need to setup up a standard HTML form, which is the whole
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3477 purpose of this file. We link to some handy javascript which sends the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3478 form through only once. This is to stop users hitting the send button
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3479 multiple times when they are impatient and thus having the form sent
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3480 multiple times::
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3481
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3482 <form method="POST" onSubmit="return submit_once()"
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3483 enctype="multipart/form-data">
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3484
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3485 Next we define some code which sets up the minimum list of fields that
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3486 we require the user to enter. There will be only one field - "name" - so
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3487 they better put something in it, otherwise the whole form is pointless::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3488
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3489 <input type="hidden" name="@required" value="name">
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3490
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3491 To get everything to line up properly we will put everything in a table,
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3492 and put a nice big header on it so the user has an idea what is
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3493 happening::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3494
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3495 <table class="form">
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3496 <tr><th class="header" colspan="2">Category</th></tr>
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3497
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3498 Next, we need the field into which the user is going to enter the new
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3499 category. The ``context.name.field(size=60)`` bit tells Roundup to
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3500 generate a normal HTML field of size 60, and the contents of that field
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3501 will be the "name" variable of the current context (namely "category").
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3502 The upshot of this is that when the user types something in
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3503 to the form, a new category will be created with that name::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3504
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3505 <tr>
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
3506 <th>Name</th>
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3507 <td tal:content="structure python:context.name.field(size=60)">
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3508 name</td>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3509 </tr>
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3510
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3511 Then a submit button so that the user can submit the new category::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3512
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3513 <tr>
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3514 <td>&nbsp;</td>
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3515 <td colspan="3" tal:content="structure context/submit">
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3516 submit button will go here
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3517 </td>
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3518 </tr>
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3519
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3520 Finally we finish off the tags we used at the start to do the METAL
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3521 stuff::
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3522
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3523 </td>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3524 </tal:block>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3525
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3526 So putting it all together, and closing the table and form we get::
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3527
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3528 <!-- category.item -->
1214
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
3529 <tal:block metal:use-macro="templates/page/macros/icing">
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3530 <title metal:fill-slot="head_title">Category editing</title>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3531 <td class="page-header-top" metal:fill-slot="body_title">
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3532 <h2>Category editing</h2>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3533 </td>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3534 <td class="content" metal:fill-slot="content">
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3535 <form method="POST" onSubmit="return submit_once()"
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3536 enctype="multipart/form-data">
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3537
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3538 <table class="form">
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3539 <tr><th class="header" colspan="2">Category</th></tr>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3540
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3541 <tr>
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
3542 <th>Name</th>
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3543 <td tal:content="structure python:context.name.field(size=60)">
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3544 name</td>
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3545 </tr>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3546
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3547 <tr>
1829
4e4afbe3cd30 Move '<input type="hidden">' elements into a block.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1825
diff changeset
3548 <td>
4e4afbe3cd30 Move '<input type="hidden">' elements into a block.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1825
diff changeset
3549 &nbsp;
4e4afbe3cd30 Move '<input type="hidden">' elements into a block.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1825
diff changeset
3550 <input type="hidden" name="@required" value="name">
4e4afbe3cd30 Move '<input type="hidden">' elements into a block.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1825
diff changeset
3551 </td>
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3552 <td colspan="3" tal:content="structure context/submit">
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3553 submit button will go here
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3554 </td>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3555 </tr>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3556 </table>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3557 </form>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3558 </td>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3559 </tal:block>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3560
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3561 This is quite a lot to just ask the user one simple question, but there
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3562 is a lot of setup for basically one line (the form line) to do its work.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3563 To add another field to "category" would involve one more line (well,
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3564 maybe a few extra to get the formatting correct).
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3565
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3566
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3567 Adding the category to the issue
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3568 ::::::::::::::::::::::::::::::::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3569
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3570 We now have the ability to create issues to our heart's content, but
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3571 that is pointless unless we can assign categories to issues. Just like
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3572 the ``html/category.item.html`` file was used to define how to add a new
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3573 category, the ``html/issue.item.html`` is used to define how a new issue
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3574 is created.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3575
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3576 Just like ``category.issue.html``, this file defines a form which has a
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3577 table to lay things out. It doesn't matter where in the table we add new
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3578 stuff, it is entirely up to your sense of aesthetics::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3579
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
3580 <th>Category</th>
3582
026adc5f1e13 fix "Adding a new constrained field to the classic schema" example in docs
Richard Jones <richard@users.sourceforge.net>
parents: 3580
diff changeset
3581 <td>
026adc5f1e13 fix "Adding a new constrained field to the classic schema" example in docs
Richard Jones <richard@users.sourceforge.net>
parents: 3580
diff changeset
3582 <span tal:replace="structure context/category/field" />
026adc5f1e13 fix "Adding a new constrained field to the classic schema" example in docs
Richard Jones <richard@users.sourceforge.net>
parents: 3580
diff changeset
3583 <span tal:replace="structure python:db.category.classhelp('name',
026adc5f1e13 fix "Adding a new constrained field to the classic schema" example in docs
Richard Jones <richard@users.sourceforge.net>
parents: 3580
diff changeset
3584 property='category', width='200')" />
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3585 </td>
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3586
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3587 First, we define a nice header so that the user knows what the next
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3588 section is, then the middle line does what we are most interested in.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3589 This ``context/category/field`` gets replaced by a field which contains
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3590 the category in the current context (the current context being the new
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3591 issue).
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3592
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3593 The classhelp lines generate a link (labelled "list") to a popup window
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3594 which contains the list of currently known categories.
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3595
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3596
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3597 Searching on categories
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3598 :::::::::::::::::::::::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3599
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3600 Now we can add categories, and create issues with categories. The next
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3601 obvious thing that we would like to be able to do, would be to search
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3602 for issues based on their category, so that, for example, anyone working
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3603 on the web server could look at all issues in the category "Web".
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3604
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3605 If you look for "Search Issues" in the ``html/page.html`` file, you will
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3606 find that it looks something like
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3607 ``<a href="issue?@template=search">Search Issues</a>``. This shows us
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3608 that when you click on "Search Issues" it will be looking for a
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3609 ``issue.search.html`` file to display. So that is the file that we will
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3610 change.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3611
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3612 If you look at this file it should begin to seem familiar, although it
1730
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3613 does use some new macros. You can add the new category search code anywhere you
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3614 like within that form::
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3615
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3616 <tr tal:define="name string:category;
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3617 db_klass string:category;
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3618 db_content string:name;">
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3619 <th>Priority:</th>
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3620 <td metal:use-macro="search_select"></td>
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3621 <td metal:use-macro="column_input"></td>
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3622 <td metal:use-macro="sort_input"></td>
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3623 <td metal:use-macro="group_input"></td>
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3624 </tr>
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3625
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3626 The definitions in the ``<tr>`` opening tag are used by the macros:
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3627
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3628 - ``search_select`` expands to a drop-down box with all categories using
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3629 ``db_klass`` and ``db_content``.
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3630 - ``column_input`` expands to a checkbox for selecting what columns
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3631 should be displayed.
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3632 - ``sort_input`` expands to a radio button for selecting what property
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3633 should be sorted on.
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3634 - ``group_input`` expands to a radio button for selecting what property
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3635 should be grouped on.
1730
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3636
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3637 The category search code above would expand to the following::
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3638
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3639 <tr>
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3640 <th>Category:</th>
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3641 <td>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3642 <select name="category">
1730
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3643 <option value="">don't care</option>
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3644 <option value="">------------</option>
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3645 <option value="1">scipy</option>
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3646 <option value="2">chaco</option>
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3647 <option value="3">weave</option>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3648 </select>
1730
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3649 </td>
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3650 <td><input type="checkbox" name=":columns" value="category"></td>
3696
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
3651 <td><input type="radio" name=":sort0" value="category"></td>
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
3652 <td><input type="radio" name=":group0" value="category"></td>
1730
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3653 </tr>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3654
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3655 Adding category to the default view
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3656 :::::::::::::::::::::::::::::::::::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3657
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3658 We can now add categories, add issues with categories, and search for
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3659 issues based on categories. This is everything that we need to do;
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3660 however, there is some more icing that we would like. I think the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3661 category of an issue is important enough that it should be displayed by
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3662 default when listing all the issues.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3663
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3664 Unfortunately, this is a bit less obvious than the previous steps. The
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3665 code defining how the issues look is in ``html/issue.index.html``. This
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3666 is a large table with a form down at the bottom for redisplaying and so
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3667 forth.
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3668
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3669 Firstly we need to add an appropriate header to the start of the table::
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3670
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3671 <th tal:condition="request/show/category">Category</th>
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3672
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3673 The *condition* part of this statement is to avoid displaying the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3674 Category column if the user has selected not to see it.
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3675
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3676 The rest of the table is a loop which will go through every issue that
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3677 matches the display criteria. The loop variable is "i" - which means
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3678 that every issue gets assigned to "i" in turn.
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3679
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3680 The new part of code to display the category will look like this::
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3681
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3682 <td tal:condition="request/show/category"
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3683 tal:content="i/category"></td>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3684
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3685 The condition is the same as above: only display the condition when the
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3686 user hasn't asked for it to be hidden. The next part is to set the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3687 content of the cell to be the category part of "i" - the current issue.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3688
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3689 Finally we have to edit ``html/page.html`` again. This time, we need to
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3690 tell it that when the user clicks on "Unassigned Issues" or "All Issues",
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3691 the category column should be included in the resulting list. If you
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3692 scroll down the page file, you can see the links with lots of options.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3693 The option that we are interested in is the ``:columns=`` one which
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3694 tells roundup which fields of the issue to display. Simply add
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3695 "category" to that list and it all should work.
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3696
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3697 Adding a time log to your issues
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3698 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3699
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3700 We want to log the dates and amount of time spent working on issues, and
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3701 be able to give a summary of the total time spent on a particular issue.
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3702
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
3703 1. Add a new class to your tracker ``schema.py``::
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3704
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3705 # storage for time logging
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3706 timelog = Class(db, "timelog", period=Interval())
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3707
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3708 Note that we automatically get the date of the time log entry
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3709 creation through the standard property "creation".
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3710
3652
3a19d31be628 add in note about perms
Richard Jones <richard@users.sourceforge.net>
parents: 3649
diff changeset
3711 You will need to grant "Creation" permission to the users who are
3653
cfa7fa2c5e0f arg rest
Richard Jones <richard@users.sourceforge.net>
parents: 3652
diff changeset
3712 allowed to add timelog entries. You may do this with::
3652
3a19d31be628 add in note about perms
Richard Jones <richard@users.sourceforge.net>
parents: 3649
diff changeset
3713
3a19d31be628 add in note about perms
Richard Jones <richard@users.sourceforge.net>
parents: 3649
diff changeset
3714 db.security.addPermissionToRole('User', 'Create', 'timelog')
3a19d31be628 add in note about perms
Richard Jones <richard@users.sourceforge.net>
parents: 3649
diff changeset
3715 db.security.addPermissionToRole('User', 'View', 'timelog')
3a19d31be628 add in note about perms
Richard Jones <richard@users.sourceforge.net>
parents: 3649
diff changeset
3716
3653
cfa7fa2c5e0f arg rest
Richard Jones <richard@users.sourceforge.net>
parents: 3652
diff changeset
3717 If users are also able to *edit* timelog entries, then also include::
3652
3a19d31be628 add in note about perms
Richard Jones <richard@users.sourceforge.net>
parents: 3649
diff changeset
3718
3a19d31be628 add in note about perms
Richard Jones <richard@users.sourceforge.net>
parents: 3649
diff changeset
3719 db.security.addPermissionToRole('User', 'Edit', 'timelog')
3a19d31be628 add in note about perms
Richard Jones <richard@users.sourceforge.net>
parents: 3649
diff changeset
3720
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3721 2. Link to the new class from your issue class (again, in
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
3722 ``schema.py``)::
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3723
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3724 issue = IssueClass(db, "issue",
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
3725 assignedto=Link("user"), keyword=Multilink("keyword"),
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3726 priority=Link("priority"), status=Link("status"),
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3727 times=Multilink("timelog"))
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3728
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3729 the "times" property is the new link to the "timelog" class.
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3730
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3731 3. We'll need to let people add in times to the issue, so in the web
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3732 interface we'll have a new entry field. This is a special field
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3733 because unlike the other fields in the ``issue.item`` template, it
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3734 affects a different item (a timelog item) and not the template's
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3735 item (an issue). We have a special syntax for form fields that affect
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3736 items other than the template default item (see the cgi
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3737 documentation on `special form variables`_). In particular, we add a
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3738 field to capture a new timelog item's period::
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3739
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3740 <tr>
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
3741 <th>Time Log</th>
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3742 <td colspan=3><input type="text" name="timelog-1@period" />
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3743 (enter as '3y 1m 4d 2:40:02' or parts thereof)
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3744 </td>
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3745 </tr>
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3746
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3747 and another hidden field that links that new timelog item (new
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3748 because it's marked as having id "-1") to the issue item. It looks
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3749 like this::
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3750
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3751 <input type="hidden" name="@link@times" value="timelog-1" />
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3752
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3753 On submission, the "-1" timelog item will be created and assigned a
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3754 real item id. The "times" property of the issue will have the new id
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3755 added to it.
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3756
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3757 The full entry will now look like this::
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3758
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3759 <tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3760 <th>Time Log</th>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3761 <td colspan=3><input type="text" name="timelog-1@period" />
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3762 (enter as '3y 1m 4d 2:40:02' or parts thereof)
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3763 <input type="hidden" name="@link@times" value="timelog-1" />
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3764 </td>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3765 </tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3766
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3767
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3768 4. We want to display a total of the timelog times that have been
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3769 accumulated for an issue. To do this, we'll need to actually write
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3770 some Python code, since it's beyond the scope of PageTemplates to
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3771 perform such calculations. We do this by adding a module ``timespent.py``
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3772 to the ``extensions`` directory in our tracker. The contents of this
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3773 file is as follows::
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3774
3717
5770f1802cd0 better conflict retry in postgresql backend [SF#1552809]
Richard Jones <richard@users.sourceforge.net>
parents: 3697
diff changeset
3775 from roundup import date
5770f1802cd0 better conflict retry in postgresql backend [SF#1552809]
Richard Jones <richard@users.sourceforge.net>
parents: 3697
diff changeset
3776
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3777 def totalTimeSpent(times):
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3778 ''' Call me with a list of timelog items (which have an
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3779 Interval "period" property)
1270
c3424abf7f77 added ability to implement new templating utility methods
Richard Jones <richard@users.sourceforge.net>
parents: 1262
diff changeset
3780 '''
3717
5770f1802cd0 better conflict retry in postgresql backend [SF#1552809]
Richard Jones <richard@users.sourceforge.net>
parents: 3697
diff changeset
3781 total = date.Interval('0d')
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3782 for time in times:
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3783 total += time.period._value
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3784 return total
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3785
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3786 def init(instance):
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3787 instance.registerUtil('totalTimeSpent', totalTimeSpent)
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3788
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3789 We will now be able to access the ``totalTimeSpent`` function via the
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3790 ``utils`` variable in our templates, as shown in the next step.
1270
c3424abf7f77 added ability to implement new templating utility methods
Richard Jones <richard@users.sourceforge.net>
parents: 1262
diff changeset
3791
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3792 5. Display the timelog for an issue::
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3793
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3794 <table class="otherinfo" tal:condition="context/times">
1270
c3424abf7f77 added ability to implement new templating utility methods
Richard Jones <richard@users.sourceforge.net>
parents: 1262
diff changeset
3795 <tr><th colspan="3" class="header">Time Log
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3796 <tal:block
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3797 tal:replace="python:utils.totalTimeSpent(context.times)" />
1270
c3424abf7f77 added ability to implement new templating utility methods
Richard Jones <richard@users.sourceforge.net>
parents: 1262
diff changeset
3798 </th></tr>
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3799 <tr><th>Date</th><th>Period</th><th>Logged By</th></tr>
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3800 <tr tal:repeat="time context/times">
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3801 <td tal:content="time/creation"></td>
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3802 <td tal:content="time/period"></td>
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3803 <td tal:content="time/creator"></td>
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3804 </tr>
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3805 </table>
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3806
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3807 I put this just above the Messages log in my issue display. Note our
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3808 use of the ``totalTimeSpent`` method which will total up the times
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3809 for the issue and return a new Interval. That will be automatically
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3810 displayed in the template as text like "+ 1y 2:40" (1 year, 2 hours
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3811 and 40 minutes).
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3812
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3813 6. If you're using a persistent web server - ``roundup-server`` or
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3814 ``mod_python`` for example - then you'll need to restart that to pick up
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3815 the code changes. When that's done, you'll be able to use the new
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3816 time logging interface.
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3817
3657
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
3818 An extension of this modification attaches the timelog entries to any
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
3819 change message entered at the time of the timelog entry:
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
3820
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3821 A. Add a link to the timelog to the msg class in ``schema.py``:
3657
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
3822
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
3823 msg = FileClass(db, "msg",
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
3824 author=Link("user", do_journal='no'),
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
3825 recipients=Multilink("user", do_journal='no'),
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
3826 date=Date(),
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
3827 summary=String(),
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
3828 files=Multilink("file"),
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
3829 messageid=String(),
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3830 inreplyto=String(),
3657
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
3831 times=Multilink("timelog"))
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
3832
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3833 B. Add a new hidden field that links that new timelog item (new
3657
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
3834 because it's marked as having id "-1") to the new message.
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3835 The link is placed in ``issue.item.html`` in the same section that
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3836 handles the timelog entry.
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3837
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3838 It looks like this after this addition::
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3839
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3840 <tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3841 <th>Time Log</th>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3842 <td colspan=3><input type="text" name="timelog-1@period" />
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3843 (enter as '3y 1m 4d 2:40:02' or parts thereof)
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3844 <input type="hidden" name="@link@times" value="timelog-1" />
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3845 <input type="hidden" name="msg-1@link@times" value="timelog-1" />
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3846 </td>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3847 </tr>
3657
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
3848
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
3849 The "times" property of the message will have the new id added to it.
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
3850
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3851 C. Add the timelog listing from step 5. to the ``msg.item.html`` template
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3852 so that the timelog entry appears on the message view page. Note that
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3853 the call to totalTimeSpent is not used here since there will only be one
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3854 single timelog entry for each message.
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3855
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3856 I placed it after the Date entry like this::
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3857
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3858 <tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3859 <th i18n:translate="">Date:</th>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3860 <td tal:content="context/date"></td>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3861 </tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3862 </table>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3863
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3864 <table class="otherinfo" tal:condition="context/times">
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3865 <tr><th colspan="3" class="header">Time Log</th></tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3866 <tr><th>Date</th><th>Period</th><th>Logged By</th></tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3867 <tr tal:repeat="time context/times">
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3868 <td tal:content="time/creation"></td>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3869 <td tal:content="time/period"></td>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3870 <td tal:content="time/creator"></td>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3871 </tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3872 </table>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3873
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3874 <table class="messages">
3657
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
3875
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3876
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3877 Tracking different types of issues
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3878 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3879
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3880 Sometimes you will want to track different types of issues - developer,
2159
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
3881 customer support, systems, sales leads, etc. A single Roundup tracker is
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3882 able to support multiple types of issues. This example demonstrates adding
3289
5da323b46907 doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3276
diff changeset
3883 a system support issue class to a tracker.
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3884
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3885 1. Figure out what information you're going to want to capture. OK, so
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3886 this is obvious, but sometimes it's better to actually sit down for a
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3887 while and think about the schema you're going to implement.
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3888
3289
5da323b46907 doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3276
diff changeset
3889 2. Add the new issue class to your tracker's ``schema.py``. Just after the
5da323b46907 doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3276
diff changeset
3890 "issue" class definition, add::
5da323b46907 doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3276
diff changeset
3891
5da323b46907 doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3276
diff changeset
3892 # list our systems
5da323b46907 doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3276
diff changeset
3893 system = Class(db, "system", name=String(), order=Number())
5da323b46907 doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3276
diff changeset
3894 system.setkey("name")
5da323b46907 doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3276
diff changeset
3895
5da323b46907 doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3276
diff changeset
3896 # store issues related to those systems
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3897 support = IssueClass(db, "support",
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
3898 assignedto=Link("user"), keyword=Multilink("keyword"),
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3899 status=Link("status"), deadline=Date(),
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3900 affects=Multilink("system"))
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3901
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3902 3. Copy the existing ``issue.*`` (item, search and index) templates in the
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3903 tracker's ``html`` to ``support.*``. Edit them so they use the properties
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3904 defined in the ``support`` class. Be sure to check for hidden form
2159
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
3905 variables like "required" to make sure they have the correct set of
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
3906 required properties.
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
3907
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3908 4. Edit the modules in the ``detectors``, adding lines to their ``init``
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3909 functions where appropriate. Look for ``audit`` and ``react`` registrations
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3910 on the ``issue`` class, and duplicate them for ``support``.
2159
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
3911
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
3912 5. Create a new sidebar box for the new support class. Duplicate the
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3913 existing issues one, changing the ``issue`` class name to ``support``.
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3914
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3915 6. Re-start your tracker and start using the new ``support`` class.
2159
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
3916
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
3917
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
3918 Optionally, you might want to restrict the users able to access this new
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
3919 class to just the users with a new "SysAdmin" Role. To do this, we add
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
3920 some security declarations::
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3921
2991
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
3922 db.security.addPermissionToRole('SysAdmin', 'View', 'support')
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
3923 db.security.addPermissionToRole('SysAdmin', 'Create', 'support')
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
3924 db.security.addPermissionToRole('SysAdmin', 'Edit', 'support')
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3925
2159
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
3926 You would then (as an "admin" user) edit the details of the appropriate
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
3927 users, and add "SysAdmin" to their Roles list.
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
3928
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
3929 Alternatively, you might want to change the Edit/View permissions granted
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3930 for the ``issue`` class so that it's only available to users with the "System"
2159
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
3931 or "Developer" Role, and then the new class you're adding is available to
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
3932 all with the "User" Role.
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3933
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3934
4891
ad3d628e73f2 docs: Link custom authentication examples in admin guide
anatoly techtonik <techtonik@gmail.com>
parents: 4888
diff changeset
3935 .. _external-authentication:
ad3d628e73f2 docs: Link custom authentication examples in admin guide
anatoly techtonik <techtonik@gmail.com>
parents: 4888
diff changeset
3936
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3937 Using External User Databases
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3938 -----------------------------
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3939
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3940 Using an external password validation source
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3941 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3942
3228
1b15e9eeb592 fixes to the "Using an external password validation source"...
Richard Jones <richard@users.sourceforge.net>
parents: 3130
diff changeset
3943 .. note:: You will need to either have an "admin" user in your external
1b15e9eeb592 fixes to the "Using an external password validation source"...
Richard Jones <richard@users.sourceforge.net>
parents: 3130
diff changeset
3944 password source *or* have one of your regular users have
1b15e9eeb592 fixes to the "Using an external password validation source"...
Richard Jones <richard@users.sourceforge.net>
parents: 3130
diff changeset
3945 the Admin Role assigned. If you need to assign the Role *after*
1b15e9eeb592 fixes to the "Using an external password validation source"...
Richard Jones <richard@users.sourceforge.net>
parents: 3130
diff changeset
3946 making the changes below, you may use the ``roundup-admin``
1b15e9eeb592 fixes to the "Using an external password validation source"...
Richard Jones <richard@users.sourceforge.net>
parents: 3130
diff changeset
3947 program to edit a user's details.
1b15e9eeb592 fixes to the "Using an external password validation source"...
Richard Jones <richard@users.sourceforge.net>
parents: 3130
diff changeset
3948
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3949 We have a centrally-managed password changing system for our users. This
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3950 results in a UN*X passwd-style file that we use for verification of
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3951 users. Entries in the file consist of ``name:password`` where the
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3952 password is encrypted using the standard UN*X ``crypt()`` function (see
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3953 the ``crypt`` module in your Python distribution). An example entry
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3954 would be::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3955
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3956 admin:aamrgyQfDFSHw
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3957
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3958 Each user of Roundup must still have their information stored in the Roundup
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3959 database - we just use the passwd file to check their password. To do this, we
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3960 need to override the standard ``verifyPassword`` method defined in
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3961 ``roundup.cgi.actions.LoginAction`` and register the new class. The
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3962 following is added as ``externalpassword.py`` in the tracker ``extensions``
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3963 directory::
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3964
3228
1b15e9eeb592 fixes to the "Using an external password validation source"...
Richard Jones <richard@users.sourceforge.net>
parents: 3130
diff changeset
3965 import os, crypt
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3966 from roundup.cgi.actions import LoginAction
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3967
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3968 class ExternalPasswordLoginAction(LoginAction):
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3969 def verifyPassword(self, userid, password):
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3970 '''Look through the file, line by line, looking for a
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3971 name that matches.
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3972 '''
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3973 # get the user's username
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3974 username = self.db.user.get(userid, 'username')
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3975
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3976 # the passwords are stored in the "passwd.txt" file in the
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3977 # tracker home
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3978 file = os.path.join(self.db.config.TRACKER_HOME, 'passwd.txt')
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3979
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3980 # see if we can find a match
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3981 for ent in [line.strip().split(':') for line in
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3982 open(file).readlines()]:
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3983 if ent[0] == username:
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3984 return crypt.crypt(password, ent[1][:2]) == ent[1]
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3985
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3986 # user doesn't exist in the file
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3987 return 0
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3988
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3989 def init(instance):
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3990 instance.registerAction('login', ExternalPasswordLoginAction)
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3991
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3992 You should also remove the redundant password fields from the ``user.item``
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3993 template.
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3994
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3995
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
3996 Using a UN*X passwd file as the user database
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3997 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
3998
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3999 On some systems the primary store of users is the UN*X passwd file. It
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4000 holds information on users such as their username, real name, password
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4001 and primary user group.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4002
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4003 Roundup can use this store as its primary source of user information,
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4004 but it needs additional information too - email address(es), roundup
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4005 Roles, vacation flags, roundup hyperdb item ids, etc. Also, "retired"
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4006 users must still exist in the user database, unlike some passwd files in
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4007 which the users are removed when they no longer have access to a system.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4008
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4009 To make use of the passwd file, we therefore synchronise between the two
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4010 user stores. We also use the passwd file to validate the user logins, as
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4011 described in the previous example, `using an external password
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4012 validation source`_. We keep the user lists in sync using a fairly
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4013 simple script that runs once a day, or several times an hour if more
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4014 immediate access is needed. In short, it:
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4015
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4016 1. parses the passwd file, finding usernames, passwords and real names,
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4017 2. compares that list to the current roundup user list:
1299
b2d04ce03802 Email improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 1293
diff changeset
4018
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4019 a. entries no longer in the passwd file are *retired*
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4020 b. entries with mismatching real names are *updated*
1293
Richard Jones <richard@users.sourceforge.net>
parents: 1292
diff changeset
4021 c. entries only exist in the passwd file are *created*
1299
b2d04ce03802 Email improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 1293
diff changeset
4022
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4023 3. send an email to administrators to let them know what's been done.
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4024
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4025 The retiring and updating are simple operations, requiring only a call
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4026 to ``retire()`` or ``set()``. The creation operation requires more
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4027 information though - the user's email address and their Roundup Roles.
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4028 We're going to assume that the user's email address is the same as their
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4029 login name, so we just append the domain name to that. The Roles are
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4030 determined using the passwd group identifier - mapping their UN*X group
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4031 to an appropriate set of Roles.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4032
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4033 The script to perform all this, broken up into its main components, is
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4034 as follows. Firstly, we import the necessary modules and open the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4035 tracker we're to work on::
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4036
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4037 import sys, os, smtplib
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4038 from roundup import instance, date
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4039
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4040 # open the tracker
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4041 tracker_home = sys.argv[1]
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4042 tracker = instance.open(tracker_home)
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4043
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4044 Next we read in the *passwd* file from the tracker home::
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4045
3228
1b15e9eeb592 fixes to the "Using an external password validation source"...
Richard Jones <richard@users.sourceforge.net>
parents: 3130
diff changeset
4046 # read in the users from the "passwd.txt" file
1b15e9eeb592 fixes to the "Using an external password validation source"...
Richard Jones <richard@users.sourceforge.net>
parents: 3130
diff changeset
4047 file = os.path.join(tracker_home, 'passwd.txt')
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4048 users = [x.strip().split(':') for x in open(file).readlines()]
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4049
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4050 Handle special users (those to ignore in the file, and those who don't
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4051 appear in the file)::
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4052
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4053 # users to not keep ever, pre-load with the users I know aren't
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4054 # "real" users
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4055 ignore = ['ekmmon', 'bfast', 'csrmail']
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4056
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4057 # users to keep - pre-load with the roundup-specific users
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4058 keep = ['comment_pool', 'network_pool', 'admin', 'dev-team',
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4059 'cs_pool', 'anonymous', 'system_pool', 'automated']
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4060
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4061 Now we map the UN*X group numbers to the Roles that users should have::
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4062
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4063 roles = {
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4064 '501': 'User,Tech', # tech
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4065 '502': 'User', # finance
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4066 '503': 'User,CSR', # customer service reps
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4067 '504': 'User', # sales
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4068 '505': 'User', # marketing
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4069 }
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4070
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4071 Now we do all the work. Note that the body of the script (where we have
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4072 the tracker database open) is wrapped in a ``try`` / ``finally`` clause,
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4073 so that we always close the database cleanly when we're finished. So, we
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4074 now do all the work::
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4075
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4076 # open the database
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4077 db = tracker.open('admin')
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4078 try:
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4079 # store away messages to send to the tracker admins
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4080 msg = []
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4081
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4082 # loop over the users list read in from the passwd file
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4083 for user,passw,uid,gid,real,home,shell in users:
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4084 if user in ignore:
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4085 # this user shouldn't appear in our tracker
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4086 continue
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4087 keep.append(user)
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4088 try:
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4089 # see if the user exists in the tracker
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4090 uid = db.user.lookup(user)
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4091
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4092 # yes, they do - now check the real name for correctness
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4093 if real != db.user.get(uid, 'realname'):
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4094 db.user.set(uid, realname=real)
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4095 msg.append('FIX %s - %s'%(user, real))
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4096 except KeyError:
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4097 # nope, the user doesn't exist
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4098 db.user.create(username=user, realname=real,
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4099 address='%s@ekit-inc.com'%user, roles=roles[gid])
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4100 msg.append('ADD %s - %s (%s)'%(user, real, roles[gid]))
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4101
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4102 # now check that all the users in the tracker are also in our
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4103 # "keep" list - retire those who aren't
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4104 for uid in db.user.list():
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4105 user = db.user.get(uid, 'username')
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4106 if user not in keep:
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4107 db.user.retire(uid)
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4108 msg.append('RET %s'%user)
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4109
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4110 # if we did work, then send email to the tracker admins
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4111 if msg:
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4112 # create the email
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4113 msg = '''Subject: %s user database maintenance
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4114
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4115 %s
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4116 '''%(db.config.TRACKER_NAME, '\n'.join(msg))
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4117
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4118 # send the email
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4119 smtp = smtplib.SMTP(db.config.MAILHOST)
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4120 addr = db.config.ADMIN_EMAIL
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4121 smtp.sendmail(addr, addr, msg)
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4122
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4123 # now we're done - commit the changes
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4124 db.commit()
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4125 finally:
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4126 # always close the database cleanly
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4127 db.close()
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4128
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4129 And that's it!
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4130
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4131
1680
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4132 Using an LDAP database for user information
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4133 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1680
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4134
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4135 A script that reads users from an LDAP store using
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4136 http://python-ldap.sf.net/ and then compares the list to the users in the
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4137 roundup user database would be pretty easy to write. You'd then have it run
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4138 once an hour / day (or on demand if you can work that into your LDAP store
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4139 workflow). See the example `Using a UN*X passwd file as the user database`_
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4140 for more information about doing this.
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4141
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4142 To authenticate off the LDAP store (rather than using the passwords in the
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4143 Roundup user database) you'd use the same python-ldap module inside an
2017
31d920b31642 Update customization examples too, expand upgrade notice a bit.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2016
diff changeset
4144 extension to the cgi interface. You'd do this by overriding the method called
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4145 ``verifyPassword`` on the ``LoginAction`` class in your tracker's
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4146 ``extensions`` directory (see `using an external password validation
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4147 source`_). The method is implemented by default as::
1680
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4148
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4149 def verifyPassword(self, userid, password):
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4150 ''' Verify the password that the user has supplied
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4151 '''
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4152 stored = self.db.user.get(self.userid, 'password')
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4153 if password == stored:
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4154 return 1
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4155 if not password and not stored:
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4156 return 1
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4157 return 0
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4158
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4159 So you could reimplement this as something like::
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4160
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4161 def verifyPassword(self, userid, password):
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4162 ''' Verify the password that the user has supplied
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4163 '''
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4164 # look up some unique LDAP information about the user
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4165 username = self.db.user.get(self.userid, 'username')
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4166 # now verify the password supplied against the LDAP store
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4167
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4168
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4169 Changes to Tracker Behaviour
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4170 ----------------------------
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4171
3830
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4172 Preventing SPAM
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4173 ~~~~~~~~~~~~~~~
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4174
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4175 The following detector code may be installed in your tracker's
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4176 ``detectors`` directory. It will block any messages being created that
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4177 have HTML attachments (a very common vector for spam and phishing)
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4178 and any messages that have more than 2 HTTP URLs in them. Just copy
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4179 the following into ``detectors/anti_spam.py`` in your tracker::
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4180
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4181 from roundup.exceptions import Reject
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4182
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4183 def reject_html(db, cl, nodeid, newvalues):
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4184 if newvalues['type'] == 'text/html':
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4185 raise Reject, 'not allowed'
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4186
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4187 def reject_manylinks(db, cl, nodeid, newvalues):
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4188 content = newvalues['content']
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4189 if content.count('http://') > 2:
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4190 raise Reject, 'not allowed'
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4191
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4192 def init(db):
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4193 db.file.audit('create', reject_html)
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4194 db.msg.audit('create', reject_manylinks)
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4195
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4196 You may also wish to block image attachments if your tracker does not
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4197 need that ability::
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4198
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4199 if newvalues['type'].startswith('image/'):
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4200 raise Reject, 'not allowed'
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4201
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4202
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4203 Stop "nosy" messages going to people on vacation
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4204 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4205
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4206 When users go on vacation and set up vacation email bouncing, you'll
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4207 start to see a lot of messages come back through Roundup "Fred is on
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4208 vacation". Not very useful, and relatively easy to stop.
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4209
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4210 1. add a "vacation" flag to your users::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4211
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4212 user = Class(db, "user",
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4213 username=String(), password=Password(),
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4214 address=String(), realname=String(),
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4215 phone=String(), organisation=String(),
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4216 alternate_addresses=String(),
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4217 roles=String(), queries=Multilink("query"),
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4218 vacation=Boolean())
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4219
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4220 2. So that users may edit the vacation flags, add something like the
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4221 following to your ``user.item`` template::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4222
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4223 <tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4224 <th>On Vacation</th>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4225 <td tal:content="structure context/vacation/field">vacation</td>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4226 </tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4227
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4228 3. edit your detector ``nosyreactor.py`` so that the ``nosyreaction()``
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4229 consists of::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4230
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4231 def nosyreaction(db, cl, nodeid, oldvalues):
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4232 users = db.user
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4233 messages = db.msg
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4234 # send a copy of all new messages to the nosy list
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4235 for msgid in determineNewMessages(cl, nodeid, oldvalues):
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4236 try:
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4237 # figure the recipient ids
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4238 sendto = []
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4239 seen_message = {}
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4240 recipients = messages.get(msgid, 'recipients')
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4241 for recipid in messages.get(msgid, 'recipients'):
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4242 seen_message[recipid] = 1
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4243
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4244 # figure the author's id, and indicate they've received
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4245 # the message
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4246 authid = messages.get(msgid, 'author')
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4247
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4248 # possibly send the message to the author, as long as
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4249 # they aren't anonymous
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4250 if (db.config.MESSAGES_TO_AUTHOR == 'yes' and
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4251 users.get(authid, 'username') != 'anonymous'):
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4252 sendto.append(authid)
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4253 seen_message[authid] = 1
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4254
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4255 # now figure the nosy people who weren't recipients
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4256 nosy = cl.get(nodeid, 'nosy')
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4257 for nosyid in nosy:
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4258 # Don't send nosy mail to the anonymous user (that
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4259 # user shouldn't appear in the nosy list, but just
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4260 # in case they do...)
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4261 if users.get(nosyid, 'username') == 'anonymous':
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4262 continue
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4263 # make sure they haven't seen the message already
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4264 if not seen_message.has_key(nosyid):
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4265 # send it to them
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4266 sendto.append(nosyid)
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4267 recipients.append(nosyid)
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4268
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4269 # generate a change note
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4270 if oldvalues:
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4271 note = cl.generateChangeNote(nodeid, oldvalues)
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4272 else:
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4273 note = cl.generateCreateNote(nodeid)
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4274
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4275 # we have new recipients
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4276 if sendto:
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4277 # filter out the people on vacation
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4278 sendto = [i for i in sendto
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4279 if not users.get(i, 'vacation', 0)]
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4280
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4281 # map userids to addresses
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4282 sendto = [users.get(i, 'address') for i in sendto]
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4283
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4284 # update the message's recipients list
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4285 messages.set(msgid, recipients=recipients)
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4286
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4287 # send the message
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4288 cl.send_message(nodeid, msgid, note, sendto)
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4289 except roundupdb.MessageSendError, message:
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4290 raise roundupdb.DetectorError, message
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4291
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4292 Note that this is the standard nosy reaction code, with the small
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4293 addition of::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4294
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4295 # filter out the people on vacation
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4296 sendto = [i for i in sendto if not users.get(i, 'vacation', 0)]
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4297
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4298 which filters out the users that have the vacation flag set to true.
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4299
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4300 Adding in state transition control
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4301 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4302
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4303 Sometimes tracker admins want to control the states to which users may
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4304 move issues. You can do this by following these steps:
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4305
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4306 1. make "status" a required variable. This is achieved by adding the
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4307 following to the top of the form in the ``issue.item.html``
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4308 template::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4309
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4310 <input type="hidden" name="@required" value="status">
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4311
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4312 This will force users to select a status.
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4313
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4314 2. add a Multilink property to the status class::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4315
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4316 stat = Class(db, "status", ... , transitions=Multilink('status'),
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4317 ...)
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4318
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4319 and then edit the statuses already created, either:
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4320
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4321 a. through the web using the class list -> status class editor, or
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4322 b. using the ``roundup-admin`` "set" command.
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4323
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4324 3. add an auditor module ``checktransition.py`` in your tracker's
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4325 ``detectors`` directory, for example::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4326
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4327 def checktransition(db, cl, nodeid, newvalues):
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4328 ''' Check that the desired transition is valid for the "status"
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4329 property.
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4330 '''
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4331 if not newvalues.has_key('status'):
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4332 return
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4333 current = cl.get(nodeid, 'status')
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4334 new = newvalues['status']
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4335 if new == current:
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4336 return
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4337 ok = db.status.get(current, 'transitions')
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4338 if new not in ok:
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4339 raise ValueError, 'Status not allowed to move from "%s" to "%s"'%(
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4340 db.status.get(current, 'name'), db.status.get(new, 'name'))
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4341
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4342 def init(db):
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4343 db.issue.audit('set', checktransition)
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4344
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4345 4. in the ``issue.item.html`` template, change the status editing bit
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4346 from::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4347
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4348 <th>Status</th>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4349 <td tal:content="structure context/status/menu">status</td>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4350
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4351 to::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4352
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4353 <th>Status</th>
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4354 <td>
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4355 <select tal:condition="context/id" name="status">
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4356 <tal:block tal:define="ok context/status/transitions"
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4357 tal:repeat="state db/status/list">
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4358 <option tal:condition="python:state.id in ok"
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4359 tal:attributes="
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4360 value state/id;
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4361 selected python:state.id == context.status.id"
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4362 tal:content="state/name"></option>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4363 </tal:block>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4364 </select>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4365 <tal:block tal:condition="not:context/id"
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4366 tal:replace="structure context/status/menu" />
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4367 </td>
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4368
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4369 which displays only the allowed status to transition to.
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4370
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
4371
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4372 Blocking issues that depend on other issues
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4373 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4374
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4375 We needed the ability to mark certain issues as "blockers" - that is,
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4376 they can't be resolved until another issue (the blocker) they rely on is
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4377 resolved. To achieve this:
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4378
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4379 1. Create a new property on the ``issue`` class:
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4380 ``blockers=Multilink("issue")``. To do this, edit the definition of
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4381 this class in your tracker's ``schema.py`` file. Change this::
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4382
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4383 issue = IssueClass(db, "issue",
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4384 assignedto=Link("user"), keyword=Multilink("keyword"),
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4385 priority=Link("priority"), status=Link("status"))
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4386
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4387 to this, adding the blockers entry::
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4388
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4389 issue = IssueClass(db, "issue",
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4390 blockers=Multilink("issue"),
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4391 assignedto=Link("user"), keyword=Multilink("keyword"),
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4392 priority=Link("priority"), status=Link("status"))
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4393
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4394 2. Add the new ``blockers`` property to the ``issue.item.html`` edit
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4395 page, using something like::
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4396
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
4397 <th>Waiting On</th>
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4398 <td>
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4399 <span tal:replace="structure python:context.blockers.field(showid=1,
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4400 size=20)" />
3881
e7050411a774 fix documentation per [SF#731171] thanks to Forest Wilkinson
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3878
diff changeset
4401 <span tal:replace="structure python:db.issue.classhelp('id,title',
e7050411a774 fix documentation per [SF#731171] thanks to Forest Wilkinson
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3878
diff changeset
4402 property='blockers')" />
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4403 <span tal:condition="context/blockers"
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4404 tal:repeat="blk context/blockers">
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4405 <br>View: <a tal:attributes="href string:issue${blk/id}"
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4406 tal:content="blk/id"></a>
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4407 </span>
3881
e7050411a774 fix documentation per [SF#731171] thanks to Forest Wilkinson
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3878
diff changeset
4408 </td>
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4409
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4410 You'll need to fiddle with your item page layout to find an
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4411 appropriate place to put it - I'll leave that fun part up to you.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4412 Just make sure it appears in the first table, possibly somewhere near
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4413 the "superseders" field.
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4414
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4415 3. Create a new detector module (see below) which enforces the rules:
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4416
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4417 - issues may not be resolved if they have blockers
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4418 - when a blocker is resolved, it's removed from issues it blocks
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4419
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4420 The contents of the detector should be something like this::
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4421
3258
1cbde34afa77 fix to doc
Richard Jones <richard@users.sourceforge.net>
parents: 3241
diff changeset
4422
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4423 def blockresolution(db, cl, nodeid, newvalues):
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4424 ''' If the issue has blockers, don't allow it to be resolved.
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4425 '''
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4426 if nodeid is None:
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4427 blockers = []
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4428 else:
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4429 blockers = cl.get(nodeid, 'blockers')
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4430 blockers = newvalues.get('blockers', blockers)
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4431
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4432 # don't do anything if there's no blockers or the status hasn't
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4433 # changed
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4434 if not blockers or not newvalues.has_key('status'):
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4435 return
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4436
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4437 # get the resolved state ID
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4438 resolved_id = db.status.lookup('resolved')
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4439
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4440 # format the info
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4441 u = db.config.TRACKER_WEB
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4442 s = ', '.join(['<a href="%sissue%s">%s</a>'%(
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4443 u,id,id) for id in blockers])
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4444 if len(blockers) == 1:
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4445 s = 'issue %s is'%s
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4446 else:
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4447 s = 'issues %s are'%s
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4448
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4449 # ok, see if we're trying to resolve
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4450 if newvalues['status'] == resolved_id:
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4451 raise ValueError, "This issue can't be resolved until %s resolved."%s
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4452
3258
1cbde34afa77 fix to doc
Richard Jones <richard@users.sourceforge.net>
parents: 3241
diff changeset
4453
1cbde34afa77 fix to doc
Richard Jones <richard@users.sourceforge.net>
parents: 3241
diff changeset
4454 def resolveblockers(db, cl, nodeid, oldvalues):
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4455 ''' When we resolve an issue that's a blocker, remove it from the
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4456 blockers list of the issue(s) it blocks.
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4457 '''
3258
1cbde34afa77 fix to doc
Richard Jones <richard@users.sourceforge.net>
parents: 3241
diff changeset
4458 newstatus = cl.get(nodeid,'status')
1cbde34afa77 fix to doc
Richard Jones <richard@users.sourceforge.net>
parents: 3241
diff changeset
4459
1cbde34afa77 fix to doc
Richard Jones <richard@users.sourceforge.net>
parents: 3241
diff changeset
4460 # no change?
1cbde34afa77 fix to doc
Richard Jones <richard@users.sourceforge.net>
parents: 3241
diff changeset
4461 if oldvalues.get('status', None) == newstatus:
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4462 return
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4463
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4464 resolved_id = db.status.lookup('resolved')
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4465
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4466 # interesting?
3258
1cbde34afa77 fix to doc
Richard Jones <richard@users.sourceforge.net>
parents: 3241
diff changeset
4467 if newstatus != resolved_id:
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4468 return
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4469
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4470 # yes - find all the blocked issues, if any, and remove me from
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4471 # their blockers list
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4472 issues = cl.find(blockers=nodeid)
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4473 for issueid in issues:
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4474 blockers = cl.get(issueid, 'blockers')
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4475 if nodeid in blockers:
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4476 blockers.remove(nodeid)
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4477 cl.set(issueid, blockers=blockers)
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4478
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4479 def init(db):
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4480 # might, in an obscure situation, happen in a create
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4481 db.issue.audit('create', blockresolution)
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4482 db.issue.audit('set', blockresolution)
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4483
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4484 # can only happen on a set
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4485 db.issue.react('set', resolveblockers)
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4486
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4487 Put the above code in a file called "blockers.py" in your tracker's
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4488 "detectors" directory.
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4489
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4490 4. Finally, and this is an optional step, modify the tracker web page
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4491 URLs so they filter out issues with any blockers. You do this by
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4492 adding an additional filter on "blockers" for the value "-1". For
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4493 example, the existing "Show All" link in the "page" template (in the
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4494 tracker's "html" directory) looks like this::
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4495
3796
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4496 <a href="#"
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4497 tal:attributes="href python:request.indexargs_url('issue', {
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4498 '@sort': '-activity',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4499 '@group': 'priority',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4500 '@filter': 'status',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4501 '@columns': columns_showall,
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4502 '@search_text': '',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4503 'status': status_notresolved,
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4504 '@dispname': i18n.gettext('Show All'),
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4505 })"
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4506 i18n:translate="">Show All</a><br>
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4507
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4508 modify it to add the "blockers" info to the URL (note, both the
3590
Richard Jones <richard@users.sourceforge.net>
parents: 3582
diff changeset
4509 "@filter" *and* "blockers" values must be specified)::
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4510
3796
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4511 <a href="#"
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4512 tal:attributes="href python:request.indexargs_url('issue', {
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4513 '@sort': '-activity',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4514 '@group': 'priority',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4515 '@filter': 'status,blockers',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4516 '@columns': columns_showall,
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4517 '@search_text': '',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4518 'status': status_notresolved,
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4519 'blockers': '-1',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4520 '@dispname': i18n.gettext('Show All'),
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4521 })"
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4522 i18n:translate="">Show All</a><br>
2409
Richard Jones <richard@users.sourceforge.net>
parents: 2397
diff changeset
4523
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
4524 The above examples are line-wrapped on the trailing & and should
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
4525 be unwrapped.
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4526
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4527 That's it. You should now be able to set blockers on your issues. Note
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4528 that if you want to know whether an issue has any other issues dependent
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4529 on it (i.e. it's in their blockers list) you can look at the journal
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4530 history at the bottom of the issue page - look for a "link" event to
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4531 another issue's "blockers" property.
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4532
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4533 Add users to the nosy list based on the keyword
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4534 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4535
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4536 Let's say we need the ability to automatically add users to the nosy
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4537 list based
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4538 on the occurance of a keyword. Every user should be allowed to edit their
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4539 own list of keywords for which they want to be added to the nosy list.
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4540
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4541 Below, we'll show that this change can be done with minimal
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4542 understanding of the Roundup system, using only copy and paste.
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4543
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4544 This requires three changes to the tracker: a change in the database to
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4545 allow per-user recording of the lists of keywords for which he wants to
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4546 be put on the nosy list, a change in the user view allowing them to edit
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4547 this list of keywords, and addition of an auditor which updates the nosy
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4548 list when a keyword is set.
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4549
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4550 Adding the nosy keyword list
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4551 ::::::::::::::::::::::::::::
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4552
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4553 The change to make in the database, is that for any user there should be a list
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4554 of keywords for which he wants to be put on the nosy list. Adding a
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4555 ``Multilink`` of ``keyword`` seems to fullfill this. As such, all that has to
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4556 be done is to add a new field to the definition of ``user`` within the file
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4557 ``schema.py``. We will call this new field ``nosy_keywords``, and the updated
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4558 definition of user will be::
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4559
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4560 user = Class(db, "user",
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4561 username=String(), password=Password(),
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4562 address=String(), realname=String(),
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4563 phone=String(), organisation=String(),
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4564 alternate_addresses=String(),
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4565 queries=Multilink('query'), roles=String(),
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4566 timezone=String(),
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4567 nosy_keywords=Multilink('keyword'))
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4568
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4569 Changing the user view to allow changing the nosy keyword list
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4570 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4571
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4572 We want any user to be able to change the list of keywords for which
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4573 he will by default be added to the nosy list. We choose to add this
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4574 to the user view, as is generated by the file ``html/user.item.html``.
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4575 We can easily
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4576 see that the keyword field in the issue view has very similar editing
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4577 requirements as our nosy keywords, both being lists of keywords. As
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4578 such, we look for Keywords in ``issue.item.html``, and extract the
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4579 associated parts from there. We add this to ``user.item.html`` at the
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4580 bottom of the list of viewed items (i.e. just below the 'Alternate
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4581 E-mail addresses' in the classic template)::
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4582
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4583 <tr>
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4584 <th>Nosy Keywords</th>
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4585 <td>
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4586 <span tal:replace="structure context/nosy_keywords/field" />
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4587 <span tal:replace="structure python:db.keyword.classhelp(property='nosy_keywords')" />
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4588 </td>
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4589 </tr>
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4590
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4591
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4592 Addition of an auditor to update the nosy list
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4593 ::::::::::::::::::::::::::::::::::::::::::::::
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4594
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4595 The more difficult part is the logic to add
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4596 the users to the nosy list when required.
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4597 We choose to perform this action whenever the keywords on an
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4598 item are set (this includes the creation of items).
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4599 Here we choose to start out with a copy of the
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4600 ``detectors/nosyreaction.py`` detector, which we copy to the file
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4601 ``detectors/nosy_keyword_reaction.py``.
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4602 This looks like a good start as it also adds users
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4603 to the nosy list. A look through the code reveals that the
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4604 ``nosyreaction`` function actually sends the e-mail.
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4605 We don't need this. Therefore, we can change the ``init`` function to::
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4606
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4607 def init(db):
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4608 db.issue.audit('create', update_kw_nosy)
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4609 db.issue.audit('set', update_kw_nosy)
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4610
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4611 After that, we rename the ``updatenosy`` function to ``update_kw_nosy``.
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4612 The first two blocks of code in that function relate to setting
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4613 ``current`` to a combination of the old and new nosy lists. This
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4614 functionality is left in the new auditor. The following block of
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4615 code, which handled adding the assignedto user(s) to the nosy list in
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4616 ``updatenosy``, should be replaced by a block of code to add the
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4617 interested users to the nosy list. We choose here to loop over all
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4618 new keywords, than looping over all users,
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4619 and assign the user to the nosy list when the keyword occurs in the user's
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4620 ``nosy_keywords``. The next part in ``updatenosy`` -- adding the author
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4621 and/or recipients of a message to the nosy list -- is obviously not
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4622 relevant here and is thus deleted from the new auditor. The last
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4623 part, copying the new nosy list to ``newvalues``, can stay as is.
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4624 This results in the following function::
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4625
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4626 def update_kw_nosy(db, cl, nodeid, newvalues):
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4627 '''Update the nosy list for changes to the keywords
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4628 '''
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4629 # nodeid will be None if this is a new node
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4630 current = {}
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4631 if nodeid is None:
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4632 ok = ('new', 'yes')
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4633 else:
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4634 ok = ('yes',)
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4635 # old node, get the current values from the node if they haven't
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4636 # changed
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4637 if not newvalues.has_key('nosy'):
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4638 nosy = cl.get(nodeid, 'nosy')
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4639 for value in nosy:
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4640 if not current.has_key(value):
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4641 current[value] = 1
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4642
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4643 # if the nosy list changed in this transaction, init from the new value
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4644 if newvalues.has_key('nosy'):
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4645 nosy = newvalues.get('nosy', [])
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4646 for value in nosy:
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4647 if not db.hasnode('user', value):
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4648 continue
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4649 if not current.has_key(value):
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4650 current[value] = 1
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4651
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4652 # add users with keyword in nosy_keywords to the nosy list
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4653 if newvalues.has_key('keyword') and newvalues['keyword'] is not None:
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4654 keyword_ids = newvalues['keyword']
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4655 for keyword in keyword_ids:
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4656 # loop over all users,
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4657 # and assign user to nosy when keyword in nosy_keywords
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4658 for user_id in db.user.list():
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4659 nosy_kw = db.user.get(user_id, "nosy_keywords")
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4660 found = 0
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4661 for kw in nosy_kw:
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4662 if kw == keyword:
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4663 found = 1
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4664 if found:
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4665 current[user_id] = 1
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4666
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4667 # that's it, save off the new nosy list
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4668 newvalues['nosy'] = current.keys()
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4669
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4670 These two function are the only ones needed in the file.
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4671
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4672 TODO: update this example to use the ``find()`` Class method.
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4673
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4674 Caveats
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4675 :::::::
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4676
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4677 A few problems with the design here can be noted:
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4678
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4679 Multiple additions
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4680 When a user, after automatic selection, is manually removed
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4681 from the nosy list, he is added to the nosy list again when the
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4682 keyword list of the issue is updated. A better design might be
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4683 to only check which keywords are new compared to the old list
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4684 of keywords, and only add users when they have indicated
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4685 interest on a new keyword.
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4686
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4687 The code could also be changed to only trigger on the ``create()``
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4688 event, rather than also on the ``set()`` event, thus only setting
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4689 the nosy list when the issue is created.
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4690
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4691 Scalability
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4692 In the auditor, there is a loop over all users. For a site with
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4693 only few users this will pose no serious problem; however, with
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4694 many users this will be a serious performance bottleneck.
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4695 A way out would be to link from the keywords to the users who
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4696 selected these keywords as nosy keywords. This will eliminate the
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4697 loop over all users.
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4698
4781
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4699 Restricting updates that arrive by email
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4700 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4701
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4702 Roundup supports multiple update methods:
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4703
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4704 1. command line
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4705 2. plain email
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4706 3. pgp signed email
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4707 4. web access
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4708
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4709 in some cases you may need to prevent changes to properties by some of
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4710 these methods. For example you can set up issues that are viewable
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4711 only by people on the nosy list. So you must prevent unauthenticated
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4712 changes to the nosy list.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4713
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4714 Since plain email can be easily forged, it does not provide sufficient
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4715 authentication in this senario.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4716
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4717 To prevent this we can add a detector that audits the source of the
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4718 transaction and rejects the update if it changes the nosy list.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4719
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4720 Create the detector (auditor) module and add it to the detectors
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4721 directory of your tracker::
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4722
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4723 from roundup import roundupdb, hyperdb
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4724
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4725 from roundup.mailgw import Unauthorized
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4726
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4727 def restrict_nosy_changes(db, cl, nodeid, newvalues):
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4728 '''Do not permit changes to nosy via email.'''
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4729
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4730 if not (newvalues.has_key('nosy')):
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4731 # the nosy field has not changed so no need to check.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4732 return
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4733
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4734 if db.tx_Source in ['web', 'email-sig-openpgp', 'cli' ]:
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4735 # if the source of the transaction is from an authenticated
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4736 # source or a privileged process allow the transaction.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4737 # Other possible sources: 'email'
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4738 return
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4739
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4740 # otherwise raise an error
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4741 raise Unauthorized, \
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4742 'Changes to nosy property not allowed via %s for this issue.'%\
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4743 tx_Source
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4744
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4745 def init(db):
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4746 ''' Install restrict_nosy_changes to run after other auditors.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4747
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4748 Allow initial creation email to set nosy.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4749 So don't execute: db.issue.audit('create', requestedbyauditor)
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4750
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4751 Set priority to 110 to run this auditor after other auditors
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4752 that can cause nosy to change.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4753 '''
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4754 db.issue.audit('set', restrict_nosy_changes, 110)
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4755
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4756 This detector (auditor) will prevent updates to the nosy field if it
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4757 arrives by email. Since it runs after other auditors (due to the
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4758 priority of 110), it will also prevent changes to the nosy field that
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4759 are done by other auditors if triggered by an email.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4760
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4761 Note that db.tx_Source was not present in roundup versions before
4790
07014a4b8a49 tx_Source property: doc fix.
Bernhard Reiter <bernhard@intevation.de>
parents: 4781
diff changeset
4762 1.4.22, so you must be running a newer version to use this detector.
4781
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4763 Read the CHANGES.txt document in the roundup source code for further
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4764 details on tx_Source.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4765
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4766 Changes to Security and Permissions
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4767 -----------------------------------
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4768
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4769 Restricting the list of users that are assignable to a task
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4770 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4771
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
4772 1. In your tracker's ``schema.py``, create a new Role, say "Developer"::
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4773
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4774 db.security.addRole(name='Developer', description='A developer')
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4775
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4776 2. Just after that, create a new Permission, say "Fixer", specific to
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4777 "issue"::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4778
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4779 p = db.security.addPermission(name='Fixer', klass='issue',
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4780 description='User is allowed to be assigned to fix issues')
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4781
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4782 3. Then assign the new Permission to your "Developer" Role::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4783
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4784 db.security.addPermissionToRole('Developer', p)
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4785
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4786 4. In the issue item edit page (``html/issue.item.html`` in your tracker
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4787 directory), use the new Permission in restricting the "assignedto"
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4788 list::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4789
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4790 <select name="assignedto">
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4791 <option value="-1">- no selection -</option>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4792 <tal:block tal:repeat="user db/user/list">
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4793 <option tal:condition="python:user.hasPermission(
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4794 'Fixer', context._classname)"
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4795 tal:attributes="
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4796 value user/id;
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4797 selected python:user.id == context.assignedto"
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4798 tal:content="user/realname"></option>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4799 </tal:block>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4800 </select>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4801
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4802 For extra security, you may wish to setup an auditor to enforce the
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4803 Permission requirement (install this as ``assignedtoFixer.py`` in your
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4804 tracker ``detectors`` directory)::
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4805
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4806 def assignedtoMustBeFixer(db, cl, nodeid, newvalues):
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4807 ''' Ensure the assignedto value in newvalues is used with the
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4808 Fixer Permission
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4809 '''
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4810 if not newvalues.has_key('assignedto'):
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4811 # don't care
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4812 return
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4813
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4814 # get the userid
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4815 userid = newvalues['assignedto']
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4816 if not db.security.hasPermission('Fixer', userid, cl.classname):
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4817 raise ValueError, 'You do not have permission to edit %s'%cl.classname
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4818
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4819 def init(db):
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4820 db.issue.audit('set', assignedtoMustBeFixer)
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4821 db.issue.audit('create', assignedtoMustBeFixer)
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4822
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4823 So now, if an edit action attempts to set "assignedto" to a user that
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4824 doesn't have the "Fixer" Permission, the error will be raised.
1816
61a23c293147 added another example
Richard Jones <richard@users.sourceforge.net>
parents: 1808
diff changeset
4825
3121
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
4826
1954
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
4827 Users may only edit their issues
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4828 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1954
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
4829
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4830 In this case, users registering themselves are granted Provisional
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4831 access, meaning they
1954
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
4832 have access to edit the issues they submit, but not others. We create a new
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
4833 Role called "Provisional User" which is granted to newly-registered users,
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
4834 and has limited access. One of the Permissions they have is the new "Edit
3121
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
4835 Own" on issues (regular users have "Edit".)
1954
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
4836
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
4837 First up, we create the new Role and Permission structure in
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
4838 ``schema.py``::
1954
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
4839
3121
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
4840 #
1954
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
4841 # New users not approved by the admin
3121
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
4842 #
1954
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
4843 db.security.addRole(name='Provisional User',
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
4844 description='New user registered via web or email')
2991
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
4845
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
4846 # These users need to be able to view and create issues but only edit
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
4847 # and view their own
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
4848 db.security.addPermissionToRole('Provisional User', 'Create', 'issue')
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
4849 def own_issue(db, userid, itemid):
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
4850 '''Determine whether the userid matches the creator of the issue.'''
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
4851 return userid == db.issue.get(itemid, 'creator')
3079
64df8d65cc54 fix "Users may only edit their issues"
Richard Jones <richard@users.sourceforge.net>
parents: 3052
diff changeset
4852 p = db.security.addPermission(name='Edit', klass='issue',
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4853 check=own_issue, description='Can only edit own issues')
1954
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
4854 db.security.addPermissionToRole('Provisional User', p)
3079
64df8d65cc54 fix "Users may only edit their issues"
Richard Jones <richard@users.sourceforge.net>
parents: 3052
diff changeset
4855 p = db.security.addPermission(name='View', klass='issue',
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4856 check=own_issue, description='Can only view own issues')
1954
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
4857 db.security.addPermissionToRole('Provisional User', p)
2991
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
4858
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
4859 # Assign the Permissions for issue-related classes
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
4860 for cl in 'file', 'msg', 'query', 'keyword':
3121
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
4861 db.security.addPermissionToRole('Provisional User', 'View', cl)
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
4862 db.security.addPermissionToRole('Provisional User', 'Edit', cl)
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
4863 db.security.addPermissionToRole('Provisional User', 'Create', cl)
2991
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
4864 for cl in 'priority', 'status':
3121
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
4865 db.security.addPermissionToRole('Provisional User', 'View', cl)
1954
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
4866
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
4867 # and give the new users access to the web and email interface
2991
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
4868 db.security.addPermissionToRole('Provisional User', 'Web Access')
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
4869 db.security.addPermissionToRole('Provisional User', 'Email Access')
1954
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
4870
3260
e41e1540a287 fix provisional user so they can view their own record
Richard Jones <richard@users.sourceforge.net>
parents: 3258
diff changeset
4871 # make sure they can view & edit their own user record
e41e1540a287 fix provisional user so they can view their own record
Richard Jones <richard@users.sourceforge.net>
parents: 3258
diff changeset
4872 def own_record(db, userid, itemid):
e41e1540a287 fix provisional user so they can view their own record
Richard Jones <richard@users.sourceforge.net>
parents: 3258
diff changeset
4873 '''Determine whether the userid matches the item being accessed.'''
e41e1540a287 fix provisional user so they can view their own record
Richard Jones <richard@users.sourceforge.net>
parents: 3258
diff changeset
4874 return userid == itemid
e41e1540a287 fix provisional user so they can view their own record
Richard Jones <richard@users.sourceforge.net>
parents: 3258
diff changeset
4875 p = db.security.addPermission(name='View', klass='user', check=own_record,
e41e1540a287 fix provisional user so they can view their own record
Richard Jones <richard@users.sourceforge.net>
parents: 3258
diff changeset
4876 description="User is allowed to view their own user details")
e41e1540a287 fix provisional user so they can view their own record
Richard Jones <richard@users.sourceforge.net>
parents: 3258
diff changeset
4877 db.security.addPermissionToRole('Provisional User', p)
e41e1540a287 fix provisional user so they can view their own record
Richard Jones <richard@users.sourceforge.net>
parents: 3258
diff changeset
4878 p = db.security.addPermission(name='Edit', klass='user', check=own_record,
e41e1540a287 fix provisional user so they can view their own record
Richard Jones <richard@users.sourceforge.net>
parents: 3258
diff changeset
4879 description="User is allowed to edit their own user details")
e41e1540a287 fix provisional user so they can view their own record
Richard Jones <richard@users.sourceforge.net>
parents: 3258
diff changeset
4880 db.security.addPermissionToRole('Provisional User', p)
1954
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
4881
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4882 Then, in ``config.ini``, we change the Role assigned to newly-registered
1954
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
4883 users, replacing the existing ``'User'`` values::
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
4884
2921
ad4fb8a14a97 more doc updates, not so many TODOs any more
Richard Jones <richard@users.sourceforge.net>
parents: 2915
diff changeset
4885 [main]
ad4fb8a14a97 more doc updates, not so many TODOs any more
Richard Jones <richard@users.sourceforge.net>
parents: 2915
diff changeset
4886 ...
4941
b76710818d31 Roundup Tracker isssue #: 2550857
John Rouillard <rouilj@ieee.org>
parents: 4921
diff changeset
4887 new_web_user_roles = Provisional User
b76710818d31 Roundup Tracker isssue #: 2550857
John Rouillard <rouilj@ieee.org>
parents: 4921
diff changeset
4888 new_email_user_roles = Provisional User
1954
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
4889
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
4890
3126
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
4891 All users may only view and edit issues, files and messages they create
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
4892 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
4893
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
4894 Replace the standard "classic" tracker View and Edit Permission assignments
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
4895 for the "issue", "file" and "msg" classes with the following::
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
4896
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
4897 def checker(klass):
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
4898 def check(db, userid, itemid, klass=klass):
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
4899 return db.getclass(klass).get(itemid, 'creator') == userid
3580
5c26b9bbd31a fix "All users may only view and edit issues, files and messages they...
Richard Jones <richard@users.sourceforge.net>
parents: 3548
diff changeset
4900 return check
3126
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
4901 for cl in 'issue', 'file', 'msg':
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
4902 p = db.security.addPermission(name='View', klass=cl,
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
4903 check=checker(cl))
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
4904 db.security.addPermissionToRole('User', p)
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
4905 p = db.security.addPermission(name='Edit', klass=cl,
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
4906 check=checker(cl))
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
4907 db.security.addPermissionToRole('User', p)
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
4908 db.security.addPermissionToRole('User', 'Create', cl)
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
4909
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
4910
4300
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
4911 Moderating user registration
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
4912 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
4913
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
4914 You could set up new-user moderation in a public tracker by:
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
4915
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
4916 1. creating a new highly-restricted user role "Pending",
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
4917 2. set the config new_web_user_roles and/or new_email_user_roles to that
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
4918 role,
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
4919 3. have an auditor that emails you when new users are created with that
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
4920 role using roundup.mailer
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
4921 4. edit the role to "User" for valid users.
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
4922
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
4923 Some simple javascript might help in the last step. If you have high volume
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
4924 you could search for all currently-Pending users and do a bulk edit of all
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
4925 their roles at once (again probably with some simple javascript help).
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
4926
3126
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
4927
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4928 Changes to the Web User Interface
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4929 ---------------------------------
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4930
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4931 Adding action links to the index page
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4932 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4933
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4934 Add a column to the ``item.index.html`` template.
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4935
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4936 Resolving the issue::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4937
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4938 <a tal:attributes="href
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4939 string:issue${i/id}?:status=resolved&:action=edit">resolve</a>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4940
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4941 "Take" the issue::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4942
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4943 <a tal:attributes="href
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4944 string:issue${i/id}?:assignedto=${request/user/id}&:action=edit">take</a>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4945
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4946 ... and so on.
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4947
1966
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
4948 Colouring the rows in the issue index according to priority
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4949 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1966
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
4950
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
4951 A simple ``tal:attributes`` statement will do the bulk of the work here. In
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4952 the ``issue.index.html`` template, add this to the ``<tr>`` that
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4953 displays the rows of data::
1966
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
4954
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
4955 <tr tal:attributes="class string:priority-${i/priority/plain}">
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
4956
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
4957 and then in your stylesheet (``style.css``) specify the colouring for the
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4958 different priorities, as follows::
1966
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
4959
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
4960 tr.priority-critical td {
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
4961 background-color: red;
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
4962 }
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
4963
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
4964 tr.priority-urgent td {
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
4965 background-color: orange;
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
4966 }
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
4967
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
4968 and so on, with far less offensive colours :)
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
4969
2009
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4970 Editing multiple items in an index view
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4971 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2009
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4972
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4973 To edit the status of all items in the item index view, edit the
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4974 ``issue.item.html``:
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4975
2726
aa95c79cff8b clarification
Richard Jones <richard@users.sourceforge.net>
parents: 2589
diff changeset
4976 1. add a form around the listing table (separate from the existing
aa95c79cff8b clarification
Richard Jones <richard@users.sourceforge.net>
parents: 2589
diff changeset
4977 index-page form), so at the top it reads::
2009
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4978
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4979 <form method="POST" tal:attributes="action request/classname">
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4980 <table class="list">
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4981
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4982 and at the bottom of that table::
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4983
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4984 </table>
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4985 </form
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4986
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4987 making sure you match the ``</table>`` from the list table, not the
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4988 navigation table or the subsequent form table.
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4989
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4990 2. in the display for the issue property, change::
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4991
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4992 <td tal:condition="request/show/status"
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4993 tal:content="python:i.status.plain() or default">&nbsp;</td>
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4994
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4995 to::
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4996
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4997 <td tal:condition="request/show/status"
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4998 tal:content="structure i/status/field">&nbsp;</td>
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
4999
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5000 this will result in an edit field for the status property.
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5001
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
5002 3. after the ``tal:block`` which lists the index items (marked by
2009
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5003 ``tal:repeat="i batch"``) add a new table row::
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5004
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5005 <tr>
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5006 <td tal:attributes="colspan python:len(request.columns)">
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5007 <input type="submit" value=" Save Changes ">
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5008 <input type="hidden" name="@action" value="edit">
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5009 <tal:block replace="structure request/indexargs_form" />
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5010 </td>
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5011 </tr>
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5012
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5013 which gives us a submit button, indicates that we are performing an edit
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
5014 on any changed statuses. The final ``tal:block`` will make sure that the
2009
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5015 current index view parameters (filtering, columns, etc) will be used in
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5016 rendering the next page (the results of the editing).
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5017
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5018
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5019 Displaying only message summaries in the issue display
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5020 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5021
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
5022 Alter the ``issue.item`` template section for messages to::
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5023
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5024 <table class="messages" tal:condition="context/messages">
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5025 <tr><th colspan="5" class="header">Messages</th></tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5026 <tr tal:repeat="msg context/messages">
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5027 <td><a tal:attributes="href string:msg${msg/id}"
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5028 tal:content="string:msg${msg/id}"></a></td>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5029 <td tal:content="msg/author">author</td>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5030 <td class="date" tal:content="msg/date/pretty">date</td>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5031 <td tal:content="msg/summary">summary</td>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5032 <td>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5033 <a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5034 remove</a>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5035 </td>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5036 </tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5037 </table>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5038
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5039
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5040 Enabling display of either message summaries or the entire messages
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5041 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5042
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5043 This is pretty simple - all we need to do is copy the code from the
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5044 example `displaying only message summaries in the issue display`_ into
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5045 our template alongside the summary display, and then introduce a switch
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
5046 that shows either the one or the other. We'll use a new form variable,
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5047 ``@whole_messages`` to achieve this::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5048
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5049 <table class="messages" tal:condition="context/messages">
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5050 <tal:block tal:condition="not:request/form/@whole_messages/value | python:0">
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5051 <tr><th colspan="3" class="header">Messages</th>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5052 <th colspan="2" class="header">
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5053 <a href="?@whole_messages=yes">show entire messages</a>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5054 </th>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5055 </tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5056 <tr tal:repeat="msg context/messages">
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5057 <td><a tal:attributes="href string:msg${msg/id}"
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5058 tal:content="string:msg${msg/id}"></a></td>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5059 <td tal:content="msg/author">author</td>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5060 <td class="date" tal:content="msg/date/pretty">date</td>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5061 <td tal:content="msg/summary">summary</td>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5062 <td>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5063 <a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">remove</a>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5064 </td>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5065 </tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5066 </tal:block>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5067
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5068 <tal:block tal:condition="request/form/@whole_messages/value | python:0">
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5069 <tr><th colspan="2" class="header">Messages</th>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5070 <th class="header">
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5071 <a href="?@whole_messages=">show only summaries</a>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5072 </th>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5073 </tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5074 <tal:block tal:repeat="msg context/messages">
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5075 <tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5076 <th tal:content="msg/author">author</th>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5077 <th class="date" tal:content="msg/date/pretty">date</th>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5078 <th style="text-align: right">
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5079 (<a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">remove</a>)
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5080 </th>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5081 </tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5082 <tr><td colspan="3" tal:content="msg/content"></td></tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5083 </tal:block>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5084 </tal:block>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5085 </table>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5086
3121
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
5087
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5088 Setting up a "wizard" (or "druid") for controlled adding of issues
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5089 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5090
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5091 1. Set up the page templates you wish to use for data input. My wizard
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5092 is going to be a two-step process: first figuring out what category
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5093 of issue the user is submitting, and then getting details specific to
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5094 that category. The first page includes a table of help, explaining
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5095 what the category names mean, and then the core of the form::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5096
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5097 <form method="POST" onSubmit="return submit_once()"
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5098 enctype="multipart/form-data">
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5099 <input type="hidden" name="@template" value="add_page1">
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5100 <input type="hidden" name="@action" value="page1_submit">
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5101
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5102 <strong>Category:</strong>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5103 <tal:block tal:replace="structure context/category/menu" />
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5104 <input type="submit" value="Continue">
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5105 </form>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5106
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5107 The next page has the usual issue entry information, with the
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5108 addition of the following form fragments::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5109
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5110 <form method="POST" onSubmit="return submit_once()"
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5111 enctype="multipart/form-data"
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5112 tal:condition="context/is_edit_ok"
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5113 tal:define="cat request/form/category/value">
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5114
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5115 <input type="hidden" name="@template" value="add_page2">
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5116 <input type="hidden" name="@required" value="title">
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5117 <input type="hidden" name="category" tal:attributes="value cat">
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5118 .
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5119 .
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5120 .
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5121 </form>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5122
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
5123 Note that later in the form, I use the value of "cat" to decide which
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
5124 form elements should be displayed. For example::
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5125
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5126 <tal:block tal:condition="python:cat in '6 10 13 14 15 16 17'.split()">
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5127 <tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5128 <th>Operating System</th>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5129 <td tal:content="structure context/os/field"></td>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5130 </tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5131 <tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5132 <th>Web Browser</th>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5133 <td tal:content="structure context/browser/field"></td>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5134 </tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5135 </tal:block>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5136
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5137 ... the above section will only be displayed if the category is one
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5138 of 6, 10, 13, 14, 15, 16 or 17.
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5139
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5140 3. Determine what actions need to be taken between the pages - these are
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5141 usually to validate user choices and determine what page is next. Now encode
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
5142 those actions in a new ``Action`` class (see `defining new web actions`_)::
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
5143
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
5144 from roundup.cgi.actions import Action
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5145
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5146 class Page1SubmitAction(Action):
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5147 def handle(self):
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5148 ''' Verify that the user has selected a category, and then move
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5149 on to page 2.
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5150 '''
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5151 category = self.form['category'].value
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5152 if category == '-1':
4880
ca692423e401 Different approach to fix XSS in issue2550817
Ralf Schlatterbeck <rsc@runtux.com>
parents: 4790
diff changeset
5153 self.client.add_error_message('You must select a category of report')
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5154 return
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5155 # everything's ok, move on to the next page
4464
c62c0f383e41 Fix incorrect setting of template in customizing.txt example action
Richard Jones <richard@users.sourceforge.net>
parents: 4435
diff changeset
5156 self.client.template = 'add_page2'
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5157
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
5158 def init(instance):
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
5159 instance.registerAction('page1_submit', Page1SubmitAction)
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5160
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5161 4. Use the usual "new" action as the ``@action`` on the final page, and
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5162 you're done (the standard context/submit method can do this for you).
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5163
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5164
3548
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5165 Debugging Trackers
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5166 ==================
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5167
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5168 There are three switches in tracker configs that turn on debugging in
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5169 Roundup:
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5170
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5171 1. web :: debug
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5172 2. mail :: debug
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5173 3. logging :: level
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5174
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5175 See the config.ini file or the `tracker configuration`_ section above for
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5176 more information.
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5177
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5178 Additionally, the ``roundup-server.py`` script has its own debugging mode
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5179 in which it reloads edited templates immediately when they are changed,
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5180 rather than requiring a web server restart.
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5181
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5182
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
5183 .. _`design documentation`: design.html
4325
6ec048310de7 add simple doc about translating customised tracker content
Richard Jones <richard@users.sourceforge.net>
parents: 4300
diff changeset
5184 .. _`developer's guide`: developers.html

Roundup Issue Tracker: http://roundup-tracker.org/