annotate doc/customizing.txt @ 5232:462b0f76fce8

issue2550864 - Potential information leakage via journal/history Fix this by making the hyperdb::Class::history function check for view permissions on the journaled properties. So a user that sees [hidden] for a property in the web interface doesn;t see the property changes in the history. While doing this, relocated the filter for quiet properties from the templating class to the hyperdb. Also added the skipquiet option to the history command in roundup-admin.py to enable filtering of quiet params. Also changed calls to history() in the backend databases to report all items. Changed inline documentation for all history calls that document the actions. The create action (before nov 6 2002) used to record all parameters. After that point the create call uses an empty dictionary. The filtering code depends on the create dictionary being empty. It may not operate properly on very old roundup databases. Changed calls to logging.getLogger to roundup.hyperdb.backends to allow filtering the back end while keeping hyperdb logging. In cgi/templating.py, changed history() function consolidating handiling of link and unlink actions Added tests for quiet property filtering and permission filtering of history.
author John Rouillard <rouilj@ieee.org>
date Fri, 14 Apr 2017 23:24:18 -0400
parents 8743b7226dc7
children 15440504fb04
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
5231
8743b7226dc7 Fix issue with retreiving raw template files using the @@file mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5227
diff changeset
90 Example configuration settings are below.
8743b7226dc7 Fix issue with retreiving raw template files using the @@file mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5227
diff changeset
91
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
92 Section **main**
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
93 database -- ``db``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
94 Database directory path. The path may be either absolute or relative
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
95 to the directory containig this config file.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
96
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
97 templates -- ``html``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
98 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
99 or relative to the directory containing this config file.
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
100
3922
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
101 static_files -- default *blank*
5231
8743b7226dc7 Fix issue with retreiving raw template files using the @@file mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5227
diff changeset
102 A list of space separated directory paths (or a single directory).
8743b7226dc7 Fix issue with retreiving raw template files using the @@file mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5227
diff changeset
103 These directories hold additional static files available via Web UI.
8743b7226dc7 Fix issue with retreiving raw template files using the @@file mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5227
diff changeset
104 These directories may contain sitewide images, CSS stylesheets etc. If
8743b7226dc7 Fix issue with retreiving raw template files using the @@file mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5227
diff changeset
105 a '-' is included, the list processing ends and the TEMPLATES
8743b7226dc7 Fix issue with retreiving raw template files using the @@file mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5227
diff changeset
106 directory is not searched after the specified directories. If this
8743b7226dc7 Fix issue with retreiving raw template files using the @@file mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5227
diff changeset
107 option is not set, all static files are taken from the TEMPLATES
8743b7226dc7 Fix issue with retreiving raw template files using the @@file mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5227
diff changeset
108 directory.
3922
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
109
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
110 admin_email -- ``roundup-admin``
2914
c75a19894d3e alex's feedback
Richard Jones <richard@users.sourceforge.net>
parents: 2911
diff changeset
111 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
112 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
113 below is used.
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
114
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
115 dispatcher_email -- ``roundup-admin``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
116 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
117 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
118 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
119 below is used.
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
120
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
121 email_from_tag -- default *blank*
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
122 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
123 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
124 is usually: ``"Foo Bar" <issue_tracker@tracker.example>``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
125 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
126 ``"Foo Bar EMAIL_FROM_TAG" <issue_tracker@tracker.example>``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
127
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
128 new_web_user_roles -- ``User``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
129 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
130 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
131
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
132 new_email_user_roles -- ``User``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
133 Roles that a user gets when they register with Email Gateway.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
134 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
135
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
136 error_messages_to -- ``user``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
137 Send error message emails to the ``dispatcher``, ``user``, or ``both``?
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
138 The dispatcher is configured using the DISPATCHER_EMAIL setting.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
139 Allowed values: ``dispatcher``, ``user``, or ``both``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
140
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
141 html_version -- ``html4``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
142 HTML version to generate. The templates are ``html4`` by default.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
143 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
144 var to ``xhtml`` too so all auto-generated HTML is compliant.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
145 Allowed values: ``html4``, ``xhtml``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
146
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
147 timezone -- ``0``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
148 Numeric timezone offset used when users do not choose their own
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
149 in their settings.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
150
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
151 instant_registration -- ``yes``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
152 Register new users instantly, or require confirmation via
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
153 email?
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
154 Allowed values: ``yes``, ``no``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
155
3544
5cd1c83dea50 Features and fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 3535
diff changeset
156 email_registration_confirmation -- ``yes``
5cd1c83dea50 Features and fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 3535
diff changeset
157 Offer registration confirmation by email or only through the web?
5cd1c83dea50 Features and fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 3535
diff changeset
158 Allowed values: ``yes``, ``no``
5cd1c83dea50 Features and fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 3535
diff changeset
159
5cd1c83dea50 Features and fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 3535
diff changeset
160 indexer_stopwords -- default *blank*
5cd1c83dea50 Features and fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 3535
diff changeset
161 Additional stop-words for the full-text indexer specific to
5cd1c83dea50 Features and fixes.
Richard Jones <richard@users.sourceforge.net>
parents: 3535
diff changeset
162 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
163 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
164
3922
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
165 umask -- ``02``
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
166 Defines the file creation mode mask.
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
167
5047
b8a04cce88ff Adding documentation for csv_field_size to the customizing tracker section issue2550669
John Rouillard <rouilj@ieee.org>
parents: 5004
diff changeset
168 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
169 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
170 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
171 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
172 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
173 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
174 import.
b8a04cce88ff Adding documentation for csv_field_size to the customizing tracker section issue2550669
John Rouillard <rouilj@ieee.org>
parents: 5004
diff changeset
175
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
176 Section **tracker**
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
177 name -- ``Roundup issue tracker``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
178 A descriptive name for your roundup instance.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
179
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
180 web -- ``http://host.example/demo/``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
181 The web address that the tracker is viewable at.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
182 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
183 The URL MUST include the cgi-bin part or anything else
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
184 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
185 You MUST include a trailing '/' in the URL.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
186
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
187 email -- ``issue_tracker``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
188 Email address that mail to roundup should go to.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
189
3922
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
190 language -- default *blank*
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
191 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
192 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
193 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
194
3548
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
195 Section **web**
4088
34434785f308 Plug a number of security holes:
Richard Jones <richard@users.sourceforge.net>
parents: 4036
diff changeset
196 allow_html_file -- ``no``
34434785f308 Plug a number of security holes:
Richard Jones <richard@users.sourceforge.net>
parents: 4036
diff changeset
197 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
198 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
199 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
200 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
201
3548
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
202 http_auth -- ``yes``
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
203 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
204 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
205 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
206 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
207 Authentication in your web interface.
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
208
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
209 use_browser_language -- ``yes``
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
210 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
211 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
212 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
213 Operating System.
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
214 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
215
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
216 debug -- ``no``
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
217 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
218 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
219 tracker admin."),
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
220
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
221 Section **rdbms**
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
222 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
223
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
224 name -- ``roundup``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
225 Name of the database to use.
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 host -- ``localhost``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
228 Database server host.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
229
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
230 port -- default *blank*
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
231 TCP port number of the database server. Postgresql usually resides on
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
232 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
233 option empty to use backend default.
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 user -- ``roundup``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
236 Database user name that Roundup should use.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
237
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
238 password -- ``roundup``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
239 Database user password.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
240
3922
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
241 read_default_file -- ``~/.my.cnf``
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
242 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
243
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
244 read_default_group -- ``roundup``
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
245 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
246 MySQL connections.
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
247
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
248 Section **logging**
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
249 config -- default *blank*
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
250 Path to configuration file for standard Python logging module. If this
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
251 option is set, logging configuration is loaded from specified file;
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
252 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
253 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
254
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
255 filename -- default *blank*
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
256 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
257 name specified, log messages are written on stderr. If above 'config'
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
258 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
259 or relative to the directory containig this config file.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
260
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
261 level -- ``ERROR``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
262 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
263 option is set, this option has no effect.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
264 Allowed values: ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
265
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
266 Section **mail**
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
267 Outgoing email options. Used for nosy messages, password reset and
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
268 registration approval requests.
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 domain -- ``localhost``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
271 Domain name used for email addresses.
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 host -- default *blank*
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
274 SMTP mail host that roundup will use to send mail
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
275
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
276 username -- default *blank*
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
277 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
278 If username is not empty, password (below) MUST be set!
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
279
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
280 password -- default *blank*
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
281 SMTP login password.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
282 Set this if your mail host requires authenticated access.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
283
3878
6d14a3b4e295 allow admin to specify port and local hostname for SMTP connections
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3830
diff changeset
284 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
285 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
286 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
287
6d14a3b4e295 allow admin to specify port and local hostname for SMTP connections
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3830
diff changeset
288 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
289 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
290 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
291 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
292
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
293 tls -- ``no``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
294 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
295 then you may set this option to 'yes'.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
296 Allowed values: ``yes``, ``no``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
297
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
298 tls_keyfile -- default *blank*
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
299 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
300 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
301 relative to the directory containig this config file.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
302
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
303 tls_certfile -- default *blank*
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
304 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
305 certificate chain file. The path may be either absolute or relative
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
306 to the directory containig this config file.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
307
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
308 charset -- utf-8
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
309 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
310 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
311 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
312 (eg. iso-8859-1).
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
313
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
314 debug -- default *blank*
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
315 Setting this option makes Roundup to write all outgoing email messages
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
316 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
317 as environment variable SENDMAILDEBUG. Environment variable takes
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
318 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
319 containig this config file.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
320
3922
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
321 add_authorinfo -- ``yes``
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
322 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
323 roundup.
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
324
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
325 add_authoremail -- ``yes``
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
326 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
327 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
328 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
329 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
330
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
331 Section **mailgw**
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
332 Roundup Mail Gateway options
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
333
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
334 keep_quoted_text -- ``yes``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
335 Keep email citations when accepting messages. Setting this to ``no`` strips
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
336 out "quoted" text from the message. Signatures are also stripped.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
337 Allowed values: ``yes``, ``no``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
338
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
339 leave_body_unchanged -- ``no``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
340 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
341 signatures.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
342 Allowed values: ``yes``, ``no``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
343
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
344 default_class -- ``issue``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
345 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
346 To disable, leave the value blank.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
347
3922
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
348 language -- default *blank*
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
349 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
350 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
351
3417
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
352 subject_prefix_parsing -- ``strict``
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
353 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
354 ``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
355 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
356 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
357 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
358
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
359 subject_suffix_parsing -- ``strict``
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
360 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
361 ``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
362 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
363 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
364 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
365
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
366 subject_suffix_delimiters -- ``[]``
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
367 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
368 line.
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
369
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
370 subject_content_match -- ``always``
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
371 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
372 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
373 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
374 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
375 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
376
4406
3a0395583de5 add missing config options
Richard Jones <richard@users.sourceforge.net>
parents: 4325
diff changeset
377 subject_updates_title -- ``yes``
3a0395583de5 add missing config options
Richard Jones <richard@users.sourceforge.net>
parents: 4325
diff changeset
378 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
379 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
380 the subject of incoming email messages.
3a0395583de5 add missing config options
Richard Jones <richard@users.sourceforge.net>
parents: 4325
diff changeset
381
3922
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
382 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
383 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
384 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
385 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
386 (UTF8-encoded).
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
387
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
388 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
389 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
390 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
391
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
392 sign_re -- ``^[>|\s]*-- ?$``
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
393 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
394 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
395
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
396 eol_re -- ``[\r\n]+``
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
397 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
398 Expression (UTF8-encoded).
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
399
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
400 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
401 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
402 Expression (UTF8-encoded).
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
403
4406
3a0395583de5 add missing config options
Richard Jones <richard@users.sourceforge.net>
parents: 4325
diff changeset
404 ignore_alternatives -- ``no``
3a0395583de5 add missing config options
Richard Jones <richard@users.sourceforge.net>
parents: 4325
diff changeset
405 When parsing incoming mails, roundup uses the first
3a0395583de5 add missing config options
Richard Jones <richard@users.sourceforge.net>
parents: 4325
diff changeset
406 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
407 multipart/alternative, and this option is set, all other
3a0395583de5 add missing config options
Richard Jones <richard@users.sourceforge.net>
parents: 4325
diff changeset
408 parts of the multipart/alternative are ignored. The default
3a0395583de5 add missing config options
Richard Jones <richard@users.sourceforge.net>
parents: 4325
diff changeset
409 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
410
3922
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
411 Section **pgp**
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
412 OpenPGP mail processing options
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 enable -- ``no``
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
415 Enable PGP processing. Requires pyme.
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
416
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
417 roles -- default *blank*
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
418 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
419 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
420
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
421 homedir -- default *blank*
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
422 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
423 specified.
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
424
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
425 Section **nosy**
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
426 Nosy messages sending
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
427
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
428 messages_to_author -- ``no``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
429 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
430 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
431 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
432 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
433 Allowed values: ``yes``, ``no``, ``new``, ``nosy``
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
434
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
435 signature_position -- ``bottom``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
436 Where to place the email signature.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
437 Allowed values: ``top``, ``bottom``, ``none``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
438
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
439 add_author -- ``new``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
440 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
441 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
442 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
443 followups too. If ``no``, they're never added to the nosy.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
444 Allowed values: ``yes``, ``no``, ``new``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
445
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
446 add_recipients -- ``new``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
447 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
448 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
449 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
450 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
451 Allowed values: ``yes``, ``no``, ``new``
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
452
3417
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
453 email_sending -- ``single``
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3409
diff changeset
454 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
455 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
456 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
457
3922
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
458 max_attachment_size -- ``2147483647``
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
459 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
460 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
461 download page for the file.
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
462
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3904
diff changeset
463
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
464 You may generate a new default config file using the ``roundup-admin
5231
8743b7226dc7 Fix issue with retreiving raw template files using the @@file mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5227
diff changeset
465 genconfig`` command. You can generate a new config file merging in
8743b7226dc7 Fix issue with retreiving raw template files using the @@file mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5227
diff changeset
466 existing settings using the ``roundup-admin updateconfig`` command.
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
467
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
468 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
469 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
470 name, so "domain" in the section "mail" becomes MAIL_DOMAIN. The
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
471 configuration variables available are:
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
472
3768
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
473 Extending the configuration file
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
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
476 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
477 you can add two new config.ini files:
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
478
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
479 - 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
480 to the config variable as "ext".
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
481 - 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
482 to the config variable as "detectors".
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
483
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
484 For example, the following in ``detectors/config.ini``::
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
485
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
486 [main]
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
487 qa_recipients = email@example.com
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
488
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
489 is accessible as::
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
490
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
491 db.config.detectors['QA_RECIPIENTS']
ef5da136cdc5 document extending config
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
492
3772
13e8825da493 Documentation update for common lib directory
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3769
diff changeset
493 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
494 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
495
d41ee0fdae71 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3768
diff changeset
496 [qa]
d41ee0fdae71 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3768
diff changeset
497 recipients = email@example.com
d41ee0fdae71 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3768
diff changeset
498
d41ee0fdae71 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3768
diff changeset
499 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
500
1360
aa7e4e8b14be allow additional control over the roundupdb email sending...
Richard Jones <richard@users.sourceforge.net>
parents: 1335
diff changeset
501
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1083
diff changeset
502 Tracker Schema
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
503 ==============
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
504
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
505 .. note::
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
506 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
507 `web interface`_ HTML template files and `detectors`_ to reflect
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
508 your changes.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
509
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
510 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
511 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
512 tracker.
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
513
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
514 The ``schema.py`` module
2153
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
515 ------------------------
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
516
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
517 The ``schema.py`` module contains two functions:
2153
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
518
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
519 **open**
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
520 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
521 **schema** of the tracker. It defines the **Classes** and **properties**
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
522 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
523 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
524 them.
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
525 **init**
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
526 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
527 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
528 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
529 info about how this works.
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
530
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
531
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
532 The "classic" schema
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
533 --------------------
643f9c9d7517 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2149
diff changeset
534
3476
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
535 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
536 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
537 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
538 specifying (default) labelling and ordering of classes.)::
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
539
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
540 pri = Class(db, "priority", name=String(), order=String())
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
541 pri.setkey("name")
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
542
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
543 stat = Class(db, "status", name=String(), order=String())
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
544 stat.setkey("name")
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
545
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
546 keyword = Class(db, "keyword", name=String())
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
547 keyword.setkey("name")
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
548
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
549 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
550 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
551 phone=String(), alternate_addresses=String(),
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3747
diff changeset
552 queries=Multilink('query'), roles=String(), timezone=String())
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
553 user.setkey("username")
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
554
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
555 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
556 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
557 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
558
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3747
diff changeset
559 file = FileClass(db, "file", name=String())
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
560
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
561 issue = IssueClass(db, "issue", keyword=Multilink("keyword"),
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
562 status=Link("status"), assignedto=Link("user"),
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
563 priority=Link("priority"))
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
564 issue.setkey('title')
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
565
1832
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
566
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
567 What you can't do to the schema
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
568 -------------------------------
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
569
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
570 You must never:
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
571
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
572 **Remove the users class**
2739
deb298529c2b doc clarification
Richard Jones <richard@users.sourceforge.net>
parents: 2726
diff changeset
573 This class is the only *required* class in Roundup.
deb298529c2b doc clarification
Richard Jones <richard@users.sourceforge.net>
parents: 2726
diff changeset
574
deb298529c2b doc clarification
Richard Jones <richard@users.sourceforge.net>
parents: 2726
diff changeset
575 **Remove the "username", "address", "password" or "realname" user properties**
deb298529c2b doc clarification
Richard Jones <richard@users.sourceforge.net>
parents: 2726
diff changeset
576 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
577
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
578 **Change the type of a property**
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
579 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
580 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
581 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
582 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
583 assignedto_list and remove the old assignedto property.
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
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
586 What you can do to the schema
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
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
589 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
590 initialised (or used). You may:
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 **Add new properties to classes, or add whole new classes**
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
593 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
594 from adding new information to a tracker's schema.
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
595
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
596 **Remove properties**
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
597 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
598 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
599 detectors_.
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
600
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
601
f7b0ca3de3dc doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1829
diff changeset
602
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
603 Classes and Properties - creating a new information store
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
604 ---------------------------------------------------------
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
605
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1083
diff changeset
606 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
607
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
608 priority
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
609 Defines the possible levels of urgency for issues.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
610
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
611 status
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
612 Defines the possible states of processing the issue may be in.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
613
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
614 keyword
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
615 Initially empty, will hold keywords useful for searching issues.
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 user
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
618 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
619 for all users using 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 msg
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 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
623 generated by roundup.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
624
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
625 file
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
626 Initially empty, will hold all files attached to issues.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
627
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
628 issue
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
629 Initially empty, this is where the issue information is stored.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
630
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
631 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
632 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
633 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
634 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
635 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
636 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
637
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
638
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
639 Class and Items
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
640 ~~~~~~~~~~~~~~~
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
641
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
642 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
643 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
644 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
645
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
646 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
647 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
648 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
649
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
650
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
651 Properties
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
652 ~~~~~~~~~~
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
653
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
654 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
655
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
656 * 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
657 * 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
658 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
659 class.
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
660 * Date properties store date-and-time stamps. Their values are Timestamp
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
661 objects.
5067
e424987d294a Add support for an integer type to join the existing number type.
John Rouillard <rouilj@ieee.org>
parents: 5064
diff changeset
662 * Integer properties store integer values. (Number can store real/float values.)
5175
e1e40674a0bc Implement double-precision Number
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5161
diff changeset
663 * Number properties store numeric values. There is an option to use
e1e40674a0bc Implement double-precision Number
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5161
diff changeset
664 double-precision floating point numbers.
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
665 * 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
666 * 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
667 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
668 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
669 * 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
670 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
671
5064
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
672 Properties can have additional attributes to change the default
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
673 behaviour:
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
674
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
675 * 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
676 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
677 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
678 text index.
5175
e1e40674a0bc Implement double-precision Number
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5161
diff changeset
679 * Number properties can have a ``use_double`` attribute that, when set
e1e40674a0bc Implement double-precision Number
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5161
diff changeset
680 to ``True``, will use double precision floating point in the database.
5064
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
681 * Link and Multilink properties can have several attributes:
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
682
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
683 - ``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
684 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
685 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
686 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
687 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
688 events.
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
689 - ``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
690 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
691 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
692 (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
693 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
694 ``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
695 - 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
696 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
697 roundup creates email headers of the form::
5064
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
698
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
699 X-Roundup-issue-prop: value
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
700
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
701 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
702 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
703 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
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 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
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 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
708
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 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
710 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
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 ``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
713
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 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
715 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
716
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 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
718
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 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
720 ``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
721 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
722
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 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
724 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
725 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
726 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
727 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
728 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
729 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
730 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
731 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
732 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
733 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
734
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 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
736 will be no header. However setting::
5135
9e8d8cd49f40 removing unneeded whitespace
John Rouillard <rouilj@ieee.org>
parents: 5131
diff changeset
737
9e8d8cd49f40 removing unneeded whitespace
John Rouillard <rouilj@ieee.org>
parents: 5131
diff changeset
738 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
739
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
740 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
741 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
742
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 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
744 username=joe_user, setting::
5064
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
745
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
746 msg_header_property="username"
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
747
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
748 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
749 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
750
5064
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
751 X-Roundup-issue-assigned_to: joe_user
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
752
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
753 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
754
a927f9549af0 Fix issue2550751: Email Header Issue.
John Rouillard <rouilj@ieee.org>
parents: 5114
diff changeset
755 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
756 the header from being generated on outgoing mail.
5064
46da0db55545 Document some existing property attributes
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5047
diff changeset
757
3097
Richard Jones <richard@users.sourceforge.net>
parents: 3079
diff changeset
758 All Classes automatically have a number of properties by default:
Richard Jones <richard@users.sourceforge.net>
parents: 3079
diff changeset
759
Richard Jones <richard@users.sourceforge.net>
parents: 3079
diff changeset
760 *creator*
Richard Jones <richard@users.sourceforge.net>
parents: 3079
diff changeset
761 Link to the user that created the item.
Richard Jones <richard@users.sourceforge.net>
parents: 3079
diff changeset
762 *creation*
Richard Jones <richard@users.sourceforge.net>
parents: 3079
diff changeset
763 Date the item was created.
Richard Jones <richard@users.sourceforge.net>
parents: 3079
diff changeset
764 *actor*
Richard Jones <richard@users.sourceforge.net>
parents: 3079
diff changeset
765 Link to the user that last modified the item.
Richard Jones <richard@users.sourceforge.net>
parents: 3079
diff changeset
766 *activity*
Richard Jones <richard@users.sourceforge.net>
parents: 3079
diff changeset
767 Date the item was last modified.
Richard Jones <richard@users.sourceforge.net>
parents: 3079
diff changeset
768
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
769
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
770 FileClass
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
771 ~~~~~~~~~
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
772
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
773 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
774 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
775 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
776 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
777 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
778 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
779 type of the file.
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
780
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
781
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
782 IssueClass
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
783 ~~~~~~~~~~
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
784
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
785 IssueClasses automatically include the "messages", "files", "nosy", and
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
786 "superseder" properties.
1674
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 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
789 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
790 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
791 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
792 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
793 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
794
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
795 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
796 "creator" properties.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
797
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
798 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
799 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
800 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
801 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
802 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
803
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
804
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
805 setkey(property)
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
806 ~~~~~~~~~~~~~~~~
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
807
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
808 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
809 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
810 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
811 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
812 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
813 assign an issue to him, we could do either of::
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
814
1570
93e0a565cee5 fix the "set" command usage statement
Richard Jones <richard@users.sourceforge.net>
parents: 1568
diff changeset
815 roundup-admin set issue23 assignedto=2
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
816
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
817 or::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
818
1570
93e0a565cee5 fix the "set" command usage statement
Richard Jones <richard@users.sourceforge.net>
parents: 1568
diff changeset
819 roundup-admin set issue23 assignedto=richard
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
820
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
821 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
822
3476
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
823 setlabelprop(property)
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
824 ~~~~~~~~~~~~~~~~~~~~~~
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
825
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
826 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
827 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
828 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
829 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
830
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
831 * 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
832 * the "name" property
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
833 * the "title" property
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
834 * 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
835
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
836 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
837 explicitly.
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
838
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
839 setorderprop(property)
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
840 ~~~~~~~~~~~~~~~~~~~~~~
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 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
843 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
844 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
845 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
846 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
847 for the order property:
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
848
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
849 * the property named "order"
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
850 * 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
851
1142dafe0d7f added setorderprop() and setlabelprop() to Class (lots of patches)
Richard Jones <richard@users.sourceforge.net>
parents: 3470
diff changeset
852 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
853 explicitly.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
854
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
855 create(information)
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
856 ~~~~~~~~~~~~~~~~~~~
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
857
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
858 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
859 in the "definitional" classes like "priority" and "status".
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
860
684
5b23ff865f3a added a "detectors" directory...
Richard Jones <richard@users.sourceforge.net>
parents: 673
diff changeset
861
2897
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
862 A note about ordering
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
863 ~~~~~~~~~~~~~~~~~~~~~
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
864
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
865 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
866 depending on the properties being sorted on:
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
867
5067
e424987d294a Add support for an integer type to join the existing number type.
John Rouillard <rouilj@ieee.org>
parents: 5064
diff changeset
868 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
869 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
870 case-sensitively.
2897
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
871 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
872 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
873 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
874 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
875 so on.
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
876
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
877 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
878 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
879 property, or sorting will result in random ordering.
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
880
21a0b049fed8 notes about sorting
Richard Jones <richard@users.sourceforge.net>
parents: 2886
diff changeset
881
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
882 Examples of adding to your schema
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
883 ---------------------------------
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
884
3754
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3747
diff changeset
885 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
886 new functionality.
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
887
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
888
684
5b23ff865f3a added a "detectors" directory...
Richard Jones <richard@users.sourceforge.net>
parents: 673
diff changeset
889 Detectors - adding behaviour to your tracker
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
890 ============================================
909
ef9c759c243e Fix to hasPermission, thanks Stefan Seefeld.
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
891 .. _detectors:
684
5b23ff865f3a added a "detectors" directory...
Richard Jones <richard@users.sourceforge.net>
parents: 673
diff changeset
892
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
893 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
894 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
895 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
896
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
897 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
898 (**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
899 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
900 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
901 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
902 for you are:
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
903
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
904 **nosyreaction.py**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
905 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
906 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
907 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
908 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
909 (such as adding new authors, etc.)
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
910 **statusauditor.py**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
911 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
912 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
913 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
914 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
915 defined.
1777
fbe08359511a customisation doc update
Richard Jones <richard@users.sourceforge.net>
parents: 1773
diff changeset
916 **messagesummary.py**
fbe08359511a customisation doc update
Richard Jones <richard@users.sourceforge.net>
parents: 1773
diff changeset
917 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
918 content.
fbe08359511a customisation doc update
Richard Jones <richard@users.sourceforge.net>
parents: 1773
diff changeset
919 **userauditor.py**
fbe08359511a customisation doc update
Richard Jones <richard@users.sourceforge.net>
parents: 1773
diff changeset
920 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
921 roles lists).
fbe08359511a customisation doc update
Richard Jones <richard@users.sourceforge.net>
parents: 1773
diff changeset
922
fbe08359511a customisation doc update
Richard Jones <richard@users.sourceforge.net>
parents: 1773
diff changeset
923 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
924 or remove these detectors.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
925
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
926 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
927 interface for detectors.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
928
909
ef9c759c243e Fix to hasPermission, thanks Stefan Seefeld.
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
929 __ design.html
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
930
2209
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 Detector API
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
933 ------------
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
934
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
935 Auditors are called with the arguments::
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
936
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
937 audit(db, cl, itemid, newdata)
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
938
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
939 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
940 IssueClass within the database, and ``newdata`` is a dictionary mapping
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
941 property names to values.
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 ``create()`` operation, the ``itemid`` argument is None and
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
944 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
945 is about to be created.
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 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
948 properties that are about to be changed.
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
949
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
950 For a ``retire()`` or ``restore()`` operation, newdata is None.
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
951
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
952 Reactors are called with the arguments::
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
953
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
954 react(db, cl, itemid, olddata)
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 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
957 IssueClass within the database, and ``olddata`` is a dictionary mapping
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
958 property names to values.
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
959
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
960 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
961 newly-created item and ``olddata`` is None.
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
962
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
963 For a ``set()`` operation, ``olddata`` contains the names and previous
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
964 values of properties that were changed.
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
965
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
966 For a ``retire()`` or ``restore()`` operation, ``itemid`` is the id of
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
967 the retired or restored item and ``olddata`` is None.
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
968
0b76c4961802 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 2193
diff changeset
969
2193
b1a29edd6214 added another sample detector
Richard Jones <richard@users.sourceforge.net>
parents: 2180
diff changeset
970 Additional Detectors Ready For Use
b1a29edd6214 added another sample detector
Richard Jones <richard@users.sourceforge.net>
parents: 2180
diff changeset
971 ----------------------------------
b1a29edd6214 added another sample detector
Richard Jones <richard@users.sourceforge.net>
parents: 2180
diff changeset
972
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
973 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
974 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
975 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
976
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
977 **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
978 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
979 (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
980 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
981 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
982 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
983 be sent, e.g. ``channels = irc://chat.freenode.net/channelname``.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
984 **newissuecopy.py**
684
5b23ff865f3a added a "detectors" directory...
Richard Jones <richard@users.sourceforge.net>
parents: 673
diff changeset
985 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
986 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
987 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
988 email errors!
2193
b1a29edd6214 added another sample detector
Richard Jones <richard@users.sourceforge.net>
parents: 2180
diff changeset
989 **creator_resolution.py**
b1a29edd6214 added another sample detector
Richard Jones <richard@users.sourceforge.net>
parents: 2180
diff changeset
990 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
991 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
992 "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
993 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
994 **email_auditor.py**
b1a29edd6214 added another sample detector
Richard Jones <richard@users.sourceforge.net>
parents: 2180
diff changeset
995 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
996 extension .eml.
b1a29edd6214 added another sample detector
Richard Jones <richard@users.sourceforge.net>
parents: 2180
diff changeset
997 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
998 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
999 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
1000 information, see the detector code - it has a length explanation.
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
1001
684
5b23ff865f3a added a "detectors" directory...
Richard Jones <richard@users.sourceforge.net>
parents: 673
diff changeset
1002
2129
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1003 Auditor or Reactor?
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1004 -------------------
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1005
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1006 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
1007
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1008 **Auditors**
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1009 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
1010 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
1011 **Reactors**
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1012 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
1013 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
1014 detector loops.
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1015
2138
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
1016
2129
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1017 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
1018 ---------------------------------------
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1019
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1020 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
1021 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
1022 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
1023 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
1024 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
1025
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1026 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
1027
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1028 from roundup.exceptions import Reject
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1029
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1030 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
1031
5004
494d255043c9 Display errors containing HTML with RejectRaw (issue2550847)
John Kristensen <john@jerrykan.com>
parents: 4975
diff changeset
1032 raise Reject('Description of error')
494d255043c9 Display errors containing HTML with RejectRaw (issue2550847)
John Kristensen <john@jerrykan.com>
parents: 4975
diff changeset
1033
494d255043c9 Display errors containing HTML with RejectRaw (issue2550847)
John Kristensen <john@jerrykan.com>
parents: 4975
diff changeset
1034 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
1035 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
1036 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
1037 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
1038 ``RejectRaw``.
2129
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1039
3fd672293712 add and use Reject exception [SF#700265]
Richard Jones <richard@users.sourceforge.net>
parents: 2122
diff changeset
1040
2138
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
1041 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
1042 -----------------------------
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
1043
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
1044 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
1045 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
1046
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
1047 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
1048 ``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
1049 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
1050 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
1051 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
1052
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
1053
4921
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1054 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
1055 ================================================
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1056 .. _extensions:
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1057
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1058 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
1059 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
1060 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
1061
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1062 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
1063 ``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
1064 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
1065 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
1066
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1067 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
1068 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
1069 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
1070 flexible extension point mechanism.
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1071
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1072
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1073 * ``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
1074 (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
1075
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1076 * ``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
1077 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
1078 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
1079 instead of ``cgi.action.Action``.
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
1080
898
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
1081 Database Content
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
1082 ================
898
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
1083
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
1084 .. note::
3754
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3747
diff changeset
1085 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
1086 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
1087
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1088 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
1089 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
1090 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
1091 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
1092
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1083
diff changeset
1093 **Changing content before tracker initialisation**
3241
78d2f3ce85f6 filename change
Richard Jones <richard@users.sourceforge.net>
parents: 3228
diff changeset
1094 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
1095 created using the ``create( ... )`` methods.
898
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
1096
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1083
diff changeset
1097 **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
1098 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
1099 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
1100 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
1101
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1102 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
1103 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
1104 question.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1105
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1106 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
1107 requires database content changes.
898
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
1108
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
1109
2003
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents: 1998
diff changeset
1110 Security / Access Controls
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents: 1998
diff changeset
1111 ==========================
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1112
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1113 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
1114
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1115 - Create (everything)
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1116 - Edit (everything)
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1117 - View (everything)
4296
72463e22640d fix some more documentation for the Register permission
Richard Jones <richard@users.sourceforge.net>
parents: 4088
diff changeset
1118 - Register (User class only)
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1119
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1120 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
1121 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
1122 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
1123 also define:
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1124
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1125 *Email Access*
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1126 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
1127 Anonymous users access to the email interface. When granted to the
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1128 Anonymous user, they will be automatically registered by the email
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1129 interface (see also the ``new_email_user_roles`` configuration option).
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1130 *Web Access*
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1131 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
1132 the login form, regardless of this setting (thus enabling logging in).
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1133 *Web Roles*
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1134 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
1135 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
1136
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1137 These are hooked into the default Roles:
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1138
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1139 - 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
1140 - User (Web Access; Email Access)
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1141 - Anonymous (Web Access)
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1142
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1143 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
1144 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
1145
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1146 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
1147
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1148 - 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
1149 - View priority, status
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1150 - View user
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1151 - Edit their own user record
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1152
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1153 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
1154
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1155 - Web interface access
4296
72463e22640d fix some more documentation for the Register permission
Richard Jones <richard@users.sourceforge.net>
parents: 4088
diff changeset
1156 - Register user (for registration)
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1157 - 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
1158
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1159 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
1160
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1161 #
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1162 # TRACKER SECURITY SETTINGS
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1163 #
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1164 # 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
1165 # about security setup.
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1166
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1167 #
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1168 # REGULAR USERS
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1169 #
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1170 # 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
1171 db.security.addPermissionToRole('User', 'Web Access')
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1172 db.security.addPermissionToRole('User', 'Email Access')
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1173
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1174 # 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
1175 # to regular users now
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1176 for cl in 'issue', 'file', 'msg', 'query', 'keyword':
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1177 db.security.addPermissionToRole('User', 'View', cl)
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1178 db.security.addPermissionToRole('User', 'Edit', cl)
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1179 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
1180 for cl in 'priority', 'status':
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1181 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
1182
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1183 # 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
1184 # if you don't want them to
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1185 db.security.addPermissionToRole('User', 'View', 'user')
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1186
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1187 # Users should be able to edit their own details -- this permission
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1188 # 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
1189 # is their own.
5186
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1190 def own_record(db, userid, itemid, **ctx):
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1191 '''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
1192 return userid == itemid
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1193 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
1194 description="User is allowed to view their own user details")
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1195 db.security.addPermissionToRole('User', p)
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1196 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
1197 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
1198 db.security.addPermissionToRole('User', p)
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1199
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 # ANONYMOUS USER PERMISSIONS
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1202 #
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1203 # 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
1204 # 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
1205 # 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
1206 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
1207
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1208 # 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
1209 # 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
1210 # "Create" user Permission below)
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1211 # 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
1212 # public trackers.
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1213 #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
1214
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1215 # 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
1216 # Role. Choices here are:
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1217 # - Allow anonymous users to register
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1218 db.security.addPermissionToRole('Anonymous', 'Create', 'user')
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1219
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1220 # 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
1221 # information)
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1222 for cl in 'issue', 'file', 'msg', 'keyword', 'priority', 'status':
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1223 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
1224
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1225 # [OPTIONAL]
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1226 # 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
1227 # related file and message items)
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1228 #for cl in 'issue', 'file', 'msg':
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1229 # db.security.addPermissionToRole('Anonymous', 'Create', cl)
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1230 # 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
1231
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1232
3117
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1233 Automatic Permission Checks
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1234 ---------------------------
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1235
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1236 Permissions are automatically checked when information is rendered
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1237 through the web. This includes:
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1238
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1239 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
1240 similar methods. If the check fails, the text "[hidden]" will be
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1241 displayed.
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1242 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
1243 the ``field()`` or similar methods. If the check fails, the property
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1244 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
1245 checking performed)
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1246 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
1247 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
1248 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
1249 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
1250 allowed to view this page." will be displayed.
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1251 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
1252 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
1253 allowed to view this page." will be displayed.
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1254
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 3097
diff changeset
1255
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1256 New User Roles
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1257 --------------
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1258
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1259 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
1260
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1261 - NEW_WEB_USER_ROLES
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1262 - NEW_EMAIL_USER_ROLES
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1263
3276
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1264 The `users may only edit their issues`_ example shows customisation of
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1265 these parameters.
3124e578db02 Email fixes:
Richard Jones <richard@users.sourceforge.net>
parents: 3260
diff changeset
1266
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 Changing Access Controls
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1269 ------------------------
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 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
1272 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
1273 interface if they register through email.
1244
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 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
1276 current Role and Permission configuration in your tracker.
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1277
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1278
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1279 Adding a new Permission
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1280 ~~~~~~~~~~~~~~~~~~~~~~~
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1281
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1282 When adding a new Permission, you will need to:
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1283
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1284 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
1285 ``security.addPermission``, for example::
2a4309450202 security fixes and doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2069
diff changeset
1286
5196
e0732fd6a6c7 Implement props_only feature for permissions.
rouilj@uland
parents: 5186
diff changeset
1287 db.security.addPermission(name="View", klass='frozzle',
2076
2a4309450202 security fixes and doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2069
diff changeset
1288 description="User is allowed to access frozzles")
2a4309450202 security fixes and doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2069
diff changeset
1289
2a4309450202 security fixes and doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2069
diff changeset
1290 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
1291 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
1292 "``roundup-admin security``")
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1293 3. add it to the relevant HTML interface templates
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1294 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
1295 interfaces module
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1296
5196
e0732fd6a6c7 Implement props_only feature for permissions.
rouilj@uland
parents: 5186
diff changeset
1297 The ``addPermission`` method takes a few optional parameters:
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1298
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1299 **properties**
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1300 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
1301 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
1302 'email') ...``)
5196
e0732fd6a6c7 Implement props_only feature for permissions.
rouilj@uland
parents: 5186
diff changeset
1303 **props_only**
e0732fd6a6c7 Implement props_only feature for permissions.
rouilj@uland
parents: 5186
diff changeset
1304 A boolean value (set to false by default) that is a new feature
e0732fd6a6c7 Implement props_only feature for permissions.
rouilj@uland
parents: 5186
diff changeset
1305 in roundup 1.6.
5206
8d2c1c9a49e1 format fix
John Rouillard <rouilj@ieee.org>
parents: 5201
diff changeset
1306 A permission defined using:
8d2c1c9a49e1 format fix
John Rouillard <rouilj@ieee.org>
parents: 5201
diff changeset
1307
5196
e0732fd6a6c7 Implement props_only feature for permissions.
rouilj@uland
parents: 5186
diff changeset
1308 ``properties=('list', 'of', 'property', 'names')``
5206
8d2c1c9a49e1 format fix
John Rouillard <rouilj@ieee.org>
parents: 5201
diff changeset
1309
5196
e0732fd6a6c7 Implement props_only feature for permissions.
rouilj@uland
parents: 5186
diff changeset
1310 is used to determine access for things other than just those
e0732fd6a6c7 Implement props_only feature for permissions.
rouilj@uland
parents: 5186
diff changeset
1311 properties. For example a check for View permission on the issue
e0732fd6a6c7 Implement props_only feature for permissions.
rouilj@uland
parents: 5186
diff changeset
1312 class or an issue item can use any View permission for the issue
e0732fd6a6c7 Implement props_only feature for permissions.
rouilj@uland
parents: 5186
diff changeset
1313 class even if that permission has a property list. This can be
e0732fd6a6c7 Implement props_only feature for permissions.
rouilj@uland
parents: 5186
diff changeset
1314 confusing and surprising as you would think that a permission
e0732fd6a6c7 Implement props_only feature for permissions.
rouilj@uland
parents: 5186
diff changeset
1315 including properties would be used only for determining the
e0732fd6a6c7 Implement props_only feature for permissions.
rouilj@uland
parents: 5186
diff changeset
1316 access permission for those properties.
e0732fd6a6c7 Implement props_only feature for permissions.
rouilj@uland
parents: 5186
diff changeset
1317
e0732fd6a6c7 Implement props_only feature for permissions.
rouilj@uland
parents: 5186
diff changeset
1318 Setting ``props_only=True`` will make the permission valid only for
e0732fd6a6c7 Implement props_only feature for permissions.
rouilj@uland
parents: 5186
diff changeset
1319 those properties.
e0732fd6a6c7 Implement props_only feature for permissions.
rouilj@uland
parents: 5186
diff changeset
1320
e0732fd6a6c7 Implement props_only feature for permissions.
rouilj@uland
parents: 5186
diff changeset
1321 If you use a lot of permissions with property checks, it can be
e0732fd6a6c7 Implement props_only feature for permissions.
rouilj@uland
parents: 5186
diff changeset
1322 difficult to change all of them. Calling the function:
e0732fd6a6c7 Implement props_only feature for permissions.
rouilj@uland
parents: 5186
diff changeset
1323
e0732fd6a6c7 Implement props_only feature for permissions.
rouilj@uland
parents: 5186
diff changeset
1324 db.security.set_props_only_default(True)
e0732fd6a6c7 Implement props_only feature for permissions.
rouilj@uland
parents: 5186
diff changeset
1325
e0732fd6a6c7 Implement props_only feature for permissions.
rouilj@uland
parents: 5186
diff changeset
1326 at the top of ``schema.py`` will make every permission creation
e0732fd6a6c7 Implement props_only feature for permissions.
rouilj@uland
parents: 5186
diff changeset
1327 behave as though props_only was set to True. It is expected that the
e0732fd6a6c7 Implement props_only feature for permissions.
rouilj@uland
parents: 5186
diff changeset
1328 default of True will become the default in a future Roundup release.
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1329 **check**
5186
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1330 A function to be executed which returns boolean determining whether
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1331 the Permission is allowed. If it returns True, the permission is
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1332 allowed, if it returns False the permission is denied. The function
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1333 can have one of two signatures::
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1334
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1335 check(db, userid, itemid)
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1336
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1337 or::
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1338
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1339 check(db, userid, itemid, **ctx)
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1340
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1341 where ``db`` is a handle on the open database, ``userid`` is
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1342 the user attempting access and ``itemid`` is the specific item being
5186
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1343 accessed. If the second form is used the ``ctx`` dictionary is
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1344 defined with the following values::
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1345
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1346 ctx['property'] the name of the property being checked or None if
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1347 it's a class check.
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1348
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1349 ctx['classname'] the name of the class that is being checked
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1350 (issue, query ....).
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1351
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1352 ctx['permission'] the name of the permission (e.g. View, Edit...).
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1353
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1354 The second form is preferred as it makes it easier to implement more
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1355 complex permission schemes. An example of the use of ``ctx`` can be
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1356 found in the ``upgrading.txt`` or `upgrading.html`_ document.
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1357
36630a062fb5 Check in enhanced form for check command used by addPermission.
John Rouillard <rouilj@ieee.org>
parents: 5185
diff changeset
1358 .. _`upgrading.html`: upgrading.html
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1359
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1360 Example Scenarios
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1361 ~~~~~~~~~~~~~~~~~
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1362
3126
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
1363 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
1364
3404
7d48c5b1e8f2 merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3363
diff changeset
1365 **anonymous access through the e-mail gateway**
7d48c5b1e8f2 merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3363
diff changeset
1366 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
1367 ("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
1368 "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
1369 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
1370 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
1371 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
1372 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
1373 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
1374 - they're *anonymous*.
7d48c5b1e8f2 merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3363
diff changeset
1375
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1376 **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
1377 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
1378 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
1379 (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
1380 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
1381 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
1382 by uncommenting the appropriate addPermissionToRole in your tracker's
c07ae92cebbc doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3718
diff changeset
1383 ``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
1384 "new_email_user_roles" config variable.
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1385
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1386 **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
1387 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
1388 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
1389 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
1390 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
1391 auditor. See the example
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1392 `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
1393
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1394 **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
1395 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
1396 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
1397 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
1398 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
1399 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
1400 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
1401
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1402 <option tal:condition="python:request.user.hasPermission('Closer')"
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1403 value="resolved">Resolved</option>
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1404
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1405 **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
1406 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
1407 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
1408 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
1409 interface.
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1410
1317
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1304
diff changeset
1411 **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
1412 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
1413 editing users::
1317
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1304
diff changeset
1414
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1304
diff changeset
1415 db.security.addRole(name='User Admin', description='Managing users')
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1304
diff changeset
1416 p = db.security.getPermission('Edit', 'user')
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1304
diff changeset
1417 db.security.addPermissionToRole('User Admin', p)
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1304
diff changeset
1418
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1304
diff changeset
1419 and assign the Role to the users who need the permission.
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1304
diff changeset
1420
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
1421
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1422 Web Interface
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
1423 =============
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1424
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1425 .. contents::
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1426 :local:
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1427
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1428 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
1429 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
1430 (``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
1431 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
1432 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
1433 ``roundup.cgi.client.Client`` class - which handles the rest of the
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
1434 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
1435 much anything you want as a web interface to your tracker.
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
1436
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1437
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
1438
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1439 Repercussions of changing the tracker schema
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
1440 ---------------------------------------------
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1441
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1442 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
1443 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
1444
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1445 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
1446 have properties added or removed,
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1447 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
1448 "home" page's content arguments.
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1449
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
1450
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
1451 How requests are processed
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
1452 --------------------------
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
1453
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1454 The basic processing of a web request proceeds as follows:
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1455
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1456 1. figure out who we are, defaulting to the "anonymous" user
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1457 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
1458 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
1459 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
1460 output
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1461
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1462 In some situations, exceptions occur:
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1463
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1464 - 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
1465 - 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
1466 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
1467 - 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
1468 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
1469 - 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
1470 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
1471 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
1472 the action to take place
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1473 - 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
1474 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
1475 client
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1476
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
1477
4725
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1478 Roundup URL design
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1479 ------------------
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1480
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1481 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
1482 lead to the main tracker page:
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1483
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1484 1. ``/``
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1485 2. ``/index``
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1486 3. ``/home``
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1487
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1488 The following prefix is used to access static resources:
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1489
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1490 4. ``/@@file/``
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1491
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1492 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
1493 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
1494 for specific items of that class. Example for class URL:
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1495
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1496 5. ``/issue``
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1497
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1498 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
1499 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
1500
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1501 6. ``/issue1``
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1502
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1503
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
1504 Determining web context
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
1505 -----------------------
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
1506
4725
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1507 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
1508 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
1509 parameter. Typical URL paths look like:
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1510
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1511 1. ``/tracker/issue``
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1512 2. ``/tracker/issue1``
2589
809758599cdc oops, double-@
Richard Jones <richard@users.sourceforge.net>
parents: 2588
diff changeset
1513 3. ``/tracker/@@file/style.css``
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1514 4. ``/cgi-bin/roundup.cgi/tracker/file1``
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1515 5. ``/cgi-bin/roundup.cgi/tracker/file1/kitten.png``
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1516
4725
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1517 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
1518 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
1519 "file1/kitten.png" in the cases above.
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1520
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1521 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
1522 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
1523 to switch into "home" context.
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1524 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
1525 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
1526 from the tracker TEMPLATES directory (or STATIC_FILES, if configured).
9b9d9cb9734a Document Roundup URL design
anatoly techtonik <techtonik@gmail.com>
parents: 4723
diff changeset
1527 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
1528 by raising SendStaticFile exception.
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1529 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
1530 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
1531 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
1532 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
1533 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
1534 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
1535 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
1536 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
1537 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
1538 This raises a ``SendFile`` exception.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1539
5154
f608eeecf638 issue2550891: Allow subdir in template value. Anthony (antmail)
John Rouillard <rouilj@ieee.org>
parents: 5135
diff changeset
1540 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
1541 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
1542 ``@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
1543
5154
f608eeecf638 issue2550891: Allow subdir in template value. Anthony (antmail)
John Rouillard <rouilj@ieee.org>
parents: 5135
diff changeset
1544 - only classname supplied: "index"
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1545 - full item designator supplied: "item"
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1546
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
1547
2227
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1548 The "home" Context
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1549 ------------------
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1550
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1551 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
1552 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
1553 list or specific issue).
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1554
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1555 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
1556 interface. You'd probably have:
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1557
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1558 - 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
1559 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
1560 - 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
1561 "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
1562 page up, you use the URL:
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1563
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1564 <tracker url>/home?@template=navigation
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1565
15c20983fd13 more info about the "home" context
Richard Jones <richard@users.sourceforge.net>
parents: 2209
diff changeset
1566
2134
00dfd8b50773 doc clarification
Richard Jones <richard@users.sourceforge.net>
parents: 2129
diff changeset
1567 Serving static content
00dfd8b50773 doc clarification
Richard Jones <richard@users.sourceforge.net>
parents: 2129
diff changeset
1568 ----------------------
00dfd8b50773 doc clarification
Richard Jones <richard@users.sourceforge.net>
parents: 2129
diff changeset
1569
00dfd8b50773 doc clarification
Richard Jones <richard@users.sourceforge.net>
parents: 2129
diff changeset
1570 See the previous section `determining web context`_ where it describes
2589
809758599cdc oops, double-@
Richard Jones <richard@users.sourceforge.net>
parents: 2588
diff changeset
1571 ``@@file`` paths.
2134
00dfd8b50773 doc clarification
Richard Jones <richard@users.sourceforge.net>
parents: 2129
diff changeset
1572
00dfd8b50773 doc clarification
Richard Jones <richard@users.sourceforge.net>
parents: 2129
diff changeset
1573
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
1574 Performing actions in web requests
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
1575 ----------------------------------
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
1576
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
1577 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
1578 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
1579 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
1580 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
1581 of:
1058
a55ef5a98fd3 more docco... and we need to check for web access Permission!
Richard Jones <richard@users.sourceforge.net>
parents: 1057
diff changeset
1582
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1583 **login**
1058
a55ef5a98fd3 more docco... and we need to check for web access Permission!
Richard Jones <richard@users.sourceforge.net>
parents: 1057
diff changeset
1584 Attempt to log a user in.
1278
0c0494deb09f doc for the retire action
Richard Jones <richard@users.sourceforge.net>
parents: 1270
diff changeset
1585
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1586 **logout**
1058
a55ef5a98fd3 more docco... and we need to check for web access Permission!
Richard Jones <richard@users.sourceforge.net>
parents: 1057
diff changeset
1587 Log the user out - make them "anonymous".
1278
0c0494deb09f doc for the retire action
Richard Jones <richard@users.sourceforge.net>
parents: 1270
diff changeset
1588
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1589 **register**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1590 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
1591 log them in.
1278
0c0494deb09f doc for the retire action
Richard Jones <richard@users.sourceforge.net>
parents: 1270
diff changeset
1592
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1593 **edit**
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1594 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
1595 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
1596
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1597 **new**
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1598 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
1599 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
1600 ``__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
1601 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
1602 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
1603
1278
0c0494deb09f doc for the retire action
Richard Jones <richard@users.sourceforge.net>
parents: 1270
diff changeset
1604 **retire**
0c0494deb09f doc for the retire action
Richard Jones <richard@users.sourceforge.net>
parents: 1270
diff changeset
1605 Retire the item in the database.
0c0494deb09f doc for the retire action
Richard Jones <richard@users.sourceforge.net>
parents: 1270
diff changeset
1606
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1607 **editCSV**
1058
a55ef5a98fd3 more docco... and we need to check for web access Permission!
Richard Jones <richard@users.sourceforge.net>
parents: 1057
diff changeset
1608 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
1609 *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
1610 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
1611 features.
1058
a55ef5a98fd3 more docco... and we need to check for web access Permission!
Richard Jones <richard@users.sourceforge.net>
parents: 1057
diff changeset
1612
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1613 **search**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1614 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
1615
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1616 - 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
1617 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
1618 them to :filter.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1619
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1620 - 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
1621 user's query list.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1622
2017
31d920b31642 Update customization examples too, expand upgrade notice a bit.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2016
diff changeset
1623 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
1624 "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
1625 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
1626 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
1627 web actions`_).
31d920b31642 Update customization examples too, expand upgrade notice a bit.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2016
diff changeset
1628
31d920b31642 Update customization examples too, expand upgrade notice a bit.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2016
diff changeset
1629 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
1630 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
1631 for each action are:
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1632
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1633 **login**
2991
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1634 Determine whether the user has the "Web Access" Permission.
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1635 **logout**
1058
a55ef5a98fd3 more docco... and we need to check for web access Permission!
Richard Jones <richard@users.sourceforge.net>
parents: 1057
diff changeset
1636 No permission checks are made.
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1637 **register**
3404
7d48c5b1e8f2 merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3363
diff changeset
1638 Determine whether the user has the ("Create", "user") Permission.
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1639 **edit**
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1640 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
1641 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
1642 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
1643 special Permission "Web Roles".
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1644 **new**
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1645 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
1646 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
1647 be created if the user has the ("Create", "user") Permission.
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1648 **editCSV**
2991
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1649 Determine whether the user has permission to edit this class.
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
1650 **search**
2991
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1651 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
1652
5201
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1653 Protecting users from web application attacks
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1654 ---------------------------------------------
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1655
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1656 There is a class of attacks known as Cross Site Request Forgeries
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1657 (CSRF). Malicious code running in the browser can making a
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1658 request to roundup while you are logged into roundup. The
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1659 malicious code piggy backs on your existing roundup session to
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1660 make changes without your knowledge. Roundup 1.6 has support for
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1661 defending against this by analyzing the
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1662
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1663 * Referer,
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1664 * Origin, and
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1665 * Host or
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1666 * X-Forwarded-Host
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1667
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1668 HTTP headers. It compares the headers to the value of the web setting
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1669 in the [tracker] section of the tracker's ``config.ini``.
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1670
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1671 Also a per form token (also called a nonce) can be enabled for
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1672 the tracker using the ``csrf_enforce_token`` option in
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1673 config.ini. When enabled, roundup will validate a hidden form
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1674 field called ``@csrf``. If the validation fails (or the token
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1675 is used more than one) the request is rejected. The ``@csrf``
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1676 input field is added automatically by calling the ``submit``
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1677 function/path. It can also be added manually by calling
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1678 anti_csrf_nonce() directly. For example:
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1679
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1680 <input name="@csrf" type="hidden"
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1681 tal:attributes="value python:utils.anti_csrf_nonce(lifetime=10)">
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1682
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1683 By default a nonce lifetime is 2 weeks. However the lifetime (in
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1684 minutes) can be set by passing a lifetime argument as shown
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1685 above. The example above makes the nonce lifetime 10 minutes.
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1686
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1687 Search for @csrf in this document for more examples. There are
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1688 more examples and information in ``upgrading.txt``.
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1689
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1690 The token protects you because malicious code supplied by another
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1691 site is unable to obtain the token. Thus many attempts they make
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1692 to submit a request are rejected.
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1693
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1694 The protection on the xmlrpc interface is untested, but is based
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1695 on a valid header check against the roundup url and the presence
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1696 of the ``X-REQUESTED-WITH`` header. Work to improve this is a
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1697 future project after the 1.6 release.
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1698
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1699 The enforcement levels an be modified in ``config.ini``. Refer to
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1700 that file for details.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1701
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1702 Special form variables
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
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1705 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
1706 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
1707
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1708 - 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
1709 - 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
1710 properties,
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1711 - 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
1712 current item.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1713 - 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
1714 - 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
1715 operation to be successful.
5158
63294ed25e84 issue1842687: Keywords: After creating, stay in "Create New" mode.
John Rouillard <rouilj@ieee.org>
parents: 5156
diff changeset
1716 - 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
1717 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
1718 created item.
3429
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1719 - 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
1720
3293
8897483a9f8b doc tweak
Richard Jones <richard@users.sourceforge.net>
parents: 3292
diff changeset
1721 These operations will only take place if the form action (the
8897483a9f8b doc tweak
Richard Jones <richard@users.sourceforge.net>
parents: 3292
diff changeset
1722 ``@action`` variable) is "edit" or "new".
8897483a9f8b doc tweak
Richard Jones <richard@users.sourceforge.net>
parents: 3292
diff changeset
1723
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1724 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
1725 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
1726
3429
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1727 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
1728
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1729 ``@language``
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1730 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
1731 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
1732 (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
1733 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
1734 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
1735 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
1736 configuration or OS environment.
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1737
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1738 ``@charset``
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1739 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
1740 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
1741 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
1742 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
1743 (UTF-8).
963003d2ffdd add @language and @charset to "Special form variables" section
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3417
diff changeset
1744
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1745 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
1746
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1747 ``<propname>``
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1748 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
1749
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1750 ``<designator>"@"<propname>``
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1751 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
1752
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1753 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
1754
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1755 ``<classname><N>``
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1756 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
1757
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1758 ``<classname>"-"<N>``
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1759 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
1760 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
1761 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
1762 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
1763 item.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1764
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1765 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
1766 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
1767
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1768 ``@required``
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1769 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
1770 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
1771 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
1772
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1773 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
1774 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
1775 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
1776 <designator>.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1777
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1778 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
1779 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
1780
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1781 ``@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
1782 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
1783 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
1784 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
1785 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
1786 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
1787 property.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1788
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1789 ``@link@<propname>=<designator>``
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1790 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
1791 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
1792 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
1793 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
1794 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
1795 form variable.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1796
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1797 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
1798 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
1799 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
1800
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1801 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
1802 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
1803 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
1804
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1805 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
1806 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
1807 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
1808
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1809 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
1810 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
1811 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
1812
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1813 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
1814 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
1815 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
1816 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
1817 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
1818
5067
e424987d294a Add support for an integer type to join the existing number type.
John Rouillard <rouilj@ieee.org>
parents: 5064
diff changeset
1819 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
1820 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
1821 appropriate
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1822
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1823 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
1824 designator.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1825
5161
12190efa30d4 I realized that the __came_from and __redirect_to url parameters I
John Rouillard <rouilj@ieee.org>
parents: 5158
diff changeset
1826 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
1827 @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
1828 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
1829 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
1830 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
1831 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
1832 the url to https.
5158
63294ed25e84 issue1842687: Keywords: After creating, stay in "Create New" mode.
John Rouillard <rouilj@ieee.org>
parents: 5156
diff changeset
1833
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1834 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
1835
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1836 @note
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1837 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
1838
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1839 @link@messages=msg-1
1918
Richard Jones <richard@users.sourceforge.net>
parents: 1850
diff changeset
1840 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
1841
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1842 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
1843 "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
1844 time, respectively.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1845
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1846 @file
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1847 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
1848
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1849 @link@files=file-1
1918
Richard Jones <richard@users.sourceforge.net>
parents: 1850
diff changeset
1850 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
1851
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1852 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
1853 uploads.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1854
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1855 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
1856 specified, the action::
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1857
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1858 @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
1859
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1860 is also performed.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1861
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1862 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
1863 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
1864 returning.
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1865
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1866
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
1867 Default templates
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
1868 -----------------
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
1869
1952
c40ed9113285 Applied Stefan Seefeld's html4/xhtml patch with some changes.
Richard Jones <richard@users.sourceforge.net>
parents: 1918
diff changeset
1870 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
1871 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
1872 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
1873
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1874 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
1875 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
1876 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
1877
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1878 **page.html**
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1879 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
1880 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
1881 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
1882 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
1883 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
1884 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
1885 title.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1886 **home.html**
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
1887 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
1888 **home.classlist.html**
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1889 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
1890 tracker
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1891 **classname.item.html**
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
1892 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
1893 **classname.index.html**
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
1894 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
1895 **classname.search.html**
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
1896 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
1897 **_generic.index.html**
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1898 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
1899 ``*classname*.index`` available
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1900 **_generic.help.html**
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1901 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
1902 ``*classname*.help``
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1903 **user.register.html**
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1904 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
1905 page
4435
386200d0c929 Some minor typos fixed in doc/customizing.txt (Thanks Ralf Hemmecke).
Bernhard Reiter <Bernhard.Reiter@intevation.de>
parents: 4406
diff changeset
1906 **style.css**
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
1907 a static file that is served up as-is
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1908
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1909 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
1910
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
1911 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
1912 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
1913 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
1914 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
1915
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
1916 http://your.tracker.example/tracker/issue?@template=test
1147
89b1a8a468e7 more doc, "fixer" example
Richard Jones <richard@users.sourceforge.net>
parents: 1144
diff changeset
1917
89b1a8a468e7 more doc, "fixer" example
Richard Jones <richard@users.sourceforge.net>
parents: 1144
diff changeset
1918 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
1919
5154
f608eeecf638 issue2550891: Allow subdir in template value. Anthony (antmail)
John Rouillard <rouilj@ieee.org>
parents: 5135
diff changeset
1920 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
1921 directory. So if you specify::
f608eeecf638 issue2550891: Allow subdir in template value. Anthony (antmail)
John Rouillard <rouilj@ieee.org>
parents: 5135
diff changeset
1922
f608eeecf638 issue2550891: Allow subdir in template value. Anthony (antmail)
John Rouillard <rouilj@ieee.org>
parents: 5135
diff changeset
1923 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
1924
f608eeecf638 issue2550891: Allow subdir in template value. Anthony (antmail)
John Rouillard <rouilj@ieee.org>
parents: 5135
diff changeset
1925 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
1926 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
1927 ``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
1928 it will return an error.
1147
89b1a8a468e7 more doc, "fixer" example
Richard Jones <richard@users.sourceforge.net>
parents: 1144
diff changeset
1929
5185
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1930 Implementing Modal Editing Using @template
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1931 ------------------------------------------
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1932
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1933 Many item templates allow you to edit the item. They contain
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1934 code that renders edit boxes if the user has edit permissions.
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1935 Otherwise the template will just display the item information.
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1936
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1937 In some cases you want to do a modal edit. The user has to take some
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1938 action (click a button or follow a link) to shift from display mode to
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1939 edit mode. When the changes are submitted, ending the edit mode,
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1940 the user is returned to display mode.
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1941
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1942 Modal workflows usually slow things down and are not implemented by
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1943 default templates. However for some workflows a modal edit is useful.
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1944 For example a batch edit mode that allows the user to edit a number of
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1945 issues all from one form could be implemented as a modal workflow of:
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1946
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1947 * search for issues to modify
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1948 * switch to edit mode and change values
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1949 * exit back to the results of the search
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1950
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1951 To implement the modal edit, assume you have an issue.edit.html
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1952 template that implements an edit form. On the display page (a version
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1953 of issue.item.html modified to only display information) add a link
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1954 that calls the display url, but adds ``@template=edit`` to the link.
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1955
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1956 This will now display the edit page. On the edit page you want to add
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1957 a hidden text field to your form named ``@template`` with the value:
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1958 ``item|edit``. When the form is submitted it is validated. If the
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1959 form is correct the user will see the item rendered using the item
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1960 template. If there is an error (validation failed) the item will be
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1961 rendered using the edit template. The edit template that is rendered
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1962 will display all the changes that the user made to the form before it
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1963 was submitted. The user can correct the error and resubmit the changes
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1964 until the form validates.
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1965
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1966 If the form failed to validate but the ``@template`` field had the
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1967 value ``item`` the user would still see the error, but all of the data
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1968 the user entered would be discarded. The user would have to redo all
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1969 the edits again.
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1970
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
1971
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
1972 How the templates work
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
1973 ----------------------
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
1974
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1975
4619
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1976 Templating engines
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1977 ~~~~~~~~~~~~~~~~~~
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1978
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1979 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
1980 `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
1981 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
1982 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
1983 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
1984 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
1985 ``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
1986 differences" section of `Chameleon documentation`__.
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1987
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1988 **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
1989 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
1990 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
1991 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
1992 future release.
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1993
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1994 **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
1995 recommended for production use.
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1996
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1997 .. _Chameleon:
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1998 http://chameleon.repoze.org/
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
1999 .. _z3c.pt:
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
2000 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
2001 __ 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
2002 .. _TAL:
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
2003 .. _Template Attribute Language:
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
2004 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
2005
d9254d300d6e Add some notes about Chameleon in the documentation
Cheer Xiao <xiaqqaix@gmail.com>
parents: 4464
diff changeset
2006
1214
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
2007 Basic Templating Actions
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
2008 ~~~~~~~~~~~~~~~~~~~~~~~~
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
2009
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2010 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
2011 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
2012 The basic TAL commands are:
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2013
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
2014 **tal:define="variable expression; variable expression; ..."**
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2015 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
2016 example::
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2017
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2018 <html tal:define="title request/description">
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2019 <head><title tal:content="title"></title></head>
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2020 </html>
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2021
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2022 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
2023 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
2024 <html> tag may then use the "title" variable.
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2025
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
2026 **tal:condition="expression"**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2027 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
2028 example::
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2029
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2030 <p tal:condition="python:request.user.hasPermission('View', 'issue')">
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2031 Display some issue information.
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2032 </p>
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2033
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2034 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
2035 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
2036 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
2037 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
2038 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
2039 spaces!).
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2040
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
2041 **tal:repeat="variable expression"**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2042 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
2043 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
2044 special "repeat" variable for each element. For example::
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2045
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2046 <tr tal:repeat="u user/list">
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2047 <td tal:content="u/id"></td>
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2048 <td tal:content="u/username"></td>
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2049 <td tal:content="u/realname"></td>
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2050 </tr>
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2051
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2052 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
2053 "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
2054 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
2055 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
2056 below on `the repeat variable`_.
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
2057
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
2058 **tal:replace="expression"**
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2059 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
2060
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2061 <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
2062
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2063 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
2064 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
2065 resultant output would be "Bruce".
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2066
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
2067 **tal:content="expression"**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2068 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
2069 For example::
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2070
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2071 <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
2072 </span>
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2073
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2074 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
2075 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
2076 resultant output would be "<span>Bruce</span>".
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2077
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
2078 **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
2079 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
2080 example::
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2081
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2082 <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
2083
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2084 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
2085 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
2086 be something like "user123".
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2087
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
2088 **tal:omit-tag="expression"**
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2089 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
2090 example::
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2091
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2092 <span tal:omit-tag="python:1">Hello, world!</span>
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2093
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2094 would result in output of::
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2095
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2096 Hello, world!
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
2097
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2098 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
2099 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
2100
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2101 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
2102 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
2103 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
2104 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
2105 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
2106 illegal tag placement to effect the repeat).
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
2107
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
2108
1214
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
2109 Templating Expressions
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
2110 ~~~~~~~~~~~~~~~~~~~~~~
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
2111
2296
5092d44194dd added links to TAL specifications
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2227
diff changeset
2112 Templating Expressions are covered by `Template Attribute Language
5092d44194dd added links to TAL specifications
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2227
diff changeset
2113 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
2114 attribute values may be one of the following forms:
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
2115
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
2116 **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
2117 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
2118 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
2119 ``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
2120 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
2121 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
2122 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
2123 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
2124 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
2125 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
2126 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
2127
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2128 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
2129 "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
2130 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
2131 case of ``tal:attributes``).
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2132
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2133 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
2134 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
2135 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
2136 the case of ``tal:replace``).
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
2137
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
2138 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
2139 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
2140 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
2141 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
2142
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2143 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
2144 ``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
2145 expressions.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2146
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2147 **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
2148 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
2149 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
2150 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
2151
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2152 **Python Expressions** - eg. ``python: 1+1``
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
2153 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
2154 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
2155 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
2156 ``checklist`` is a method.
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
2157
1448
bbb1e5f8fc93 added info about structure/not:/path()
Richard Jones <richard@users.sourceforge.net>
parents: 1436
diff changeset
2158 Modifiers:
bbb1e5f8fc93 added info about structure/not:/path()
Richard Jones <richard@users.sourceforge.net>
parents: 1436
diff changeset
2159
bbb1e5f8fc93 added info about structure/not:/path()
Richard Jones <richard@users.sourceforge.net>
parents: 1436
diff changeset
2160 **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
2161 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
2162 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
2163 ``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
2164 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
2165 to the web browser for rendering.
1448
bbb1e5f8fc93 added info about structure/not:/path()
Richard Jones <richard@users.sourceforge.net>
parents: 1436
diff changeset
2166
bbb1e5f8fc93 added info about structure/not:/path()
Richard Jones <richard@users.sourceforge.net>
parents: 1436
diff changeset
2167 **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
2168 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
2169 expression.
1448
bbb1e5f8fc93 added info about structure/not:/path()
Richard Jones <richard@users.sourceforge.net>
parents: 1436
diff changeset
2170
2296
5092d44194dd added links to TAL specifications
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2227
diff changeset
2171 .. _TALES:
5092d44194dd added links to TAL specifications
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2227
diff changeset
2172 .. _Template Attribute Language Expression Syntax:
5092d44194dd added links to TAL specifications
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2227
diff changeset
2173 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
2174
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
2175
1214
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
2176 Template Macros
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
2177 ~~~~~~~~~~~~~~~
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
2178
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2179 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
2180 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
2181 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
2182
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2183 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
2184 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
2185 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
2186 Attribute Language`_, or METAL. The macro commands are:
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2187
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2188 **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
2189 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
2190 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
2191 example::
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2192
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2193 <html metal:define-macro="page">
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2194 ...
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2195 </html>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2196
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2197 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
2198 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
2199 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
2200 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
2201 ``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
2202 "page" template.
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2203
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2204 **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
2205 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
2206 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
2207 For example::
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2208
1214
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
2209 <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
2210 ...
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2211 </tal:block>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2212
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2213 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
2214 "page" template.
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2215
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2216 **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
2217 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
2218 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
2219 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
2220 so::
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2221
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2222 <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
2223
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2224 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
2225 like this::
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2226
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2227 <title metal:fill-slot="head_title">My Title</title>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2228
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2229 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
2230 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
2231
2296
5092d44194dd added links to TAL specifications
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2227
diff changeset
2232 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
2233 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
2234 *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
2235
2296
5092d44194dd added links to TAL specifications
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2227
diff changeset
2236 .. _METAL:
5092d44194dd added links to TAL specifications
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2227
diff changeset
2237 .. _Macro Expansion Template Attribute Language:
5092d44194dd added links to TAL specifications
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2227
diff changeset
2238 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
2239
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2240 Information available to templates
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
2241 ----------------------------------
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2242
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
2243 This is implemented by ``roundup.cgi.templating.RoundupPageTemplate``
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
2244
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2245 The following variables are available to templates.
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2246
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
2247 **context**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2248 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
2249 or a `hyperdb item wrapper`_
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
2250 **request**
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2251 Includes information about the current request, including:
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2252 - the current index information (``filterspec``, ``filter`` args,
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2253 ``properties``, etc) parsed out of the form.
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2254 - 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
2255 - "form"
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2256 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
2257 to value (specifically a cgi.FieldStorage)
5857cd1a0db9 add language to the "request" template var
Richard Jones <richard@users.sourceforge.net>
parents: 3922
diff changeset
2258 - "env" the CGI environment variables
5857cd1a0db9 add language to the "request" template var
Richard Jones <richard@users.sourceforge.net>
parents: 3922
diff changeset
2259 - "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
2260 - "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
2261 - "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
2262 - "classname" the current classname (possibly None)
5857cd1a0db9 add language to the "request" template var
Richard Jones <richard@users.sourceforge.net>
parents: 3922
diff changeset
2263 - "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
2264 **config**
2921
ad4fb8a14a97 more doc updates, not so many TODOs any more
Richard Jones <richard@users.sourceforge.net>
parents: 2915
diff changeset
2265 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
2266 file (eg. TRACKER_NAME, etc.)
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
2267 **db**
1254
77920c42aeb9 Expose the tracker config as a variable for templating
Richard Jones <richard@users.sourceforge.net>
parents: 1252
diff changeset
2268 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
2269 **templates**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2270 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
2271 *use-macro* commands.
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2272 **utils**
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2273 This variable makes available some utility functions like batching.
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
2274 **nothing**
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2275 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
2276 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
2277 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
2278 ``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
2279 example::
1100
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2280
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2281 <span tal:attributes="class nothing">Hello, World!</span>
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2282
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2283 would result in::
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2284
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2285 <span>Hello, World!</span>
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2286
1125
3c1533be3822 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1124
diff changeset
2287 **default**
1100
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2288 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
2289 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
2290 remain. So::
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2291
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2292 <span tal:replace="default">Hello, World!</span>
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2293
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2294 would result in::
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2295
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
2296 <span>Hello, World!</span>
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2297
2526
dfe0bde4ff7f "Information available to templates": 'true' and 'false' constants
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2511
diff changeset
2298 **true**, **false**
dfe0bde4ff7f "Information available to templates": 'true' and 'false' constants
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2511
diff changeset
2299 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
2300 instead of ``python:1`` and ``python:0``.
2540
bad572863a85 "Information available to templates": i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2526
diff changeset
2301 **i18n**
bad572863a85 "Information available to templates": i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2526
diff changeset
2302 Internationalization service, providing two string translation methods:
bad572863a85 "Information available to templates": i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2526
diff changeset
2303
bad572863a85 "Information available to templates": i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2526
diff changeset
2304 **gettext** (*message*)
bad572863a85 "Information available to templates": i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2526
diff changeset
2305 Return the localized translation of message
bad572863a85 "Information available to templates": i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2526
diff changeset
2306 **ngettext** (*singular*, *plural*, *number*)
bad572863a85 "Information available to templates": i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2526
diff changeset
2307 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
2308 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
2309 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
2310 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
2311 return plural otherwise.
bad572863a85 "Information available to templates": i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2526
diff changeset
2312
bad572863a85 "Information available to templates": i18n
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2526
diff changeset
2313 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
2314 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
2315
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2316 The context variable
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
2317 ~~~~~~~~~~~~~~~~~~~~
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2318
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2319 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
2320 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
2321
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2322 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
2323 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
2324 `hyperdb class wrapper`_.
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2325 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
2326 `hyperdb item wrapper`_.
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2327
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2328 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
2329 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
2330
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2331 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
2332 appear if the property is displayed through ``context/property`` or
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2333 ``context/property/field``.
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2334 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
2335 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
2336 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
2337 "context/id".
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2338
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2339 Hyperdb class wrapper
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2340 :::::::::::::::::::::
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2341
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
2342 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
2343 class.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2344
4435
386200d0c929 Some minor typos fixed in doc/customizing.txt (Thanks Ralf Hemmecke).
Bernhard Reiter <Bernhard.Reiter@intevation.de>
parents: 4406
diff changeset
2345 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
2346 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
2347 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
2348 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
2349 mind.
1123
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 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
2352 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
2353 from the CGI form.
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2354
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2355 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
2356
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 Method Description
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2359 =========== =============================================================
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2360 properties return a `hyperdb property wrapper`_ for all of this class's
5222
9bf221cebef3 Make properties method return only properties the user can search.
John Rouillard <rouilj@ieee.org>
parents: 5206
diff changeset
2361 properties that are searchable by the user. You can use
9bf221cebef3 Make properties method return only properties the user can search.
John Rouillard <rouilj@ieee.org>
parents: 5206
diff changeset
2362 the argument cansearch=False to get all properties.
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2363 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
2364 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
2365 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
2366 filter lists of items from this class, filtered and sorted. Two
5185
349bef975367 Make @template support two alternate templates for error and ok cases.
John Rouillard <rouilj@ieee.org>
parents: 5175
diff changeset
2367 options are available for sorting:
2858
0357a9c93933 fix filter() doc
Richard Jones <richard@users.sourceforge.net>
parents: 2855
diff changeset
2368
0357a9c93933 fix filter() doc
Richard Jones <richard@users.sourceforge.net>
parents: 2855
diff changeset
2369 1. by the current *request* filterspec/filter/sort/group args
0357a9c93933 fix filter() doc
Richard Jones <richard@users.sourceforge.net>
parents: 2855
diff changeset
2370 2. by the "filterspec", "sort" and "group" keyword args.
0357a9c93933 fix filter() doc
Richard Jones <richard@users.sourceforge.net>
parents: 2855
diff changeset
2371 "filterspec" is ``{propname: value(s)}``. "sort" and
3696
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2372 "group" are an optionally empty list ``[(dir, prop)]``
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2373 where dir is '+', '-' or None
2858
0357a9c93933 fix filter() doc
Richard Jones <richard@users.sourceforge.net>
parents: 2855
diff changeset
2374 and prop is a prop name or None.
0357a9c93933 fix filter() doc
Richard Jones <richard@users.sourceforge.net>
parents: 2855
diff changeset
2375
3718
0d561b24ceff support sqlite3
Richard Jones <richard@users.sourceforge.net>
parents: 3717
diff changeset
2376 The propname in filterspec and prop in a sort/group spec
0d561b24ceff support sqlite3
Richard Jones <richard@users.sourceforge.net>
parents: 3717
diff changeset
2377 may be transitive, i.e., it may contain properties of
0d561b24ceff support sqlite3
Richard Jones <richard@users.sourceforge.net>
parents: 3717
diff changeset
2378 the form link.link.link.name.
0d561b24ceff support sqlite3
Richard Jones <richard@users.sourceforge.net>
parents: 3717
diff changeset
2379
0d561b24ceff support sqlite3
Richard Jones <richard@users.sourceforge.net>
parents: 3717
diff changeset
2380 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
2381 the last week, sorted by activity date:
0d561b24ceff support sqlite3
Richard Jones <richard@users.sourceforge.net>
parents: 3717
diff changeset
2382 ``issue.filter(filterspec={"priority": "1",
0d561b24ceff support sqlite3
Richard Jones <richard@users.sourceforge.net>
parents: 3717
diff changeset
2383 'messages.creation' : '.-1w;'}, sort=[('activity', '+')])``
2858
0357a9c93933 fix filter() doc
Richard Jones <richard@users.sourceforge.net>
parents: 2855
diff changeset
2384
3688
722ab52d47fc added filter_sql to SQL backends which takes an arbitrary SQL statement...
Richard Jones <richard@users.sourceforge.net>
parents: 3660
diff changeset
2385 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
2386
722ab52d47fc added filter_sql to SQL backends which takes an arbitrary SQL statement...
Richard Jones <richard@users.sourceforge.net>
parents: 3660
diff changeset
2387 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
2388 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
2389
722ab52d47fc added filter_sql to SQL backends which takes an arbitrary SQL statement...
Richard Jones <richard@users.sourceforge.net>
parents: 3660
diff changeset
2390 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
2391
722ab52d47fc added filter_sql to SQL backends which takes an arbitrary SQL statement...
Richard Jones <richard@users.sourceforge.net>
parents: 3660
diff changeset
2392 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
2393 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
2394 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
2395
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2396 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
2397 "help" template.
3363
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2398
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2399 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
2400 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
2401 "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
2402 (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
2403 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
2404 activity).
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2405
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2406 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
2407 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
2408 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
2409
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2410 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
2411 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
2412 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
2413
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2414 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
2415
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2416 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
2417 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
2418 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
2419
7bc1e9c42a26 allow specification of pagesize, sorting and filtering in "classhelp" popups
Richard Jones <richard@users.sourceforge.net>
parents: 3293
diff changeset
2420 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
2421 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
2422 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
2423
5201
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
2424 submit generate a submit button (and action and @csrf hidden elements)
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2425 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
2426 history returns 'New node - no history' :)
1136
7e193bbda38e added generic item editing
Richard Jones <richard@users.sourceforge.net>
parents: 1133
diff changeset
2427 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
2428 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
2429 =========== =============================================================
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2430
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2431 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
2432 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
2433 expression. For example::
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2434
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2435 python:context['list']
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2436
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2437 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
2438
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2439
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2440 Hyperdb item wrapper
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2441 ::::::::::::::::::::
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2442
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
2443 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
2444 class.
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2445
4435
386200d0c929 Some minor typos fixed in doc/customizing.txt (Thanks Ralf Hemmecke).
Bernhard Reiter <Bernhard.Reiter@intevation.de>
parents: 4406
diff changeset
2446 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
2447
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2448 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
2449 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
2450 from the CGI form.
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2451
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2452 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
2453
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2454 =============== ========================================================
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2455 Method Description
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2456 =============== ========================================================
5201
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
2457 submit generate a submit button (and action and @csrf hidden elements)
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2458 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
2459 implemented**)
5227
690ec4f438df Added missing documentation of the showall parameter to the history
John Rouillard <rouilj@ieee.org>
parents: 5222
diff changeset
2460 history render the journal of the current item as
690ec4f438df Added missing documentation of the showall parameter to the history
John Rouillard <rouilj@ieee.org>
parents: 5222
diff changeset
2461 HTML. By default properties marked as "quiet" (see
690ec4f438df Added missing documentation of the showall parameter to the history
John Rouillard <rouilj@ieee.org>
parents: 5222
diff changeset
2462 `design documentation`_) are not shown unless the
690ec4f438df Added missing documentation of the showall parameter to the history
John Rouillard <rouilj@ieee.org>
parents: 5222
diff changeset
2463 function is called with the showall=True parameter.
5232
462b0f76fce8 issue2550864 - Potential information leakage via journal/history
John Rouillard <rouilj@ieee.org>
parents: 5231
diff changeset
2464 Properties that are not Viewable to the user are not
462b0f76fce8 issue2550864 - Potential information leakage via journal/history
John Rouillard <rouilj@ieee.org>
parents: 5231
diff changeset
2465 shown.
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2466 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
2467 for the query
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2468 hasPermission specific to the "user" class - determine whether the
2991
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
2469 user has a Permission. The signature is::
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
2470
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
2471 hasPermission(self, permission, [classname=],
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
2472 [property=], [itemid=])
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
2473
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
2474 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
2475 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
2476 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
2477
75dc225613cc fix security check for hasPermission(Permission, None)
Richard Jones <richard@users.sourceforge.net>
parents: 3510
diff changeset
2478 hasRole(self, rolename)
75dc225613cc fix security check for hasPermission(Permission, None)
Richard Jones <richard@users.sourceforge.net>
parents: 3510
diff changeset
2479
1136
7e193bbda38e added generic item editing
Richard Jones <richard@users.sourceforge.net>
parents: 1133
diff changeset
2480 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
2481 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
2482 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
2483 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
2484 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
2485 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
2486 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
2487 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
2488 ``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
2489 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
2490 (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
2491 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
2492 ``activity`` cannot be copied.
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2493 =============== ========================================================
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2494
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2495 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
2496 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
2497 expression. For example::
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2498
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2499 python:context['journal']
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2500
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2501 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
2502
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2503
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2504 Hyperdb property wrapper
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2505 ::::::::::::::::::::::::
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2506
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
2507 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
2508 ``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
2509 ``HTMLNumberProperty``, and so on).
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2510
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2511 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
2512 value may be either:
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2513
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2514 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
2515 the hyperdb
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2516 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
2517 the CGI form
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2518
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2519
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2520 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
2521
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2522 =============== ========================================================
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2523 Attribute Description
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2524 =============== ========================================================
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2525 _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
2526 _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
2527 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
2528 =============== ========================================================
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2529
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2530 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
2531
1773
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2532 =========== ================================================================
1780
d2801a2b0a77 Initial implementation (half-baked) at new Tracker instance.
Richard Jones <richard@users.sourceforge.net>
parents: 1777
diff changeset
2533 Method Description
1773
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2534 =========== ================================================================
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2535 plain render a "plain" representation of the property. This method
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2536 may take two arguments:
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2537
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2538 escape
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2539 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
2540 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
2541 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
2542 option is used in the template. The following ``tal:content``
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2543 expressions are all equivalent::
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2544
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2545 "structure python:msg.content.plain(escape=1)"
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2546 "python:msg.content.plain()"
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2547 "msg/content/plain"
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2548 "msg/content"
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2549
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2550 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
2551 complex expression.
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2552
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2553 hyperlink
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2554 If true, turn URLs, email addresses and hyperdb item
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2555 designators in the text into hyperlinks (default: no). Note
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2556 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
2557 want to use this ``tal:content`` expression::
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2558
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2559 "structure python:msg.content.plain(hyperlink=1)"
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2560
2958
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2561 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
2562 transformation done in the plain() method.
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2563
1773
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2564 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
2565
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2566 "structure msg/content/hyperlinked"
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2567
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2568 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
2569 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
2570 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
2571 arguments:
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2572
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2573 size
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2574 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
2575
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2576 format (Date properties only)
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2577 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
2578 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
2579 below.
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2580
3649
12633662ff63 include the popcal in Date field editing and search fields by default
Richard Jones <richard@users.sourceforge.net>
parents: 3648
diff changeset
2581 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
2582 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
2583 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
2584
1773
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2585 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
2586 as StructuredText (requires the StructureText module to be
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2587 installed separately)
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2588 multiline only on String properties - render a multiline form edit
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2589 field for the property
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2590 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
2591 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
2592 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
2593 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
2594 replaced with %20.
1773
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2595 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
2596 for the property, used for confirmation that the user typed
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2597 the password correctly. Generates a field with name
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2598 "name:confirm".
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2599 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
2600 property
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2601 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
2602 and now
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2603 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
2604 with some timezone offset, for example::
55046bb7f789 tweaking
Richard Jones <richard@users.sourceforge.net>
parents: 2003
diff changeset
2605
55046bb7f789 tweaking
Richard Jones <richard@users.sourceforge.net>
parents: 2003
diff changeset
2606 python:context.creation.local(10)
55046bb7f789 tweaking
Richard Jones <richard@users.sourceforge.net>
parents: 2003
diff changeset
2607
55046bb7f789 tweaking
Richard Jones <richard@users.sourceforge.net>
parents: 2003
diff changeset
2608 will render the date with a +10 hour offset.
2088
90769be53b4b doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 2076
diff changeset
2609 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
2610 Mar 2004"). Takes an optional format argument, for example::
90769be53b4b doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 2076
diff changeset
2611
90769be53b4b doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 2076
diff changeset
2612 python:context.activity.pretty('%Y-%m-%d')
90769be53b4b doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 2076
diff changeset
2613
90769be53b4b doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 2076
diff changeset
2614 Will format as "2004-03-19" instead.
90769be53b4b doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 2076
diff changeset
2615
90769be53b4b doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 2076
diff changeset
2616 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
2617 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
2618 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
2619 Reference: time module`__)
3292
8c7b522dc934 added date selection popup windows (thanks Marcus Priesch)
Richard Jones <richard@users.sourceforge.net>
parents: 3291
diff changeset
2620 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
2621 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
2622
3597
Richard Jones <richard@users.sourceforge.net>
parents: 3590
diff changeset
2623 <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
2624
3647
d4112ddfc0bb doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 3597
diff changeset
2625 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
2626 typically you'd have::
3647
d4112ddfc0bb doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 3597
diff changeset
2627
d4112ddfc0bb doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 3597
diff changeset
2628 <span tal:replace="structure context/due/field" />
d4112ddfc0bb doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 3597
diff changeset
2629 <span tal:replace="structure context/due/popcal" />
d4112ddfc0bb doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 3597
diff changeset
2630
1773
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2631 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
2632 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
2633
021b131bd816 doc fixes, one more fix to the permissions-in-listings fix
Richard Jones <richard@users.sourceforge.net>
parents: 3126
diff changeset
2634 size
021b131bd816 doc fixes, one more fix to the permissions-in-listings fix
Richard Jones <richard@users.sourceforge.net>
parents: 3126
diff changeset
2635 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
2636 height
021b131bd816 doc fixes, one more fix to the permissions-in-listings fix
Richard Jones <richard@users.sourceforge.net>
parents: 3126
diff changeset
2637 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
2638 showid
021b131bd816 doc fixes, one more fix to the permissions-in-listings fix
Richard Jones <richard@users.sourceforge.net>
parents: 3126
diff changeset
2639 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
2640 additional
021b131bd816 doc fixes, one more fix to the permissions-in-listings fix
Richard Jones <richard@users.sourceforge.net>
parents: 3126
diff changeset
2641 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
2642 sort_on
021b131bd816 doc fixes, one more fix to the permissions-in-listings fix
Richard Jones <richard@users.sourceforge.net>
parents: 3126
diff changeset
2643 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
2644 (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
2645 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
2646 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
2647 value
fd32170475f5 allow preselection of values in templating menu()s (patch [SF#1396085])
Richard Jones <richard@users.sourceforge.net>
parents: 3463
diff changeset
2648 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
2649
021b131bd816 doc fixes, one more fix to the permissions-in-listings fix
Richard Jones <richard@users.sourceforge.net>
parents: 3126
diff changeset
2650 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
2651 filtering the items in the list - they're passed as the
3597
Richard Jones <richard@users.sourceforge.net>
parents: 3590
diff changeset
2652 "filterspec" argument to a Class.filter() call. For example::
Richard Jones <richard@users.sourceforge.net>
parents: 3590
diff changeset
2653
Richard Jones <richard@users.sourceforge.net>
parents: 3590
diff changeset
2654 <span tal:replace="structure context/status/menu" />
Richard Jones <richard@users.sourceforge.net>
parents: 3590
diff changeset
2655
Richard Jones <richard@users.sourceforge.net>
parents: 3590
diff changeset
2656 <span tal:replace="python:context.status.menu(order='+name",
Richard Jones <richard@users.sourceforge.net>
parents: 3590
diff changeset
2657 value='chatting',
Richard Jones <richard@users.sourceforge.net>
parents: 3590
diff changeset
2658 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
2659
2883
1ca5ebe9b16a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2858
diff changeset
2660 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
2661 items sorted by some property, for example::
1ca5ebe9b16a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2858
diff changeset
2662
1ca5ebe9b16a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2858
diff changeset
2663 python:context.files.sorted('creation')
1ca5ebe9b16a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2858
diff changeset
2664
1ca5ebe9b16a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2858
diff changeset
2665 Will list the files by upload date.
1773
5f15fb95180c various cosmetic fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1730
diff changeset
2666 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
2667 items in reverse order
2180
58b6d1747973 Web interface tweaks.
Richard Jones <richard@users.sourceforge.net>
parents: 2159
diff changeset
2668 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
2669 =========== ================================================================
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2670
2958
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2671 __ http://docs.python.org/lib/module-time.html
1ae91c2fa5fe merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
2672
2138
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
2673 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
2674 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
2675 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
2676
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
2677 context/title/field
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
2678
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2134
diff changeset
2679 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
2680 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
2681 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
2682 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
2683 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
2684
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2685
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2686 The request variable
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
2687 ~~~~~~~~~~~~~~~~~~~~
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2688
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
2689 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
2690 class.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2691
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2692 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
2693 request.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2694
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2695 .. 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
2696
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2697 =========== ============================================================
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2698 Variable Holds
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2699 =========== ============================================================
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2700 form the CGI form as a cgi.FieldStorage
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2701 env the CGI environment variables
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1083
diff changeset
2702 base the base URL for this tracker
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2703 user a HTMLUser instance for this user
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2704 classname the current classname (possibly None)
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2705 template the current template (suffix, also possibly None)
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2706 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
2707 =========== ============================================================
1083
40fc5f8cd55c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1074
diff changeset
2708
40fc5f8cd55c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1074
diff changeset
2709 **Index page specific variables (indexing arguments)**
40fc5f8cd55c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1074
diff changeset
2710
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2711 =========== ============================================================
1083
40fc5f8cd55c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1074
diff changeset
2712 Variable Holds
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2713 =========== ============================================================
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2714 columns dictionary of the columns to display in an index page
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2715 show a convenience access to columns - request/show/colname will
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
2716 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
2717 sort index sort columns [(direction, column name)]
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2718 group index grouping properties [(direction, column name)]
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2719 filter properties to filter the index on
3718
0d561b24ceff support sqlite3
Richard Jones <richard@users.sourceforge.net>
parents: 3717
diff changeset
2720 filterspec values to filter the index on (property=value, eg
0d561b24ceff support sqlite3
Richard Jones <richard@users.sourceforge.net>
parents: 3717
diff changeset
2721 ``priority=1`` or ``messages.author=42``
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2722 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
2723 =========== ============================================================
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2724
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2725 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
2726
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2727 =============== ========================================================
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2728 Method Description
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2729 =============== ========================================================
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2730 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
2731 page title
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2732 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
2733 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
2734 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
2735 of the templating
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2736 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
2737 list of items (see `hyperdb item wrapper`_, and
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2738 `batching`_)
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2739 =============== ========================================================
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2740
1142
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2741 The form variable
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2742 :::::::::::::::::
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2743
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2744 The form variable is a bit special because it's actually a python
1142
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2745 FieldStorage object. That means that you have two ways to access its
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2746 contents. For example, to look up the CGI form value for the variable
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2747 "name", use the path expression::
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2748
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2749 request/form/name/value
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2750
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2751 or the python expression::
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2752
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2753 python:request.form['name'].value
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2754
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2755 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
2756 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
2757 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
2758 "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
2759 ``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
2760 best to know beforehand what you're dealing with.
1142
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2761
Richard Jones <richard@users.sourceforge.net>
parents: 1136
diff changeset
2762
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2763 The db variable
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2764 ~~~~~~~~~~~~~~~
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2765
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
2766 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
2767 class.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2768
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2769 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
2770 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
2771
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2772 db/user
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2773 python:db.user
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2774
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1680
diff changeset
2775 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
2776 ``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
2777 ``request/user``), but it can be useful in detectors or interfaces.
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1680
diff changeset
2778
1123
644d3075c2df more documentation, fixed bug in request/description
Richard Jones <richard@users.sourceforge.net>
parents: 1113
diff changeset
2779 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
2780
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2781
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2782 The templates variable
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2783 ~~~~~~~~~~~~~~~~~~~~~~
1073
cf30c6cdca02 More documentation.
Richard Jones <richard@users.sourceforge.net>
parents: 1070
diff changeset
2784
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
2785 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
2786 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
2787 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
2788
42f6c76950a4 Cancel version bump to 1.5.0 - the impact is minimal, so just update
anatoly techtonik <techtonik@gmail.com>
parents: 4695
diff changeset
2789 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
2790 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
2791 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
2792
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2793 templates/name
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2794
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2795 or the python expression::
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2796
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2797 templates[name]
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2798
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2799 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
2800 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
2801 macro (called "macro_name"), use the path expression::
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2802
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2803 templates/name/macros/macro_name
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2804
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2805 or the python expression::
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2806
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2807 templates[name].macros[macro_name]
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2808
2855
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2809 The repeat variable
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2810 ~~~~~~~~~~~~~~~~~~~
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2811
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2812 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
2813 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
2814 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
2815
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2816 repeat/user
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2817 python:repeat['user']
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2818
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2819 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
2820
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2821 =============== =========================================================
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2822 Method Description
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2823 =============== =========================================================
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2824 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
2825 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
2826 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
2827 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
2828 number Current position in the sequence, starting from 1.
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2829 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
2830 z, then aa through zz, and so on.
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2831 Letter Same as letter(), except uppercase.
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2832 roman Current position in the sequence as lowercase roman
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2833 numerals.
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2834 Roman Same as roman(), except uppercase.
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2835 =============== =========================================================
874bf6abad42 doc for repeat variable
Richard Jones <richard@users.sourceforge.net>
parents: 2739
diff changeset
2836
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2837
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2838 The utils variable
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
2839 ~~~~~~~~~~~~~~~~~~
4921
8430576a5625 doc: Reverse engineer extension handling and add separate chapter
anatoly techtonik <techtonik@gmail.com>
parents: 4891
diff changeset
2840 .. _templating utilities:
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2841
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
2842 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
2843 ``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
2844 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
2845
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2846 =============== ========================================================
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2847 Method Description
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2848 =============== ========================================================
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2849 Batch return a batch object using the supplied list
2180
58b6d1747973 Web interface tweaks.
Richard Jones <richard@users.sourceforge.net>
parents: 2159
diff changeset
2850 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
2851 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
2852 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
2853 ``_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
2854 the popupCalendar DateHTMLProperty method
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2855 =============== ========================================================
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2856
1270
c3424abf7f77 added ability to implement new templating utility methods
Richard Jones <richard@users.sourceforge.net>
parents: 1262
diff changeset
2857
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2858 Batching
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2859 ::::::::
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2860
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2861 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
2862 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
2863
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2864 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
2865 overlap=0)
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2866
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2867 or, to get the current index batch::
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2868
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2869 request/batch
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2870
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2871 The parameters are:
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2872
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2873 ========= ==============================================================
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2874 Parameter Usage
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2875 ========= ==============================================================
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2876 sequence a list of HTMLItems
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2877 size how big to make the sequence.
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2878 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
2879 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
2880 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
2881 then it is combined with this batch
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2882 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
2883 ========= ==============================================================
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2884
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2885 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
2886 addition, it has several more attributes:
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2887
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2888 =============== ========================================================
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2889 Attribute Description
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2890 =============== ========================================================
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
2891 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
2892 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
2893 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
2894 index*
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2895 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
2896 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
2897 =============== ========================================================
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2898
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2899 And several methods:
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2900
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2901 =============== ========================================================
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2902 Method Description
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2903 =============== ========================================================
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2904 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
2905 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
2906 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
2907 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
2908 =============== ========================================================
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2909
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2910 An example of batching::
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2911
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2912 <table class="otherinfo">
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2913 <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
2914 <tr tal:define="keywords db/keyword/list"
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2915 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
2916 <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
2917 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
2918 keyword here</td>
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2919 </tr>
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2920 </table>
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2921
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2922 ... 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
2923 the "keyword" class (well, their "name" anyway).
1124
1fc1f92c5f31 more doc, bugfix in Batch
Richard Jones <richard@users.sourceforge.net>
parents: 1123
diff changeset
2924
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
2925
4325
6ec048310de7 add simple doc about translating customised tracker content
Richard Jones <richard@users.sourceforge.net>
parents: 4300
diff changeset
2926 Translations
6ec048310de7 add simple doc about translating customised tracker content
Richard Jones <richard@users.sourceforge.net>
parents: 4300
diff changeset
2927 ~~~~~~~~~~~~
6ec048310de7 add simple doc about translating customised tracker content
Richard Jones <richard@users.sourceforge.net>
parents: 4300
diff changeset
2928
6ec048310de7 add simple doc about translating customised tracker content
Richard Jones <richard@users.sourceforge.net>
parents: 4300
diff changeset
2929 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
2930 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
2931 ``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
2932 create the locale files.
6ec048310de7 add simple doc about translating customised tracker content
Richard Jones <richard@users.sourceforge.net>
parents: 4300
diff changeset
2933
6ec048310de7 add simple doc about translating customised tracker content
Richard Jones <richard@users.sourceforge.net>
parents: 4300
diff changeset
2934
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2935 Displaying Properties
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
2936 ---------------------
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2937
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2938 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
2939 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
2940 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
2941 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
2942 view, that property may be displayed in an editable field.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2943
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2944
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2945 Index Views
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
2946 -----------
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2947
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2948 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
2949 classes. The template used is "*classname*.index".
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
2950
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2951
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2952 Index View Specifiers
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
2953 ~~~~~~~~~~~~~~~~~~~~~
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2954
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2955 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
2956 been added for clarity)::
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2957
3036
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2958 /issue?status=unread,in-progress,resolved&
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
2959 keyword=security,ui&
3696
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2960 @group=priority,-status&
3036
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2961 @sort=-activity&
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
2962 @filters=status,keyword&
3036
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2963 @columns=title,status,fixer
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2964
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2965 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
2966 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
2967 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
2968 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
2969 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
2970 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
2971 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
2972 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
2973 headings in the table.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2974
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2975 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
2976 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
2977 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
2978
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
2979 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
2980 "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
2981 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
2982 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
2983 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
2984 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
2985 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
2986 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
2987 properties.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2988
3036
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2989 ============ =============================================================
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2990 Argument Description
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2991 ============ =============================================================
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2992 @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
2993 descending or nothing for ascending sorting. Several
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2994 properties can be specified delimited with comma.
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2995 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
2996 use @sort0, @sort1 etc. with option @sortdir0, @sortdir1
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
2997 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
2998 sortdir0 specifies reverse order).
3036
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
2999 @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
3000 in descending or nothing for ascending order. Several
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
3001 properties can be specified delimited with comma.
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
3002 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
3003 use @group0, @group1 etc. with option @groupdir0, @groupdir1
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3688
diff changeset
3004 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
3005 groupdir0 specifies reverse order).
3036
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
3006 @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
3007 all.
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
3008 @filter indicates which properties are being used in filtering.
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
3009 Default is none.
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
3010 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
3011 have (very basic search/filter).
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
3012 @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
3013 issue titles, etc)
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
3014 ============ =============================================================
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
3015
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3016
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
3017 Searching Views
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3018 ---------------
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3019
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
3020 .. note::
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
3021 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
3022 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
3023 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
3024
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3025 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
3026 "*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
3027 ``@action`` variable. The "search" action:
1245
d8c98af869ff merge from maint-0-5
Richard Jones <richard@users.sourceforge.net>
parents: 1244
diff changeset
3028
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3029 - 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
3030 searching
3036
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
3031 - sets the ``@filter`` variable correctly
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
3032 - 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
3033
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3034 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
3035 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
3036 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
3037 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
3038 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
3039 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
3040 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
3041
3036
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
3042 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
3043 provide an additional argument:
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
3044
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
3045 ============ =============================================================
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
3046 Argument Description
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
3047 ============ =============================================================
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
3048 @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
3049 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
3050 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
3051 schema has this ability, but the *minimal* template schema
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
3052 does not.
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2991
diff changeset
3053 ============ =============================================================
1245
d8c98af869ff merge from maint-0-5
Richard Jones <richard@users.sourceforge.net>
parents: 1244
diff changeset
3054
d8c98af869ff merge from maint-0-5
Richard Jones <richard@users.sourceforge.net>
parents: 1244
diff changeset
3055
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3056 Item Views
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3057 ----------
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3058
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3059 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
3060 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
3061 "history" section.
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3062
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3063
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3064 Editor Section
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3065 ~~~~~~~~~~~~~~
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 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
3068 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
3069
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3070 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
3071 "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
3072 template)::
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3073
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3074 <table class="form">
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3075 <tr>
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
3076 <th>Title</th>
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3077 <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
3078 </tr>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3079
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3080 <tr>
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
3081 <th>Priority</th>
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3082 <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
3083 <th>Status</th>
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3084 <td tal:content="structure context/status/menu">status</td>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3085 </tr>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3086
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3087 <tr>
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
3088 <th>Superseder</th>
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3089 <td>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3090 <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
3091 <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
3092 <span tal:condition="context/superseder">
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3093 <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
3094 </span>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3095 </td>
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
3096 <th>Nosy List</th>
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3097 <td>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3098 <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
3099 <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
3100 </td>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3101 </tr>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3102
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3103 <tr>
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
3104 <th>Assigned To</th>
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3105 <td tal:content="structure context/assignedto/menu">
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3106 assignedto menu
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3107 </td>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3108 <td>&nbsp;</td>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3109 <td>&nbsp;</td>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3110 </tr>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3111
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3112 <tr>
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
3113 <th>Change Note</th>
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3114 <td colspan="3">
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1083
diff changeset
3115 <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
3116 </td>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3117 </tr>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3118
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3119 <tr>
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
3120 <th>File</th>
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3121 <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
3122 </tr>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3123
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3124 <tr>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3125 <td>&nbsp;</td>
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3126 <td colspan="3" tal:content="structure context/submit">
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3127 submit button will go here
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3128 </td>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3129 </tr>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3130 </table>
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3131
673
604c84696461 link() htmltemplate function now has a "showid" option for links & multilinks.
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
3132
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3133 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
3134 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
3135 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
3136 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
3137
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3138
1638
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3139 Form values
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3140 :::::::::::
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3141
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3142 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
3143 meet the various needs of:
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3144
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3145 1. editing the current item (perhaps an issue item)
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3146 2. editing information related to the current item (eg. messages or
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3147 attached files)
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3148 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
3149 spent on an issue)
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3150
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3151 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
3152 ":" or "@", and other text ("required") is fixed.
1638
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3153
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3154 Properties are specified as form variables:
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3155
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3156 ``<propname>``
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3157 property on the current context item
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3158
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3159 ``<designator>:<propname>``
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3160 property on the indicated item (for editing related information)
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3161
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3162 ``<classname>-<N>:<propname>``
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3163 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
3164 items to attach to the current item)
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3165
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3166 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
3167 the special form values:
1638
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3168
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3169 ``@required``
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3170 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
3171 raised.
1638
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3172
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3173 ``@remove@<propname>=id(s)``
1638
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3174 The ids will be removed from the multilink property.
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3175
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3176 ``:add:<propname>=id(s)``
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3177 The ids will be added to the multilink property.
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3178
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3179 ``:link:<propname>=<designator>``
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3180 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
3181 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
3182 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
3183 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
3184 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
3185 newly created item of class <designator> (where <designator> must be
1638
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3186 <classname>-<N>).
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3187
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3188 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
3189 designator.
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3190
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3191 Two special form values are supported for backwards compatibility:
1638
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3192
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3193 ``:note``
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3194 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
3195 context item. This is ALWAYS designated "msg-1".
1638
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3196 ``:file``
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3197 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
3198 :note. This is ALWAYS designated "file-1".
1638
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3199
4a47eb555e51 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1614
diff changeset
3200
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3201 Spool Section
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3202 ~~~~~~~~~~~~~
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3203
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3204 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
3205 of an issue.
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3206
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3207 TODO
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3208
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3209
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3210 History Section
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3211 ~~~~~~~~~~~~~~~
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3212
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3213 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
3214 journal. This is generally generated with the template::
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3215
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3216 <tal:block tal:replace="structure context/history" />
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3217
5232
462b0f76fce8 issue2550864 - Potential information leakage via journal/history
John Rouillard <rouilj@ieee.org>
parents: 5231
diff changeset
3218 or::
462b0f76fce8 issue2550864 - Potential information leakage via journal/history
John Rouillard <rouilj@ieee.org>
parents: 5231
diff changeset
3219
462b0f76fce8 issue2550864 - Potential information leakage via journal/history
John Rouillard <rouilj@ieee.org>
parents: 5231
diff changeset
3220 <tal:block
462b0f76fce8 issue2550864 - Potential information leakage via journal/history
John Rouillard <rouilj@ieee.org>
parents: 5231
diff changeset
3221 tal:replace="structure python:context.history(showall=True)" />
462b0f76fce8 issue2550864 - Potential information leakage via journal/history
John Rouillard <rouilj@ieee.org>
parents: 5231
diff changeset
3222
462b0f76fce8 issue2550864 - Potential information leakage via journal/history
John Rouillard <rouilj@ieee.org>
parents: 5231
diff changeset
3223 if you want to show history entries for quiet properties.
462b0f76fce8 issue2550864 - Potential information leakage via journal/history
John Rouillard <rouilj@ieee.org>
parents: 5231
diff changeset
3224
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3225 *To be done:*
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3226
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3227 *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
3228 templating through the "journal" method of the item*::
1074
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3229
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3230 <tal:block tal:repeat="entry context/journal">
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3231 a journal entry
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3232 </tal:block>
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3233
954ad22eb7d9 more doc, more cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 1073
diff changeset
3234 *where each journal entry is an HTMLJournalEntry.*
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3235
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3236
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3237 Defining new web actions
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3238 ------------------------
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3239
2016
2112962f5bb1 Update documentation for the client.py split and add an upgrade notice.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2009
diff changeset
3240 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
3241 These are added to the tracker ``extensions`` directory and registered
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3242 using ``instance.registerAction``.
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3243
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3244 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
3245
2112962f5bb1 Update documentation for the client.py split and add an upgrade notice.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2009
diff changeset
3246 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
3247 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
3248 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
3249 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
3250
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3251 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
3252 issues`_" for an example.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3253
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3254
2016
2112962f5bb1 Update documentation for the client.py split and add an upgrade notice.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2009
diff changeset
3255 Define the new action class
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3256 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3257
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3258 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
3259 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
3260
3291
bb08ffc56967 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3289
diff changeset
3261 from roundup.cgi.actions import Action
bb08ffc56967 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3289
diff changeset
3262
2016
2112962f5bb1 Update documentation for the client.py split and add an upgrade notice.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2009
diff changeset
3263 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
3264 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
3265 ''' 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
3266 '''
2112962f5bb1 Update documentation for the client.py split and add an upgrade notice.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2009
diff changeset
3267
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3268 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
3269 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
3270
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3271 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
3272 It may then:
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3273
4880
ca692423e401 Different approach to fix XSS in issue2550817
Ralf Schlatterbeck <rsc@runtux.com>
parents: 4790
diff changeset
3274 - add information to ``self.client._ok_message``
ca692423e401 Different approach to fix XSS in issue2550817
Ralf Schlatterbeck <rsc@runtux.com>
parents: 4790
diff changeset
3275 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
3276 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
3277 - 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
3278 next
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3279 - 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
3280 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
3281
2112962f5bb1 Update documentation for the client.py split and add an upgrade notice.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2009
diff changeset
3282
2112962f5bb1 Update documentation for the client.py split and add an upgrade notice.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2009
diff changeset
3283 Register the action class
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3284 ~~~~~~~~~~~~~~~~~~~~~~~~~~
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3285
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3286 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
3287 it with the following code appended to your ``myaction.py`` file::
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3288
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3289 def init(instance):
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3290 instance.registerAction('myaction', myActionClass)
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3291
2016
2112962f5bb1 Update documentation for the client.py split and add an upgrade notice.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 2009
diff changeset
3292 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
3293
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3294
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3295 Use the new action
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3296 ~~~~~~~~~~~~~~~~~~
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3297
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3298 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
3299
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3300 <input type="hidden" name="@action" value="myaction">
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3301
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3302 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
3303
2046
f913b6beac35 document and make easier the actions-returning-content idiom
Richard Jones <richard@users.sourceforge.net>
parents: 2034
diff changeset
3304 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
3305 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
f913b6beac35 document and make easier the actions-returning-content idiom
Richard Jones <richard@users.sourceforge.net>
parents: 2034
diff changeset
3306
f913b6beac35 document and make easier the actions-returning-content idiom
Richard Jones <richard@users.sourceforge.net>
parents: 2034
diff changeset
3307 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
3308 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
3309 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
3310 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
3311 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
3312 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
3313 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
3314
f913b6beac35 document and make easier the actions-returning-content idiom
Richard Jones <richard@users.sourceforge.net>
parents: 2034
diff changeset
3315 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
3316
f913b6beac35 document and make easier the actions-returning-content idiom
Richard Jones <richard@users.sourceforge.net>
parents: 2034
diff changeset
3317 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
3318 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
3319 spreadsheet or database).
f913b6beac35 document and make easier the actions-returning-content idiom
Richard Jones <richard@users.sourceforge.net>
parents: 2034
diff changeset
3320
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
3321
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3322 8-bit character set support in Web interface
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3323 --------------------------------------------
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3324
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3325 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
3326 and a browser cookie.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3327
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3328 - In forms, use the ``@charset`` variable.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3329 - To use the cookie override, have the ``roundup_charset`` cookie set.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3330
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3331 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
3332 ``kio8-r``).
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3333
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3334 Inside Roundup, all strings are stored and processed in utf-8.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3335 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
3336 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
3337 characters in form fields). This version allows one to change
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3338 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
3339 the following code to your ``page.html`` template::
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3340
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3341 <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
3342 <a tal:attributes="href python:request.indexargs_url(uri,
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3343 {'@charset':'utf-8'})">utf-8</a>
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3344 <a tal:attributes="href python:request.indexargs_url(uri,
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3345 {'@charset':'koi8-r'})">koi8-r</a>
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3346 </tal:block>
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3347
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3348 (substitute ``koi8-r`` with appropriate charset for your language).
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3349 Charset preference is kept in the browser cookie ``roundup_charset``.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3350
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3351 ``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
3352 should be changed to include actual character set name::
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3353
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3354 <meta http-equiv="Content-Type"
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3355 tal:attributes="content string:text/html;; charset=${request/client/charset}"
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3356 />
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3357
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3358 The charset is also sent in the http header.
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3359
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
3360
1100
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
3361 Examples
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
3362 ========
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
3363
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3364 .. contents::
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3365 :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
3366 :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
3367
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3368
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3369 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
3370 --------------------------------------
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3371
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
3372 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
3373 the database.
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
3374
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3375
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1215
diff changeset
3376 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
3377 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1100
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
3378
3122
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3379 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
3380 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
3381 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
3382
3409
80dc8011228e mention schema mutation
Richard Jones <richard@users.sourceforge.net>
parents: 3404
diff changeset
3383 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
3384 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
3385 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
3386 caches the schema).
3122
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3387
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3388 1. Modify the ``schema.py``::
3122
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3389
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3390 issue = IssueClass(db, "issue",
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
3391 assignedto=Link("user"), keyword=Multilink("keyword"),
3122
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3392 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
3393 due_date=Date())
3122
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3394
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3395 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
3396
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3397 <tr>
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3398 <th>Due Date</th>
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3399 <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
3400 </tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3401
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3402 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
3403
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3404 <tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3405 <th>Due Date</th>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3406 <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
3407 </tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3408
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3409 3. Add the property to the ``issue.index.html`` page::
3122
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3410
3123
5894c7bea8ce *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3122
diff changeset
3411 (in the heading row)
5894c7bea8ce *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3122
diff changeset
3412 <th tal:condition="request/show/due_date">Due Date</th>
5894c7bea8ce *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3122
diff changeset
3413 (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
3414 <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
3415 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
3416
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3417 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
3418 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
3419
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3420 <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
3421 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
3422
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3423 4. Add the property to the ``issue.search.html`` page::
3122
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3424
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3425 <tr tal:define="name string:due_date">
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3426 <th i18n:translate="">Due Date:</th>
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3427 <td metal:use-macro="search_input"></td>
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3428 <td metal:use-macro="column_input"></td>
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3429 <td metal:use-macro="sort_input"></td>
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3430 <td metal:use-macro="group_input"></td>
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3431 </tr>
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3432
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3433 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
3434 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
3435 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
3436
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3437 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
3438 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
3439
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3440 Adding a new constrained field to the classic schema
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3441 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
3442
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3443 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
3444 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
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 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
3448 ::::::::::::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3449
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3450 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
3451 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
3452 issue: a category.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3453
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3454 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
3455 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
3456 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
3457 best).
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3458
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3459
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3460 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
3461 ::::::::::::::::::::::::::::::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3462
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3463 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
3464 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
3465 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
3466 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
3467
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3468 # 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
3469
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3470 add::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3471
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3472 category = Class(db, "category", name=String())
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3473 category.setkey("name")
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3474
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3475 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
3476 "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
3477 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
3478 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
3479 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
3480 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
3481 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
3482 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
3483
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3484 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
3485 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
3486 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
3487 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
3488 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
3489 the category::
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3490
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3491 issue = IssueClass(db, "issue", ... ,
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3492 category=Multilink("category"), ... )
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3493
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3494 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
3495 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
3496 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
3497
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3498 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
3499 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
3500
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3501
1235
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3502 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
3503 :::::::::::::::::::::::::::::::::
1235
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3504
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3505 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
3506 "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
3507 ``initial_data.py`` under the comment::
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3508
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3509 # 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
3510 # 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
3511
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3512 Add::
1235
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3513
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3514 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
3515 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
3516 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
3517 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
3518
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3519 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
3520 ``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
3521
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3522 % 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
3523 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
3524 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
3525 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
3526 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
3527 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
3528 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
3529 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
3530 3
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3531 roundup> exit...
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3532 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
3533
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
3534
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3535 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
3536 ::::::::::::::::::::::::::::::::::::::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3537
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3538 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
3539 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
3540 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
3541 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
3542
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3543 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
3544 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
3545
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3546 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
3547 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
3548
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3549 # Assign the access and edit permissions for issue, file and message
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3550 # to regular users now
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3551 for cl in 'issue', 'file', 'msg', 'category':
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3552 p = db.security.getPermission('View', cl)
2991
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
3553 db.security.addPermissionToRole('User', 'View', cl)
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
3554 db.security.addPermissionToRole('User', 'Edit', cl)
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
3555 db.security.addPermissionToRole('User', 'Create', cl)
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3556
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3557 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
3558 so that normal users can view and edit "category" objects.
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3559
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3560 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
3561 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
3562 interface stuff.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3563
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3564
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3565 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
3566 ::::::::::::::::::::::::::::::::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3567
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3568 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
3569 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
3570 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
3571 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
3572
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3573 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
3574 "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
3575 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
3576 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
3577 the classblock for the *issue* class::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3578
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3579 <p class="classblock"
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3580 tal:condition="python:request.user.hasPermission('View', 'category')">
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3581 <b>Categories</b><br>
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3582 <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
3583 href="category?@template=item">New Category<br></a>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3584 </p>
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3585
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3586 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
3587 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
3588 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
3589 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
3590 get that.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3591
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3592 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
3593 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
3594 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
3595 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
3596 categories.
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3597
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3598 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
3599 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
3600 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
3601 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
3602 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
3603 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
3604 would see the "Categories" stuff.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3605
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3606
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3607 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
3608 ::::::::::::::::::::::::::::::::::::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3609
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3610 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
3611 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
3612 conditions. Now we have to write that page.
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3613
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3614 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
3615 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
3616 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
3617 write now.
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3618
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3619 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
3620 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
3621 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
3622 from which files by looking for these comments::
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3623
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3624 <!-- category.item -->
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3625
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3626 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
3627 trappings::
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3628
1214
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
3629 <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
3630 <title metal:fill-slot="head_title">Category editing</title>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3631 <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
3632 <h2>Category editing</h2>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3633 </td>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3634 <td class="content" metal:fill-slot="content">
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3635
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3636 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
3637 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
3638 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
3639 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
3640 multiple times::
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3641
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3642 <form method="POST" onSubmit="return submit_once()"
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3643 enctype="multipart/form-data">
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3644
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3645 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
3646 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
3647 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
3648
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3649 <input type="hidden" name="@required" value="name">
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3650
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3651 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
3652 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
3653 happening::
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 <table class="form">
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3656 <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
3657
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3658 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
3659 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
3660 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
3661 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
3662 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
3663 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
3664
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3665 <tr>
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
3666 <th>Name</th>
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3667 <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
3668 name</td>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3669 </tr>
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3670
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3671 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
3672
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3673 <tr>
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3674 <td>&nbsp;</td>
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3675 <td colspan="3" tal:content="structure context/submit">
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3676 submit button will go here
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3677 </td>
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3678 </tr>
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3679
5201
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
3680 The ``context/submit`` bit generates the submit button but also
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
3681 generates the @action and @csrf hidden fields. The @action field is
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
3682 used to tell roundup how to process the form. The @csrf field provides
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
3683 a unique single use token to defend against CSRF attacks. (More about
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
3684 anti-csrf measures can be found in ``upgrading.txt``.)
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
3685
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3686 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
3687 stuff::
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3688
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3689 </td>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3690 </tal:block>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3691
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3692 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
3693
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3694 <!-- category.item -->
1214
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
3695 <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
3696 <title metal:fill-slot="head_title">Category editing</title>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3697 <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
3698 <h2>Category editing</h2>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3699 </td>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3700 <td class="content" metal:fill-slot="content">
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3701 <form method="POST" onSubmit="return submit_once()"
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3702 enctype="multipart/form-data">
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3703
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3704 <table class="form">
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3705 <tr><th class="header" colspan="2">Category</th></tr>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3706
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3707 <tr>
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
3708 <th>Name</th>
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3709 <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
3710 name</td>
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3711 </tr>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3712
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3713 <tr>
1829
4e4afbe3cd30 Move '<input type="hidden">' elements into a block.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1825
diff changeset
3714 <td>
4e4afbe3cd30 Move '<input type="hidden">' elements into a block.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1825
diff changeset
3715 &nbsp;
4e4afbe3cd30 Move '<input type="hidden">' elements into a block.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1825
diff changeset
3716 <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
3717 </td>
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3718 <td colspan="3" tal:content="structure context/submit">
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3719 submit button will go here
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3720 </td>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3721 </tr>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3722 </table>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3723 </form>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3724 </td>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
3725 </tal:block>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3726
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3727 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
3728 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
3729 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
3730 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
3731
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3732
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3733 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
3734 ::::::::::::::::::::::::::::::::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3735
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3736 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
3737 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
3738 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
3739 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
3740 is created.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3741
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3742 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
3743 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
3744 stuff, it is entirely up to your sense of aesthetics::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3745
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
3746 <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
3747 <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
3748 <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
3749 <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
3750 property='category', width='200')" />
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3751 </td>
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3752
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3753 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
3754 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
3755 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
3756 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
3757 issue).
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3758
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3759 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
3760 which contains the list of currently known categories.
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3761
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3762
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3763 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
3764 :::::::::::::::::::::::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3765
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3766 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
3767 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
3768 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
3769 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
3770
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3771 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
3772 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
3773 ``<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
3774 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
3775 ``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
3776 change.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3777
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3778 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
3779 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
3780 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
3781
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3782 <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
3783 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
3784 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
3785 <th>Priority:</th>
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3786 <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
3787 <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
3788 <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
3789 <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
3790 </tr>
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3791
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3792 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
3793
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3794 - ``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
3795 ``db_klass`` and ``db_content``.
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3796 - ``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
3797 should be displayed.
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3798 - ``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
3799 should be sorted on.
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3800 - ``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
3801 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
3802
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3803 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
3804
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3805 <tr>
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3806 <th>Category:</th>
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3807 <td>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3808 <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
3809 <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
3810 <option value="">------------</option>
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3811 <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
3812 <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
3813 <option value="3">weave</option>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3814 </select>
1730
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3815 </td>
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
3816 <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
3817 <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
3818 <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
3819 </tr>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3820
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3821 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
3822 :::::::::::::::::::::::::::::::::::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3823
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3824 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
3825 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
3826 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
3827 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
3828 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
3829
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3830 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
3831 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
3832 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
3833 forth.
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3834
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3835 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
3836
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3837 <th tal:condition="request/show/category">Category</th>
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3838
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3839 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
3840 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
3841
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3842 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
3843 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
3844 that every issue gets assigned to "i" in turn.
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3845
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3846 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
3847
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3848 <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
3849 tal:content="i/category"></td>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3850
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3851 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
3852 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
3853 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
3854
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3855 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
3856 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
3857 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
3858 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
3859 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
3860 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
3861 "category" to that list and it all should work.
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
3862
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3863 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
3864 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3865
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3866 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
3867 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
3868
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
3869 1. Add a new class to your tracker ``schema.py``::
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3870
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3871 # storage for time logging
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3872 timelog = Class(db, "timelog", period=Interval())
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3873
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3874 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
3875 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
3876
3652
3a19d31be628 add in note about perms
Richard Jones <richard@users.sourceforge.net>
parents: 3649
diff changeset
3877 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
3878 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
3879
3a19d31be628 add in note about perms
Richard Jones <richard@users.sourceforge.net>
parents: 3649
diff changeset
3880 db.security.addPermissionToRole('User', 'Create', 'timelog')
3a19d31be628 add in note about perms
Richard Jones <richard@users.sourceforge.net>
parents: 3649
diff changeset
3881 db.security.addPermissionToRole('User', 'View', 'timelog')
3a19d31be628 add in note about perms
Richard Jones <richard@users.sourceforge.net>
parents: 3649
diff changeset
3882
3653
cfa7fa2c5e0f arg rest
Richard Jones <richard@users.sourceforge.net>
parents: 3652
diff changeset
3883 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
3884
3a19d31be628 add in note about perms
Richard Jones <richard@users.sourceforge.net>
parents: 3649
diff changeset
3885 db.security.addPermissionToRole('User', 'Edit', 'timelog')
3a19d31be628 add in note about perms
Richard Jones <richard@users.sourceforge.net>
parents: 3649
diff changeset
3886
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3887 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
3888 ``schema.py``)::
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3889
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3890 issue = IssueClass(db, "issue",
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
3891 assignedto=Link("user"), keyword=Multilink("keyword"),
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3892 priority=Link("priority"), status=Link("status"),
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3893 times=Multilink("timelog"))
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3894
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3895 the "times" property is the new link to the "timelog" class.
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3896
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3897 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
3898 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
3899 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
3900 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
3901 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
3902 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
3903 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
3904 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
3905
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3906 <tr>
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
3907 <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
3908 <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
3909 (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
3910 </td>
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3911 </tr>
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3912
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3913 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
3914 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
3915 like this::
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3916
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3917 <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
3918
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3919 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
3920 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
3921 added to it.
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3922
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3923 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
3924
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3925 <tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3926 <th>Time Log</th>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3927 <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
3928 (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
3929 <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
3930 </td>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3931 </tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3932
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
3933
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3934 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
3935 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
3936 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
3937 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
3938 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
3939 file is as follows::
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3940
3717
5770f1802cd0 better conflict retry in postgresql backend [SF#1552809]
Richard Jones <richard@users.sourceforge.net>
parents: 3697
diff changeset
3941 from roundup import date
5770f1802cd0 better conflict retry in postgresql backend [SF#1552809]
Richard Jones <richard@users.sourceforge.net>
parents: 3697
diff changeset
3942
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3943 def totalTimeSpent(times):
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3944 ''' Call me with a list of timelog items (which have an
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3945 Interval "period" property)
1270
c3424abf7f77 added ability to implement new templating utility methods
Richard Jones <richard@users.sourceforge.net>
parents: 1262
diff changeset
3946 '''
3717
5770f1802cd0 better conflict retry in postgresql backend [SF#1552809]
Richard Jones <richard@users.sourceforge.net>
parents: 3697
diff changeset
3947 total = date.Interval('0d')
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3948 for time in times:
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3949 total += time.period._value
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3950 return total
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3951
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3952 def init(instance):
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3953 instance.registerUtil('totalTimeSpent', totalTimeSpent)
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3954
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
3955 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
3956 ``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
3957
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
3958 5. Display the timelog for an issue::
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3959
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3960 <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
3961 <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
3962 <tal:block
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3963 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
3964 </th></tr>
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3965 <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
3966 <tr tal:repeat="time context/times">
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3967 <td tal:content="time/creation"></td>
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3968 <td tal:content="time/period"></td>
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3969 <td tal:content="time/creator"></td>
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3970 </tr>
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3971 </table>
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3972
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3973 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
3974 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
3975 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
3976 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
3977 and 40 minutes).
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
3978
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3979 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
3980 ``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
3981 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
3982 time logging interface.
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
3983
3657
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
3984 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
3985 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
3986
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3987 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
3988
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
3989 msg = FileClass(db, "msg",
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
3990 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
3991 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
3992 date=Date(),
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
3993 summary=String(),
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
3994 files=Multilink("file"),
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
3995 messageid=String(),
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3996 inreplyto=String(),
3657
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
3997 times=Multilink("timelog"))
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
3998
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
3999 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
4000 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
4001 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
4002 handles the timelog entry.
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
4003
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
4004 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
4005
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
4006 <tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
4007 <th>Time Log</th>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
4008 <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
4009 (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
4010 <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
4011 <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
4012 </td>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
4013 </tr>
3657
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
4014
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
4015 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
4016
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
4017 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
4018 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
4019 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
4020 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
4021
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
4022 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
4023
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
4024 <tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
4025 <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
4026 <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
4027 </tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
4028 </table>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
4029
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
4030 <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
4031 <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
4032 <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
4033 <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
4034 <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
4035 <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
4036 <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
4037 </tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
4038 </table>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
4039
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
4040 <table class="messages">
3657
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
4041
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4042
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4043 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
4044 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4045
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4046 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
4047 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
4048 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
4049 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
4050
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4051 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
4052 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
4053 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
4054
3289
5da323b46907 doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3276
diff changeset
4055 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
4056 "issue" class definition, add::
5da323b46907 doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3276
diff changeset
4057
5da323b46907 doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3276
diff changeset
4058 # list our systems
5da323b46907 doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3276
diff changeset
4059 system = Class(db, "system", name=String(), order=Number())
5da323b46907 doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3276
diff changeset
4060 system.setkey("name")
5da323b46907 doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3276
diff changeset
4061
5da323b46907 doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3276
diff changeset
4062 # 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
4063 support = IssueClass(db, "support",
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4064 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
4065 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
4066 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
4067
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4068 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
4069 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
4070 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
4071 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
4072 required properties.
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
4073
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4074 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
4075 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
4076 on the ``issue`` class, and duplicate them for ``support``.
2159
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
4077
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
4078 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
4079 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
4080
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4081 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
4082
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
4083
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
4084 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
4085 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
4086 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
4087
2991
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
4088 db.security.addPermissionToRole('SysAdmin', 'View', 'support')
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
4089 db.security.addPermissionToRole('SysAdmin', 'Create', 'support')
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
4090 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
4091
2159
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
4092 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
4093 users, and add "SysAdmin" to their Roles list.
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
4094
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
4095 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
4096 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
4097 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
4098 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
4099
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4100
4891
ad3d628e73f2 docs: Link custom authentication examples in admin guide
anatoly techtonik <techtonik@gmail.com>
parents: 4888
diff changeset
4101 .. _external-authentication:
ad3d628e73f2 docs: Link custom authentication examples in admin guide
anatoly techtonik <techtonik@gmail.com>
parents: 4888
diff changeset
4102
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4103 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
4104 -----------------------------
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4105
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4106 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
4107 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4108
3228
1b15e9eeb592 fixes to the "Using an external password validation source"...
Richard Jones <richard@users.sourceforge.net>
parents: 3130
diff changeset
4109 .. 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
4110 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
4111 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
4112 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
4113 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
4114
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4115 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
4116 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
4117 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
4118 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
4119 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
4120 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
4121
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4122 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
4123
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4124 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
4125 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
4126 need to override the standard ``verifyPassword`` method defined in
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
4127 ``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
4128 following is added as ``externalpassword.py`` in the tracker ``extensions``
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
4129 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
4130
3228
1b15e9eeb592 fixes to the "Using an external password validation source"...
Richard Jones <richard@users.sourceforge.net>
parents: 3130
diff changeset
4131 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
4132 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
4133
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4134 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
4135 def verifyPassword(self, userid, password):
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
4136 '''Look through the file, line by line, looking for a
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
4137 name that matches.
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
4138 '''
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4139 # 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
4140 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
4141
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4142 # 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
4143 # 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
4144 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
4145
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4146 # 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
4147 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
4148 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
4149 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
4150 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
4151
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4152 # 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
4153 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
4154
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
4155 def init(instance):
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
4156 instance.registerAction('login', ExternalPasswordLoginAction)
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
4157
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
4158 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
4159 template.
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4160
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4161
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4162 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
4163 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4164
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4165 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
4166 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
4167 and primary user group.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4168
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4169 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
4170 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
4171 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
4172 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
4173 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
4174
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4175 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
4176 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
4177 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
4178 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
4179 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
4180 immediate access is needed. In short, it:
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4181
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4182 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
4183 2. compares that list to the current roundup user list:
1299
b2d04ce03802 Email improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 1293
diff changeset
4184
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4185 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
4186 b. entries with mismatching real names are *updated*
1293
Richard Jones <richard@users.sourceforge.net>
parents: 1292
diff changeset
4187 c. entries only exist in the passwd file are *created*
1299
b2d04ce03802 Email improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 1293
diff changeset
4188
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4189 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
4190
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4191 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
4192 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
4193 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
4194 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
4195 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
4196 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
4197 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
4198
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4199 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
4200 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
4201 tracker we're to work on::
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4202
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4203 import sys, os, smtplib
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4204 from roundup import instance, date
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4205
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4206 # open the tracker
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4207 tracker_home = sys.argv[1]
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4208 tracker = instance.open(tracker_home)
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4209
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4210 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
4211
3228
1b15e9eeb592 fixes to the "Using an external password validation source"...
Richard Jones <richard@users.sourceforge.net>
parents: 3130
diff changeset
4212 # 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
4213 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
4214 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
4215
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4216 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
4217 appear in the file)::
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4218
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4219 # 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
4220 # "real" users
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4221 ignore = ['ekmmon', 'bfast', 'csrmail']
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4222
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4223 # 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
4224 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
4225 'cs_pool', 'anonymous', 'system_pool', 'automated']
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4226
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4227 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
4228
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4229 roles = {
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4230 '501': 'User,Tech', # tech
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4231 '502': 'User', # finance
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4232 '503': 'User,CSR', # customer service reps
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4233 '504': 'User', # sales
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4234 '505': 'User', # marketing
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4235 }
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4236
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4237 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
4238 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
4239 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
4240 now do all the work::
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4241
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4242 # open the database
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4243 db = tracker.open('admin')
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4244 try:
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4245 # 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
4246 msg = []
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4247
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4248 # 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
4249 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
4250 if user in ignore:
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4251 # this user shouldn't appear in our tracker
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4252 continue
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4253 keep.append(user)
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4254 try:
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4255 # see if the user exists in the tracker
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4256 uid = db.user.lookup(user)
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4257
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4258 # 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
4259 if real != db.user.get(uid, 'realname'):
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4260 db.user.set(uid, realname=real)
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4261 msg.append('FIX %s - %s'%(user, real))
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4262 except KeyError:
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4263 # nope, the user doesn't exist
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4264 db.user.create(username=user, realname=real,
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4265 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
4266 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
4267
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4268 # 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
4269 # "keep" list - retire those who aren't
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4270 for uid in db.user.list():
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4271 user = db.user.get(uid, 'username')
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4272 if user not in keep:
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4273 db.user.retire(uid)
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4274 msg.append('RET %s'%user)
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4275
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4276 # 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
4277 if msg:
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4278 # create the email
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4279 msg = '''Subject: %s user database maintenance
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4280
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4281 %s
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4282 '''%(db.config.TRACKER_NAME, '\n'.join(msg))
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4283
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4284 # send the email
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4285 smtp = smtplib.SMTP(db.config.MAILHOST)
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4286 addr = db.config.ADMIN_EMAIL
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4287 smtp.sendmail(addr, addr, msg)
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4288
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4289 # now we're done - commit the changes
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4290 db.commit()
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4291 finally:
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4292 # always close the database cleanly
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4293 db.close()
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4294
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4295 And that's it!
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4296
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4297
1680
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4298 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
4299 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1680
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4300
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4301 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
4302 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
4303 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
4304 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
4305 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
4306 for more information about doing this.
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4307
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4308 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
4309 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
4310 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
4311 ``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
4312 ``extensions`` directory (see `using an external password validation
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4313 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
4314
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4315 def verifyPassword(self, userid, password):
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4316 ''' Verify the password that the user has supplied
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4317 '''
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4318 stored = self.db.user.get(self.userid, 'password')
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4319 if password == stored:
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4320 return 1
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4321 if not password and not stored:
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4322 return 1
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4323 return 0
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4324
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4325 So you could reimplement this as something like::
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4326
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4327 def verifyPassword(self, userid, password):
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4328 ''' Verify the password that the user has supplied
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4329 '''
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4330 # 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
4331 username = self.db.user.get(self.userid, 'username')
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4332 # 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
4333
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
4334
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4335 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
4336 ----------------------------
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4337
3830
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4338 Preventing SPAM
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4339 ~~~~~~~~~~~~~~~
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4340
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4341 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
4342 ``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
4343 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
4344 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
4345 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
4346
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4347 from roundup.exceptions import Reject
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4348
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4349 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
4350 if newvalues['type'] == 'text/html':
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4351 raise Reject, 'not allowed'
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4352
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4353 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
4354 content = newvalues['content']
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4355 if content.count('http://') > 2:
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4356 raise Reject, 'not allowed'
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4357
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4358 def init(db):
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4359 db.file.audit('create', reject_html)
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4360 db.msg.audit('create', reject_manylinks)
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4361
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4362 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
4363 need that ability::
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4364
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4365 if newvalues['type'].startswith('image/'):
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4366 raise Reject, 'not allowed'
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4367
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
4368
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4369 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
4370 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4371
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4372 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
4373 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
4374 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
4375
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4376 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
4377
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4378 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
4379 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
4380 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
4381 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
4382 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
4383 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
4384 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
4385
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4386 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
4387 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
4388
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4389 <tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4390 <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
4391 <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
4392 </tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4393
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4394 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
4395 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
4396
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4397 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
4398 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
4399 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
4400 # 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
4401 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
4402 try:
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4403 # 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
4404 sendto = []
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4405 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
4406 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
4407 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
4408 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
4409
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4410 # 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
4411 # 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
4412 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
4413
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4414 # 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
4415 # 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
4416 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
4417 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
4418 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
4419 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
4420
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4421 # 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
4422 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
4423 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
4424 # 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
4425 # 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
4426 # 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
4427 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
4428 continue
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4429 # 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
4430 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
4431 # 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
4432 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
4433 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
4434
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4435 # 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
4436 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
4437 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
4438 else:
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4439 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
4440
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4441 # 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
4442 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
4443 # 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
4444 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
4445 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
4446
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4447 # 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
4448 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
4449
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4450 # 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
4451 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
4452
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4453 # 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
4454 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
4455 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
4456 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
4457
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4458 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
4459 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
4460
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4461 # 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
4462 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
4463
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4464 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
4465
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4466 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
4467 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4468
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4469 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
4470 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
4471
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4472 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
4473 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
4474 template::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4475
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4476 <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
4477
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4478 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
4479
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4480 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
4481
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4482 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
4483 ...)
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4484
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4485 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
4486
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4487 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
4488 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
4489
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4490 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
4491 ``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
4492
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4493 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
4494 ''' 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
4495 property.
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4496 '''
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4497 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
4498 return
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4499 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
4500 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
4501 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
4502 return
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4503 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
4504 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
4505 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
4506 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
4507
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4508 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
4509 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
4510
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4511 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
4512 from::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4513
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4514 <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
4515 <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
4516
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4517 to::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4518
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4519 <th>Status</th>
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4520 <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
4521 <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
4522 <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
4523 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
4524 <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
4525 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
4526 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
4527 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
4528 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
4529 </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
4530 </select>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4531 <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
4532 tal:replace="structure context/status/menu" />
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
4533 </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
4534
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4535 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
4536
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
4537
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4538 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
4539 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4540
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4541 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
4542 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
4543 resolved. To achieve this:
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4544
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4545 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
4546 ``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
4547 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
4548
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4549 issue = IssueClass(db, "issue",
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4550 assignedto=Link("user"), keyword=Multilink("keyword"),
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4551 priority=Link("priority"), status=Link("status"))
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4552
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4553 to this, adding the blockers entry::
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4554
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4555 issue = IssueClass(db, "issue",
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4556 blockers=Multilink("issue"),
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4557 assignedto=Link("user"), keyword=Multilink("keyword"),
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4558 priority=Link("priority"), status=Link("status"))
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4559
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4560 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
4561 page, using something like::
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4562
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
4563 <th>Waiting On</th>
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4564 <td>
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4565 <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
4566 size=20)" />
3881
e7050411a774 fix documentation per [SF#731171] thanks to Forest Wilkinson
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3878
diff changeset
4567 <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
4568 property='blockers')" />
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4569 <span tal:condition="context/blockers"
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4570 tal:repeat="blk context/blockers">
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4571 <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
4572 tal:content="blk/id"></a>
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4573 </span>
3881
e7050411a774 fix documentation per [SF#731171] thanks to Forest Wilkinson
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3878
diff changeset
4574 </td>
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4575
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4576 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
4577 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
4578 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
4579 the "superseders" field.
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4580
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4581 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
4582
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4583 - 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
4584 - 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
4585
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4586 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
4587
3258
1cbde34afa77 fix to doc
Richard Jones <richard@users.sourceforge.net>
parents: 3241
diff changeset
4588
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4589 def blockresolution(db, cl, nodeid, newvalues):
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4590 ''' 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
4591 '''
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4592 if nodeid is None:
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4593 blockers = []
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4594 else:
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4595 blockers = cl.get(nodeid, 'blockers')
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4596 blockers = newvalues.get('blockers', blockers)
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4597
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4598 # 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
4599 # changed
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4600 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
4601 return
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4602
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4603 # get the resolved state ID
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4604 resolved_id = db.status.lookup('resolved')
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4605
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4606 # format the info
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4607 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
4608 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
4609 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
4610 if len(blockers) == 1:
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4611 s = 'issue %s is'%s
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4612 else:
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4613 s = 'issues %s are'%s
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4614
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4615 # 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
4616 if newvalues['status'] == resolved_id:
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4617 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
4618
3258
1cbde34afa77 fix to doc
Richard Jones <richard@users.sourceforge.net>
parents: 3241
diff changeset
4619
1cbde34afa77 fix to doc
Richard Jones <richard@users.sourceforge.net>
parents: 3241
diff changeset
4620 def resolveblockers(db, cl, nodeid, oldvalues):
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4621 ''' 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
4622 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
4623 '''
3258
1cbde34afa77 fix to doc
Richard Jones <richard@users.sourceforge.net>
parents: 3241
diff changeset
4624 newstatus = cl.get(nodeid,'status')
1cbde34afa77 fix to doc
Richard Jones <richard@users.sourceforge.net>
parents: 3241
diff changeset
4625
1cbde34afa77 fix to doc
Richard Jones <richard@users.sourceforge.net>
parents: 3241
diff changeset
4626 # no change?
1cbde34afa77 fix to doc
Richard Jones <richard@users.sourceforge.net>
parents: 3241
diff changeset
4627 if oldvalues.get('status', None) == newstatus:
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4628 return
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4629
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4630 resolved_id = db.status.lookup('resolved')
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4631
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4632 # interesting?
3258
1cbde34afa77 fix to doc
Richard Jones <richard@users.sourceforge.net>
parents: 3241
diff changeset
4633 if newstatus != resolved_id:
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4634 return
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4635
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4636 # 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
4637 # their blockers list
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4638 issues = cl.find(blockers=nodeid)
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4639 for issueid in issues:
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4640 blockers = cl.get(issueid, 'blockers')
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4641 if nodeid in blockers:
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4642 blockers.remove(nodeid)
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4643 cl.set(issueid, blockers=blockers)
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4644
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4645 def init(db):
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4646 # 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
4647 db.issue.audit('create', blockresolution)
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4648 db.issue.audit('set', blockresolution)
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4649
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4650 # can only happen on a set
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4651 db.issue.react('set', resolveblockers)
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4652
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4653 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
4654 "detectors" directory.
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4655
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4656 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
4657 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
4658 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
4659 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
4660 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
4661
3796
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4662 <a href="#"
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4663 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
4664 '@sort': '-activity',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4665 '@group': 'priority',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4666 '@filter': 'status',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4667 '@columns': columns_showall,
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4668 '@search_text': '',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4669 'status': status_notresolved,
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4670 '@dispname': i18n.gettext('Show All'),
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4671 })"
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4672 i18n:translate="">Show All</a><br>
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4673
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4674 modify it to add the "blockers" info to the URL (note, both the
3590
Richard Jones <richard@users.sourceforge.net>
parents: 3582
diff changeset
4675 "@filter" *and* "blockers" values must be specified)::
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4676
3796
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4677 <a href="#"
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4678 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
4679 '@sort': '-activity',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4680 '@group': 'priority',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4681 '@filter': 'status,blockers',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4682 '@columns': columns_showall,
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4683 '@search_text': '',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4684 'status': status_notresolved,
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4685 'blockers': '-1',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4686 '@dispname': i18n.gettext('Show All'),
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4687 })"
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
4688 i18n:translate="">Show All</a><br>
2409
Richard Jones <richard@users.sourceforge.net>
parents: 2397
diff changeset
4689
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
4690 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
4691 be unwrapped.
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4692
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
4693 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
4694 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
4695 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
4696 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
4697 another issue's "blockers" property.
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4698
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4699 Add users to the nosy list based on the keyword
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4700 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4701
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4702 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
4703 list based
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4704 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
4705 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
4706
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4707 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
4708 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
4709
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4710 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
4711 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
4712 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
4713 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
4714 list when a keyword is set.
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4715
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4716 Adding the nosy keyword list
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4717 ::::::::::::::::::::::::::::
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4718
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4719 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
4720 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
4721 ``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
4722 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
4723 ``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
4724 definition of user will be::
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4725
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4726 user = Class(db, "user",
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4727 username=String(), password=Password(),
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4728 address=String(), realname=String(),
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4729 phone=String(), organisation=String(),
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4730 alternate_addresses=String(),
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4731 queries=Multilink('query'), roles=String(),
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4732 timezone=String(),
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4733 nosy_keywords=Multilink('keyword'))
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4734
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4735 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
4736 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4737
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4738 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
4739 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
4740 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
4741 We can easily
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4742 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
4743 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
4744 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
4745 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
4746 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
4747 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
4748
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4749 <tr>
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4750 <th>Nosy Keywords</th>
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4751 <td>
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4752 <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
4753 <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
4754 </td>
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4755 </tr>
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4756
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4757
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4758 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
4759 ::::::::::::::::::::::::::::::::::::::::::::::
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4760
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4761 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
4762 the users to the nosy list when required.
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4763 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
4764 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
4765 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
4766 ``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
4767 ``detectors/nosy_keyword_reaction.py``.
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4768 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
4769 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
4770 ``nosyreaction`` function actually sends the e-mail.
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4771 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
4772
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4773 def init(db):
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4774 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
4775 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
4776
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4777 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
4778 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
4779 ``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
4780 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
4781 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
4782 ``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
4783 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
4784 new keywords, than looping over all users,
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4785 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
4786 ``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
4787 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
4788 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
4789 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
4790 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
4791
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4792 def update_kw_nosy(db, cl, nodeid, newvalues):
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4793 '''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
4794 '''
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4795 # 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
4796 current = {}
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4797 if nodeid is None:
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4798 ok = ('new', 'yes')
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4799 else:
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4800 ok = ('yes',)
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4801 # 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
4802 # changed
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4803 if not newvalues.has_key('nosy'):
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4804 nosy = cl.get(nodeid, 'nosy')
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4805 for value in nosy:
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4806 if not current.has_key(value):
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4807 current[value] = 1
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4809 # 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
4810 if newvalues.has_key('nosy'):
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4811 nosy = newvalues.get('nosy', [])
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4812 for value in nosy:
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4813 if not db.hasnode('user', value):
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4814 continue
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4815 if not current.has_key(value):
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4816 current[value] = 1
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4817
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4818 # 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
4819 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
4820 keyword_ids = newvalues['keyword']
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4821 for keyword in keyword_ids:
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4822 # loop over all users,
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4823 # 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
4824 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
4825 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
4826 found = 0
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4827 for kw in nosy_kw:
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4828 if kw == keyword:
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4829 found = 1
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4830 if found:
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4831 current[user_id] = 1
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4832
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4833 # 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
4834 newvalues['nosy'] = current.keys()
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4835
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4836 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
4837
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4838 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
4839
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4840 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
4841 :::::::
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4842
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4843 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
4844
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4845 Multiple additions
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4846 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
4847 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
4848 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
4849 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
4850 of keywords, and only add users when they have indicated
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4851 interest on a new keyword.
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4852
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4853 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
4854 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
4855 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
4856
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
4857 Scalability
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4858 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
4859 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
4860 many users this will be a serious performance bottleneck.
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
4861 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
4862 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
4863 loop over all users.
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
4864
4781
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4865 Restricting updates that arrive by email
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4866 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4867
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4868 Roundup supports multiple update methods:
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4869
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4870 1. command line
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4871 2. plain email
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4872 3. pgp signed email
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4873 4. web access
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4874
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4875 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
4876 these methods. For example you can set up issues that are viewable
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4877 only by people on the nosy list. So you must prevent unauthenticated
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4878 changes to the nosy list.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4879
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4880 Since plain email can be easily forged, it does not provide sufficient
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4881 authentication in this senario.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4882
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4883 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
4884 transaction and rejects the update if it changes the nosy list.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4885
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4886 Create the detector (auditor) module and add it to the detectors
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4887 directory of your tracker::
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4888
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4889 from roundup import roundupdb, hyperdb
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4890
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4891 from roundup.mailgw import Unauthorized
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4892
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4893 def restrict_nosy_changes(db, cl, nodeid, newvalues):
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4894 '''Do not permit changes to nosy via email.'''
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4895
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4896 if not (newvalues.has_key('nosy')):
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4897 # the nosy field has not changed so no need to check.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4898 return
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4899
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4900 if db.tx_Source in ['web', 'email-sig-openpgp', 'cli' ]:
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4901 # if the source of the transaction is from an authenticated
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4902 # source or a privileged process allow the transaction.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4903 # Other possible sources: 'email'
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4904 return
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4905
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4906 # otherwise raise an error
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4907 raise Unauthorized, \
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4908 'Changes to nosy property not allowed via %s for this issue.'%\
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4909 tx_Source
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4910
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4911 def init(db):
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4912 ''' Install restrict_nosy_changes to run after other auditors.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4913
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4914 Allow initial creation email to set nosy.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4915 So don't execute: db.issue.audit('create', requestedbyauditor)
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4916
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4917 Set priority to 110 to run this auditor after other auditors
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4918 that can cause nosy to change.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4919 '''
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4920 db.issue.audit('set', restrict_nosy_changes, 110)
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4921
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4922 This detector (auditor) will prevent updates to the nosy field if it
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4923 arrives by email. Since it runs after other auditors (due to the
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4924 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
4925 are done by other auditors if triggered by an email.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4926
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4927 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
4928 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
4929 Read the CHANGES.txt document in the roundup source code for further
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4930 details on tx_Source.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
4931
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4932 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
4933 -----------------------------------
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4934
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4935 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
4936 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4937
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
4938 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
4939
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4940 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
4941
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4942 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
4943 "issue"::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4944
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4945 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
4946 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
4947
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4948 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
4949
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4950 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
4951
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4952 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
4953 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
4954 list::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4955
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4956 <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
4957 <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
4958 <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
4959 <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
4960 '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
4961 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
4962 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
4963 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
4964 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
4965 </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
4966 </select>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4967
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4968 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
4969 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
4970 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
4971
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4972 def assignedtoMustBeFixer(db, cl, nodeid, newvalues):
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4973 ''' 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
4974 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
4975 '''
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4976 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
4977 # 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
4978 return
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4979
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4980 # 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
4981 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
4982 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
4983 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
4984
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4985 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
4986 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
4987 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
4988
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
4989 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
4990 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
4991
3121
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
4992
1954
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
4993 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
4994 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1954
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
4995
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
4996 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
4997 access, meaning they
1954
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
4998 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
4999 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
5000 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
5001 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
5002
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
5003 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
5004 ``schema.py``::
1954
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
5005
3121
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
5006 #
1954
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
5007 # New users not approved by the admin
3121
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
5008 #
1954
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
5009 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
5010 description='New user registered via web or email')
2991
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
5011
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
5012 # 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
5013 # and view their own
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
5014 db.security.addPermissionToRole('Provisional User', 'Create', 'issue')
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
5015 def own_issue(db, userid, itemid):
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
5016 '''Determine whether the userid matches the creator of the issue.'''
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
5017 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
5018 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
5019 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
5020 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
5021 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
5022 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
5023 db.security.addPermissionToRole('Provisional User', p)
2991
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
5024
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
5025 # Assign the Permissions for issue-related classes
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
5026 for cl in 'file', 'msg', 'query', 'keyword':
3121
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
5027 db.security.addPermissionToRole('Provisional User', 'View', cl)
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
5028 db.security.addPermissionToRole('Provisional User', 'Edit', cl)
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
5029 db.security.addPermissionToRole('Provisional User', 'Create', cl)
2991
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
5030 for cl in 'priority', 'status':
3121
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
5031 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
5032
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
5033 # 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
5034 db.security.addPermissionToRole('Provisional User', 'Web Access')
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
5035 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
5036
3260
e41e1540a287 fix provisional user so they can view their own record
Richard Jones <richard@users.sourceforge.net>
parents: 3258
diff changeset
5037 # 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
5038 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
5039 '''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
5040 return userid == itemid
e41e1540a287 fix provisional user so they can view their own record
Richard Jones <richard@users.sourceforge.net>
parents: 3258
diff changeset
5041 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
5042 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
5043 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
5044 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
5045 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
5046 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
5047
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
5048 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
5049 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
5050
2921
ad4fb8a14a97 more doc updates, not so many TODOs any more
Richard Jones <richard@users.sourceforge.net>
parents: 2915
diff changeset
5051 [main]
ad4fb8a14a97 more doc updates, not so many TODOs any more
Richard Jones <richard@users.sourceforge.net>
parents: 2915
diff changeset
5052 ...
4941
b76710818d31 Roundup Tracker isssue #: 2550857
John Rouillard <rouilj@ieee.org>
parents: 4921
diff changeset
5053 new_web_user_roles = Provisional User
b76710818d31 Roundup Tracker isssue #: 2550857
John Rouillard <rouilj@ieee.org>
parents: 4921
diff changeset
5054 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
5055
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
5056
3126
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
5057 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
5058 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
5059
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
5060 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
5061 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
5062
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
5063 def checker(klass):
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
5064 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
5065 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
5066 return check
3126
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
5067 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
5068 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
5069 check=checker(cl))
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
5070 db.security.addPermissionToRole('User', p)
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
5071 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
5072 check=checker(cl))
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
5073 db.security.addPermissionToRole('User', p)
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
5074 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
5075
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
5076
4300
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
5077 Moderating user registration
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
5078 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
5079
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
5080 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
5081
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
5082 1. creating a new highly-restricted user role "Pending",
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
5083 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
5084 role,
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
5085 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
5086 role using roundup.mailer
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
5087 4. edit the role to "User" for valid users.
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
5088
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
5089 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
5090 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
5091 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
5092
3126
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
5093
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5094 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
5095 ---------------------------------
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 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
5098 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5099
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
5100 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
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 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
5103
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5104 <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
5105 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
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 "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
5108
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5109 <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
5110 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
5111
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
5112 ... 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
5113
1966
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
5114 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
5115 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1966
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
5116
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
5117 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
5118 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
5119 displays the rows of data::
1966
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
5120
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
5121 <tr tal:attributes="class string:priority-${i/priority/plain}">
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
5122
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
5123 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
5124 different priorities, as follows::
1966
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
5125
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
5126 tr.priority-critical td {
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
5127 background-color: red;
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
5128 }
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
5129
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
5130 tr.priority-urgent td {
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
5131 background-color: orange;
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
5132 }
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
5133
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
5134 and so on, with far less offensive colours :)
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
5135
2009
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5136 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
5137 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2009
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5138
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5139 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
5140 ``issue.item.html``:
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5141
2726
aa95c79cff8b clarification
Richard Jones <richard@users.sourceforge.net>
parents: 2589
diff changeset
5142 1. add a form around the listing table (separate from the existing
aa95c79cff8b clarification
Richard Jones <richard@users.sourceforge.net>
parents: 2589
diff changeset
5143 index-page form), so at the top it reads::
2009
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5144
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5145 <form method="POST" tal:attributes="action request/classname">
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5146 <table class="list">
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5147
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5148 and at the bottom of that table::
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5149
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5150 </table>
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5151 </form
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5152
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5153 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
5154 navigation table or the subsequent form table.
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5155
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5156 2. in the display for the issue property, change::
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5157
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5158 <td tal:condition="request/show/status"
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5159 tal:content="python:i.status.plain() or default">&nbsp;</td>
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5160
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5161 to::
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5162
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5163 <td tal:condition="request/show/status"
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5164 tal:content="structure i/status/field">&nbsp;</td>
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5165
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5166 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
5167
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
5168 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
5169 ``tal:repeat="i batch"``) add a new table row::
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5170
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5171 <tr>
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5172 <td tal:attributes="colspan python:len(request.columns)">
5201
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
5173 <input name="@csrf" type="hidden"
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
5174 tal:attributes="value python:utils.anti_csrf_nonce()">
2009
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5175 <input type="submit" value=" Save Changes ">
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5176 <input type="hidden" name="@action" value="edit">
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5177 <tal:block replace="structure request/indexargs_form" />
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5178 </td>
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5179 </tr>
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5180
5201
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
5181 which gives us a submit button, indicates that we are performing an
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
5182 edit on any changed statuses, and provides a defense against cross
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
5183 site request forgery attacks.
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
5184
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
5185 The final ``tal:block`` will make sure that the current index view
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
5186 parameters (filtering, columns, etc) will be used in rendering the
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
5187 next page (the results of the editing).
2009
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
5188
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5189
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5190 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
5191 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5192
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
5193 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
5194
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5195 <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
5196 <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
5197 <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
5198 <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
5199 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
5200 <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
5201 <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
5202 <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
5203 <td>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5204 <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
5205 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
5206 </td>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5207 </tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5208 </table>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5209
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5210
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5211 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
5212 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5213
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5214 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
5215 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
5216 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
5217 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
5218 ``@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
5219
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5220 <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
5221 <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
5222 <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
5223 <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
5224 <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
5225 </th>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5226 </tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5227 <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
5228 <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
5229 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
5230 <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
5231 <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
5232 <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
5233 <td>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5234 <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
5235 </td>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5236 </tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5237 </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
5238
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5239 <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
5240 <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
5241 <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
5242 <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
5243 </th>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5244 </tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5245 <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
5246 <tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5247 <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
5248 <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
5249 <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
5250 (<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
5251 </th>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5252 </tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5253 <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
5254 </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
5255 </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
5256 </table>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5257
3121
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
5258
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5259 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
5260 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5261
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5262 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
5263 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
5264 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
5265 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
5266 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
5267
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5268 <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
5269 enctype="multipart/form-data">
5201
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
5270 <input name="@csrf" type="hidden"
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
5271 tal:attributes="value python:utils.anti_csrf_nonce()">
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5272 <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
5273 <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
5274
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5275 <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
5276 <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
5277 <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
5278 </form>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5279
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5280 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
5281 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
5282
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5283 <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
5284 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
5285 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
5286 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
5287
5201
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
5288 <input name="@csrf" type="hidden"
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
5289 tal:attributes="value python:utils.anti_csrf_nonce()">
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5290 <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
5291 <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
5292 <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
5293 .
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5294 .
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5295 .
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5296 </form>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5297
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
5298 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
5299 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
5300
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5301 <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
5302 <tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5303 <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
5304 <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
5305 </tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5306 <tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5307 <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
5308 <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
5309 </tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5310 </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
5311
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5312 ... 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
5313 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
5314
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5315 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
5316 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
5317 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
5318
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
5319 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
5320
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5321 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
5322 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
5323 ''' 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
5324 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
5325 '''
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5326 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
5327 if category == '-1':
4880
ca692423e401 Different approach to fix XSS in issue2550817
Ralf Schlatterbeck <rsc@runtux.com>
parents: 4790
diff changeset
5328 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
5329 return
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5330 # 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
5331 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
5332
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
5333 def init(instance):
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
5334 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
5335
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5336 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
5337 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
5338
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
5339
3548
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5340 Debugging Trackers
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5341 ==================
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5342
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5343 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
5344 Roundup:
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5345
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5346 1. web :: debug
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5347 2. mail :: debug
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5348 3. logging :: level
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5349
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5350 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
5351 more information.
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5352
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5353 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
5354 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
5355 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
5356
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
5357
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
5358 .. _`design documentation`: design.html
4325
6ec048310de7 add simple doc about translating customised tracker content
Richard Jones <richard@users.sourceforge.net>
parents: 4300
diff changeset
5359 .. _`developer's guide`: developers.html

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