Mercurial > p > roundup > code

annotate doc/customizing.txt @ 7355:2b1cbe079ff5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Main TOC gets depth 3; Example section TOC removed. Since the doc is split, the top level TOC is shorter and can display the individual example sections. This means the example section TOC isn't needed.
author John Rouillard <rouilj@ieee.org>
date Tue, 16 May 2023 01:26:21 -0400
parents f3c9ba5db30b
children 0cb4541bad71
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6586
24e2eeb2ed9a Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents: 6583
diff changeset
1 .. meta::
6774
e7b4ad2c57ac landmarks, skiplink, remove bad attrs, autocomplete search
John Rouillard <rouilj@ieee.org>
parents: 6752
diff changeset
2 :description:
6586
24e2eeb2ed9a Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents: 6583
diff changeset
3 How to customize and extend the Roundup Issue
24e2eeb2ed9a Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents: 6583
diff changeset
4 Tracker. Includes many cookbook and how-to
24e2eeb2ed9a Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents: 6583
diff changeset
5 examples. Reference for the design and internals
24e2eeb2ed9a Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents: 6583
diff changeset
6 needed to understand and extend the examples to meet
24e2eeb2ed9a Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents: 6583
diff changeset
7 new needs.
24e2eeb2ed9a Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents: 6583
diff changeset
8
4033
bca7c59ac400 Enhance documentation generation.
Stefan Seefeld <stefan@seefeld.name>
parents: 3968
diff changeset
9 :tocdepth: 2
bca7c59ac400 Enhance documentation generation.
Stefan Seefeld <stefan@seefeld.name>
parents: 3968
diff changeset
10
1215
f83efa574177 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1214
diff changeset
11 ===================
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
12 Customising Roundup
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
13 ===================
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
14
1070
af0abadfda3a *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1058
diff changeset
15 .. 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
16 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
17
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 684
diff changeset
18 .. contents::
7355
2b1cbe079ff5 Main TOC gets depth 3; Example section TOC removed.
John Rouillard <rouilj@ieee.org>
parents: 7352
diff changeset
19 :depth: 3
4888
b07014d6a7aa docs: Fix table of contents on customizing page
anatoly techtonik <techtonik@gmail.com>
parents: 4880
diff changeset
20 :local:
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 684
diff changeset
21
898
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
22 What You Can Do
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
23 ===============
898
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
24
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
25 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
26 `design documentation`_.
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
27
1850
6e80f8f760a4 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1832
diff changeset
28 Customisation of Roundup can take one of six forms:
898
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
29
7352
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
30 1. `tracker configuration <reference.html#tracker-configuration>`_ changes
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
31 2. database, or `tracker schema <reference.html#tracker-schema>`_ changes
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
32 3. "definition" class `database content <reference.html#database-content>`_ changes
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
33 4. behavioural changes through `detectors <reference.html#detectors>`_,
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
34 `extensions <reference.html#extensions>`_ and
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
35 `interfaces.py <reference.html#interfaces-py>`_
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
36 5. `security / access controls <reference.html#security-access-controls>`_
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
37 6. change the `web interface <reference.html#web-interface>`_
898
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
38
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
39 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
40 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
41 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
42 includes adding or removing properties from classes.
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
43
6163
c2fd254c9257 Doc updates/indexing.
John Rouillard <rouilj@ieee.org>
parents: 6160
diff changeset
44 .. _CustomExamples:
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2897
diff changeset
45
1100
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
46 Examples
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
47 ========
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
48
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
49 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
50 --------------------------------------
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
51
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
52 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
53 the database.
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
54
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
55
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1215
diff changeset
56 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
57 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1100
f96deb4fb935 more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
58
3122
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
59 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
60 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
61 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
62
3409
80dc8011228e mention schema mutation
Richard Jones <richard@users.sourceforge.net>
parents: 3404
diff changeset
63 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
64 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
65 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
66 caches the schema).
3122
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
67
6163
c2fd254c9257 Doc updates/indexing.
John Rouillard <rouilj@ieee.org>
parents: 6160
diff changeset
68 .. index:: schema; example changes
c2fd254c9257 Doc updates/indexing.
John Rouillard <rouilj@ieee.org>
parents: 6160
diff changeset
69
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
70 1. Modify the ``schema.py``::
3122
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
71
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
72 issue = IssueClass(db, "issue",
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
73 assignedto=Link("user"), keyword=Multilink("keyword"),
3122
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
74 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
75 due_date=Date())
3122
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
76
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
77 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
78
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
79 <tr>
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
80 <th>Due Date</th>
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
81 <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
82 </tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
83
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
84 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
85
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
86 <tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
87 <th>Due Date</th>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
88 <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
89 </tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
90
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
91 3. Add the property to the ``issue.index.html`` page::
3122
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
92
3123
5894c7bea8ce *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3122
diff changeset
93 (in the heading row)
5894c7bea8ce *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3122
diff changeset
94 <th tal:condition="request/show/due_date">Due Date</th>
5894c7bea8ce *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3122
diff changeset
95 (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
96 <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
97 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
98
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
99 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
100 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
101
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
102 <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
103 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
104
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
105 4. Add the property to the ``issue.search.html`` page::
3122
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
106
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
107 <tr tal:define="name string:due_date">
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
108 <th i18n:translate="">Due Date:</th>
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
109 <td metal:use-macro="search_input"></td>
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
110 <td metal:use-macro="column_input"></td>
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
111 <td metal:use-macro="sort_input"></td>
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
112 <td metal:use-macro="group_input"></td>
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
113 </tr>
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
114
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
115 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
116 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
117 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
118
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
119 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
120 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
121
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
122 Adding a new constrained field to the classic schema
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
123 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6e8eb05435cf new example
Richard Jones <richard@users.sourceforge.net>
parents: 3121
diff changeset
124
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
125 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
126 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
127
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
128
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
129 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
130 ::::::::::::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
131
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
132 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
133 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
134 issue: a category.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
135
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
136 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
137 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
138 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
139 best).
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
140
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
141
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
142 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
143 ::::::::::::::::::::::::::::::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
144
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
145 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
146 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
147 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
148 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
149
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
150 # 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
151
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
152 add::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
153
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
154 category = Class(db, "category", name=String())
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
155 category.setkey("name")
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
156
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
157 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
158 "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
159 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
160 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
161 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
162 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
163 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
164 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
165
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
166 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
167 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
168 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
169 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
170 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
171 the category::
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
172
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
173 issue = IssueClass(db, "issue", ... ,
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
174 category=Multilink("category"), ... )
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
175
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
176 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
177 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
178 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
179
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
180 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
181 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
182
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
183
1235
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
184 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
185 :::::::::::::::::::::::::::::::::
1235
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
186
6174
5522c950a2e4 Add indexing for roundup-admin references.
John Rouillard <rouilj@ieee.org>
parents: 6171
diff changeset
187 If you haven't initialised the database with the
5522c950a2e4 Add indexing for roundup-admin references.
John Rouillard <rouilj@ieee.org>
parents: 6171
diff changeset
188 "``roundup-admin initialise``" command, then you
5522c950a2e4 Add indexing for roundup-admin references.
John Rouillard <rouilj@ieee.org>
parents: 6171
diff changeset
189 can add the following to the tracker ``initial_data.py``
5522c950a2e4 Add indexing for roundup-admin references.
John Rouillard <rouilj@ieee.org>
parents: 6171
diff changeset
190 under the comment::
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
191
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
192 # 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
193 # 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
194
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
195 Add::
1235
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
196
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
197 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
198 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
199 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
200 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
201
6174
5522c950a2e4 Add indexing for roundup-admin references.
John Rouillard <rouilj@ieee.org>
parents: 6171
diff changeset
202 .. index:: roundup-admin; create entries in class
5522c950a2e4 Add indexing for roundup-admin references.
John Rouillard <rouilj@ieee.org>
parents: 6171
diff changeset
203
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
204 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
205 ``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
206
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
207 % 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
208 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
209 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
210 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
211 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
212 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
213 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
214 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
215 3
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
216 roundup> exit...
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
217 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
218
7441653e5330 added hook for external password validation, and some more docco
Richard Jones <richard@users.sourceforge.net>
parents: 1234
diff changeset
219
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
220 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
221 ::::::::::::::::::::::::::::::::::::::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
222
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
223 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
224 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
225 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
226 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
227
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
228 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
229 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
230
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
231 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
232 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
233
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
234 # Assign the access and edit permissions for issue, file and message
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
235 # to regular users now
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
236 for cl in 'issue', 'file', 'msg', 'category':
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
237 p = db.security.getPermission('View', cl)
2991
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
238 db.security.addPermissionToRole('User', 'View', cl)
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
239 db.security.addPermissionToRole('User', 'Edit', cl)
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
240 db.security.addPermissionToRole('User', 'Create', cl)
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
241
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
242 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
243 so that normal users can view and edit "category" objects.
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
244
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
245 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
246 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
247 interface stuff.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
248
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
249
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
250 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
251 ::::::::::::::::::::::::::::::::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
252
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
253 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
254 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
255 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
256 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
257
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
258 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
259 "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
260 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
261 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
262 the classblock for the *issue* class::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
263
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
264 <p class="classblock"
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
265 tal:condition="python:request.user.hasPermission('View', 'category')">
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
266 <b>Categories</b><br>
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
267 <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
268 href="category?@template=item">New Category<br></a>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
269 </p>
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
270
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
271 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
272 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
273 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
274 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
275 get that.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
276
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
277 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
278 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
279 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
280 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
281 categories.
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
282
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
283 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
284 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
285 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
286 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
287 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
288 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
289 would see the "Categories" stuff.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
290
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
291
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
292 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
293 ::::::::::::::::::::::::::::::::::::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
294
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
295 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
296 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
297 conditions. Now we have to write that page.
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
298
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
299 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
300 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
301 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
302 write now.
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
303
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
304 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
305 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
306 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
307 from which files by looking for these comments::
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
308
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
309 <!-- category.item -->
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
310
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
311 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
312 trappings::
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
313
1214
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
314 <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
315 <title metal:fill-slot="head_title">Category editing</title>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
316 <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
317 <h2>Category editing</h2>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
318 </td>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
319 <td class="content" metal:fill-slot="content">
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
320
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
321 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
322 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
323 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
324 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
325 multiple times::
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
326
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
327 <form method="POST" onSubmit="return submit_once()"
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
328 enctype="multipart/form-data">
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
329
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
330 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
331 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
332 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
333
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
334 <input type="hidden" name="@required" value="name">
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
335
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
336 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
337 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
338 happening::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
339
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
340 <table class="form">
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
341 <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
342
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
343 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
344 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
345 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
346 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
347 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
348 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
349
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
350 <tr>
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
351 <th>Name</th>
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
352 <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
353 name</td>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
354 </tr>
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
355
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
356 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
357
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
358 <tr>
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
359 <td>&nbsp;</td>
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
360 <td colspan="3" tal:content="structure context/submit">
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
361 submit button will go here
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
362 </td>
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
363 </tr>
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
364
5201
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
365 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
366 generates the @action and @csrf hidden fields. The @action field is
7268
91125d474c1e doc updates, normalize roundup => Roundup, add links, typo fixes
John Rouillard <rouilj@ieee.org>
parents: 7267
diff changeset
367 used to tell Roundup how to process the form. The @csrf field provides
5201
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
368 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
369 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
370
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
371 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
372 stuff::
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
373
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
374 </td>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
375 </tal:block>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
376
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
377 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
378
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
379 <!-- category.item -->
1214
3ed25834f33c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1213
diff changeset
380 <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
381 <title metal:fill-slot="head_title">Category editing</title>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
382 <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
383 <h2>Category editing</h2>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
384 </td>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
385 <td class="content" metal:fill-slot="content">
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
386 <form method="POST" onSubmit="return submit_once()"
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
387 enctype="multipart/form-data">
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
388
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
389 <table class="form">
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
390 <tr><th class="header" colspan="2">Category</th></tr>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
391
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
392 <tr>
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
393 <th>Name</th>
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
394 <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
395 name</td>
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
396 </tr>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
397
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
398 <tr>
1829
4e4afbe3cd30 Move '<input type="hidden">' elements into a block.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1825
diff changeset
399 <td>
4e4afbe3cd30 Move '<input type="hidden">' elements into a block.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1825
diff changeset
400 &nbsp;
4e4afbe3cd30 Move '<input type="hidden">' elements into a block.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1825
diff changeset
401 <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
402 </td>
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
403 <td colspan="3" tal:content="structure context/submit">
1213
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
404 submit button will go here
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
405 </td>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
406 </tr>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
407 </table>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
408 </form>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
409 </td>
3a5e05edcd87 added doc for METAL
Richard Jones <richard@users.sourceforge.net>
parents: 1164
diff changeset
410 </tal:block>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
411
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
412 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
413 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
414 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
415 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
416
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
417
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
418 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
419 ::::::::::::::::::::::::::::::::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
420
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
421 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
422 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
423 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
424 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
425 is created.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
426
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
427 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
428 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
429 stuff, it is entirely up to your sense of aesthetics::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
430
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
431 <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
432 <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
433 <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
434 <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
435 property='category', width='200')" />
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
436 </td>
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
437
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
438 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
439 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
440 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
441 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
442 issue).
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
443
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
444 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
445 which contains the list of currently known categories.
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
446
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
447
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
448 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
449 :::::::::::::::::::::::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
450
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
451 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
452 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
453 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
454 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
455
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
456 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
457 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
458 ``<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
459 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
460 ``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
461 change.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
462
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
463 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
464 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
465 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
466
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
467 <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
468 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
469 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
470 <th>Priority:</th>
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
471 <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
472 <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
473 <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
474 <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
475 </tr>
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
476
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
477 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
478
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
479 - ``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
480 ``db_klass`` and ``db_content``.
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
481 - ``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
482 should be displayed.
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
483 - ``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
484 should be sorted on.
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
485 - ``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
486 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
487
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
488 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
489
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
490 <tr>
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
491 <th>Category:</th>
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
492 <td>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
493 <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
494 <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
495 <option value="">------------</option>
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
496 <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
497 <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
498 <option value="3">weave</option>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
499 </select>
1730
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
500 </td>
2dd6b4c825e9 Final touches to fix query editing. It should work now.
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1711
diff changeset
501 <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
502 <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
503 <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
504 </tr>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
505
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
506 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
507 :::::::::::::::::::::::::::::::::::
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
508
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
509 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
510 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
511 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
512 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
513 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
514
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
515 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
516 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
517 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
518 forth.
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
519
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
520 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
521
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
522 <th tal:condition="request/show/category">Category</th>
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
523
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
524 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
525 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
526
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
527 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
528 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
529 that every issue gets assigned to "i" in turn.
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
530
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
531 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
532
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
533 <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
534 tal:content="i/category"></td>
1098
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
535
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
536 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
537 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
538 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
539
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
540 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
541 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
542 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
543 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
544 The option that we are interested in is the ``:columns=`` one which
7268
91125d474c1e doc updates, normalize roundup => Roundup, add links, typo fixes
John Rouillard <rouilj@ieee.org>
parents: 7267
diff changeset
545 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
546 "category" to that list and it all should work.
c5819344714c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1096
diff changeset
547
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
548 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
549 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
550
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
551 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
552 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
553
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
554 1. Add a new class to your tracker ``schema.py``::
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
555
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
556 # storage for time logging
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
557 timelog = Class(db, "timelog", period=Interval())
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
558
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
559 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
560 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
561
3652
3a19d31be628 add in note about perms
Richard Jones <richard@users.sourceforge.net>
parents: 3649
diff changeset
562 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
563 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
564
3a19d31be628 add in note about perms
Richard Jones <richard@users.sourceforge.net>
parents: 3649
diff changeset
565 db.security.addPermissionToRole('User', 'Create', 'timelog')
3a19d31be628 add in note about perms
Richard Jones <richard@users.sourceforge.net>
parents: 3649
diff changeset
566 db.security.addPermissionToRole('User', 'View', 'timelog')
3a19d31be628 add in note about perms
Richard Jones <richard@users.sourceforge.net>
parents: 3649
diff changeset
567
3653
cfa7fa2c5e0f arg rest
Richard Jones <richard@users.sourceforge.net>
parents: 3652
diff changeset
568 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
569
3a19d31be628 add in note about perms
Richard Jones <richard@users.sourceforge.net>
parents: 3649
diff changeset
570 db.security.addPermissionToRole('User', 'Edit', 'timelog')
3a19d31be628 add in note about perms
Richard Jones <richard@users.sourceforge.net>
parents: 3649
diff changeset
571
6163
c2fd254c9257 Doc updates/indexing.
John Rouillard <rouilj@ieee.org>
parents: 6160
diff changeset
572 .. index:: schema; example changes
c2fd254c9257 Doc updates/indexing.
John Rouillard <rouilj@ieee.org>
parents: 6160
diff changeset
573
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
574 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
575 ``schema.py``)::
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
576
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
577 issue = IssueClass(db, "issue",
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
578 assignedto=Link("user"), keyword=Multilink("keyword"),
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
579 priority=Link("priority"), status=Link("status"),
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
580 times=Multilink("timelog"))
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
581
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
582 the "times" property is the new link to the "timelog" class.
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
583
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
584 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
585 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
586 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
587 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
588 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
589 items other than the template default item (see the cgi
7352
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
590 documentation on `special form variables
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
591 <reference.html#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
592 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
593
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
594 <tr>
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
595 <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
596 <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
597 (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
598 </td>
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
599 </tr>
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
600
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
601 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
602 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
603 like this::
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
604
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
605 <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
606
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
607 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
608 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
609 added to it.
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
610
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
611 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
612
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
613 <tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
614 <th>Time Log</th>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
615 <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
616 (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
617 <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
618 </td>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
619 </tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
620
7352
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
621 .. _adding-a-time-log-to-your-issues-4:
1679
e2caeaa34ed4 fix timelog documentation, add new cgi special for variable doc
Richard Jones <richard@users.sourceforge.net>
parents: 1674
diff changeset
622
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
623 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
624 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
625 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
626 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
627 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
628 file is as follows::
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
629
3717
5770f1802cd0 better conflict retry in postgresql backend [SF#1552809]
Richard Jones <richard@users.sourceforge.net>
parents: 3697
diff changeset
630 from roundup import date
5770f1802cd0 better conflict retry in postgresql backend [SF#1552809]
Richard Jones <richard@users.sourceforge.net>
parents: 3697
diff changeset
631
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
632 def totalTimeSpent(times):
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
633 ''' Call me with a list of timelog items (which have an
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
634 Interval "period" property)
1270
c3424abf7f77 added ability to implement new templating utility methods
Richard Jones <richard@users.sourceforge.net>
parents: 1262
diff changeset
635 '''
3717
5770f1802cd0 better conflict retry in postgresql backend [SF#1552809]
Richard Jones <richard@users.sourceforge.net>
parents: 3697
diff changeset
636 total = date.Interval('0d')
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
637 for time in times:
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
638 total += time.period._value
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
639 return total
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
640
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
641 def init(instance):
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
642 instance.registerUtil('totalTimeSpent', totalTimeSpent)
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
643
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
644 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
645 ``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
646
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
647 5. Display the timelog for an issue::
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
648
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
649 <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
650 <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
651 <tal:block
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
652 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
653 </th></tr>
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
654 <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
655 <tr tal:repeat="time context/times">
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
656 <td tal:content="time/creation"></td>
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
657 <td tal:content="time/period"></td>
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
658 <td tal:content="time/creator"></td>
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
659 </tr>
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
660 </table>
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
661
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
662 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
663 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
664 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
665 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
666 and 40 minutes).
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
667
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
668 6. If you're using a persistent web server - ``roundup-server`` or
5891
6e341009593b Deprecate mod_python issue2551005
John Rouillard <rouilj@ieee.org>
parents: 5881
diff changeset
669 ``mod_wsgi`` 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
670 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
671 time logging interface.
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
672
3657
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
673 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
674 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
675
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
676 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
677
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
678 msg = FileClass(db, "msg",
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
679 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
680 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
681 date=Date(),
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
682 summary=String(),
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
683 files=Multilink("file"),
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
684 messageid=String(),
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
685 inreplyto=String(),
3657
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
686 times=Multilink("timelog"))
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
687
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
688 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
689 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
690 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
691 handles the timelog entry.
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
692
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
693 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
694
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
695 <tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
696 <th>Time Log</th>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
697 <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
698 (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
699 <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
700 <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
701 </td>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
702 </tr>
3657
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
703
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
704 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
705
3818
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
706 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
707 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
708 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
709 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
710
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
711 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
712
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
713 <tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
714 <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
715 <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
716 </tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
717 </table>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
718
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
719 <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
720 <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
721 <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
722 <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
723 <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
724 <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
725 <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
726 </tr>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
727 </table>
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
728
e5043875a03d Improved due_date and timelog customisation docs [SF#1625124]
Richard Jones <richard@users.sourceforge.net>
parents: 3796
diff changeset
729 <table class="messages">
3657
f7db2771e87d add info about storing Store TimeLog with Messages
Richard Jones <richard@users.sourceforge.net>
parents: 3653
diff changeset
730
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
731
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
732 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
733 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
734
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
735 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
736 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
737 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
738 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
739
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
740 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
741 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
742 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
743
3289
5da323b46907 doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3276
diff changeset
744 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
745 "issue" class definition, add::
5da323b46907 doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3276
diff changeset
746
5da323b46907 doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3276
diff changeset
747 # list our systems
5da323b46907 doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3276
diff changeset
748 system = Class(db, "system", name=String(), order=Number())
5da323b46907 doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3276
diff changeset
749 system.setkey("name")
5da323b46907 doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3276
diff changeset
750
5da323b46907 doc fix
Richard Jones <richard@users.sourceforge.net>
parents: 3276
diff changeset
751 # 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
752 support = IssueClass(db, "support",
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
753 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
754 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
755 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
756
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
757 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
758 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
759 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
760 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
761 required properties.
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
762
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
763 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
764 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
765 on the ``issue`` class, and duplicate them for ``support``.
2159
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
766
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
767 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
768 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
769
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
770 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
771
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
772
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
773 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
774 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
775 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
776
2991
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
777 db.security.addPermissionToRole('SysAdmin', 'View', 'support')
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
778 db.security.addPermissionToRole('SysAdmin', 'Create', 'support')
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
779 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
780
2159
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
781 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
782 users, and add "SysAdmin" to their Roles list.
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
783
c22329f379ae *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2156
diff changeset
784 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
785 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
786 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
787 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
788
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
789
4891
ad3d628e73f2 docs: Link custom authentication examples in admin guide
anatoly techtonik <techtonik@gmail.com>
parents: 4888
diff changeset
790 .. _external-authentication:
ad3d628e73f2 docs: Link custom authentication examples in admin guide
anatoly techtonik <techtonik@gmail.com>
parents: 4888
diff changeset
791
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
792 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
793 -----------------------------
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
794
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
795 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
796 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
797
3228
1b15e9eeb592 fixes to the "Using an external password validation source"...
Richard Jones <richard@users.sourceforge.net>
parents: 3130
diff changeset
798 .. 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
799 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
800 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
801 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
802 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
803
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
804 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
805 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
806 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
807 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
808 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
809 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
810
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
811 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
812
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
813 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
814 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
815 need to override the standard ``verifyPassword`` method defined in
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
816 ``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
817 following is added as ``externalpassword.py`` in the tracker ``extensions``
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
818 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
819
3228
1b15e9eeb592 fixes to the "Using an external password validation source"...
Richard Jones <richard@users.sourceforge.net>
parents: 3130
diff changeset
820 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
821 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
822
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
823 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
824 def verifyPassword(self, userid, password):
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
825 '''Look through the file, line by line, looking for a
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
826 name that matches.
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
827 '''
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
828 # 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
829 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
830
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
831 # 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
832 # 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
833 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
834
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
835 # 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
836 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
837 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
838 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
839 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
840
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
841 # 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
842 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
843
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
844 def init(instance):
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
845 instance.registerAction('login', ExternalPasswordLoginAction)
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
846
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
847 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
848 template.
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
849
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
850
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
851 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
852 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
853
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
854 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
855 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
856 and primary user group.
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
857
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
858 Roundup can use this store as its primary source of user information,
7268
91125d474c1e doc updates, normalize roundup => Roundup, add links, typo fixes
John Rouillard <rouilj@ieee.org>
parents: 7267
diff changeset
859 but it needs additional information too - email address(es), Roundup
91125d474c1e doc updates, normalize roundup => Roundup, add links, typo fixes
John Rouillard <rouilj@ieee.org>
parents: 7267
diff changeset
860 Roles, vacation flags, Roundup hyperdb item ids, etc. Also, "retired"
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
861 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
862 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
863
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
864 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
865 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
866 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
867 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
868 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
869 immediate access is needed. In short, it:
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
870
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
871 1. parses the passwd file, finding usernames, passwords and real names,
7268
91125d474c1e doc updates, normalize roundup => Roundup, add links, typo fixes
John Rouillard <rouilj@ieee.org>
parents: 7267
diff changeset
872 2. compares that list to the current Roundup user list:
1299
b2d04ce03802 Email improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 1293
diff changeset
873
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
874 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
875 b. entries with mismatching real names are *updated*
1293
Richard Jones <richard@users.sourceforge.net>
parents: 1292
diff changeset
876 c. entries only exist in the passwd file are *created*
1299
b2d04ce03802 Email improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 1293
diff changeset
877
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
878 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
879
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
880 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
881 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
882 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
883 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
884 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
885 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
886 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
887
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
888 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
889 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
890 tracker we're to work on::
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
891
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
892 import sys, os, smtplib
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
893 from roundup import instance, date
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
894
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
895 # open the tracker
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
896 tracker_home = sys.argv[1]
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
897 tracker = instance.open(tracker_home)
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
898
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
899 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
900
3228
1b15e9eeb592 fixes to the "Using an external password validation source"...
Richard Jones <richard@users.sourceforge.net>
parents: 3130
diff changeset
901 # 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
902 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
903 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
904
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
905 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
906 appear in the file)::
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
907
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
908 # 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
909 # "real" users
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
910 ignore = ['ekmmon', 'bfast', 'csrmail']
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
911
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
912 # 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
913 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
914 'cs_pool', 'anonymous', 'system_pool', 'automated']
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
915
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
916 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
917
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
918 roles = {
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
919 '501': 'User,Tech', # tech
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
920 '502': 'User', # finance
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
921 '503': 'User,CSR', # customer service reps
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
922 '504': 'User', # sales
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
923 '505': 'User', # marketing
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
924 }
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
925
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
926 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
927 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
928 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
929 now do all the work::
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
930
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
931 # open the database
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
932 db = tracker.open('admin')
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
933 try:
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
934 # 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
935 msg = []
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
936
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
937 # 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
938 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
939 if user in ignore:
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
940 # this user shouldn't appear in our tracker
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
941 continue
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
942 keep.append(user)
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
943 try:
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
944 # see if the user exists in the tracker
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
945 uid = db.user.lookup(user)
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
946
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
947 # 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
948 if real != db.user.get(uid, 'realname'):
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
949 db.user.set(uid, realname=real)
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
950 msg.append('FIX %s - %s'%(user, real))
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
951 except KeyError:
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
952 # nope, the user doesn't exist
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
953 db.user.create(username=user, realname=real,
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
954 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
955 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
956
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
957 # 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
958 # "keep" list - retire those who aren't
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
959 for uid in db.user.list():
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
960 user = db.user.get(uid, 'username')
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
961 if user not in keep:
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
962 db.user.retire(uid)
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
963 msg.append('RET %s'%user)
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
964
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
965 # 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
966 if msg:
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
967 # create the email
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
968 msg = '''Subject: %s user database maintenance
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
969
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
970 %s
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
971 '''%(db.config.TRACKER_NAME, '\n'.join(msg))
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
972
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
973 # send the email
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
974 smtp = smtplib.SMTP(db.config.MAILHOST)
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
975 addr = db.config.ADMIN_EMAIL
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
976 smtp.sendmail(addr, addr, msg)
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
977
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
978 # now we're done - commit the changes
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
979 db.commit()
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
980 finally:
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
981 # always close the database cleanly
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
982 db.close()
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
983
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
984 And that's it!
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
985
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
986
1680
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
987 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
988 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1680
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
989
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
990 A script that reads users from an LDAP store using
5367
f3b844fda420 Updated links to handle:
John Rouillard <rouilj@ieee.org>
parents: 5365
diff changeset
991 https://pypi.org/project/python-ldap/ and then compares the list to the users in the
7268
91125d474c1e doc updates, normalize roundup => Roundup, add links, typo fixes
John Rouillard <rouilj@ieee.org>
parents: 7267
diff changeset
992 Roundup user database would be pretty easy to write. You'd then have it run
1680
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
993 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
994 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
995 for more information about doing this.
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
996
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
997 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
998 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
999 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
1000 ``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
1001 ``extensions`` directory (see `using an external password validation
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1002 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
1003
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
1004 def verifyPassword(self, userid, password):
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
1005 ''' Verify the password that the user has supplied
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
1006 '''
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
1007 stored = self.db.user.get(self.userid, 'password')
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
1008 if password == stored:
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
1009 return 1
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
1010 if not password and not stored:
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
1011 return 1
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
1012 return 0
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
1013
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
1014 So you could reimplement this as something like::
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
1015
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
1016 def verifyPassword(self, userid, password):
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
1017 ''' Verify the password that the user has supplied
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
1018 '''
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
1019 # 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
1020 username = self.db.user.get(self.userid, 'username')
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
1021 # 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
1022
86cc794cc3a0 added simplistic LDAP authentication example
Richard Jones <richard@users.sourceforge.net>
parents: 1679
diff changeset
1023
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1024 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
1025 ----------------------------
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1026
6168
de9d602c8ce6 more index entries and CHANGES.txt update for them.
John Rouillard <rouilj@ieee.org>
parents: 6163
diff changeset
1027 .. index:: single: auditors; how to register (example)
de9d602c8ce6 more index entries and CHANGES.txt update for them.
John Rouillard <rouilj@ieee.org>
parents: 6163
diff changeset
1028 single: reactors; how to register (example)
de9d602c8ce6 more index entries and CHANGES.txt update for them.
John Rouillard <rouilj@ieee.org>
parents: 6163
diff changeset
1029
3830
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
1030 Preventing SPAM
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
1031 ~~~~~~~~~~~~~~~
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
1032
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
1033 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
1034 ``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
1035 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
1036 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
1037 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
1038
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
1039 from roundup.exceptions import Reject
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
1040
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
1041 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
1042 if newvalues['type'] == 'text/html':
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5268
diff changeset
1043 raise Reject('not allowed')
3830
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
1044
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
1045 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
1046 content = newvalues['content']
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
1047 if content.count('http://') > 2:
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5268
diff changeset
1048 raise Reject('not allowed')
3830
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
1049
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
1050 def init(db):
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
1051 db.file.audit('create', reject_html)
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
1052 db.msg.audit('create', reject_manylinks)
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
1053
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
1054 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
1055 need that ability::
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
1056
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
1057 if newvalues['type'].startswith('image/'):
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5268
diff changeset
1058 raise Reject('not allowed')
3830
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
1059
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3818
diff changeset
1060
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1061 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
1062 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1063
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1064 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
1065 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
1066 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
1067
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1068 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
1069
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1070 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
1071 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
1072 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
1073 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
1074 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
1075 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
1076 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
1077
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1078 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
1079 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
1080
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1081 <tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1082 <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
1083 <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
1084 </tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1085
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1086 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
1087 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
1088
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1089 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
1090 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
1091 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
1092 # 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
1093 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
1094 try:
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1095 # 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
1096 sendto = []
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1097 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
1098 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
1099 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
1100 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
1101
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1102 # 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
1103 # 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
1104 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
1105
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1106 # 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
1107 # 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
1108 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
1109 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
1110 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
1111 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
1112
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1113 # 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
1114 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
1115 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
1116 # 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
1117 # 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
1118 # 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
1119 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
1120 continue
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1121 # make sure they haven't seen the message already
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5268
diff changeset
1122 if nosyid not in seen_message:
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1123 # 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
1124 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
1125 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
1126
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1127 # 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
1128 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
1129 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
1130 else:
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1131 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
1132
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1133 # 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
1134 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
1135 # 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
1136 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
1137 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
1138
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1139 # 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
1140 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
1141
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1142 # 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
1143 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
1144
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1145 # 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
1146 cl.send_message(nodeid, msgid, note, sendto)
5248
198b6e810c67 Use Python-3-compatible 'as' syntax for except statements
Eric S. Raymond <esr@thyrsus.com>
parents: 5239
diff changeset
1147 except roundupdb.MessageSendError as message:
198b6e810c67 Use Python-3-compatible 'as' syntax for except statements
Eric S. Raymond <esr@thyrsus.com>
parents: 5239
diff changeset
1148 raise roundupdb.DetectorError(message)
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1149
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1150 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
1151 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
1152
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1153 # 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
1154 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
1155
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1156 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
1157
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1158 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
1159 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1160
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1161 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
1162 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
1163
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1164 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
1165 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
1166 template::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1167
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1168 <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
1169
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1170 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
1171
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1172 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
1173
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1174 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
1175 ...)
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1176
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1177 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
1178
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1179 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
1180 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
1181
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1182 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
1183 ``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
1184
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1185 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
1186 ''' 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
1187 property.
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1188 '''
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5268
diff changeset
1189 if 'status' not in newvalues:
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1190 return
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1191 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
1192 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
1193 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
1194 return
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1195 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
1196 if new not in ok:
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5268
diff changeset
1197 raise ValueError('Status not allowed to move from "%s" to "%s"'%(
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5268
diff changeset
1198 db.status.get(current, 'name'), db.status.get(new, 'name')))
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1199
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1200 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
1201 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
1202
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1203 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
1204 from::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1205
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1206 <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
1207 <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
1208
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1209 to::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1210
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1211 <th>Status</th>
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
1212 <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
1213 <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
1214 <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
1215 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
1216 <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
1217 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
1218 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
1219 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
1220 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
1221 </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
1222 </select>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1223 <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
1224 tal:replace="structure context/status/menu" />
1292
f7d9fefcae88 Fixes for SourceForge tracker bugs.
Richard Jones <richard@users.sourceforge.net>
parents: 1278
diff changeset
1225 </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
1226
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1227 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
1228
1262
a66dd1573ebd new example
Richard Jones <richard@users.sourceforge.net>
parents: 1255
diff changeset
1229
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1230 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
1231 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1232
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1233 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
1234 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
1235 resolved. To achieve this:
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1236
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1237 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
1238 ``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
1239 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
1240
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1241 issue = IssueClass(db, "issue",
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
1242 assignedto=Link("user"), keyword=Multilink("keyword"),
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1243 priority=Link("priority"), status=Link("status"))
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1244
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1245 to this, adding the blockers entry::
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1246
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1247 issue = IssueClass(db, "issue",
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1248 blockers=Multilink("issue"),
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
1249 assignedto=Link("user"), keyword=Multilink("keyword"),
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1250 priority=Link("priority"), status=Link("status"))
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1251
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1252 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
1253 page, using something like::
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1254
1825
fad32dafc174 Replaced all uses of the 'nowrap' attribute with its CSS equivalent:
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1817
diff changeset
1255 <th>Waiting On</th>
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1256 <td>
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1257 <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
1258 size=20)" />
3881
e7050411a774 fix documentation per [SF#731171] thanks to Forest Wilkinson
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3878
diff changeset
1259 <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
1260 property='blockers')" />
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1261 <span tal:condition="context/blockers"
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1262 tal:repeat="blk context/blockers">
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1263 <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
1264 tal:content="blk/id"></a>
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1265 </span>
3881
e7050411a774 fix documentation per [SF#731171] thanks to Forest Wilkinson
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3878
diff changeset
1266 </td>
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1267
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1268 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
1269 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
1270 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
1271 the "superseders" field.
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1272
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1273 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
1274
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1275 - 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
1276 - 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
1277
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1278 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
1279
3258
1cbde34afa77 fix to doc
Richard Jones <richard@users.sourceforge.net>
parents: 3241
diff changeset
1280
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1281 def blockresolution(db, cl, nodeid, newvalues):
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1282 ''' 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
1283 '''
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1284 if nodeid is None:
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1285 blockers = []
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1286 else:
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1287 blockers = cl.get(nodeid, 'blockers')
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1288 blockers = newvalues.get('blockers', blockers)
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1289
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1290 # 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
1291 # changed
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5268
diff changeset
1292 if not blockers or 'status' not in newvalues:
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1293 return
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1294
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1295 # get the resolved state ID
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1296 resolved_id = db.status.lookup('resolved')
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1297
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1298 # format the info
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1299 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
1300 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
1301 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
1302 if len(blockers) == 1:
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1303 s = 'issue %s is'%s
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1304 else:
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1305 s = 'issues %s are'%s
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1306
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1307 # 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
1308 if newvalues['status'] == resolved_id:
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5268
diff changeset
1309 raise ValueError("This issue can't be resolved until %s resolved."%s)
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1310
3258
1cbde34afa77 fix to doc
Richard Jones <richard@users.sourceforge.net>
parents: 3241
diff changeset
1311
1cbde34afa77 fix to doc
Richard Jones <richard@users.sourceforge.net>
parents: 3241
diff changeset
1312 def resolveblockers(db, cl, nodeid, oldvalues):
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1313 ''' 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
1314 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
1315 '''
3258
1cbde34afa77 fix to doc
Richard Jones <richard@users.sourceforge.net>
parents: 3241
diff changeset
1316 newstatus = cl.get(nodeid,'status')
1cbde34afa77 fix to doc
Richard Jones <richard@users.sourceforge.net>
parents: 3241
diff changeset
1317
1cbde34afa77 fix to doc
Richard Jones <richard@users.sourceforge.net>
parents: 3241
diff changeset
1318 # no change?
1cbde34afa77 fix to doc
Richard Jones <richard@users.sourceforge.net>
parents: 3241
diff changeset
1319 if oldvalues.get('status', None) == newstatus:
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1320 return
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1321
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1322 resolved_id = db.status.lookup('resolved')
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1323
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1324 # interesting?
3258
1cbde34afa77 fix to doc
Richard Jones <richard@users.sourceforge.net>
parents: 3241
diff changeset
1325 if newstatus != resolved_id:
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1326 return
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1327
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1328 # 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
1329 # their blockers list
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1330 issues = cl.find(blockers=nodeid)
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1331 for issueid in issues:
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1332 blockers = cl.get(issueid, 'blockers')
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1333 if nodeid in blockers:
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1334 blockers.remove(nodeid)
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1335 cl.set(issueid, blockers=blockers)
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1336
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1337 def init(db):
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1338 # 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
1339 db.issue.audit('create', blockresolution)
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1340 db.issue.audit('set', blockresolution)
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1341
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1342 # can only happen on a set
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1343 db.issue.react('set', resolveblockers)
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1344
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1345 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
1346 "detectors" directory.
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1347
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1348 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
1349 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
1350 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
1351 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
1352 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
1353
3796
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
1354 <a href="#"
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
1355 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
1356 '@sort': '-activity',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
1357 '@group': 'priority',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
1358 '@filter': 'status',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
1359 '@columns': columns_showall,
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
1360 '@search_text': '',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
1361 'status': status_notresolved,
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
1362 '@dispname': i18n.gettext('Show All'),
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
1363 })"
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
1364 i18n:translate="">Show All</a><br>
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1365
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1366 modify it to add the "blockers" info to the URL (note, both the
3590
Richard Jones <richard@users.sourceforge.net>
parents: 3582
diff changeset
1367 "@filter" *and* "blockers" values must be specified)::
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1368
3796
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
1369 <a href="#"
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
1370 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
1371 '@sort': '-activity',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
1372 '@group': 'priority',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
1373 '@filter': 'status,blockers',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
1374 '@columns': columns_showall,
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
1375 '@search_text': '',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
1376 'status': status_notresolved,
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
1377 'blockers': '-1',
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
1378 '@dispname': i18n.gettext('Show All'),
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
1379 })"
aef19fff38dd If-Modified-Since handling was broken
Richard Jones <richard@users.sourceforge.net>
parents: 3772
diff changeset
1380 i18n:translate="">Show All</a><br>
2409
Richard Jones <richard@users.sourceforge.net>
parents: 2397
diff changeset
1381
3052
230f7394cce9 fix to fix
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
1382 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
1383 be unwrapped.
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1384
1674
0807e3676133 Reflowed to 72 columns, some tidying, updating & rephrasing ..
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1671
diff changeset
1385 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
1386 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
1387 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
1388 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
1389 another issue's "blockers" property.
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1390
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
1391 Add users to the nosy list based on the keyword
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
1392 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1393
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1394 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
1395 list based
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
1396 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
1397 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
1398
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1399 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
1400 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
1401
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1402 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
1403 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
1404 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
1405 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
1406 list when a keyword is set.
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
1407
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
1408 Adding the nosy keyword list
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
1409 ::::::::::::::::::::::::::::
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
1410
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
1411 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
1412 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
1413 ``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
1414 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
1415 ``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
1416 definition of user will be::
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1417
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1418 user = Class(db, "user",
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1419 username=String(), password=Password(),
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1420 address=String(), realname=String(),
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1421 phone=String(), organisation=String(),
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1422 alternate_addresses=String(),
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1423 queries=Multilink('query'), roles=String(),
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1424 timezone=String(),
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1425 nosy_keywords=Multilink('keyword'))
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1426
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
1427 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
1428 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
1429
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
1430 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
1431 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
1432 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
1433 We can easily
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
1434 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
1435 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
1436 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
1437 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
1438 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
1439 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
1440
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1441 <tr>
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
1442 <th>Nosy Keywords</th>
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1443 <td>
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1444 <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
1445 <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
1446 </td>
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1447 </tr>
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1448
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1449
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1450 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
1451 ::::::::::::::::::::::::::::::::::::::::::::::
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1452
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1453 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
1454 the users to the nosy list when required.
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
1455 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
1456 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
1457 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
1458 ``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
1459 ``detectors/nosy_keyword_reaction.py``.
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1460 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
1461 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
1462 ``nosyreaction`` function actually sends the e-mail.
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1463 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
1464
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1465 def init(db):
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1466 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
1467 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
1468
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1469 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
1470 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
1471 ``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
1472 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
1473 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
1474 ``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
1475 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
1476 new keywords, than looping over all users,
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
1477 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
1478 ``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
1479 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
1480 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
1481 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
1482 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
1483
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1484 def update_kw_nosy(db, cl, nodeid, newvalues):
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
1485 '''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
1486 '''
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1487 # 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
1488 current = {}
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1489 if nodeid is None:
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1490 ok = ('new', 'yes')
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1491 else:
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1492 ok = ('yes',)
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1493 # 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
1494 # changed
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5268
diff changeset
1495 if 'nosy' not in newvalues:
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1496 nosy = cl.get(nodeid, 'nosy')
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1497 for value in nosy:
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5268
diff changeset
1498 if value not in current:
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1499 current[value] = 1
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1500
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1501 # if the nosy list changed in this transaction, init from the new value
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5268
diff changeset
1502 if 'nosy' in newvalues:
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1503 nosy = newvalues.get('nosy', [])
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1504 for value in nosy:
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1505 if not db.hasnode('user', value):
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1506 continue
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5268
diff changeset
1507 if value not in current:
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1508 current[value] = 1
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1509
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
1510 # add users with keyword in nosy_keywords to the nosy list
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5268
diff changeset
1511 if 'keyword' in newvalues and newvalues['keyword'] is not None:
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
1512 keyword_ids = newvalues['keyword']
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
1513 for keyword in keyword_ids:
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1514 # loop over all users,
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
1515 # 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
1516 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
1517 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
1518 found = 0
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1519 for kw in nosy_kw:
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
1520 if kw == keyword:
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1521 found = 1
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1522 if found:
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1523 current[user_id] = 1
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1524
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1525 # that's it, save off the new nosy list
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5268
diff changeset
1526 newvalues['nosy'] = list(current.keys())
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1527
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1528 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
1529
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1530 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
1531
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1532 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
1533 :::::::
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1534
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1535 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
1536
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1537 Multiple additions
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1538 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
1539 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
1540 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
1541 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
1542 of keywords, and only add users when they have indicated
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
1543 interest on a new keyword.
1808
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1544
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1545 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
1546 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
1547 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
1548
3ac35c8e1782 new example and some more installation docs
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1549 Scalability
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1550 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
1551 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
1552 many users this will be a serious performance bottleneck.
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3881
diff changeset
1553 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
1554 selected these keywords as nosy keywords. This will eliminate the
6168
de9d602c8ce6 more index entries and CHANGES.txt update for them.
John Rouillard <rouilj@ieee.org>
parents: 6163
diff changeset
1555 loop over all users. See the ``rev_multilink`` attribute to make
de9d602c8ce6 more index entries and CHANGES.txt update for them.
John Rouillard <rouilj@ieee.org>
parents: 6163
diff changeset
1556 this easier.
1559
6bfb9c9de03c added blockers customisation example to doc
Richard Jones <richard@users.sourceforge.net>
parents: 1522
diff changeset
1557
4781
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1558 Restricting updates that arrive by email
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1559 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1560
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1561 Roundup supports multiple update methods:
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1562
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1563 1. command line
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1564 2. plain email
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1565 3. pgp signed email
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1566 4. web access
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1567
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1568 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
1569 these methods. For example you can set up issues that are viewable
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1570 only by people on the nosy list. So you must prevent unauthenticated
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1571 changes to the nosy list.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1572
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1573 Since plain email can be easily forged, it does not provide sufficient
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1574 authentication in this senario.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1575
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1576 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
1577 transaction and rejects the update if it changes the nosy list.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1578
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1579 Create the detector (auditor) module and add it to the detectors
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1580 directory of your tracker::
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1581
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1582 from roundup import roundupdb, hyperdb
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1583
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1584 from roundup.mailgw import Unauthorized
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1585
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1586 def restrict_nosy_changes(db, cl, nodeid, newvalues):
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1587 '''Do not permit changes to nosy via email.'''
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1588
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5268
diff changeset
1589 if 'nosy' not in newvalues:
4781
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1590 # the nosy field has not changed so no need to check.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1591 return
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1592
5881
9938c40e03bc Add "rest" and "xmlrpc" values for database tx_Source property
John Rouillard <rouilj@ieee.org>
parents: 5759
diff changeset
1593 if db.tx_Source in ['web', 'rest', 'xmlrpc', 'email-sig-openpgp', 'cli' ]:
4781
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1594 # if the source of the transaction is from an authenticated
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1595 # source or a privileged process allow the transaction.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1596 # Other possible sources: 'email'
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1597 return
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1598
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1599 # otherwise raise an error
5248
198b6e810c67 Use Python-3-compatible 'as' syntax for except statements
Eric S. Raymond <esr@thyrsus.com>
parents: 5239
diff changeset
1600 raise Unauthorized( \
4781
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1601 'Changes to nosy property not allowed via %s for this issue.'%\
5248
198b6e810c67 Use Python-3-compatible 'as' syntax for except statements
Eric S. Raymond <esr@thyrsus.com>
parents: 5239
diff changeset
1602 tx_Source)
4781
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1603
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1604 def init(db):
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1605 ''' Install restrict_nosy_changes to run after other auditors.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1606
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1607 Allow initial creation email to set nosy.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1608 So don't execute: db.issue.audit('create', requestedbyauditor)
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1609
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1610 Set priority to 110 to run this auditor after other auditors
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1611 that can cause nosy to change.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1612 '''
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1613 db.issue.audit('set', restrict_nosy_changes, 110)
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1614
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1615 This detector (auditor) will prevent updates to the nosy field if it
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1616 arrives by email. Since it runs after other auditors (due to the
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1617 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
1618 are done by other auditors if triggered by an email.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1619
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1620 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
1621 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
1622 Read the CHANGES.txt document in the roundup source code for further
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1623 details on tx_Source.
6e9b9743de89 Implementation for:
John Rouillard <rouilj@ieee.org>
parents: 4726
diff changeset
1624
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1625 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
1626 -----------------------------------
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1627
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1628 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
1629 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1630
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2958
diff changeset
1631 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
1632
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1633 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
1634
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1635 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
1636 "issue"::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1637
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1638 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
1639 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
1640
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1641 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
1642
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1643 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
1644
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1645 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
1646 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
1647 list::
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1648
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1649 <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
1650 <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
1651 <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
1652 <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
1653 '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
1654 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
1655 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
1656 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
1657 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
1658 </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
1659 </select>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1660
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1661 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
1662 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
1663 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
1664
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1665 def assignedtoMustBeFixer(db, cl, nodeid, newvalues):
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1666 ''' 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
1667 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
1668 '''
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5268
diff changeset
1669 if 'assignedto' not in newvalues:
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1670 # 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
1671 return
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1672
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1673 # 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
1674 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
1675 if not db.security.hasPermission('Fixer', userid, cl.classname):
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5268
diff changeset
1676 raise ValueError('You do not have permission to edit %s'%cl.classname)
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1677
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1678 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
1679 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
1680 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
1681
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1682 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
1683 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
1684
3121
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
1685
1954
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
1686 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
1687 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1954
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
1688
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1689 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
1690 access, meaning they
1954
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
1691 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
1692 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
1693 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
1694 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
1695
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
1696 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
1697 ``schema.py``::
1954
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
1698
3121
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
1699 #
1954
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
1700 # New users not approved by the admin
3121
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
1701 #
1954
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
1702 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
1703 description='New user registered via web or email')
2991
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1704
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1705 # 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
1706 # and view their own
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1707 db.security.addPermissionToRole('Provisional User', 'Create', 'issue')
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1708 def own_issue(db, userid, itemid):
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1709 '''Determine whether the userid matches the creator of the issue.'''
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1710 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
1711 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
1712 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
1713 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
1714 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
1715 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
1716 db.security.addPermissionToRole('Provisional User', p)
5537
d698d3d843a9 'Provisional User' example needed to have search permissions added
John Rouillard <rouilj@ieee.org>
parents: 5367
diff changeset
1717 # This allows the interface to get the names of the properties
d698d3d843a9 'Provisional User' example needed to have search permissions added
John Rouillard <rouilj@ieee.org>
parents: 5367
diff changeset
1718 # in the issue. Used for selecting sorting and grouping
d698d3d843a9 'Provisional User' example needed to have search permissions added
John Rouillard <rouilj@ieee.org>
parents: 5367
diff changeset
1719 # on the index page.
d698d3d843a9 'Provisional User' example needed to have search permissions added
John Rouillard <rouilj@ieee.org>
parents: 5367
diff changeset
1720 p = db.security.addPermission(name='Search', klass='issue')
d698d3d843a9 'Provisional User' example needed to have search permissions added
John Rouillard <rouilj@ieee.org>
parents: 5367
diff changeset
1721 db.security.addPermissionToRole ('Provisional User', p)
d698d3d843a9 'Provisional User' example needed to have search permissions added
John Rouillard <rouilj@ieee.org>
parents: 5367
diff changeset
1722
2991
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1723
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1724 # Assign the Permissions for issue-related classes
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1725 for cl in 'file', 'msg', 'query', 'keyword':
3121
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
1726 db.security.addPermissionToRole('Provisional User', 'View', cl)
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
1727 db.security.addPermissionToRole('Provisional User', 'Edit', cl)
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
1728 db.security.addPermissionToRole('Provisional User', 'Create', cl)
2991
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1729 for cl in 'priority', 'status':
3121
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
1730 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
1731
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
1732 # 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
1733 db.security.addPermissionToRole('Provisional User', 'Web Access')
b9a55628a78d more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1734 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
1735
3260
e41e1540a287 fix provisional user so they can view their own record
Richard Jones <richard@users.sourceforge.net>
parents: 3258
diff changeset
1736 # 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
1737 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
1738 '''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
1739 return userid == itemid
e41e1540a287 fix provisional user so they can view their own record
Richard Jones <richard@users.sourceforge.net>
parents: 3258
diff changeset
1740 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
1741 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
1742 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
1743 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
1744 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
1745 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
1746
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1747 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
1748 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
1749
2921
ad4fb8a14a97 more doc updates, not so many TODOs any more
Richard Jones <richard@users.sourceforge.net>
parents: 2915
diff changeset
1750 [main]
ad4fb8a14a97 more doc updates, not so many TODOs any more
Richard Jones <richard@users.sourceforge.net>
parents: 2915
diff changeset
1751 ...
4941
b76710818d31 Roundup Tracker isssue #: 2550857
John Rouillard <rouilj@ieee.org>
parents: 4921
diff changeset
1752 new_web_user_roles = Provisional User
b76710818d31 Roundup Tracker isssue #: 2550857
John Rouillard <rouilj@ieee.org>
parents: 4921
diff changeset
1753 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
1754
a71bc3a6f433 Added 'Users may only edit their issues' customisation example.
Richard Jones <richard@users.sourceforge.net>
parents: 1952
diff changeset
1755
3126
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
1756 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
1757 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
1758
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
1759 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
1760 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
1761
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
1762 def checker(klass):
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
1763 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
1764 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
1765 return check
3126
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
1766 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
1767 p = db.security.addPermission(name='View', klass=cl,
6534
7cfb7d4fce60 Fix docs mising Search permission for example.
John Rouillard <rouilj@ieee.org>
parents: 6470
diff changeset
1768 check=checker(cl),
7cfb7d4fce60 Fix docs mising Search permission for example.
John Rouillard <rouilj@ieee.org>
parents: 6470
diff changeset
1769 description='User can view only if creator.')
3126
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
1770 db.security.addPermissionToRole('User', p)
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
1771 p = db.security.addPermission(name='Edit', klass=cl,
6534
7cfb7d4fce60 Fix docs mising Search permission for example.
John Rouillard <rouilj@ieee.org>
parents: 6470
diff changeset
1772 check=checker(cl),
7cfb7d4fce60 Fix docs mising Search permission for example.
John Rouillard <rouilj@ieee.org>
parents: 6470
diff changeset
1773 description='User can edit only if creator.')
3126
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
1774 db.security.addPermissionToRole('User', p)
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
1775 db.security.addPermissionToRole('User', 'Create', cl)
6534
7cfb7d4fce60 Fix docs mising Search permission for example.
John Rouillard <rouilj@ieee.org>
parents: 6470
diff changeset
1776 # This allows the interface to get the names of the properties
7cfb7d4fce60 Fix docs mising Search permission for example.
John Rouillard <rouilj@ieee.org>
parents: 6470
diff changeset
1777 # in the issue. Used for selecting sorting and grouping
7cfb7d4fce60 Fix docs mising Search permission for example.
John Rouillard <rouilj@ieee.org>
parents: 6470
diff changeset
1778 # on the index page.
7cfb7d4fce60 Fix docs mising Search permission for example.
John Rouillard <rouilj@ieee.org>
parents: 6470
diff changeset
1779 p = db.security.addPermission(name='Search', klass='issue')
7cfb7d4fce60 Fix docs mising Search permission for example.
John Rouillard <rouilj@ieee.org>
parents: 6470
diff changeset
1780 db.security.addPermissionToRole ('User', p)
3126
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
1781
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
1782
4300
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
1783 Moderating user registration
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
1784 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
1785
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
1786 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
1787
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
1788 1. creating a new highly-restricted user role "Pending",
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
1789 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
1790 role,
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
1791 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
1792 role using roundup.mailer
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
1793 4. edit the role to "User" for valid users.
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
1794
608919e3bbbf add another simple recipe
Richard Jones <richard@users.sourceforge.net>
parents: 4296
diff changeset
1795 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
1796 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
1797 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
1798
3126
a2889d22db4a the cgi templating code now checks item-level
Richard Jones <richard@users.sourceforge.net>
parents: 3123
diff changeset
1799
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1800 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
1801 ---------------------------------
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1802
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1803 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
1804 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1805
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1806 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
1807
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1808 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
1809
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1810 <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
1811 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
1812
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1813 "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
1814
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1815 <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
1816 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
1817
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1818 ... 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
1819
1966
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
1820 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
1821 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1966
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
1822
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
1823 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
1824 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
1825 displays the rows of data::
1966
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
1826
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
1827 <tr tal:attributes="class string:priority-${i/priority/plain}">
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
1828
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
1829 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
1830 different priorities, as follows::
1966
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
1831
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
1832 tr.priority-critical td {
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
1833 background-color: red;
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
1834 }
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
1835
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
1836 tr.priority-urgent td {
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
1837 background-color: orange;
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
1838 }
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
1839
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
1840 and so on, with far less offensive colours :)
c8d8d03b6d94 another example
Richard Jones <richard@users.sourceforge.net>
parents: 1954
diff changeset
1841
2009
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1842 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
1843 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2009
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1844
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1845 To edit the status of all items in the item index view, edit the
6329
207b0fc82fc1 Fix incorrect template (Nagy Gabor); spelling fix
John Rouillard <rouilj@ieee.org>
parents: 6293
diff changeset
1846 ``issue.index.html``:
2009
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1847
2726
aa95c79cff8b clarification
Richard Jones <richard@users.sourceforge.net>
parents: 2589
diff changeset
1848 1. add a form around the listing table (separate from the existing
aa95c79cff8b clarification
Richard Jones <richard@users.sourceforge.net>
parents: 2589
diff changeset
1849 index-page form), so at the top it reads::
2009
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1850
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1851 <form method="POST" tal:attributes="action request/classname">
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1852 <table class="list">
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1853
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1854 and at the bottom of that table::
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1855
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1856 </table>
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1857 </form
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1858
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1859 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
1860 navigation table or the subsequent form table.
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1861
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1862 2. in the display for the issue property, change::
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1863
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1864 <td tal:condition="request/show/status"
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1865 tal:content="python:i.status.plain() or default">&nbsp;</td>
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1866
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1867 to::
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1868
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1869 <td tal:condition="request/show/status"
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1870 tal:content="structure i/status/field">&nbsp;</td>
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1871
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1872 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
1873
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1874 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
1875 ``tal:repeat="i batch"``) add a new table row::
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1876
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1877 <tr>
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1878 <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
1879 <input name="@csrf" type="hidden"
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1880 tal:attributes="value python:utils.anti_csrf_nonce()">
2009
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1881 <input type="submit" value=" Save Changes ">
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1882 <input type="hidden" name="@action" value="edit">
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1883 <tal:block replace="structure request/indexargs_form" />
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1884 </td>
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1885 </tr>
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1886
5201
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1887 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
1888 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
1889 site request forgery attacks.
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1890
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1891 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
1892 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
1893 next page (the results of the editing).
2009
3594e5d2b411 added new example
Richard Jones <richard@users.sourceforge.net>
parents: 2007
diff changeset
1894
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1895
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1896 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
1897 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1898
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
1899 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
1900
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1901 <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
1902 <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
1903 <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
1904 <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
1905 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
1906 <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
1907 <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
1908 <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
1909 <td>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1910 <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
1911 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
1912 </td>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1913 </tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1914 </table>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1915
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1916
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1917 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
1918 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1919
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1920 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
1921 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
1922 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
1923 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
1924 ``@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
1925
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1926 <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
1927 <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
1928 <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
1929 <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
1930 <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
1931 </th>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1932 </tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1933 <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
1934 <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
1935 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
1936 <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
1937 <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
1938 <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
1939 <td>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1940 <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
1941 </td>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1942 </tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1943 </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
1944
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1945 <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
1946 <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
1947 <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
1948 <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
1949 </th>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1950 </tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1951 <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
1952 <tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1953 <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
1954 <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
1955 <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
1956 (<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
1957 </th>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1958 </tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1959 <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
1960 </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
1961 </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
1962 </table>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1963
3121
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
1964
2156
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1965 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
1966 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1967
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1968 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
1969 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
1970 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
1971 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
1972 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
1973
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1974 <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
1975 enctype="multipart/form-data">
5201
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1976 <input name="@csrf" type="hidden"
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1977 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
1978 <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
1979 <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
1980
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1981 <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
1982 <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
1983 <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
1984 </form>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1985
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1986 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
1987 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
1988
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
1989 <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
1990 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
1991 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
1992 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
1993
5201
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1994 <input name="@csrf" type="hidden"
a9ace22e0a2f issue 2550690 - Adding anti-csrf measures to roundup following
John Rouillard <rouilj@ieee.org>
parents: 5196
diff changeset
1995 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
1996 <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
1997 <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
1998 <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
1999 .
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
2000 .
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
2001 .
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
2002 </form>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
2003
3130
7308c3c5a943 docs editing from Jean Jordaan
Richard Jones <richard@users.sourceforge.net>
parents: 3127
diff changeset
2004 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
2005 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
2006
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
2007 <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
2008 <tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
2009 <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
2010 <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
2011 </tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
2012 <tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
2013 <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
2014 <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
2015 </tr>
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
2016 </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
2017
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
2018 ... 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
2019 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
2020
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
2021 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
2022 usually to validate user choices and determine what page is next. Now encode
7352
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2023 those actions in a new ``Action`` class (see
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2024 `defining new web actions <reference.html#defining-new-web-actions>`_)::
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
2025
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
2026 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
2027
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
2028 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
2029 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
2030 ''' 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
2031 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
2032 '''
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
2033 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
2034 if category == '-1':
4880
ca692423e401 Different approach to fix XSS in issue2550817
Ralf Schlatterbeck <rsc@runtux.com>
parents: 4790
diff changeset
2035 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
2036 return
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
2037 # 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
2038 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
2039
2915
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
2040 def init(instance):
7d97c75e7cba more docs
Richard Jones <richard@users.sourceforge.net>
parents: 2914
diff changeset
2041 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
2042
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
2043 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
2044 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
2045
d68eeb9d363f reorg of the (now quite long) examples section and add new example
Richard Jones <richard@users.sourceforge.net>
parents: 2154
diff changeset
2046
5714
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2047 Silent Submit
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2048 ~~~~~~~~~~~~~
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2049
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2050 When working on an issue, most of the time the people on the nosy list
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2051 need to be notified of changes. There are cases where a user wants to
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2052 add a comment to an issue and not bother other users on the nosy
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2053 list.
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2054 This feature is called Silent Submit because it allows the user to
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2055 silently modify an issue and not tell anyone.
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2056
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2057 There are several parts to this change. The main activity part
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2058 involves editing the stock detectors/nosyreaction.py file in your
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2059 tracker. Insert the following lines near the top of the nosyreaction
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2060 function::
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2061
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2062 # Did user click button to do a silent change?
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2063 try:
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2064 if db.web['submit'] == "silent_change":
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2065 return
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2066 except (AttributeError, KeyError) as err:
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2067 # The web attribute or submit key don't exist.
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2068 # That's fine. We were probably triggered by an email
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2069 # or cli based change.
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2070 pass
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2071
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2072 This checks the submit button to see if it is the silent type. If there
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2073 are exceptions trying to make that determination they are ignored and
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2074 processing continues. You may wonder how db.web gets set. This is done
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2075 by creating an extension. Add the file extensions/edit.py with
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2076 this content::
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2077
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2078 from roundup.cgi.actions import EditItemAction
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2079
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2080 class Edit2Action(EditItemAction):
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2081 def handle(self):
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2082 self.db.web = {} # create the dict
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2083 # populate the dict by getting the value of the submit_button
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2084 # element from the form.
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2085 self.db.web['submit'] = self.form['submit_button'].value
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2086
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2087 # call the core EditItemAction to process the edit.
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2088 EditItemAction.handle(self)
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2089
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2090 def init(instance):
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2091 '''Override the default edit action with this new version'''
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2092 instance.registerAction('edit', Edit2Action)
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2093
7268
91125d474c1e doc updates, normalize roundup => Roundup, add links, typo fixes
John Rouillard <rouilj@ieee.org>
parents: 7267
diff changeset
2094 This code is a wrapper for the Roundup EditItemAction. It checks the
5714
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2095 form's submit button to save the value element. The rest of the changes
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2096 needed for the Silent Submit feature involves editing
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2097 html/issue.item.html to add the silent submit button. In
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2098 the stock issue.item.html the submit button is on a line that contains
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2099 "submit button". Replace that line with something like the following::
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2100
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2101 <input type="submit" name="submit_button"
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2102 tal:condition="context/is_edit_ok"
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2103 value="Submit Changes">&nbsp;
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2104 <button type="submit" name="submit_button"
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2105 tal:condition="context/is_edit_ok"
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2106 title="Click this to submit but not send nosy email."
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2107 value="silent_change" i18n:translate="">
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2108 Silent Change</button>
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2109
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2110 Note the difference in the value attribute for the two submit buttons.
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2111 The value "silent_change" in the button specification must match the
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2112 string in the nosy reaction function.
a5f5c044049f Documentation additions by Tom Ekberg to add example of performing
John Rouillard <rouilj@ieee.org>
parents: 5538
diff changeset
2113
7352
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2114 Changing How the Core Code Works
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2115 ================================
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2116
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2117 Example: Changing Cache-Control headers
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2118 ---------------------------------------
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2119
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2120 The Client class in cgi/client.py has a lookup table that is used to
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2121 set the Cache-Control headers for static files. The entries in this
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2122 table are set from interfaces.py using::
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2123
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2124 from roundup.cgi.client import Client
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2125
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2126 Client.Cache_Control['text/css'] = "public, max-age=3600"
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2127 Client.Cache_Control['application/javascript'] = "public, max-age=30"
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2128 Client.Cache_Control['rss.xml'] = "public, max-age=900"
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2129 Client.Cache_Control['local.js'] = "public, max-age=7200"
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2130
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2131 In this case static files delivered using @@file will have cache
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2132 headers set. These files are searched for along the `static_files`
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2133 path in the tracker's `config.ini`. In the example above:
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2134
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2135 * a css file (e.g. @@file/style.css) will be cached for an hour
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2136 * javascript files (e.g. @@file/libraries/jquery.js) will be cached
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2137 for 30 seconds
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2138 * a file named rss.xml will be cached for 15 minutes
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2139 * a file named local.js will be cached for 2 hours
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2140
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2141 Note that a file name match overrides the mime type settings.
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2142
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2143
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2144 Example: Implement password complexity checking
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2145 -----------------------------------------------
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2146
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2147 .. index:: tracker; lib directory (example)
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2148
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2149 This example uses the zxcvbn_ module that you can place in the zxcvbn
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2150 subdirectory of your tracker's lib directory.
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2151
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2152 If you add this to the interfaces.py file in the root directory of
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2153 your tracker (same place as schema.py)::
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2154
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2155 import roundup.password as password
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2156 from roundup.exceptions import Reject
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2157 from zxcvbn import zxcvbn
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2158
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2159 # monkey patch the setPassword method with this method
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2160 # that checks password strength.
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2161 origPasswordFunc = password.Password.setPassword
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2162 def mpPasswordFunc(self, plaintext, scheme, config=None):
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2163 """ Replace the password set function with one that
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2164 verifies that the password is complex enough. It
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2165 has to be done at this point and not in an auditor
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2166 as the auditor only sees the encrypted password.
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2167 """
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2168 results = zxcvbn(plaintext)
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2169 if results['score'] < 3:
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2170 l = []
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2171 map(l.extend, [[results['feedback']['warning']], results['feedback']['suggestions']])
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2172 errormsg = " ".join(l)
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2173 raise Reject ("Password is too easy to guess. " + errormsg)
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2174 return origPasswordFunc(self, plaintext, scheme, config=config)
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2175
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2176 password.Password.setPassword = mpPasswordFunc
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2177
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2178 it replaces the setPassword method in the Password class. The new
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2179 version validates that the password is sufficiently complex. Then it
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2180 passes off the setting of password to the original method.
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2181
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2182 Example: Enhance time intervals
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2183 -------------------------------
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2184
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2185 To make the user interface easier to use, you may want to support
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2186 other forms for intervals. For example you can support an interval
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2187 like 1.5 by interpreting it the same as 1:30 (1 hour 30 minutes).
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2188 Also you can allow a bare integer (e.g. 45) as a number of minutes.
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2189
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2190 To do this we intercept the from_raw method of the Interval class in
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2191 hyperdb.py with::
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2192
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2193 import roundup.hyperdb as hyperdb
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2194 origFrom_Raw = hyperdb.Interval.from_raw
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2195
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2196 def normalizeperiod(self, value, **kw):
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2197 ''' Convert alternate time forms into standard interval format
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2198
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2199 [+-] [#y] [#m] [#w] [#d] [[[H]H:MM]:SS]
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2200
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2201 if value is float, it's hour and fractional hours
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2202 if value is integer, it's number of minutes
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2203 '''
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2204 if ":" not in value:
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2205 # Not a specified interval
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2206 # if int consider number of minutes
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2207 try:
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2208 isMinutes = int(value)
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2209 minutes = isMinutes%60
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2210 hours = (isMinutes - minutes) / 60
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2211 value = "%d:%d"%(hours,minutes)
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2212 except ValueError:
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2213 pass
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2214 # if float, consider it number of hours and fractional hours.
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2215 import math
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2216 try:
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2217 afterdecimal, beforedecimal = math.modf(float(value))
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2218 value = "%d:%d"%(beforedecimal,60*afterdecimal)
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2219 except ValueError:
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2220 pass
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2221
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2222 return origFrom_Raw(self, value, **kw)
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2223
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2224 hyperdb.Interval.from_raw = normalizeperiod
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2225
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2226 any call to convert an interval from raw form now has two simpler
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2227 (and more friendly) ways to specify common time intervals.
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2228
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2229 Example: Modifying the mail gateway
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2230 -----------------------------------
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2231
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2232 One site receives email on a main gateway. The virtual alias delivery
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2233 table on the postfix server is configured with::
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2234
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2235 test-issues@example.com roundup-test@roundup-vm.example.com
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2236 test-support@example.com roundup-test+support-a@roundup-vm.example.com
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2237 test@support.example.com roundup-test+support-b@roundup-vm.example.com
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2238
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2239 These modifications to the mail gateway for Roundup allows anonymous
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2240 submissions. It hides all of the requesters under the "support"
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2241 user. It also makes some other modifications to the mail parser
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2242 allowing keywords to be set and prefixes to be defined based on the
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2243 delivery alias.
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2244
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2245 This is the entry in interfaces.py::
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2246
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2247 import roundup.mailgw
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2248 import email.utils
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2249
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2250 class SupportTracker(object):
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2251 def __init__(self, prefix=None, keyword=None):
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2252 self.prefix = prefix
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2253 self.keyword = keyword
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2254
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2255 # Define new prefixes and keywords based on local address.
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2256 support_trackers = {
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2257 ### production instances ###
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2258
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2259 ### test instances ###
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2260 'roundup-test+support-a':
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2261 SupportTracker(prefix='Support 1', keyword='support1'),
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2262 'roundup-test+support-b':
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2263 SupportTracker(prefix='Support 2', keyword='support2'),
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2264 'roundup-test2+support-a':
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2265 SupportTracker(prefix='Support 1', keyword='support1'),
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2266 'roundup-test2+support-b':
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2267 SupportTracker(prefix='Support 2', keyword='support2'),
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2268 }
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2269
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2270 class parsedMessage(roundup.mailgw.parsedMessage):
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2271 def __init__(self, mailgw, message, support_tracker):
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2272 roundup.mailgw.parsedMessage.__init__(self, mailgw, message)
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2273 if support_tracker.prefix:
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2274 self.prefix = '%s: ' % support_tracker.prefix
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2275 else:
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2276 self.prefix = ''
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2277 self.keywords = []
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2278 if support_tracker.keyword:
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2279 try:
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2280 self.keywords = [
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2281 self.db.keyword.lookup(support_tracker.keyword)]
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2282 except KeyError:
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2283 pass
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2284 self.config.ADD_AUTHOR_TO_NOSY = 'no'
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2285 self.config.ADD_RECIPIENTS_TO_NOSY = 'no'
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2286 self.config.MAILGW_KEEP_QUOTED_TEXT = 'yes'
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2287 self.config.MAILGW_LEAVE_BODY_UNCHANGED = 'yes'
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2288 self.classname = 'issue'
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2289 self.pfxmode = 'loose'
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2290 self.sfxmode = 'none'
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2291 # set the support user id
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2292 self.fixed_author = self.db.user.lookup('support')
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2293 self.fixed_props = {
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2294 'nosy': [self.fixed_author],
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2295 'keyword': self.keywords,
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2296 }
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2297
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2298 def handle_help(self):
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2299 pass
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2300
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2301 def check_subject(self):
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2302 if not self.subject:
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2303 self.subject = 'no subject'
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2304
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2305 def rego_confirm(self):
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2306 pass
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2307
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2308 def get_author_id(self):
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2309 # force the support user to be the author
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2310 self.author = self.fixed_author
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2311
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2312 def get_props(self):
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2313 self.props = {}
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2314 if not self.nodeid:
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2315 self.props.update(self.fixed_props)
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2316 self.props['title'] = ("%s%s" % (
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2317 self.prefix, self.subject.replace('[', '(').replace(']', ')')))
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2318
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2319 def get_content_and_attachments(self):
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2320 roundup.mailgw.parsedMessage.get_content_and_attachments(self)
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2321 if not self.content:
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2322 self.content = 'no text'
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2323 intro = []
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2324 for header in ['From', 'To', 'Cc']:
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2325 for addr in self.message.getaddrlist(header):
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2326 intro.append('%s: %s' % (header, email.utils.formataddr(addr)))
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2327 intro.append('Subject: %s' % self.subject)
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2328 intro.append('\n')
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2329 self.content = '\n'.join(intro) + self.content
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2330
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2331 class MailGW(roundup.mailgw.MailGW):
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2332 def parsed_message_class(self, mailgw, message):
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2333 support_tracker = None
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2334 # The delivered-to header is unique to postfix
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2335 # it is the target address:
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2336 # roundup-test+support-a@roundup-vm.example.com
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2337 # rather than
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2338 # test-support@example.com
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2339 recipients = message.getaddrlist('delivered-to')
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2340 if recipients:
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2341 localpart = recipients[0][1].rpartition('@')[0]
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2342 support_tracker = support_trackers.get(localpart)
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2343 if support_tracker:
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2344 # parse the mesage using the parsedMessage class
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2345 # defined above.
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2346 return parsedMessage(mailgw, message, support_tracker)
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2347 else:
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2348 # parse the message normally
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2349 return roundup.mailgw.parsedMessage(mailgw, message)
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2350
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2351 This is the most complex example section. The mail gateway is also one
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2352 of the more complex subsystems in Roundup, and modifying it is not
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2353 trivial.
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2354
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2355 Other Examples
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2356 --------------
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2357
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2358 See the `rest interface documentation`_ for instructions on how to add
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2359 new rest endpoints or `change the rate limiting method`_ using interfaces.py.
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2360
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2361 Examples on the Wiki
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2362 ====================
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2363
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2364 Even more examples of customization have been contributed by
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2365 users. They can be found on the `wiki
f3c9ba5db30b split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents: 7336
diff changeset
2366 <https://wiki.roundup-tracker.org>`_.
3548
61d48244e7a8 login may now be for a single session
Richard Jones <richard@users.sourceforge.net>
parents: 3544
diff changeset
2367
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1236
diff changeset
2368 .. _`design documentation`: design.html
4325
6ec048310de7 add simple doc about translating customised tracker content
Richard Jones <richard@users.sourceforge.net>
parents: 4300
diff changeset
2369 .. _`developer's guide`: developers.html
5980
54d0080769f9 Support setting cache-control headers for static files
John Rouillard <rouilj@ieee.org>
parents: 5923
diff changeset
2370 .. _`rest interface documentation`: rest.html#programming-the-rest-api
7289
74778ed75aad Add changing rest rate limiting to interface.py section.
John Rouillard <rouilj@ieee.org>
parents: 7276
diff changeset
2371 .. _change the rate limiting method: rest.html#creating-custom-rate-limits
6160
9619d64c0351 Doc updates for customizing.txt, start of index generation
John Rouillard <rouilj@ieee.org>
parents: 6159
diff changeset
2372 .. _`directions in the rest interface documentation`: rest.html#enabling-the-rest-api
9619d64c0351 Doc updates for customizing.txt, start of index generation
John Rouillard <rouilj@ieee.org>
parents: 6159
diff changeset
2373 .. _`xmlrpc interface documentation`: xmlrpc.html#through-roundup
5980
54d0080769f9 Support setting cache-control headers for static files
John Rouillard <rouilj@ieee.org>
parents: 5923
diff changeset
2374 .. _`zxcvbn`: https://github.com/dwolfhub/zxcvbn-python
6535
47b4391e1503 Fix docs mising Search permission for example. - addition
John Rouillard <rouilj@ieee.org>
parents: 6534
diff changeset
2375
Roundup Issue Tracker: http://roundup-tracker.org/