Mercurial > p > roundup > code

annotate doc/customizing.txt @ 7357:0cb4541bad71

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