Mercurial > p > roundup > code

annotate doc/customizing.txt @ 7500:c550b338616a

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