Mercurial > p > roundup > code
annotate doc/reference.txt @ 7437:0d9f704a7ef2
Reformat inclusion of COPYING.txt into license.txt.
Include as non-literal text. This removes the need to scroll to read
the license. Also makes the hyperlinks work.
Colorize the background under the included file to allow easy
identification of part of license.txt that is from COPYING.txt like we
used to have with the literal inclusion.
Had to add raw html to create a div to add the color. Using
.. container:: didn't work since indenting .. include:: caused sphinx
to throw errors on the headers in COPYING.txt.
Reformated COPYING.txt to eliminate unwanted indentation caused by
blockquote being triggered.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Mon, 29 May 2023 20:29:04 -0400 |
| parents | b4ac699c6282 |
| children | cdb81976b8bc |
| rev | line source |
|---|---|
|
7280
2a735d785836
Added new reference doc. Starter text.
John Rouillard <rouilj@ieee.org>
parents:
diff
changeset
|
1 .. meta:: |
|
2a735d785836
Added new reference doc. Starter text.
John Rouillard <rouilj@ieee.org>
parents:
diff
changeset
|
2 :description: |
|
2a735d785836
Added new reference doc. Starter text.
John Rouillard <rouilj@ieee.org>
parents:
diff
changeset
|
3 Reference for the internals of Roundup. Includes background |
|
2a735d785836
Added new reference doc. Starter text.
John Rouillard <rouilj@ieee.org>
parents:
diff
changeset
|
4 information for cookbook and how-to examples. |
|
2a735d785836
Added new reference doc. Starter text.
John Rouillard <rouilj@ieee.org>
parents:
diff
changeset
|
5 Reference for the design and internals needed to understand |
|
2a735d785836
Added new reference doc. Starter text.
John Rouillard <rouilj@ieee.org>
parents:
diff
changeset
|
6 and extend the examples to meet new needs. |
|
2a735d785836
Added new reference doc. Starter text.
John Rouillard <rouilj@ieee.org>
parents:
diff
changeset
|
7 |
|
2a735d785836
Added new reference doc. Starter text.
John Rouillard <rouilj@ieee.org>
parents:
diff
changeset
|
8 :tocdepth: 2 |
|
2a735d785836
Added new reference doc. Starter text.
John Rouillard <rouilj@ieee.org>
parents:
diff
changeset
|
9 |
|
2a735d785836
Added new reference doc. Starter text.
John Rouillard <rouilj@ieee.org>
parents:
diff
changeset
|
10 ================= |
|
2a735d785836
Added new reference doc. Starter text.
John Rouillard <rouilj@ieee.org>
parents:
diff
changeset
|
11 Roundup Reference |
|
2a735d785836
Added new reference doc. Starter text.
John Rouillard <rouilj@ieee.org>
parents:
diff
changeset
|
12 ================= |
|
2a735d785836
Added new reference doc. Starter text.
John Rouillard <rouilj@ieee.org>
parents:
diff
changeset
|
13 |
|
7357
0cb4541bad71
add welcome preface on reorg to pages
John Rouillard <rouilj@ieee.org>
parents:
7352
diff
changeset
|
14 .. admonition:: Welcome |
|
0cb4541bad71
add welcome preface on reorg to pages
John Rouillard <rouilj@ieee.org>
parents:
7352
diff
changeset
|
15 |
|
0cb4541bad71
add welcome preface on reorg to pages
John Rouillard <rouilj@ieee.org>
parents:
7352
diff
changeset
|
16 This document used to be part of the `customization document`_. The |
|
0cb4541bad71
add welcome preface on reorg to pages
John Rouillard <rouilj@ieee.org>
parents:
7352
diff
changeset
|
17 customization document was getting large and unwieldy. It was a |
|
0cb4541bad71
add welcome preface on reorg to pages
John Rouillard <rouilj@ieee.org>
parents:
7352
diff
changeset
|
18 combination of examples and internal information that made finding |
|
0cb4541bad71
add welcome preface on reorg to pages
John Rouillard <rouilj@ieee.org>
parents:
7352
diff
changeset
|
19 information difficult. We often had questions on the mailing list that |
|
0cb4541bad71
add welcome preface on reorg to pages
John Rouillard <rouilj@ieee.org>
parents:
7352
diff
changeset
|
20 were well answered in the customization document, but finding the info |
|
0cb4541bad71
add welcome preface on reorg to pages
John Rouillard <rouilj@ieee.org>
parents:
7352
diff
changeset
|
21 was difficult. |
|
0cb4541bad71
add welcome preface on reorg to pages
John Rouillard <rouilj@ieee.org>
parents:
7352
diff
changeset
|
22 |
|
0cb4541bad71
add welcome preface on reorg to pages
John Rouillard <rouilj@ieee.org>
parents:
7352
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:
7352
diff
changeset
|
24 framework`_. Help with the reorganization is welcome. |
|
0cb4541bad71
add welcome preface on reorg to pages
John Rouillard <rouilj@ieee.org>
parents:
7352
diff
changeset
|
25 |
|
0cb4541bad71
add welcome preface on reorg to pages
John Rouillard <rouilj@ieee.org>
parents:
7352
diff
changeset
|
26 This is the document you should look at for background on a tutorial |
|
0cb4541bad71
add welcome preface on reorg to pages
John Rouillard <rouilj@ieee.org>
parents:
7352
diff
changeset
|
27 or how-to guide in the customization document. |
|
0cb4541bad71
add welcome preface on reorg to pages
John Rouillard <rouilj@ieee.org>
parents:
7352
diff
changeset
|
28 |
|
0cb4541bad71
add welcome preface on reorg to pages
John Rouillard <rouilj@ieee.org>
parents:
7352
diff
changeset
|
29 .. _customization document: customizing.html |
|
0cb4541bad71
add welcome preface on reorg to pages
John Rouillard <rouilj@ieee.org>
parents:
7352
diff
changeset
|
30 .. _diataxis framework: https://diataxis.fr/ |
|
0cb4541bad71
add welcome preface on reorg to pages
John Rouillard <rouilj@ieee.org>
parents:
7352
diff
changeset
|
31 |
|
7280
2a735d785836
Added new reference doc. Starter text.
John Rouillard <rouilj@ieee.org>
parents:
diff
changeset
|
32 .. This document borrows from the ZopeBook section on ZPT. The original is at: |
|
2a735d785836
Added new reference doc. Starter text.
John Rouillard <rouilj@ieee.org>
parents:
diff
changeset
|
33 http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx |
|
2a735d785836
Added new reference doc. Starter text.
John Rouillard <rouilj@ieee.org>
parents:
diff
changeset
|
34 |
|
2a735d785836
Added new reference doc. Starter text.
John Rouillard <rouilj@ieee.org>
parents:
diff
changeset
|
35 .. contents:: |
|
2a735d785836
Added new reference doc. Starter text.
John Rouillard <rouilj@ieee.org>
parents:
diff
changeset
|
36 :depth: 2 |
|
2a735d785836
Added new reference doc. Starter text.
John Rouillard <rouilj@ieee.org>
parents:
diff
changeset
|
37 :local: |
|
2a735d785836
Added new reference doc. Starter text.
John Rouillard <rouilj@ieee.org>
parents:
diff
changeset
|
38 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
39 Trackers in a Nutshell |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
40 ====================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
41 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
42 Trackers have the following structure: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
43 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
44 .. index:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
45 single: tracker; structure db directory |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
46 single: tracker; structure detectors directory |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
47 single: tracker; structure extensions directory |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
48 single: tracker; structure html directory |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
49 single: tracker; structure html directory |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
50 single: tracker; structure lib directory |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
51 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
52 =================== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
53 Tracker File Description |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
54 =================== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
55 config.ini Holds the basic `tracker configuration`_ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
56 schema.py Holds the `tracker schema`_ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
57 initial_data.py Holds any data to be entered into the database when the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
58 tracker is initialised (optional) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
59 interfaces.py Allows `modifying the core of Roundup`_ (optional) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
60 db/ Holds the tracker's database |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
61 db/files/ Holds the tracker's upload files and messages |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
62 db/backend_name Names the database back-end for the tracker (obsolete). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
63 Use the ``backend`` setting in the ``[rdbms]`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
64 section of ``config.ini`` instead. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
65 detectors/ `Auditors and reactors`_ for this tracker |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
66 extensions/ Additional `actions`_ and `templating utilities`_ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
67 html/ Web interface templates, images and style sheets |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
68 lib/ optional common imports for detectors and extensions |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
69 =================== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
70 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
71 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
72 .. index:: config.ini |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
73 .. index:: configuration; see config.ini |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
74 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
75 Tracker Configuration |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
76 ===================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
77 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
78 The ``config.ini`` located in your tracker home contains the basic |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
79 configuration for the web and e-mail components of Roundup's interfaces. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
80 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
81 Changes to the data captured by your tracker is controlled by the `tracker |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
82 schema`_. Some configuration is also performed using permissions - see the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
83 `security / access controls`_ section. For example, to allow users to |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
84 automatically register through the email interface, you must grant the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
85 "Anonymous" Role the "Email Access" Permission. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
86 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
87 .. index:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
88 single: config.ini; sections |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
89 see: configuration; config.ini |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
90 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
91 The following is taken from the `Python Library Reference`__ (July 18, 2018) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
92 section "ConfigParser -- Configuration file parser": |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
93 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
94 The configuration file consists of sections, led by a [section] header |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
95 and followed by name: value entries, with continuations in the style |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
96 of RFC 822 (see section 3.1.1, “LONG HEADER FIELDS”); name=value is |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
97 also accepted. Note that leading whitespace is removed from |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
98 values. The optional values can contain format strings which refer to |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
99 other values in the same section, or values in a special DEFAULT |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
100 section. Additional defaults can be provided on initialization and |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
101 retrieval. Lines beginning with '#' or ';' are ignored and may be |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
102 used to provide comments. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
103 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
104 For example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
105 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
106 [My Section] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
107 foodir = %(dir)s/whatever |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
108 dir = frob |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
109 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
110 would resolve the "%(dir)s" to the value of "dir" ("frob" in this case) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
111 resulting in "foodir" being "frob/whatever". |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
112 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
113 __ https://docs.python.org/2/library/configparser.html |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
114 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
115 Example configuration settings are below. This is a partial |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
116 list. Documentation on all the settings is included in the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
117 ``config.ini`` file. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
118 |
|
7371
a210f4437b49
Incomplete work to generate config doc from config.ini
John Rouillard <rouilj@ieee.org>
parents:
7370
diff
changeset
|
119 .. .comment out. file generation needs more work include:: tracker_config.txt |
|
a210f4437b49
Incomplete work to generate config doc from config.ini
John Rouillard <rouilj@ieee.org>
parents:
7370
diff
changeset
|
120 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
121 .. index:: config.ini; sections main |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
122 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
123 Section **main** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
124 database -- ``db`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
125 Database directory path. The path may be either absolute or relative |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
126 to the directory containig this config file. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
127 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
128 templates -- ``html`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
129 Path to the HTML templates directory. The path may be either absolute |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
130 or relative to the directory containing this config file. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
131 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
132 static_files -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
133 A list of space separated directory paths (or a single directory). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
134 These directories hold additional static files available via Web UI. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
135 These directories may contain sitewide images, CSS stylesheets etc. If |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
136 a '-' is included, the list processing ends and the TEMPLATES |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
137 directory is not searched after the specified directories. If this |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
138 option is not set, all static files are taken from the TEMPLATES |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
139 directory. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
140 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
141 admin_email -- ``roundup-admin`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
142 Email address that roundup will complain to if it runs into trouble. If |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
143 the email address doesn't contain an ``@`` part, the MAIL_DOMAIN defined |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
144 below is used. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
145 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
146 dispatcher_email -- ``roundup-admin`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
147 The 'dispatcher' is a role that can get notified of new items to the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
148 database. It is used by the ERROR_MESSAGES_TO config setting. If the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
149 email address doesn't contain an ``@`` part, the MAIL_DOMAIN defined |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
150 below is used. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
151 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
152 email_from_tag -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
153 Additional text to include in the "name" part of the From: address used |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
154 in nosy messages. If the sending user is "Foo Bar", the From: line |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
155 is usually: ``"Foo Bar" <issue_tracker@tracker.example>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
156 the EMAIL_FROM_TAG goes inside the "Foo Bar" quotes like so: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
157 ``"Foo Bar EMAIL_FROM_TAG" <issue_tracker@tracker.example>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
158 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
159 new_web_user_roles -- ``User`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
160 Roles that a user gets when they register with Web User Interface. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
161 This is a comma-separated list of role names (e.g. ``Admin,User``). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
162 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
163 new_email_user_roles -- ``User`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
164 Roles that a user gets when they register with Email Gateway. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
165 This is a comma-separated string of role names (e.g. ``Admin,User``). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
166 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
167 error_messages_to -- ``user`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
168 Send error message emails to the ``dispatcher``, ``user``, or ``both``? |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
169 The dispatcher is configured using the DISPATCHER_EMAIL setting. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
170 Allowed values: ``dispatcher``, ``user``, or ``both`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
171 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
172 html_version -- ``html4`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
173 HTML version to generate. The templates are ``html4`` by default. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
174 If you wish to make them xhtml, then you'll need to change this |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
175 var to ``xhtml`` too so all auto-generated HTML is compliant. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
176 Allowed values: ``html4``, ``xhtml`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
177 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
178 timezone -- ``0`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
179 Numeric timezone offset used when users do not choose their own |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
180 in their settings. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
181 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
182 instant_registration -- ``yes`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
183 Register new users instantly, or require confirmation via |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
184 email? |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
185 Allowed values: ``yes``, ``no`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
186 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
187 email_registration_confirmation -- ``yes`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
188 Offer registration confirmation by email or only through the web? |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
189 Allowed values: ``yes``, ``no`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
190 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
191 indexer_stopwords -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
192 Additional stop-words for the full-text indexer specific to |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
193 your tracker. See the indexer source for the default list of |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
194 stop-words (e.g. ``A,AND,ARE,AS,AT,BE,BUT,BY, ...``). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
195 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
196 umask -- ``02`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
197 Defines the file creation mode mask. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
198 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
199 csv_field_size -- ``131072`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
200 Maximum size of a csv-field during import. Roundup's export |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
201 format is a csv (comma separated values) variant. The csv |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
202 reader has a limit on the size of individual fields |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
203 starting with python 2.5. Set this to a higher value if you |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
204 get the error 'Error: field larger than field limit' during |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
205 import. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
206 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
207 .. index:: config.ini; sections tracker |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
208 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
209 Section **tracker** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
210 name -- ``Roundup issue tracker`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
211 A descriptive name for your Roundup instance. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
212 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
213 web -- ``http://host.example/demo/`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
214 The web address that the tracker is viewable at. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
215 This will be included in information sent to users of the tracker. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
216 The URL MUST include the cgi-bin part or anything else |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
217 that is required to get to the home page of the tracker. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
218 You MUST include a trailing '/' in the URL. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
219 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
220 email -- ``issue_tracker`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
221 Email address that mail to Roundup should go to. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
222 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
223 language -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
224 Default locale name for this tracker. If this option is not set, the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
225 language is determined by the environment variable LANGUAGE, LC_ALL, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
226 LC_MESSAGES, or LANG, in that order of preference. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
227 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
228 .. index:: config.ini; sections web |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
229 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
230 Section **web** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
231 allow_html_file -- ``no`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
232 Setting this option enables Roundup to serve uploaded HTML |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
233 file content *as HTML*. This is a potential security risk |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
234 and is therefore disabled by default. Set to 'yes' if you |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
235 trust *all* users uploading content to your tracker. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
236 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
237 http_auth -- ``yes`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
238 Whether to use HTTP Basic Authentication, if present. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
239 Roundup will use either the REMOTE_USER or HTTP_AUTHORIZATION |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
240 variables supplied by your web server (in that order). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
241 Set this option to 'no' if you do not wish to use HTTP Basic |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
242 Authentication in your web interface. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
243 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
244 use_browser_language -- ``yes`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
245 Whether to use HTTP Accept-Language, if present. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
246 Browsers send a language-region preference list. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
247 It's usually set in the client's browser or in their |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
248 Operating System. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
249 Set this option to 'no' if you want to ignore it. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
250 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
251 debug -- ``no`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
252 Setting this option makes Roundup display error tracebacks |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
253 in the user's browser rather than emailing them to the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
254 tracker admin."), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
255 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
256 .. index:: config.ini; sections rdbms |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
257 single: config.ini; database settings |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
258 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
259 Section **rdbms** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
260 Settings in this section are used to set the backend and configure |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
261 addition settings needed by RDBMs like SQLite, Postgresql and |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
262 MySQL backends. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
263 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
264 .. index:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
265 single: postgres; select backend in config.ini |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
266 single: mysql; select backend in config.ini |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
267 single: sqlite; select backend in config.ini |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
268 single: anydbm; select backend in config.ini |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
269 see: database; postgres |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
270 see: database; mysql |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
271 see: database; sqlite |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
272 see: database; anydbm |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
273 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
274 backend -- set to value by init |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
275 The database backend such as anydbm, sqlite, mysql or postgres. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
276 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
277 name -- ``roundup`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
278 Name of the database to use. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
279 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
280 host -- ``localhost`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
281 Database server host. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
282 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
283 port -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
284 TCP port number of the database server. Postgresql usually resides on |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
285 port 5432 (if any), for MySQL default port number is 3306. Leave this |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
286 option empty to use backend default. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
287 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
288 user -- ``roundup`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
289 Database user name that Roundup should use. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
290 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
291 password -- ``roundup`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
292 Database user password. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
293 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
294 read_default_file -- ``~/.my.cnf`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
295 Name of the MySQL defaults file. Only used in MySQL connections. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
296 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
297 read_default_group -- ``roundup`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
298 Name of the group to use in the MySQL defaults file. Only used in |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
299 MySQL connections. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
300 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
301 .. index:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
302 single: sqlite; lock timeout |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
303 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
304 sqlite_timeout -- ``30`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
305 Number of seconds to wait when the SQLite database is locked. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
306 Used only for SQLite. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
307 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
308 cache_size -- `100` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
309 Size of the node cache (in elements) used to keep most recently used |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
310 data in memory. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
311 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
312 .. index:: config.ini; sections logging |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
313 see: logging; config.ini, sections logging |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
314 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
315 Section **logging** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
316 config -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
317 Path to configuration file for standard Python logging module. If this |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
318 option is set, logging configuration is loaded from specified file; |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
319 options 'filename' and 'level' in this section are ignored. The path may |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
320 be either absolute or relative to the directory containig this config file. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
321 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
322 filename -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
323 Log file name for minimal logging facility built into Roundup. If no file |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
324 name specified, log messages are written on stderr. If above 'config' |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
325 option is set, this option has no effect. The path may be either absolute |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
326 or relative to the directory containig this config file. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
327 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
328 level -- ``ERROR`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
329 Minimal severity level of messages written to log file. If above 'config' |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
330 option is set, this option has no effect. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
331 Allowed values: ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
332 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
333 .. index:: config.ini; sections mail |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
334 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
335 Section **mail** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
336 Outgoing email options. Used for nosy messages, password reset and |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
337 registration approval requests. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
338 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
339 domain -- ``localhost`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
340 Domain name used for email addresses. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
341 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
342 host -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
343 SMTP mail host that Roundup will use to send mail |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
344 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
345 username -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
346 SMTP login name. Set this if your mail host requires authenticated access. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
347 If username is not empty, password (below) MUST be set! |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
348 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
349 password -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
350 SMTP login password. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
351 Set this if your mail host requires authenticated access. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
352 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
353 port -- default *25* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
354 SMTP port on mail host. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
355 Set this if your mail host runs on a different port. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
356 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
357 local_hostname -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
358 The fully qualified domain name (FQDN) to use during SMTP sessions. If left |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
359 blank, the underlying SMTP library will attempt to detect your FQDN. If your |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
360 mail host requires something specific, specify the FQDN to use. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
361 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
362 tls -- ``no`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
363 If your SMTP mail host provides or requires TLS (Transport Layer Security) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
364 then you may set this option to 'yes'. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
365 Allowed values: ``yes``, ``no`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
366 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
367 tls_keyfile -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
368 If TLS is used, you may set this option to the name of a PEM formatted |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
369 file that contains your private key. The path may be either absolute or |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
370 relative to the directory containig this config file. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
371 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
372 tls_certfile -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
373 If TLS is used, you may set this option to the name of a PEM formatted |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
374 certificate chain file. The path may be either absolute or relative |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
375 to the directory containig this config file. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
376 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
377 charset -- utf-8 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
378 Character set to encode email headers with. We use utf-8 by default, as |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
379 it's the most flexible. Some mail readers (eg. Eudora) can't cope with |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
380 that, so you might need to specify a more limited character set |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
381 (eg. iso-8859-1). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
382 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
383 debug -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
384 Setting this option makes Roundup to write all outgoing email messages |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
385 to this file *instead* of sending them. This option has the same effect |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
386 as environment variable SENDMAILDEBUG. Environment variable takes |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
387 precedence. The path may be either absolute or relative to the directory |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
388 containig this config file. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
389 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
390 add_authorinfo -- ``yes`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
391 Add a line with author information at top of all messages send by |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
392 Roundup. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
393 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
394 add_authoremail -- ``yes`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
395 Add the mail address of the author to the author information at the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
396 top of all messages. If this is false but add_authorinfo is true, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
397 only the name of the actor is added which protects the mail address |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
398 of the actor from being exposed at mail archives, etc. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
399 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
400 .. index:: config.ini; sections mailgw |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
401 single: mailgw; config |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
402 see: mail gateway; mailgw |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
403 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
404 Section **mailgw** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
405 Roundup Mail Gateway options |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
406 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
407 keep_quoted_text -- ``yes`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
408 Keep email citations when accepting messages. Setting this to ``no`` strips |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
409 out "quoted" text from the message. Signatures are also stripped. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
410 Allowed values: ``yes``, ``no`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
411 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
412 leave_body_unchanged -- ``no`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
413 Preserve the email body as is - that is, keep the citations *and* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
414 signatures. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
415 Allowed values: ``yes``, ``no`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
416 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
417 default_class -- ``issue`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
418 Default class to use in the mailgw if one isn't supplied in email subjects. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
419 To disable, leave the value blank. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
420 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
421 language -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
422 Default locale name for the tracker mail gateway. If this option is |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
423 not set, mail gateway will use the language of the tracker instance. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
424 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
425 subject_prefix_parsing -- ``strict`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
426 Controls the parsing of the [prefix] on subject lines in incoming emails. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
427 ``strict`` will return an error to the sender if the [prefix] is not |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
428 recognised. ``loose`` will attempt to parse the [prefix] but just |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
429 pass it through as part of the issue title if not recognised. ``none`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
430 will always pass any [prefix] through as part of the issue title. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
431 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
432 subject_suffix_parsing -- ``strict`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
433 Controls the parsing of the [suffix] on subject lines in incoming emails. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
434 ``strict`` will return an error to the sender if the [suffix] is not |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
435 recognised. ``loose`` will attempt to parse the [suffix] but just |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
436 pass it through as part of the issue title if not recognised. ``none`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
437 will always pass any [suffix] through as part of the issue title. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
438 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
439 subject_suffix_delimiters -- ``[]`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
440 Defines the brackets used for delimiting the commands suffix in a subject |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
441 line. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
442 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
443 subject_content_match -- ``always`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
444 Controls matching of the incoming email subject line against issue titles |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
445 in the case where there is no designator [prefix]. ``never`` turns off |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
446 matching. ``creation + interval`` or ``activity + interval`` will match |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
447 an issue for the interval after the issue's creation or last activity. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
448 The interval is a standard Roundup interval. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
449 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
450 subject_updates_title -- ``yes`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
451 Update issue title if incoming subject of email is different. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
452 Setting this to ``no`` will ignore the title part of |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
453 the subject of incoming email messages. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
454 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
455 refwd_re -- ``(\s*\W?\s*(fw|fwd|re|aw|sv|ang)\W)+`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
456 Regular expression matching a single reply or forward prefix |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
457 prepended by the mailer. This is explicitly stripped from the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
458 subject during parsing. Value is Python Regular Expression |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
459 (UTF8-encoded). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
460 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
461 origmsg_re -- `` ^[>|\s]*-----\s?Original Message\s?-----$`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
462 Regular expression matching start of an original message if quoted |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
463 in the body. Value is Python Regular Expression (UTF8-encoded). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
464 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
465 sign_re -- ``^[>|\s]*-- ?$`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
466 Regular expression matching the start of a signature in the message |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
467 body. Value is Python Regular Expression (UTF8-encoded). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
468 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
469 eol_re -- ``[\r\n]+`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
470 Regular expression matching end of line. Value is Python Regular |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
471 Expression (UTF8-encoded). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
472 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
473 blankline_re -- ``[\r\n]+\s*[\r\n]+`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
474 Regular expression matching a blank line. Value is Python Regular |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
475 Expression (UTF8-encoded). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
476 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
477 ignore_alternatives -- ``no`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
478 When parsing incoming mails, Roundup uses the first |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
479 text/plain part it finds. If this part is inside a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
480 multipart/alternative, and this option is set, all other |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
481 parts of the multipart/alternative are ignored. The default |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
482 is to keep all parts and attach them to the issue. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
483 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
484 .. index:: config.ini; sections php |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
485 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
486 Section **pgp** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
487 OpenPGP mail processing options |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
488 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
489 enable -- ``no`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
490 Enable PGP processing. Requires gpg. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
491 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
492 roles -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
493 If specified, a comma-separated list of roles to perform PGP |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
494 processing on. If not specified, it happens for all users. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
495 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
496 homedir -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
497 Location of PGP directory. Defaults to $HOME/.gnupg if not |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
498 specified. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
499 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
500 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
501 .. index:: config.ini; sections nosy |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
502 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
503 Section **nosy** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
504 Nosy messages sending |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
505 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
506 messages_to_author -- ``no`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
507 Send nosy messages to the author of the message. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
508 If ``yes`` is used, then messages are sent to the author |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
509 even if not on the nosy list, same for ``new`` (but only for new messages). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
510 When set to ``nosy``, the nosy list controls sending messages to the author. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
511 Allowed values: ``yes``, ``no``, ``new``, ``nosy`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
512 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
513 signature_position -- ``bottom`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
514 Where to place the email signature. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
515 Allowed values: ``top``, ``bottom``, ``none`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
516 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
517 add_author -- ``new`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
518 Does the author of a message get placed on the nosy list automatically? |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
519 If ``new`` is used, then the author will only be added when a message |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
520 creates a new issue. If ``yes``, then the author will be added on |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
521 followups too. If ``no``, they're never added to the nosy. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
522 Allowed values: ``yes``, ``no``, ``new`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
523 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
524 add_recipients -- ``new`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
525 Do the recipients (``To:``, ``Cc:``) of a message get placed on the nosy |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
526 list? If ``new`` is used, then the recipients will only be added when a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
527 message creates a new issue. If ``yes``, then the recipients will be added |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
528 on followups too. If ``no``, they're never added to the nosy. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
529 Allowed values: ``yes``, ``no``, ``new`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
530 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
531 email_sending -- ``single`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
532 Controls the email sending from the nosy reactor. If ``multiple`` then |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
533 a separate email is sent to each recipient. If ``single`` then a single |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
534 email is sent with each recipient as a CC address. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
535 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
536 max_attachment_size -- ``2147483647`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
537 Attachments larger than the given number of bytes won't be attached |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
538 to nosy mails. They will be replaced by a link to the tracker's |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
539 download page for the file. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
540 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
541 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
542 .. index:: single: roundup-admin; config.ini update |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
543 single: roundup-admin; config.ini create |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
544 single: config.ini; create |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
545 single: config.ini; update |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
546 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
547 You may generate a new default config file using the ``roundup-admin |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
548 genconfig`` command. You can generate a new config file merging in |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
549 existing settings using the ``roundup-admin updateconfig`` command. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
550 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
551 Configuration variables may be referred to in lower or upper case. In code, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
552 variables not in the "main" section are referred to using their section and |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
553 name, so "domain" in the section "mail" becomes MAIL_DOMAIN. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
554 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
555 .. index:: pair: configuration; extensions |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
556 pair: configuration; detectors |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
557 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
558 Extending the configuration file |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
559 -------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
560 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
561 You can't add new variables to the config.ini file in the tracker home but |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
562 you can add two new config.ini files: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
563 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
564 - a config.ini in the ``extensions`` directory will be loaded and attached |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
565 to the config variable as "ext". |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
566 - a config.ini in the ``detectors`` directory will be loaded and attached |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
567 to the config variable as "detectors". |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
568 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
569 For example, the following in ``detectors/config.ini``:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
570 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
571 [main] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
572 qa_recipients = email@example.com |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
573 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
574 is accessible as:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
575 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
576 db.config.detectors['QA_RECIPIENTS'] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
577 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
578 Note that the name grouping applied to the main configuration file is |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
579 applied to the extension config files, so if you instead have:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
580 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
581 [qa] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
582 recipients = email@example.com |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
583 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
584 then the above ``db.config.detectors['QA_RECIPIENTS']`` will still work. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
585 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
586 Unlike values in the tracker's main ``config.ini``, the values defined |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
587 in these config files are not validated. For example: a setting that |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
588 is supposed to be an integer value (e.g. 4) could be the word |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
589 "foo". If you are writing Python code that uses these settings, you |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
590 should expect to handle invalid values. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
591 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
592 Also, incorrect values aren't discovered until the config setting is |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
593 used. This can be long after the tracker is started and the error may |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
594 not be seen in the logs. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
595 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
596 It is possible to validate these settings. Validation involves calling |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
597 the ``update_options`` method on the configuration option. This can be |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
598 done from the ``init()`` function in the Python files implementing |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
599 extensions_ or detectors_. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
600 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
601 As an example, adding the following to an extension:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
602 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
603 from roundup.configuration import SecretMandatoryOption |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
604 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
605 def init(instance): |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
606 instance.config.ext.update_option('RECAPTCHA_SECRET', |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
607 SecretMandatoryOption,description="Secret securing reCaptcha.") |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
608 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
609 similarly for a detector:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
610 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
611 from roundup.configuration import MailAddressOption |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
612 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
613 def init(db): |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
614 try: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
615 db.config.detectors.update_option('QA_RECIPIENTS', |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
616 MailAddressOption, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
617 description="Email used for QA comment followup.") |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
618 except KeyError: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
619 # COMMENT_EMAIL setting is not found, but it's optional |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
620 # so continue |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
621 pass |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
622 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
623 will allow reading the secret from a file or append the tracker domain |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
624 to an email address if it does not have a domain. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
625 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
626 Running ``roundup-admin -i tracker_home display user1`` will validate |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
627 the settings for both config.ini`s. Otherwise detector options are not |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
628 validated until the first request to the web interface (or email |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
629 gateway). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
630 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
631 There are 4 arguments for ``update_option``: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
632 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
633 1. config setting name - string (positional, mandatory) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
634 2. option type - Option derived class from configuration.py |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
635 (positional, mandatory) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
636 3. default value - string (optional, named default) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
637 4. description - string (optional, named description) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
638 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
639 The first argument is the config setting name as described at the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
640 beginning of this section. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
641 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
642 The second argument is a class in the roundup.configuration module. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
643 There are a number of these classes: BooleanOption, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
644 IntegerNumberOption, RegExpOption.... Please see the configuration |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
645 module for all Option validators and their descriptions. You can also |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
646 define your own custom validator in `interfaces.py`_. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
647 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
648 The third and fourth arguments are strings and are optional. They are |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
649 printed if there is an error and may help the user correct the problem. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
650 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
651 .. index:: ! schema |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
652 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
653 Tracker Schema |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
654 ============== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
655 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
656 .. note:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
657 if you modify the schema, you'll most likely need to edit the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
658 `web interface`_ HTML template files and `detectors`_ to reflect |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
659 your changes. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
660 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
661 A tracker schema defines what data is stored in the tracker's database. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
662 Schemas are defined using Python code in the ``schema.py`` module of your |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
663 tracker. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
664 |
| 7359 | 665 What you can/can't do to the schema |
| 666 ----------------------------------- | |
| 667 | |
| 668 Your schema may be changed at any time before or after the tracker has been | |
| 669 initialised (or used). You may: | |
| 670 | |
| 671 **Add new properties to classes, or add whole new classes** | |
| 672 This is painless and easy to do - there are generally no repercussions | |
| 673 from adding new information to a tracker's schema. | |
| 674 | |
| 675 **Remove properties** | |
| 676 Removing properties is a little more tricky - you need to make sure that | |
| 677 the property is no longer used in the `web interface`_ *or* by the | |
| 678 detectors_. | |
| 679 | |
| 680 You must never: | |
| 681 | |
| 682 **Remove the user class** | |
| 683 This class is the only *required* class in Roundup. | |
| 684 | |
| 685 **Remove the "username", "address", "password" or "realname" user properties** | |
| 686 Various parts of Roundup require these properties. Don't remove them. | |
| 687 | |
| 688 **Change the type of a property** | |
| 689 Property types must *never* [1]_ be changed - the database simply | |
| 690 doesn't take this kind of action into account. Note that you can't | |
| 691 just remove a property and re-add it as a new type either. If you | |
| 692 wanted to make the assignedto property a Multilink, you'd need to | |
| 693 create a new property assignedto_list and remove the old assignedto | |
| 694 property. | |
| 695 | |
| 696 .. [1] If you shut down the tracker, `export the database`_, modify the | |
| 697 exported csv property data to be compatible with the new type, | |
| 698 change the property type in the schema, and finally import the | |
| 699 changed exported data, you can change the property type. It is | |
| 700 not trivial nor for the faint of heart. But it can be done. | |
| 701 | |
| 702 .. _export the database: admin_guide.html#using-roundup-admin | |
| 703 | |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
704 The ``schema.py`` and ``initial_data.py`` modules |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
705 ------------------------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
706 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
707 The schema.py module is used to define what your tracker looks like |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
708 on the inside, the schema of the tracker. It defines the Classes |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
709 and properties on each class. It also defines the security for |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
710 those Classes. The next few sections describe how schemas work |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
711 and what you can do with them. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
712 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
713 The initial_data.py module sets up the initial state of your |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
714 tracker. It’s called exactly once - by the ``roundup-admin initialise`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
715 command. See the start of the section on `database content`_ for more |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
716 info about how this works. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
717 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
718 .. index:: schema; classic - description of |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
719 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
720 The "classic" schema |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
721 -------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
722 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
723 The "classic" schema looks like this (see section `setkey(property)`_ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
724 below for the meaning of ``'setkey'`` -- you may also want to look into |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
725 the sections `setlabelprop(property)`_ and `setorderprop(property)`_ for |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
726 specifying (default) labelling and ordering of classes.):: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
727 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
728 pri = Class(db, "priority", name=String(), order=String()) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
729 pri.setkey("name") |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
730 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
731 stat = Class(db, "status", name=String(), order=String()) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
732 stat.setkey("name") |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
733 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
734 keyword = Class(db, "keyword", name=String()) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
735 keyword.setkey("name") |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
736 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
737 user = Class(db, "user", username=String(), organisation=String(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
738 password=String(), address=String(), realname=String(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
739 phone=String(), alternate_addresses=String(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
740 queries=Multilink('query'), roles=String(), timezone=String()) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
741 user.setkey("username") |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
742 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
743 msg = FileClass(db, "msg", author=Link("user"), summary=String(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
744 date=Date(), recipients=Multilink("user"), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
745 files=Multilink("file"), messageid=String(), inreplyto=String()) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
746 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
747 file = FileClass(db, "file", name=String()) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
748 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
749 issue = IssueClass(db, "issue", keyword=Multilink("keyword"), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
750 status=Link("status"), assignedto=Link("user"), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
751 priority=Link("priority")) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
752 issue.setkey('title') |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
753 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
754 .. index:: schema; allowed changes |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
755 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
756 Classes and Properties - creating a new information store |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
757 --------------------------------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
758 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
759 In the tracker above, we've defined 7 classes of information: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
760 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
761 priority |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
762 Defines the possible levels of urgency for issues. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
763 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
764 status |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
765 Defines the possible states of processing the issue may be in. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
766 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
767 keyword |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
768 Initially empty, will hold keywords useful for searching issues. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
769 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
770 user |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
771 Initially holding the "admin" user, will eventually have an entry |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
772 for all users using Roundup. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
773 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
774 msg |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
775 Initially empty, will hold all e-mail messages sent to or |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
776 generated by Roundup. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
777 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
778 file |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
779 Initially empty, will hold all files attached to issues. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
780 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
781 issue |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
782 Initially empty, this is where the issue information is stored. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
783 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
784 We define the "priority" and "status" classes to allow two things: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
785 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
786 1. reduction in the amount of information stored on the issue |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
787 2. more powerful, accurate searching of issues by priority and status |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
788 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
789 By only requiring a link on the issue (which is stored as a single |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
790 number) we reduce the chance that someone mis-types a priority or |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
791 status - or simply makes a new one up. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
792 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
793 Class names are used to access items of that class in the `REST api`_ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
794 interface. The classic tracker was created before the REST interface |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
795 was added. It uses the single form (i.e. issue and user not issues and |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
796 users) for its classes. Most REST documentation suggests using plural |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
797 forms. However, to make your API consistent, use singular forms for |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
798 classes that you add. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
799 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
800 Class and Items |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
801 ~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
802 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
803 A Class defines a particular class (or type) of data that will be stored |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
804 in the database. A class comprises one or more properties, which gives |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
805 the information about the class items. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
806 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
807 The actual data entered into the database, using ``class.create()``, are |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
808 called items. They have a special immutable property called ``'id'``. We |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
809 sometimes refer to this as the *itemid*. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
810 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
811 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
812 .. index:: schema; property types |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
813 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
814 Properties |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
815 ~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
816 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
817 A Class is comprised of one or more properties of the following types: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
818 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
819 String |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
820 properties are for storing arbitrary-length strings. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
821 Password |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
822 properties are for storing encoded arbitrary-length strings. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
823 The default encoding is defined on the ``roundup.password.Password`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
824 class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
825 Date |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
826 properties store date-and-time stamps. Their values are Timestamp |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
827 objects. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
828 Interval |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
829 properties store time periods rather than absolute dates. For |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
830 example 2 hours. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
831 Integer |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
832 properties store integer values. (Number can store real/float values.) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
833 Number |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
834 properties store numeric values. There is an option to use |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
835 double-precision floating point numbers. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
836 Boolean |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
837 properties store on/off, yes/no, true/false values. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
838 Link |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
839 properties refers to a single other item selected from a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
840 specified class. The class is part of the property; the value is an |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
841 integer, the id of the chosen item. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
842 Multilink |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
843 properties refer to possibly many items in a specified |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
844 class. The value is a list of integers. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
845 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
846 Properties can have additional attributes to change the default |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
847 behaviour: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
848 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
849 .. index:: triple: schema; property attributes; required |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
850 triple: schema; property attributes; default_value |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
851 triple: schema; property attributes; quiet |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
852 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
853 * All properties support the following attributes: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
854 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
855 - ``required``: see `design documentation`_. Adds the property to |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
856 the list returned by calling get_required_props for the class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
857 - ``default_value``: see `design documentation`_ Sets the default |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
858 value if the property is not set. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
859 - ``quiet``: see `design documentation`_. Suppresses user visible |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
860 to changes to this property. The property change is not reported: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
861 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
862 - in the change feedback/confirmation message in the web |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
863 interface |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
864 - the property change section of the nosy email |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
865 - the web history at the bottom of an item's page |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
866 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
867 This can be used to store state of the user interface (e.g. the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
868 names of elements that are collapsed or hidden from the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
869 user). Making properties that are updated as an indirect result of |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
870 a user's change (e.g. updating a blockers property, counting |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
871 number of times an issue was reopened or reassigned etc.) should |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
872 not be displayed to the user as they can be confusing. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
873 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
874 .. index:: triple: schema; property attributes; indexme |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
875 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
876 * String properties can have an ``indexme`` attribute that defines if the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
877 property should be part of the full text index. The default is 'no' but this |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
878 can be set to 'yes' to allow a property's contents to be in the full |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
879 text index. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
880 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
881 .. index:: triple: schema; property attributes; use_double |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
882 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
883 * Number properties can have a ``use_double`` attribute that, when set |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
884 to ``True``, will use double precision floating point in the database. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
885 * Link and Multilink properties can have several attributes: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
886 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
887 .. index:: triple: schema; property attributes; do_journal |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
888 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
889 - ``do_journal``: By default, every change of a link property is |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
890 recorded in the item being linked to (or being unlinked). A typical |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
891 use-case for setting ``do_journal='no'`` would be to turn off |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
892 journalling of nosy list, message author and message recipient link |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
893 and unlink events to prevent the journal from clogged with these |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
894 events. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
895 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
896 .. index:: triple: schema; property attributes; try_id_parsing |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
897 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
898 - ``try_id_parsing`` is turned on by default. If entering a number |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
899 into a Link or Multilink field, Roundup interprets this number as an |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
900 ID of the item to link to. Sometimes items can have numeric names |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
901 (like, e.g., product codes). For these Roundup needs to match the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
902 numeric name and should never match an ID. In this case you can set |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
903 ``try_id_parsing='no'``. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
904 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
905 .. index:: triple: schema; property attributes; rev_multilink |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
906 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
907 - The ``rev_multilink`` option takes a property name to be inserted |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
908 into the linked-to class. This property is a Multilink property that |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
909 links back to the current class. The new Multilink is read-only (it |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
910 is automatically modified if the Link or Multilink property defining |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
911 it is modified). The new property can be used in normal searches |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
912 using the "filter" method of the Class. This means it can be used |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
913 like other Multilink properties when searching (in an index |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
914 template) or via the REST and XMLRPC APIs. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
915 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
916 As a example, suppose you want to group multiple issues into a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
917 super issue. Each issue can be part of only one super issue. It is |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
918 inefficient to find all of the issues that are part of the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
919 super issue by searching through all issues in the system looking |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
920 at the part_of link property. To make this more efficient, you |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
921 can declare an issue's part_of property as:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
922 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
923 issue = IssueClass(db, "issue", |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
924 ... |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
925 part_of = Link("issue", rev_multilink="components"), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
926 ... ) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
927 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
928 This automatically creates the ``components`` multilink on the issue |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
929 class. The ``components`` multilink is never explicitly declared in |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
930 the issue class, but it has the same effect as though you had |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
931 declared the class as:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
932 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
933 issue = IssueClass(db, "issue", |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
934 ... |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
935 part_of = Link("issue"), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
936 components = Multilink("issue"), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
937 ... ) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
938 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
939 Then wrote a detector to update the components property on the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
940 corresponding issue. Writing this detector can be tricky. There is |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
941 one other difference, you can not explicitly set/modify the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
942 ``components`` multilink. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
943 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
944 The effect of setting ``part_of = 3456`` on issue1234 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
945 automatically adds "1234" to the ``components`` property on |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
946 issue3456. You can search the ``components`` multilink just like a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
947 regular multilink, but you can't explicitly assign to it. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
948 Another difference of reverse multilinks to normal multilinks |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
949 is that when a linked node is retired, the node vanishes from the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
950 multilink, e.g. in the example above, if an issue with ``part_of`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
951 set to another issue is retired this issue vanishes from the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
952 ``components`` multilink of the other issue. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
953 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
954 You can also link between different classes. So you can modify |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
955 the issue definition to include:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
956 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
957 issue = IssueClass(db, "issue", |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
958 ... |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
959 assigned_to = Link("user", rev_multilink="responsibleFor"), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
960 ... ) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
961 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
962 This makes it easy to list all issues that the user is responsible |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
963 for (aka assigned_to). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
964 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
965 .. index:: triple: schema; property attributes; msg_header_property |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
966 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
967 - The ``msg_header_property`` is used by the mail gateway when sending |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
968 out messages. When a link or multilink property of an issue changes, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
969 Roundup creates email headers of the form:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
970 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
971 X-Roundup-issue-prop: value |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
972 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
973 where ``value`` is the ``name`` property for the linked item(s). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
974 For example, if you have a multilink for attached_files in your |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
975 issue, you will see a header:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
976 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
977 X-Roundup-issue-attached_files: MySpecialFile.doc, HisResume.txt |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
978 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
979 when the class for attached files is defined as:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
980 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
981 file = FileClass(db, "file", name=String()) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
982 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
983 ``MySpecialFile.doc`` is the name for the file object. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
984 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
985 If you have an ``assigned_to`` property in your issue class that |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
986 links to the user class and you want to add a header:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
987 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
988 X-Roundup-issue-assigned_to: ... |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
989 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
990 so that the mail recipients can filter emails where |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
991 ``X-Roundup-issue-assigned_to: name`` that contains their |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
992 username. The user class is defined as:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
993 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
994 user = Class(db, "user", |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
995 username=String(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
996 password=Password(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
997 address=String(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
998 realname=String(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
999 phone=String(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1000 organisation=String(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1001 alternate_addresses=String(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1002 queries=Multilink('query'), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1003 roles=String(), # comma-separated string of Role names |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1004 timezone=String()) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1005 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1006 Because there is no ``name`` parameter for the user class, there |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1007 will be no header. However setting:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1008 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1009 assigned_to=Link("user", msg_header_property="username") |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1010 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1011 will make the mail gateway generate an ``X-Roundup-issue-assigned_to`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1012 using the username property of the linked user. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1013 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1014 Assume assigned_to for an issue is linked to the user with |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1015 username=joe_user, setting:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1016 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1017 msg_header_property="username" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1018 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1019 for the assigned_to property will generated message headers of the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1020 form:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1021 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1022 X-Roundup-issue-assigned_to: joe_user |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1023 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1024 for emails sent on issues where joe_user has been assigned to the issue. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1025 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1026 If this property is set to the empty string "", it will prevent |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1027 the header from being generated on outgoing mail. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1028 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1029 .. index:: triple: schema; class property; creator |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1030 triple: schema; class property; creation |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1031 triple: schema; class property; actor |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1032 triple: schema; class property; activity |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1033 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1034 All Classes automatically have a number of properties by default: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1035 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1036 *creator* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1037 Link to the user that created the item. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1038 *creation* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1039 Date the item was created. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1040 *actor* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1041 Link to the user that last modified the item. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1042 *activity* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1043 Date the item was last modified. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1044 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1045 |
| 7359 | 1046 .. index:: double: schema; class methods |
| 1047 | |
| 1048 Methods | |
| 1049 ~~~~~~~ | |
| 1050 | |
| 1051 All classes have the following methods. | |
| 1052 | |
| 1053 .. index:: triple: schema; class method; setkey | |
| 1054 | |
| 1055 setkey(property) | |
| 1056 :::::::::::::::: | |
| 1057 | |
| 1058 .. index:: roundup-admin; setting assignedto on an issue | |
| 1059 | |
| 1060 Select a String property of the class to be the key property. The key | |
| 1061 property must be unique, and allows references to the items in the class | |
| 1062 by the content of the key property. That is, we can refer to users by | |
| 1063 their username: for example, let's say that there's an issue in Roundup, | |
| 1064 issue 23. There's also a user, richard, who happens to be user 2. To | |
| 1065 assign an issue to him, we could do either of:: | |
| 1066 | |
| 1067 roundup-admin set issue23 assignedto=2 | |
| 1068 | |
| 1069 or:: | |
| 1070 | |
| 1071 roundup-admin set issue23 assignedto=richard | |
| 1072 | |
| 1073 Note, the same thing can be done in the web and e-mail interfaces. | |
| 1074 | |
| 1075 .. index:: triple: schema; class method; setlabelprop | |
| 1076 | |
| 1077 setlabelprop(property) | |
| 1078 :::::::::::::::::::::: | |
| 1079 | |
| 1080 Select a property of the class to be the label property. The label | |
| 1081 property is used whereever an item should be uniquely identified, e.g., | |
| 1082 when displaying a link to an item. If setlabelprop is not specified for | |
| 1083 a class, the following values are tried for the label: | |
| 1084 | |
| 1085 * the key of the class (see the `setkey(property)`_ section above) | |
| 1086 * the "name" property | |
| 1087 * the "title" property | |
| 1088 * the first property from the sorted property name list | |
| 1089 | |
| 1090 So in most cases you can get away without specifying setlabelprop | |
| 1091 explicitly. | |
| 1092 | |
| 1093 You should make sure that users have View access to this property or | |
| 1094 the id property for a class. If the property can not be viewed by a | |
| 1095 user, looping over items in the class (e.g. messages attached to an | |
| 1096 issue) will not work. | |
| 1097 | |
| 1098 .. index:: triple: schema; class method; setorderprop | |
| 1099 | |
| 1100 setorderprop(property) | |
| 1101 :::::::::::::::::::::: | |
| 1102 | |
| 1103 Select a property of the class to be the order property. The order | |
| 1104 property is used whenever using a default sort order for the class, | |
| 1105 e.g., when grouping or sorting class A by a link to class B in the user | |
| 1106 interface, the order property of class B is used for sorting. If | |
| 1107 setorderprop is not specified for a class, the following values are tried | |
| 1108 for the order property: | |
| 1109 | |
| 1110 * the property named "order" | |
| 1111 * the label property (see `setlabelprop(property)`_ above) | |
| 1112 | |
| 1113 So in most cases you can get away without specifying setorderprop | |
| 1114 explicitly. | |
| 1115 | |
| 1116 .. index:: triple: schema; class method; create | |
| 1117 | |
| 1118 create(information) | |
| 1119 ::::::::::::::::::: | |
| 1120 | |
| 1121 Create an item in the database. This is generally used to create items | |
|
7369
15bb0d177632
use glossary directive and link some terms to the glossary.
John Rouillard <rouilj@ieee.org>
parents:
7368
diff
changeset
|
1122 in the :term:`definitional class` like "priority" and "status". |
| 7359 | 1123 |
| 1124 IssueClass | |
| 1125 ~~~~~~~~~~ | |
| 1126 | |
| 1127 IssueClasses automatically include the "messages", "files", "nosy", and | |
| 1128 "superseder" properties. | |
| 1129 | |
| 1130 The messages and files properties list the links to the messages and | |
| 1131 files related to the issue. The nosy property is a list of links to | |
| 1132 users who wish to be informed of changes to the issue - they get "CC'ed" | |
| 1133 e-mails when messages are sent to or generated by the issue. The nosy | |
| 1134 reactor (in the ``'detectors'`` directory) handles this action. The | |
| 1135 superseder link indicates an issue which has superseded this one. | |
| 1136 | |
| 1137 They also have the dynamically generated "creation", "activity" and | |
| 1138 "creator" properties. | |
| 1139 | |
| 1140 The value of the "creation" property is the date when an item was | |
| 1141 created, and the value of the "activity" property is the date when any | |
| 1142 property on the item was last edited (equivalently, these are the dates | |
| 1143 on the first and last records in the item's journal). The "creator" | |
| 1144 property holds a link to the user that created the issue. | |
| 1145 | |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1146 .. index:: triple: schema; class property; content |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1147 triple: schema; class property; type |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1148 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1149 FileClass |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1150 ~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1151 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1152 FileClasses save their "content" attribute off in a separate file from |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1153 the rest of the database. This reduces the number of large entries in |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1154 the database, which generally makes databases more efficient, and also |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1155 allows us to use command-line tools to operate on the files. They are |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1156 stored in the files sub-directory of the ``'db'`` directory in your |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1157 tracker. FileClasses also have a "type" attribute to store the MIME |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1158 type of the file. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1159 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1160 Roundup by default considers the contents of the file immutable. This |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1161 is to assist in maintaining an accurate record of correspondence. The |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1162 distributed tracker templates do not enforce this. So if you have |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1163 access to the Roundup tracker directory, you can edit the files (make |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1164 sure to preserve mode, owner and group) to remove information (e.g. if |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1165 somebody includes a password or you need to redact proprietary |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1166 information). Obviously the journal for the message/file will not |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1167 report that the file has changed. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1168 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1169 Best practice is to remove offending material and leave a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1170 placeholder. E.G. replace a password with the text:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1171 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1172 [password has been deleted 2020-12-02 --myname] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1173 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1174 If you need to delete an entire file, replace the file contents with:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1175 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1176 [file contents deleted due to spam 2020-10-21 --myname] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1177 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1178 rather than deleting the file. If you actually delete the file Roundup |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1179 will report an error to the user and email the administrator. If you |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1180 empty the file, a user downloading the file using the direct URL |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1181 (e.g. ``tracker/msg22``) may be confused and think something is broken |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1182 when they receive an empty file. Retiring a file/msg does not prevent |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1183 access to the file using the direct URL. Retiring an item only removes |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1184 it when requesting a list of all items in the class. If you are |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1185 replacing the contents, you probably want to change the content type |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1186 of the file. E.G. from ``image/jpeg`` to ``text/plain``. You can do |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1187 this easily through the web interface, or using the ``roundup-admin`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1188 command line interface. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1189 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1190 You can also change the contents of a file or message using the REST |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1191 interface. Note that this will NOT result in an entry in the journal, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1192 so again it allows a silent change. To do this you need to make two |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1193 rest requests. An example using curl is:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1194 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1195 $ curl -u demo:demo -s |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1196 -H "X-requested-with: rest" \ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1197 -H "Referer: https://tracker.example.com/demo/" \ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1198 -X GET \ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1199 https://tracker.example.com/demo/rest/data/file/30/content |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1200 { |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1201 "data": { |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1202 "id": "30", |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1203 "type": "<class 'str'>", |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1204 "link": "https://tracker.example.com/demo/rest/data/file/30/content", |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1205 "data": "hello3", |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1206 "@etag": "\"3f2f8063dbce5b6bd43567e6f4f3c671\"" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1207 } |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1208 } |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1209 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1210 using the etag, overwrite the content with:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1211 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1212 $ curl -u demo:demo -s |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1213 -H "X-requested-with: rest" \ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1214 -H "Referer: https://tracker.example.com/demo/" \ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1215 -H 'If-Match: "3f2f8063dbce5b6bd43567e6f4f3c671"' \ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1216 -X PUT \ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1217 -F "data=@hello" \ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1218 https://tracker.example.com/demo/rest/data/file/30/content |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1219 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1220 where ``hello`` is a file on local disk. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1221 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1222 You can enforce immutability in your tracker by adding an auditor (see |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1223 detectors_) for the file/msg class that rejects changes to the content |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1224 property. The auditor could also add a journal entry so that a change |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1225 via the Roundup mechanism is reported. Using a mixin (see: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1226 https://wiki.roundup-tracker.org/MixinClassFileClass) to augment the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1227 file class allows for other possibilities including signing the file, or |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1228 recording a checksum in the database and validating the file contents |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1229 at the time it gets read. This allows detection of changes done on the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1230 filesystem outside of the Roundup mechanism. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1231 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1232 .. index:: triple: schema; class property; messages |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1233 triple: schema; class property; files |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1234 triple: schema; class property; nosy |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1235 triple: schema; class property; superseder |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1236 |
| 7359 | 1237 .. index:: schema; item ordering |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1238 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1239 A note about ordering |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1240 ~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1241 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1242 When we sort items in the hyperdb, we use one of a number of methods, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1243 depending on the properties being sorted on: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1244 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1245 1. If it's a String, Integer, Number, Date or Interval property, we |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1246 just sort the scalar value of the property. Strings are sorted |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1247 case-sensitively. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1248 2. If it's a Link property, we sort by either the linked item's "order" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1249 property (if it has one) or the linked item's "id". |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1250 3. Mulitlinks sort similar to #2, but we start with the first Multilink |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1251 list item, and if they're the same, we sort by the second item, and |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1252 so on. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1253 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1254 Note that if an "order" property is defined on a Class that is used for |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1255 sorting, all items of that Class *must* have a value against the "order" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1256 property, or sorting will result in random ordering. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1257 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1258 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1259 Examples of adding to your schema |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1260 --------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1261 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1262 Some examples are in the :ref:`CustomExamples` section. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1263 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1264 Also you can start with `Roundup wiki CategorySchema`_ to see a list |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1265 of additional examples of how schemas can be customised to add new |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1266 functionality. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1267 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1268 .. _Roundup wiki CategorySchema: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1269 https://wiki.roundup-tracker.org/CategorySchema |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1270 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1271 .. index:: !detectors |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1272 .. _detectors: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1273 .. _Auditors and reactors: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1274 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1275 Detectors - adding behaviour to your tracker |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1276 ============================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1277 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1278 Detectors are initialised every time you open your tracker database, so |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1279 you're free to add and remove them any time, even after the database is |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1280 initialised via the ``roundup-admin initialise`` command. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1281 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1282 The detectors in your tracker fire *before* (**auditors**) and *after* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1283 (**reactors**) changes to the contents of your database. They are Python |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1284 modules that sit in your tracker's ``detectors`` directory. You will |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1285 have some installed by default - have a look. You can write new |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1286 detectors or modify the existing ones. The existing detectors installed |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1287 for you are: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1288 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1289 .. index:: detectors; installed |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1290 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1291 **nosyreaction.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1292 This provides the automatic nosy list maintenance and email sending. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1293 The nosy reactor (``nosyreaction``) fires when new messages are added |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1294 to issues. The nosy auditor (``updatenosy``) fires when issues are |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1295 changed, and figures out what changes need to be made to the nosy list |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1296 (such as adding new authors, etc.) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1297 **statusauditor.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1298 This provides the ``chatty`` auditor which changes the issue status |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1299 from ``unread`` or ``closed`` to ``chatting`` if new messages appear. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1300 It also provides the ``presetunread`` auditor which pre-sets the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1301 status to ``unread`` on new items if the status isn't explicitly |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1302 defined. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1303 **messagesummary.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1304 Generates the ``summary`` property for new messages based on the message |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1305 content. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1306 **userauditor.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1307 Verifies the content of some of the user fields (email addresses and |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1308 roles lists). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1309 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1310 If you don't want this default behaviour, you're completely free to change |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1311 or remove these detectors. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1312 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1313 See the detectors section in the `design document`__ for details of the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1314 interface for detectors. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1315 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1316 __ design.html |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1317 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1318 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1319 .. index:: detectors; writing api |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1320 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1321 Detector API |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1322 ------------ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1323 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1324 .. index:: pair: detectors; auditors |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1325 single: auditors; function signature |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1326 single: auditors; defining |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1327 single: auditors; arguments |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1328 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1329 Auditors are called with the arguments:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1330 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1331 audit(db, cl, itemid, newdata) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1332 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1333 where ``db`` is the database, ``cl`` is an instance of Class or |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1334 IssueClass within the database, and ``newdata`` is a dictionary mapping |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1335 property names to values. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1336 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1337 For a ``create()`` operation, the ``itemid`` argument is None and |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1338 newdata contains all of the initial property values with which the item |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1339 is about to be created. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1340 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1341 For a ``set()`` operation, newdata contains only the names and values of |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1342 properties that are about to be changed. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1343 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1344 For a ``retire()`` or ``restore()`` operation, newdata is None. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1345 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1346 .. index:: pair: detectors; reactor |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1347 single: reactors; function signature |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1348 single: reactors; defining |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1349 single: reactors; arguments |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1350 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1351 Reactors are called with the arguments:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1352 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1353 react(db, cl, itemid, olddata) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1354 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1355 where ``db`` is the database, ``cl`` is an instance of Class or |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1356 IssueClass within the database, and ``olddata`` is a dictionary mapping |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1357 property names to values. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1358 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1359 For a ``create()`` operation, the ``itemid`` argument is the id of the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1360 newly-created item and ``olddata`` is None. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1361 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1362 For a ``set()`` operation, ``olddata`` contains the names and previous |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1363 values of properties that were changed. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1364 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1365 For a ``retire()`` or ``restore()`` operation, ``itemid`` is the id of |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1366 the retired or restored item and ``olddata`` is None. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1367 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1368 .. index:: detectors; additional |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1369 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1370 Additional Detectors Ready For Use |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1371 ---------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1372 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1373 Sample additional detectors that have been found useful will appear in |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1374 the ``'detectors'`` directory of the Roundup distribution. If you want |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1375 to use one, copy it to the ``'detectors'`` of your tracker instance: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1376 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1377 **irker.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1378 This detector sends notification on IRC through an irker daemon |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1379 (http://www.catb.org/esr/irker/) when issues are created or messages |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1380 are added. In order to use it you need to install irker, start the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1381 irkerd daemon, and add an ``[irker]`` section in ``detectors/config.ini`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1382 that contains a comma-separated list of channels where the messages should |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1383 be sent, e.g. ``channels = irc://chat.freenode.net/channelname``. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1384 **newissuecopy.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1385 This detector sends an email to a team address whenever a new issue is |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1386 created. The address is hard-coded into the detector, so edit it |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1387 before you use it (look for the text 'team@team.host') or you'll get |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1388 email errors! |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1389 **creator_resolution.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1390 Catch attempts to set the status to "resolved" - if the assignedto |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1391 user isn't the creator, then set the status to "confirm-done". Note that |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1392 "classic" Roundup doesn't have that status, so you'll have to add it. If |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1393 you don't want to though, it'll just use "in-progress" instead. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1394 **email_auditor.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1395 If a file added to an issue is of type message/rfc822, we tack on the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1396 extension .eml. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1397 The reason for this is that Microsoft Internet Explorer will not open |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1398 things with a .eml attachment, as they deem it 'unsafe'. Worse yet, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1399 they'll just give you an incomprehensible error message. For more |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1400 information, see the detector code - it has a lengthy explanation. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1401 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1402 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1403 .. index:: auditors; rules for use |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1404 single: reactors; rules for use |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1405 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1406 Auditor or Reactor? |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1407 ------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1408 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1409 Generally speaking, the following rules should be observed: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1410 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1411 **Auditors** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1412 Are used for `vetoing creation of or changes to items`_. They might |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1413 also make automatic changes to item properties. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1414 **Reactors** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1415 Detect changes in the database and react accordingly. They should avoid |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1416 making changes to the database where possible, as this could create |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1417 detector loops. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1418 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1419 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1420 Vetoing creation of or changes to items |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1421 --------------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1422 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1423 Auditors may raise the ``Reject`` exception to prevent the creation of |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1424 or changes to items in the database. The mail gateway, for example, will |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1425 not attach files or messages to issues when the creation of those files or |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1426 messages are prevented through the ``Reject`` exception. It'll also not create |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1427 users if that creation is ``Reject``'ed too. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1428 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1429 To use, simply add at the top of your auditor:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1430 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1431 from roundup.exceptions import Reject |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1432 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1433 And then when your rejection criteria have been detected, simply:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1434 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1435 raise Reject('Description of error') |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1436 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1437 Error messages raised with ``Reject`` automatically have any HTML content |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1438 escaped before being displayed to the user. To display an error message to the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1439 user without performing any HTML escaping the ``RejectRaw`` should be used. All |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1440 security implications should be carefully considering before using |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1441 ``RejectRaw``. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1442 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1443 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1444 Generating email from Roundup |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1445 ----------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1446 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1447 The module ``roundup.mailer`` contains most of the nuts-n-bolts required |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1448 to generate email messages from Roundup. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1449 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1450 In addition, the ``IssueClass`` methods ``nosymessage()`` and |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1451 ``send_message()`` are used to generate nosy messages, and may generate |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1452 messages which only consist of a change note (ie. the message id parameter |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1453 is not required - this is referred to as a "System Message" because it |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1454 comes from "the system" and not a user). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1455 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1456 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1457 .. index:: extensions |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1458 .. index:: extensions; add python functions to tracker |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1459 .. _extensions: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1460 .. _actions: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1461 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1462 Extensions - adding capabilities to your tracker |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1463 ================================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1464 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1465 While detectors_ add new behavior by reacting to changes in tracked |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1466 objects, `extensions` add new actions and utilities to Roundup, which |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1467 are mostly used to enhance web interface. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1468 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1469 You can create an extension by creating Python file in your tracker |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1470 ``extensions`` directory. All files from this dir are loaded when |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1471 tracker instance is created, at which point it calls ``init(instance)`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1472 from each file supplying itself as a first argument. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1473 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1474 Note that at this point web interface is not loaded, but extensions still |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1475 can register actions for in tracker instance. This may be fixed in |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1476 Roundup 1.6 by introducing ``init_web(client)`` callback or a more |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1477 flexible extension point mechanism. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1478 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1479 * ``instance.registerUtil`` is used for adding `templating utilities`_ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1480 (see `adding a time log to your issues |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1481 <customizing.html#adding-a-time-log-to-your-issues-4>`_ for an example) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1482 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1483 * ``instance.registerAction`` is used to add more actions to instance |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1484 and to web interface. See `Defining new web actions`_ for details. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1485 Generic action can be added by inheriting from ``action.Action`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1486 instead of ``cgi.action.Action``. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1487 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1488 .. _interfaces.py: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1489 .. _modifying the core of Roundup: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1490 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1491 interfaces.py - hooking into the core of Roundup |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1492 ================================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1493 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1494 There is a magic trick for hooking into the core of Roundup. Using |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1495 this you can: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1496 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1497 * modify class data structures |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1498 * monkey patch core code to add new functionality |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1499 * modify the email gateway |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1500 * add new rest endpoints |
|
7375
9bd7ed918121
issue2551253 - Modify password PBKDF2 method to use SHA512
John Rouillard <rouilj@ieee.org>
parents:
7371
diff
changeset
|
1501 * enable experimental or future features |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1502 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1503 but with great power comes great responsibility. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1504 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1505 Interfaces.py has been around since the earliest releases of Roundup |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1506 and used to be the main way to get a lot of customization done. In |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1507 modern Roundup, the extensions_ mechanism is used to `add actions |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1508 <#defining-new-web-actions>`_ and `templating utilities`_. But there are |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1509 places where interfaces.py is still useful. Note that the tracker |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1510 directories are not on the Python system path when interfaces.py is |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1511 evaluated. You need to add library directories explictly by |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1512 modifying sys.path. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1513 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1514 See `Changing How the Core Code Works |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1515 <customizing.html#changing-how-the-core-code-works>`_ for examples. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1516 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1517 Database Content |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1518 ================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1519 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1520 .. note:: |
|
7369
15bb0d177632
use glossary directive and link some terms to the glossary.
John Rouillard <rouilj@ieee.org>
parents:
7368
diff
changeset
|
1521 If you modify the content of a :term:`definitional class`, you will |
|
7370
f37c1df6de34
Glossary updates and more term refs.
John Rouillard <rouilj@ieee.org>
parents:
7369
diff
changeset
|
1522 need to edit the tracker `detectors`_ if they reference a value of |
|
f37c1df6de34
Glossary updates and more term refs.
John Rouillard <rouilj@ieee.org>
parents:
7369
diff
changeset
|
1523 a definitional class. (E.g. if a detector checks to see if an issue |
|
f37c1df6de34
Glossary updates and more term refs.
John Rouillard <rouilj@ieee.org>
parents:
7369
diff
changeset
|
1524 has a status of "open", and you change the "open" definition to be |
|
f37c1df6de34
Glossary updates and more term refs.
John Rouillard <rouilj@ieee.org>
parents:
7369
diff
changeset
|
1525 "working", you need to change the check.) |
|
f37c1df6de34
Glossary updates and more term refs.
John Rouillard <rouilj@ieee.org>
parents:
7369
diff
changeset
|
1526 |
|
f37c1df6de34
Glossary updates and more term refs.
John Rouillard <rouilj@ieee.org>
parents:
7369
diff
changeset
|
1527 Customisation of the special :term:`definitional classes <definitional |
|
f37c1df6de34
Glossary updates and more term refs.
John Rouillard <rouilj@ieee.org>
parents:
7369
diff
changeset
|
1528 class>` (eg. status, |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1529 priority, resolution, ...) may be done either before or after the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1530 tracker is initialised. The actual method of doing so is completely |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1531 different in each case though, so be careful to use the right one. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1532 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1533 **Changing content before tracker initialisation** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1534 Edit the initial_data.py module in your tracker to alter the items |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1535 created using the ``create( ... )`` methods. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1536 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1537 **Changing content after tracker initialisation** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1538 As the "admin" user, click on the "class list" link in the web |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1539 interface to bring up a list of all database classes. Click on the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1540 name of the class you wish to change the content of. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1541 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1542 You may also use the ``roundup-admin`` interface's create, set and |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1543 retire methods to add, alter or remove items from the classes in |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1544 question. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1545 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1546 See "`adding a new field to the classic schema |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1547 <customizing.html#adding-a-new-field-to-the-classic-schema>`_" for an |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1548 example that requires database content changes. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1549 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1550 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1551 Security / Access Controls |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1552 ========================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1553 |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1554 A set of Permissions is built into the security module by default. For |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1555 each Class defined in the tracker schema, the following permissions |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1556 are defined: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1557 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1558 - Create (everything) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1559 - Edit (everything) |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1560 - Search (everything) - (used if View does not permit access) |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1561 - Retire (everything) |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1562 - Restore (everything) |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1563 - View (everything) |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1564 |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1565 All of these are assigned to the "Admin" Role by default for every |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1566 class. They allow a user to do anything. The web and email interfaces |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1567 also define: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1568 |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1569 Email Access |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1570 If defined, the user may use the email interface. Used by default to deny |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1571 Anonymous users access to the email interface. When granted to the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1572 Anonymous user, they will be automatically registered by the email |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1573 interface (see also the ``new_email_user_roles`` configuration option). |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1574 |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1575 Web Access |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1576 If defined, the user may use the web interface. This is usually |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1577 assigned to the Anonymous role as well to allow authorized users to |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1578 access the form based login. If some other authorization mode (basic |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1579 auth, SSO, etc.) is used Web Access can be removed from the |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1580 Anonymous user. |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1581 |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1582 Web Roles |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1583 Controls user access to editing the "roles" property of the "user" class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1584 TODO: deprecate in favour of a property-based control. |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1585 |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1586 Rest Access |br| Xmlrpc Access |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1587 These control access to the Rest and Xmlrpc endpoints. The Admin and User |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1588 roles have these by default in the classic tracker. See the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1589 `directions in the rest interface documentation`_ and the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1590 `xmlrpc interface documentation`_. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1591 |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1592 Register |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1593 This is assigned to the anonymous user and allows automatic user |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1594 registration by email or web. |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1595 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1596 These are hooked into the default Roles: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1597 |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1598 - Admin (Create, Edit, Retire, Restore, Search, View for everything; Web Roles) |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1599 - User (Web Access; Email Access) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1600 - Anonymous (Web Access) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1601 |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1602 Finally, the "admin" user gets the "Admin" Role, and the "anonymous" |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1603 user gets the "Anonymous" Role assigned when the tracker is installed. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1604 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1605 For the "User" Role, the "classic" tracker defines: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1606 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1607 - Create, Edit and View issue, file, msg, query, keyword |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1608 - View priority, status |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1609 - View user |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1610 - Edit their own user record |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1611 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1612 And the "Anonymous" Role is defined as: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1613 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1614 - Web interface access |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1615 - Register user (for registration) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1616 - View issue, file, msg, query, keyword, priority, status |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1617 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1618 Put together, these settings appear in the tracker's ``schema.py`` file:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1619 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1620 # |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1621 # TRACKER SECURITY SETTINGS |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1622 # |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1623 # See the configuration and customisation document for information |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1624 # about security setup. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1625 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1626 # |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1627 # REGULAR USERS |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1628 # |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1629 # Give the regular users access to the web and email interface |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1630 db.security.addPermissionToRole('User', 'Web Access') |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1631 db.security.addPermissionToRole('User', 'Email Access') |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1632 db.security.addPermissionToRole('User', 'Rest Access') |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1633 db.security.addPermissionToRole('User', 'Xmlrpc Access') |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1634 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1635 # Assign the access and edit Permissions for issue, file and message |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1636 # to regular users now |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1637 for cl in 'issue', 'file', 'msg', 'keyword': |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1638 db.security.addPermissionToRole('User', 'View', cl) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1639 db.security.addPermissionToRole('User', 'Edit', cl) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1640 db.security.addPermissionToRole('User', 'Create', cl) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1641 for cl in 'priority', 'status': |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1642 db.security.addPermissionToRole('User', 'View', cl) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1643 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1644 # May users view other user information? Comment these lines out |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1645 # if you don't want them to |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1646 p = db.security.addPermission(name='View', klass='user', |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1647 properties=('id', 'organisation', 'phone', 'realname', 'timezone', |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1648 'username')) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1649 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1650 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1651 # Users should be able to edit their own details -- this permission is |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1652 # limited to only the situation where the Viewed or Edited item is their own. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1653 def own_record(db, userid, itemid, **ctx): |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1654 '''Determine whether the userid matches the item being accessed.''' |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1655 return userid == itemid |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1656 p = db.security.addPermission(name='View', klass='user', check=own_record, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1657 description="User is allowed to view their own user details") |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1658 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1659 p = db.security.addPermission(name='Edit', klass='user', check=own_record, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1660 properties=('username', 'password', 'address', 'realname', 'phone', |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1661 'organisation', 'alternate_addresses', 'queries', 'timezone'), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1662 description="User is allowed to edit their own user details") |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1663 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1664 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1665 # Users should be able to edit and view their own queries. They should also |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1666 # be able to view any marked as not private. They should not be able to |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1667 # edit others' queries, even if they're not private |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1668 def view_query(db, userid, itemid): |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1669 private_for = db.query.get(itemid, 'private_for') |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1670 if not private_for: return True |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1671 return userid == private_for |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1672 def edit_query(db, userid, itemid): |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1673 return userid == db.query.get(itemid, 'creator') |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1674 p = db.security.addPermission(name='View', klass='query', check=view_query, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1675 description="User is allowed to view their own and public queries") |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1676 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1677 p = db.security.addPermission(name='Search', klass='query') |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1678 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1679 p = db.security.addPermission(name='Edit', klass='query', check=edit_query, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1680 description="User is allowed to edit their queries") |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1681 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1682 p = db.security.addPermission(name='Retire', klass='query', check=edit_query, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1683 description="User is allowed to retire their queries") |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1684 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1685 p = db.security.addPermission(name='Restore', klass='query', check=edit_query, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1686 description="User is allowed to restore their queries") |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1687 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1688 p = db.security.addPermission(name='Create', klass='query', |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1689 description="User is allowed to create queries") |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1690 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1691 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1692 # |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1693 # ANONYMOUS USER PERMISSIONS |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1694 # |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1695 # Let anonymous users access the web interface. Note that almost all |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1696 # trackers will need this Permission. The only situation where it's not |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1697 # required is in a tracker that uses an HTTP Basic Authenticated front-end. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1698 db.security.addPermissionToRole('Anonymous', 'Web Access') |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1699 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1700 # Let anonymous users access the email interface (note that this implies |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1701 # that they will be registered automatically, hence they will need the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1702 # "Create" user Permission below) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1703 # This is disabled by default to stop spam from auto-registering users on |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1704 # public trackers. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1705 #db.security.addPermissionToRole('Anonymous', 'Email Access') |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1706 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1707 # Assign the appropriate permissions to the anonymous user's Anonymous |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1708 # Role. Choices here are: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1709 # - Allow anonymous users to register |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1710 db.security.addPermissionToRole('Anonymous', 'Register', 'user') |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1711 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1712 # Allow anonymous users access to view issues (and the related, linked |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1713 # information) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1714 for cl in 'issue', 'file', 'msg', 'keyword', 'priority', 'status': |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1715 db.security.addPermissionToRole('Anonymous', 'View', cl) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1716 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1717 # Allow the anonymous user to use the "Show Unassigned" search. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1718 # It acts like "Show Open" if this permission is not available. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1719 # If you are running a tracker that does not allow read access for |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1720 # anonymous, you should remove this entry as it can be used to perform |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1721 # a username guessing attack against a roundup install. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1722 p = db.security.addPermission(name='Search', klass='user') |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1723 db.security.addPermissionToRole ('Anonymous', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1724 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1725 # [OPTIONAL] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1726 # Allow anonymous users access to create or edit "issue" items (and the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1727 # related file and message items) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1728 #for cl in 'issue', 'file', 'msg': |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1729 # db.security.addPermissionToRole('Anonymous', 'Create', cl) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1730 # db.security.addPermissionToRole('Anonymous', 'Edit', cl) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1731 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1732 .. index:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1733 single: roundup-admin; view class permissions |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1734 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1735 You can use ``roundup-admin security`` to verify the permissions |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1736 defined in the schema. It also verifies that properties specified in |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1737 permissions are valid for the class. This helps detect typos that can |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1738 cause baffling permission issues. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1739 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1740 Automatic Permission Checks |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1741 --------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1742 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1743 Permissions are automatically checked when information is rendered |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1744 through the web. This includes: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1745 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1746 1. View checks for properties when being rendered via the ``plain()`` or |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1747 similar methods. If the check fails, the text "[hidden]" will be |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1748 displayed. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1749 2. Edit checks for properties when the edit field is being rendered via |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1750 the ``field()`` or similar methods. If the check fails, the property |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1751 will be rendered via the ``plain()`` method (see point 1. for subsequent |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1752 checking performed) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1753 3. View checks are performed in index pages for each item being displayed |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1754 such that if the user does not have permission, the row is not rendered. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1755 4. View checks are performed at the top of item pages for the Item being |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1756 displayed. If the user does not have permission, the text "You are not |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1757 allowed to view this page." will be displayed. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1758 5. View checks are performed at the top of index pages for the Class being |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1759 displayed. If the user does not have permission, the text "You are not |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1760 allowed to view this page." will be displayed. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1761 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1762 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1763 New User Roles |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1764 -------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1765 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1766 New users are assigned the Roles defined in the config file as: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1767 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1768 - NEW_WEB_USER_ROLES |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1769 - NEW_EMAIL_USER_ROLES |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1770 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1771 The `users may only edit their issues |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1772 <customizing.html#users-may-only-edit-their-issues>`_ example shows |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1773 customisation of these parameters. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1774 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1775 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1776 Changing Access Controls |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1777 ------------------------ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1778 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1779 You may alter the configuration variables to change the Role that new |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1780 web or email users get, for example to not give them access to the web |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1781 interface if they register through email. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1782 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1783 You may use the ``roundup-admin`` "``security``" command to display the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1784 current Role and Permission configuration in your tracker. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1785 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1786 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1787 Adding a new Permission |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1788 ~~~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1789 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1790 When adding a new Permission, you will need to: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1791 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1792 1. add it to your tracker's ``schema.py`` so it is created, using |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1793 ``security.addPermission``, for example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1794 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1795 db.security.addPermission(name="View", klass='frozzle', |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1796 description="User is allowed to access frozzles") |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1797 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1798 will set up a new "View" permission on the Class "frozzle". |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1799 2. enable it for the Roles that should have it (verify with |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1800 "``roundup-admin security``") |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1801 3. add it to the relevant HTML interface templates |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1802 4. add it to the appropriate xxxPermission methods on in your tracker |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1803 interfaces module |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1804 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1805 The ``addPermission`` method takes a few optional parameters: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1806 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1807 **properties** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1808 A sequence of property names that are the only properties to apply the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1809 new Permission to (eg. ``... klass='user', properties=('name', |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1810 'email') ...``) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1811 **props_only** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1812 A boolean value (set to false by default) that is a new feature |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1813 in Roundup 1.6. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1814 A permission defined using: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1815 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1816 ``properties=('list', 'of', 'property', 'names')`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1817 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1818 is used to determine access for things other than just those |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1819 properties. For example a check for View permission on the issue |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1820 class or an issue item can use any View permission for the issue |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1821 class even if that permission has a property list. This can be |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1822 confusing and surprising as you would think that a permission |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1823 including properties would be used only for determining the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1824 access permission for those properties. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1825 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1826 ``roundup-admin security`` will report invalid properties for the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1827 class. For example a permission with an invalid summary property is |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1828 presented as:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1829 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1830 Allowed to see content of object regardless of spam status |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1831 (View for "file": ('content', 'summary') only) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1832 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1833 **Invalid properties for file: ['summary'] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1834 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1835 Setting ``props_only=True`` will make the permission valid only for |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1836 those properties. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1837 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1838 If you use a lot of permissions with property checks, it can be |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1839 difficult to change all of them. Calling the function: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1840 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1841 db.security.set_props_only_default(True) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1842 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1843 at the top of ``schema.py`` will make every permission creation |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1844 behave as though props_only was set to True. It is expected that the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1845 default of True will become the default in a future Roundup release. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1846 **check** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1847 A function to be executed which returns boolean determining whether |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1848 the Permission is allowed. If it returns True, the permission is |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1849 allowed, if it returns False the permission is denied. The function |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1850 can have one of two signatures:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1851 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1852 check(db, userid, itemid) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1853 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1854 or:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1855 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1856 check(db, userid, itemid, **ctx) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1857 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1858 where ``db`` is a handle on the open database, ``userid`` is |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1859 the user attempting access and ``itemid`` is the specific item being |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1860 accessed. If the second form is used the ``ctx`` dictionary is |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1861 defined with the following values:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1862 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1863 ctx['property'] the name of the property being checked or None if |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1864 it's a class check. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1865 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1866 ctx['classname'] the name of the class that is being checked |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1867 (issue, query ....). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1868 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1869 ctx['permission'] the name of the permission (e.g. View, Edit...). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1870 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1871 The second form is preferred as it makes it easier to implement more |
|
7378
b4ac699c6282
Link to example section rather than page.
John Rouillard <rouilj@ieee.org>
parents:
7376
diff
changeset
|
1872 complex permission schemes. An `example in upgrading.html |
|
b4ac699c6282
Link to example section rather than page.
John Rouillard <rouilj@ieee.org>
parents:
7376
diff
changeset
|
1873 <upgrading.html#enhancement-to-check-command-for-permissions>`_ |
|
b4ac699c6282
Link to example section rather than page.
John Rouillard <rouilj@ieee.org>
parents:
7376
diff
changeset
|
1874 shows the use of ``ctx``. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1875 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1876 Example Scenarios |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1877 ~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1878 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1879 See the `examples <customizing.html#examples>`_ section for longer |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1880 examples of customisation. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1881 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1882 **anonymous access through the e-mail gateway** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1883 Give the "anonymous" user the "Email Access", ("Edit", "issue") and |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1884 ("Create", "msg") Permissions but do not not give them the ("Create", |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1885 "user") Permission. This means that when an unknown user sends email |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1886 into the tracker, they're automatically logged in as "anonymous". |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1887 Since they don't have the ("Create", "user") Permission, they won't |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1888 be automatically registered, but since "anonymous" has permission to |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1889 use the gateway, they'll still be able to submit issues. Note that |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1890 the Sender information - their email address - will not be available |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1891 - they're *anonymous*. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1892 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1893 **automatic registration of users in the e-mail gateway** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1894 By giving the "anonymous" user the ("Register", "user") Permission, any |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1895 unidentified user will automatically be registered with the tracker |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1896 (with no password, so they won't be able to log in through |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1897 the web until an admin sets their password). By default new Roundup |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1898 trackers don't allow this as it opens them up to spam. It may be enabled |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1899 by uncommenting the appropriate addPermissionToRole in your tracker's |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1900 ``schema.py`` file. The new user is given the Roles list defined in the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1901 "new_email_user_roles" config variable. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1902 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1903 **only developers may be assigned issues** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1904 Create a new Permission called "Fixer" for the "issue" class. Create a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1905 new Role "Developer" which has that Permission, and assign that to the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1906 appropriate users. Filter the list of users available in the assignedto |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1907 list to include only those users. Enforce the Permission with an |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1908 auditor. See the example |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1909 `restricting the list of users that are assignable to a task |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1910 <customizing.html#restricting-the-list-of-users-that-are-assignable-to-a-task>`_. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1911 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1912 **only managers may sign off issues as complete** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1913 Create a new Permission called "Closer" for the "issue" class. Create a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1914 new Role "Manager" which has that Permission, and assign that to the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1915 appropriate users. In your web interface, only display the "resolved" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1916 issue state option when the user has the "Closer" Permissions. Enforce |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1917 the Permission with an auditor. This is very similar to the previous |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1918 example, except that the web interface check would look like:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1919 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1920 <option tal:condition="python:request.user.hasPermission('Closer')" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1921 value="resolved">Resolved</option> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1922 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1923 **don't give web access to users who register through email** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1924 Create a new Role called "Email User" which has all the Permissions of |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1925 the normal "User" Role minus the "Web Access" Permission. This will |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1926 allow users to send in emails to the tracker, but not access the web |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1927 interface. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1928 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1929 **let some users edit the details of all users** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1930 Create a new Role called "User Admin" which has the Permission for |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1931 editing users:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1932 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1933 db.security.addRole(name='User Admin', description='Managing users') |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1934 p = db.security.getPermission('Edit', 'user') |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1935 db.security.addPermissionToRole('User Admin', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1936 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1937 and assign the Role to the users who need the permission. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1938 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1939 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1940 Web Interface |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1941 ============= |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1942 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1943 .. contents:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1944 :local: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1945 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1946 The web interface is provided by the ``roundup.cgi.client`` module and |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1947 is used by ``roundup.cgi``, ``roundup-server`` and ``ZRoundup`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1948 (``ZRoundup`` is broken, until further notice). In all cases, we |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1949 determine which tracker is being accessed (the first part of the URL |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1950 path inside the scope of the CGI handler) and pass control on to the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1951 ``roundup.cgi.client.Client`` class - which handles the rest of the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1952 access through its ``main()`` method. This means that you can do pretty |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1953 much anything you want as a web interface to your tracker. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1954 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1955 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1956 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1957 Repercussions of changing the tracker schema |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1958 --------------------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1959 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1960 If you choose to change the `tracker schema`_ you will need to ensure |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1961 the web interface knows about it: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1962 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1963 1. Index, item and search pages for the relevant classes may need to |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1964 have properties added or removed, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1965 2. The "page" template may require links to be changed, as might the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1966 "home" page's content arguments. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1967 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1968 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1969 How requests are processed |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1970 -------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1971 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1972 The basic processing of a web request proceeds as follows: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1973 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1974 1. figure out who we are, defaulting to the "anonymous" user |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1975 2. figure out what the request is for - we call this the "context" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1976 3. handle any requested action (item edit, search, ...) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1977 4. render the template requested by the context, resulting in HTML |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1978 output |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1979 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1980 In some situations, exceptions occur: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1981 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1982 - HTTP Redirect (generally raised by an action) |
|
7368
8aa1a5639aef
add explanatory info for HTTP Redirect
John Rouillard <rouilj@ieee.org>
parents:
7363
diff
changeset
|
1983 the URL to redirect to is the first argument of the exception. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1984 - SendFile (generally raised by ``determine_context``) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1985 here we serve up a FileClass "content" property |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1986 - SendStaticFile (generally raised by ``determine_context``) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1987 here we serve up a file from the tracker "html" directory |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1988 - Unauthorised (generally raised by an action) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1989 here the action is cancelled, the request is rendered and an error |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1990 message is displayed indicating that permission was not granted for |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1991 the action to take place |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1992 - NotFound (raised wherever it needs to be) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1993 this exception percolates up to the CGI interface that called the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1994 client |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1995 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1996 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1997 Roundup URL design |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1998 ------------------ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1999 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2000 Each tracker has several hardcoded URLs. These three are equivalent and |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2001 lead to the main tracker page: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2002 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2003 1. ``/`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2004 2. ``/index`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2005 3. ``/home`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2006 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2007 The following prefix is used to access static resources: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2008 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2009 4. ``/@@file/`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2010 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2011 Two additional url's are used for the API's. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2012 The `REST api`_ is accessed via: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2013 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2014 5. ``/rest/`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2015 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2016 .. _`REST api`: rest.html |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2017 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2018 and the `XMLRPC api`_ is available at: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2019 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2020 6. ``/xmlrpc`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2021 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2022 .. _`XMLRPC api`: xmlrpc.html |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2023 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2024 All other URLs depend on the classes configured in Roundup database. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2025 Each class receives two URLs - one for the class itself and another |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2026 for specific items of that class. Example for class URL: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2027 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2028 7. ``/issue`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2029 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2030 This is usually used to show listings of class items. The URL for |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2031 for specific object of issue class with id 1 will look like: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2032 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2033 8. ``/issue1`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2034 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2035 .. _strip_zeros: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2036 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2037 Note that a leading string of 0's will be stripped from the id part of |
|
7369
15bb0d177632
use glossary directive and link some terms to the glossary.
John Rouillard <rouilj@ieee.org>
parents:
7368
diff
changeset
|
2038 the object :term:`designator` in the URL. E.G. ``/issue001`` is the |
|
15bb0d177632
use glossary directive and link some terms to the glossary.
John Rouillard <rouilj@ieee.org>
parents:
7368
diff
changeset
|
2039 same as ``/issue1``. Similarly for ``/file01`` etc. However you |
|
15bb0d177632
use glossary directive and link some terms to the glossary.
John Rouillard <rouilj@ieee.org>
parents:
7368
diff
changeset
|
2040 should generate URL's without the extra zeros. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2041 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2042 Determining web context |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2043 ----------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2044 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2045 To determine the "context" of a request (what request is for), we look at |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2046 the URL path after the tracker root and at ``@template`` request |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2047 parameter. Typical URL paths look like: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2048 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2049 1. ``/tracker/issue`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2050 2. ``/tracker/issue1`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2051 3. ``/tracker/@@file/style.css`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2052 4. ``/cgi-bin/roundup.cgi/tracker/file1`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2053 5. ``/cgi-bin/roundup.cgi/tracker/file1/kitten.png`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2054 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2055 where tracker root is ``/tracker/`` or ``/cgi-bin/roundup.cgi/tracker/`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2056 We're looking at "issue", "issue1", "@@file/style.css", "file1" and |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2057 "file1/kitten.png" in the cases above. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2058 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2059 1. with is no path we are in the "home" context. See `the "home" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2060 context`_ below for details. "index" or "home" paths may also be used |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2061 to switch into "home" context. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2062 2. for paths starting with "@@file" the additional path entry ("style.css" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2063 in the example above) specifies the static file to be served |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2064 from the tracker TEMPLATES directory (or STATIC_FILES, if configured). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2065 This is usually the tracker's "html" directory. Internally this works |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2066 by raising SendStaticFile exception. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2067 3. if there is something in the path (as in example 1, "issue"), it |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2068 identifies the tracker class to display. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2069 4. if the path is an item designator (as in examples 2 and 4, "issue1" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2070 and "file1"), then we're to display a specific item. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2071 :ref:`Note. <strip_zeros>` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2072 5. if the path starts with an item designator and is longer than one |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2073 entry (as in example 5, "file1/kitten.png"), then we're assumed to be |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2074 handling an item of a ``FileClass``, and the extra path information |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2075 gives the filename that the client is going to label the download |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2076 with (i.e. "file1/kitten.png" is nicer to download than "file1"). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2077 This raises a ``SendFile`` exception. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2078 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2079 Neither 2. or 5. use templates and stop before the template is |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2080 determined. For other contexts the template used is specified by the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2081 ``@template`` variable, which defaults to: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2082 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2083 - only classname supplied: "index" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2084 - full item designator supplied: "item" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2085 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2086 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2087 The "home" Context |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2088 ------------------ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2089 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2090 The "home" context is special because it allows you to add templated |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2091 pages to your tracker that don't rely on a class or item (ie. an issues |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2092 list or specific issue). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2093 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2094 Let's say you wish to add frames to control the layout of your tracker's |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2095 interface. You'd probably have: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2096 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2097 - A top-level frameset page. This page probably wouldn't be templated, so |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2098 it could be served as a static file (see `serving static content`_) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2099 - A sidebar frame that is templated. Let's call this page |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2100 "home.navigation.html" in your tracker's "html" directory. To load that |
|
7363
23abe048d1de
Fix missing pre block for url.
John Rouillard <rouilj@ieee.org>
parents:
7359
diff
changeset
|
2101 page up, you use the URL:: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2102 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2103 <tracker url>/home?@template=navigation |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2104 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2105 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2106 Serving static content |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2107 ---------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2108 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2109 See the previous section `determining web context`_ where it describes |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2110 ``@@file`` paths. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2111 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2112 These files are served without any permission checks. Any user on the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2113 internet with the url can download the file. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2114 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2115 This is rarely an issue since the html templates are just source code |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2116 and much of it can be found in the Roundup repository. Other |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2117 decoration (logos, stylesheets) are similarly not security sensitive. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2118 You can use the static_files setting in config.ini to eliminate |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2119 access to the templates directory if desired. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2120 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2121 If a file resolves to a symbolic link, it is not served. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2122 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2123 Performing actions in web requests |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2124 ---------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2125 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2126 When a user requests a web page, they may optionally also request for an |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2127 action to take place. As described in `how requests are processed`_, the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2128 action is performed before the requested page is generated. Actions are |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2129 triggered by using a ``@action`` CGI variable, where the value is one |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2130 of: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2131 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2132 **login** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2133 Attempt to log a user in. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2134 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2135 **logout** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2136 Log the user out - make them "anonymous". |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2137 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2138 **register** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2139 Attempt to create a new user based on the contents of the form and then |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2140 log them in. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2141 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2142 **edit** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2143 Perform an edit of an item in the database. There are some `special form |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2144 variables`_ you may use. Also you can set the ``__redirect_to`` form |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2145 variable to the URL that should be displayed after the edit is succesfully |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2146 completed. If you wanted to edit a sequence of issues, users etc. this |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2147 could be used to display the next item in the sequence to the user. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2148 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2149 **new** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2150 Add a new item to the database. You may use the same `special form |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2151 variables`_ as in the "edit" action. Also you can set the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2152 ``__redirect_to`` form variable to the URL that should be displayed after |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2153 the new item is created. This is useful if you want to create another |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2154 item rather than edit the newly created item. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2155 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2156 **retire** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2157 Retire the item in the database. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2158 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2159 **editCSV** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2160 Performs an edit of all of a class' items in one go. See also the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2161 *class*.csv templating method which generates the CSV data to be |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2162 edited, and the ``'_generic.index'`` template which uses both of these |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2163 features. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2164 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2165 **search** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2166 Mangle some of the form variables: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2167 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2168 - Set the form ":filter" variable based on the values of the filter |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2169 variables - if they're set to anything other than "dontcare" then add |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2170 them to :filter. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2171 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2172 - Also handle the ":queryname" variable and save off the query to the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2173 user's query list. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2174 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2175 Each of the actions is implemented by a corresponding ``*XxxAction*`` (where |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2176 "Xxx" is the name of the action) class in the ``roundup.cgi.actions`` module. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2177 These classes are registered with ``roundup.cgi.client.Client``. If you need |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2178 to define new actions, you may add them there (see `defining new |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2179 web actions`_). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2180 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2181 Each action class also has a ``*permission*`` method which determines whether |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2182 the action is permissible given the current user. The base permission checks |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2183 for each action are: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2184 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2185 **login** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2186 Determine whether the user has the "Web Access" Permission. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2187 **logout** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2188 No permission checks are made. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2189 **register** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2190 Determine whether the user has the ("Create", "user") Permission. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2191 **edit** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2192 Determine whether the user has permission to edit this item. If we're |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2193 editing the "user" class, users are allowed to edit their own details - |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2194 unless they try to edit the "roles" property, which requires the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2195 special Permission "Web Roles". |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2196 **new** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2197 Determine whether the user has permission to create this item. No |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2198 additional property checks are made. Additionally, new user items may |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2199 be created if the user has the ("Create", "user") Permission. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2200 **editCSV** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2201 Determine whether the user has permission to edit this class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2202 **search** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2203 Determine whether the user has permission to view this class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2204 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2205 Protecting users from web application attacks |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2206 --------------------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2207 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2208 There is a class of attacks known as Cross Site Request Forgeries |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2209 (CSRF). Malicious code running in the browser can making a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2210 request to Roundup while you are logged into Roundup. The |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2211 malicious code piggy backs on your existing Roundup session to |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2212 make changes without your knowledge. Roundup 1.6 has support for |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2213 defending against this by analyzing the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2214 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2215 * Referer, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2216 * Origin, and |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2217 * Host or |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2218 * X-Forwarded-Host |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2219 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2220 HTTP headers. It compares the headers to the value of the web setting |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2221 in the [tracker] section of the tracker's ``config.ini``. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2222 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2223 Also a per form token (also called a nonce) can be enabled for |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2224 the tracker using the ``csrf_enforce_token`` option in |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2225 config.ini. When enabled, Roundup will validate a hidden form |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2226 field called ``@csrf``. If the validation fails (or the token |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2227 is used more than once) the request is rejected. The ``@csrf`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2228 input field is added automatically by calling the ``submit`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2229 function/path. It can also be added manually by calling |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2230 anti_csrf_nonce() directly. For example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2231 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2232 <input name="@csrf" type="hidden" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2233 tal:attributes="value python:utils.anti_csrf_nonce(lifetime=10)"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2234 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2235 By default a nonce lifetime is 2 weeks. However the lifetime (in |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2236 minutes) can be set by passing a lifetime argument as shown |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2237 above. The example above makes the nonce lifetime 10 minutes. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2238 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2239 Search for @csrf in this document for more examples. There are |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2240 more examples and information in ``upgrading.txt``. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2241 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2242 The token protects you because malicious code supplied by another |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2243 site is unable to obtain the token. Thus many attempts they make |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2244 to submit a request are rejected. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2245 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2246 The protection on the xmlrpc interface is untested, but is based |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2247 on a valid header check against the Roundup url and the presence |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2248 of the ``X-REQUESTED-WITH`` header. Work to improve this is a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2249 future project after the 1.6 release. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2250 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2251 The enforcement levels can be modified in ``config.ini``. Refer to |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2252 that file for details. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2253 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2254 Special form variables |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2255 ---------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2256 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2257 Item properties and their values are edited with html FORM |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2258 variables and their values. You can: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2259 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2260 - Change the value of some property of the current item. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2261 - Create a new item of any class, and edit the new item's |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2262 properties, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2263 - Attach newly created items to a multilink property of the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2264 current item. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2265 - Remove items from a multilink property of the current item. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2266 - Specify that some properties are required for the edit |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2267 operation to be successful. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2268 - Redirect to a different page after creating a new item (new action |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2269 only, not edit action). Usually you end up on the page for the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2270 created item. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2271 - Set up user interface locale. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2272 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2273 These operations will only take place if the form action (the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2274 ``@action`` variable) is "edit" or "new". |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2275 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2276 In the following, <bracketed> values are variable, "@" may be |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2277 either ":" or "@", and other text "required" is fixed. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2278 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2279 Two special form variables are used to specify user language preferences: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2280 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2281 ``@language`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2282 value may be locale name or ``none``. If this variable is set to |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2283 locale name, web interface language is changed to given value |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2284 (provided that appropriate translation is available), the value |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2285 is stored in the browser cookie and will be used for all following |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2286 requests. If value is ``none`` the cookie is removed and the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2287 language is changed to the tracker default, set up in the tracker |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2288 configuration or OS environment. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2289 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2290 ``@charset`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2291 value may be character set name or ``none``. Character set name |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2292 is stored in the browser cookie and sets output encoding for all |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2293 HTML pages generated by Roundup. If value is ``none`` the cookie |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2294 is removed and HTML output is reset to Roundup internal encoding |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2295 (UTF-8). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2296 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2297 Most properties are specified as form variables: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2298 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2299 ``<propname>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2300 property on the current context item |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2301 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2302 ``<designator>"@"<propname>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2303 property on the indicated item (for editing related information) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2304 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2305 Designators name a specific item of a class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2306 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2307 ``<classname><N>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2308 Name an existing item of class <classname>. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2309 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2310 ``<classname>"-"<N>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2311 Name the <N>th new item of class <classname>. If the form |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2312 submission is successful, a new item of <classname> is |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2313 created. Within the submitted form, a particular |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2314 designator of this form always refers to the same new |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2315 item. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2316 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2317 Once we have determined the "propname", we look at it to see |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2318 if it's special: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2319 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2320 ``@required`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2321 The associated form value is a comma-separated list of |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2322 property names that must be specified when the form is |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2323 submitted for the edit operation to succeed. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2324 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2325 When the <designator> is missing, the properties are |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2326 for the current context item. When <designator> is |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2327 present, they are for the item specified by |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2328 <designator>. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2329 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2330 The "@required" specifier must come before any of the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2331 properties it refers to are assigned in the form. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2332 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2333 ``@remove@<propname>=id(s)`` or ``@add@<propname>=id(s)`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2334 The "@add@" and "@remove@" edit actions apply only to |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2335 Multilink properties. The form value must be a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2336 comma-separate list of keys for the class specified by |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2337 the simple form variable. The listed items are added |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2338 to (respectively, removed from) the specified |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2339 property. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2340 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2341 ``@link@<propname>=<designator>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2342 If the edit action is "@link@", the simple form |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2343 variable must specify a Link or Multilink property. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2344 The form value is a comma-separated list of |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2345 designators. The item corresponding to each |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2346 designator is linked to the property given by simple |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2347 form variable. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2348 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2349 None of the above (ie. just a simple form value) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2350 The value of the form variable is converted |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2351 appropriately, depending on the type of the property. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2352 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2353 For a Link('klass') property, the form value is a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2354 single key for 'klass', where the key field is |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2355 specified in schema.py. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2356 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2357 For a Multilink('klass') property, the form value is a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2358 comma-separated list of keys for 'klass', where the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2359 key field is specified in schema.py. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2360 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2361 Note that for simple-form-variables specifiying Link |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2362 and Multilink properties, the linked-to class must |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2363 have a key field. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2364 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2365 For a String() property specifying a filename, the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2366 file named by the form value is uploaded. This means we |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2367 try to set additional properties "filename" and "type" (if |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2368 they are valid for the class). Otherwise, the property |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2369 is set to the form value. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2370 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2371 For Date(), Interval(), Boolean(), Integer() and Number() |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2372 properties, the form value is converted to the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2373 appropriate value. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2374 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2375 Any of the form variables may be prefixed with a classname or |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2376 designator. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2377 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2378 Setting the form variable: ``__redirect_to=`` to a url when |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2379 @action=new redirects the user to the specified url after successfully |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2380 creating the new item. This is useful if you want the user to create |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2381 another item rather than edit the newly created item. Note that the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2382 url assigned to ``__redirect_to`` must be url encoded/quoted and be |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2383 under the tracker's base url. If the base_url uses http, you can set |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2384 the url to https. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2385 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2386 Two special form values are supported for backwards compatibility: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2387 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2388 @note |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2389 This is equivalent to:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2390 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2391 @link@messages=msg-1 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2392 msg-1@content=value |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2393 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2394 which is equivalent to the html:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2395 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2396 <textarea name="msg-1@content"></textarea> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2397 <input type="hidden" name="@link@messages" value="msg-1"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2398 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2399 except that in addition, the "author" and "date" properties of |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2400 "msg-1" are set to the userid of the submitter, and the current |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2401 time, respectively. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2402 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2403 @file |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2404 This is equivalent to:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2405 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2406 @link@files=file-1 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2407 file-1@content=value |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2408 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2409 by adding the HTML:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2410 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2411 <input type="file" name="file-1@content"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2412 <input type="hidden" name="@link@files" value="file-1"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2413 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2414 The String content value is handled as described above for file |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2415 uploads. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2416 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2417 If both the "@note" and "@file" form variables are |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2418 specified, the action:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2419 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2420 msg-1@link@files=file-1 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2421 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2422 is also performed. This would be expressed in HTML with:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2423 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2424 <input type="hidden" name="msg-1@link@files" value="file-1"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2425 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2426 We also check that FileClass items have a "content" property with |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2427 actual content, otherwise we remove them from all_props before |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2428 returning. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2429 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2430 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2431 Default templates |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2432 ----------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2433 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2434 The default templates are html4 compliant. If you wish to change them to be |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2435 xhtml compliant, you'll need to change the ``html_version`` configuration |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2436 variable in ``config.ini`` to ``'xhtml'`` instead of ``'html4'``. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2437 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2438 Most customisation of the web view can be done by modifying the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2439 templates in the tracker ``'html'`` directory. There are several types |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2440 of files in there. The *minimal* template includes: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2441 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2442 **page.html** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2443 This template usually defines the overall look of your tracker. When |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2444 you view an issue, it appears inside this template. When you view an |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2445 index, it also appears inside this template. This template defines a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2446 macro called "icing" which is used by almost all other templates as a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2447 coating for their content, using its "content" slot. It also defines |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2448 the "head_title" and "body_title" slots to allow setting of the page |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2449 title. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2450 **home.html** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2451 the default page displayed when no other page is indicated by the user |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2452 **home.classlist.html** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2453 a special version of the default page that lists the classes in the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2454 tracker |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2455 **classname.item.html** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2456 displays an item of the *classname* class |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2457 **classname.index.html** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2458 displays a list of *classname* items |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2459 **classname.search.html** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2460 displays a search page for *classname* items |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2461 **_generic.index.html** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2462 used to display a list of items where there is no |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2463 ``*classname*.index`` available |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2464 **_generic.help.html** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2465 used to display a "class help" page where there is no |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2466 ``*classname*.help`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2467 **user.register.html** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2468 a special page just for the user class, that renders the registration |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2469 page |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2470 **style.css** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2471 a static file that is served up as-is |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2472 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2473 The *classic* template has a number of additional templates. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2474 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2475 Remember that you can create any template extension you want to, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2476 so if you just want to play around with the templating for new issues, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2477 you can copy the current "issue.item" template to "issue.test", and then |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2478 access the test template using the "@template" URL argument:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2479 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2480 http://your.tracker.example/tracker/issue?@template=test |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2481 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2482 and it won't affect your users using the "issue.item" template. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2483 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2484 You can also put templates into a subdirectory of the template |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2485 directory. So if you specify:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2486 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2487 http://your.tracker.example/tracker/issue?@template=test/item |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2488 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2489 you will use the template at: ``test/issue.item.html``. If that |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2490 template doesn't exit it will try to use |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2491 ``test/_generic.item.html``. If that template doesn't exist |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2492 it will return an error. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2493 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2494 Implementing Modal Editing Using @template |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2495 ------------------------------------------ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2496 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2497 Many item templates allow you to edit the item. They contain |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2498 code that renders edit boxes if the user has edit permissions. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2499 Otherwise the template will just display the item information. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2500 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2501 In some cases you want to do a modal edit. The user has to take some |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2502 action (click a button or follow a link) to shift from display mode to |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2503 edit mode. When the changes are submitted, ending the edit mode, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2504 the user is returned to display mode. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2505 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2506 Modal workflows usually slow things down and are not implemented by |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2507 default templates. However for some workflows a modal edit is useful. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2508 For example a batch edit mode that allows the user to edit a number of |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2509 issues all from one form could be implemented as a modal workflow of: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2510 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2511 * search for issues to modify |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2512 * switch to edit mode and change values |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2513 * exit back to the results of the search |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2514 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2515 To implement the modal edit, assume you have an issue.edit.html |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2516 template that implements an edit form. On the display page (a version |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2517 of issue.item.html modified to only display information) add a link |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2518 that calls the display url, but adds ``@template=edit`` to the link. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2519 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2520 This will now display the edit page. On the edit page you want to add |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2521 a hidden text field to your form named ``@template`` with the value: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2522 ``item|edit``. When the form is submitted it is validated. If the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2523 form is correct the user will see the item rendered using the item |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2524 template. If there is an error (validation failed) the item will be |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2525 rendered using the edit template. The edit template that is rendered |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2526 will display all the changes that the user made to the form before it |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2527 was submitted. The user can correct the error and resubmit the changes |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2528 until the form validates. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2529 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2530 If the form failed to validate but the ``@template`` field had the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2531 value ``item`` the user would still see the error, but all of the data |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2532 the user entered would be discarded. The user would have to redo all |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2533 the edits again. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2534 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2535 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2536 How the templates work |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2537 ---------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2538 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2539 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2540 Templating engines |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2541 ~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2542 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2543 Since version 1.4.20 Roundup supports two templating engines: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2544 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2545 * the original `Template Attribute Language`_ (TAL) engine from Zope |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2546 * the standalone Chameleon templating engine. Chameleon is intended |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2547 as a replacement for the original TAL engine, and supports the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2548 same syntax, but they are not 100% compatible. The major (and most |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2549 likely the only) incompatibility is the default expression type being |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2550 ``python:`` instead of ``path:``. See also "Incompatibilities and |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2551 differences" section of `Chameleon documentation`__. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2552 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2553 Version 1.5.0 added experimental support for the `jinja2`_ templating |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2554 language. You must install the `jinja2`_ module in order to use it. The |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2555 ``jinja2`` template supplied with Roundup has the templates rewritten |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2556 to use ``jinja2`` rather than TAL. A number of trackers are running |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2557 using ``jinja2`` templating so it is considered less experimental than |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2558 Chameleon templating. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2559 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2560 .. _jinja2: https://palletsprojects.com/p/jinja/ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2561 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2562 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2563 **NOTE1**: For historical reasons, examples given below assumes path |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2564 expression as default expression type. With Chameleon you have to manually |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2565 resolve the path expressions. A Chameleon-based, z3c.pt, that is fully |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2566 compatible with the old TAL implementation, is planned to be included in a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2567 future release. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2568 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2569 **NOTE2**: As of 1.4.20 Chameleon support is highly experimental and **not** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2570 recommended for production use. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2571 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2572 .. _Chameleon: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2573 https://pypi.org/project/Chameleon/ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2574 .. _z3c.pt: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2575 https://pypi.org/project/z3c.pt/ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2576 __ https://chameleon.readthedocs.io/en/latest/reference.html?highlight=differences#incompatibilities-and-differences |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2577 .. _TAL: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2578 .. _Template Attribute Language: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2579 https://pagetemplates.readthedocs.io/en/latest/history/TALSpecification14.html |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2580 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2581 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2582 Basic Templating Actions |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2583 ~~~~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2584 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2585 Roundup's templates consist of special attributes on the HTML tags. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2586 These attributes form the **Template Attribute Language**, or TAL. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2587 The basic TAL commands are: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2588 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2589 **tal:define="variable expression; variable expression; ..."** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2590 Define a new variable that is local to this tag and its contents. For |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2591 example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2592 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2593 <html tal:define="title request/description"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2594 <head><title tal:content="title"></title></head> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2595 </html> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2596 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2597 In this example, the variable "title" is defined as the result of the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2598 expression "request/description". The "tal:content" command inside the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2599 <html> tag may then use the "title" variable. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2600 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2601 **tal:condition="expression"** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2602 Only keep this tag and its contents if the expression is true. For |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2603 example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2604 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2605 <p tal:condition="python:request.user.hasPermission('View', 'issue')"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2606 Display some issue information. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2607 </p> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2608 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2609 In the example, the <p> tag and its contents are only displayed if |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2610 the user has the "View" permission for issues. We consider the number |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2611 zero, a blank string, an empty list, and the built-in variable |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2612 nothing to be false values. Nearly every other value is true, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2613 including non-zero numbers, and strings with anything in them (even |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2614 spaces!). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2615 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2616 **tal:repeat="variable expression"** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2617 Repeat this tag and its contents for each element of the sequence |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2618 that the expression returns, defining a new local variable and a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2619 special "repeat" variable for each element. For example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2620 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2621 <tr tal:repeat="u user/list"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2622 <td tal:content="u/id"></td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2623 <td tal:content="u/username"></td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2624 <td tal:content="u/realname"></td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2625 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2626 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2627 The example would iterate over the sequence of users returned by |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2628 "user/list" and define the local variable "u" for each entry. Using |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2629 the repeat command creates a new variable called "repeat" which you |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2630 may access to gather information about the iteration. See the section |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2631 below on `the repeat variable`_. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2632 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2633 **tal:replace="expression"** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2634 Replace this tag with the result of the expression. For example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2635 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2636 <span tal:replace="request/user/realname" /> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2637 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2638 The example would replace the <span> tag and its contents with the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2639 user's realname. If the user's realname was "Bruce", then the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2640 resultant output would be "Bruce". |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2641 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2642 **tal:content="expression"** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2643 Replace the contents of this tag with the result of the expression. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2644 For example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2645 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2646 <span tal:content="request/user/realname">user's name appears here |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2647 </span> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2648 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2649 The example would replace the contents of the <span> tag with the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2650 user's realname. If the user's realname was "Bruce" then the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2651 resultant output would be "<span>Bruce</span>". |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2652 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2653 **tal:attributes="attribute expression; attribute expression; ..."** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2654 Set attributes on this tag to the results of expressions. For |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2655 example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2656 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2657 <a tal:attributes="href string:user${request/user/id}">My Details</a> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2658 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2659 In the example, the "href" attribute of the <a> tag is set to the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2660 value of the "string:user${request/user/id}" expression, which will |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2661 be something like "user123". |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2662 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2663 **tal:omit-tag="expression"** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2664 Remove this tag (but not its contents) if the expression is true. For |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2665 example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2666 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2667 <span tal:omit-tag="python:1">Hello, world!</span> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2668 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2669 would result in output of:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2670 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2671 Hello, world! |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2672 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2673 Note that the commands on a given tag are evaulated in the order above, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2674 so *define* comes before *condition*, and so on. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2675 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2676 Additionally, you may include tags such as <tal:block>, which are |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2677 removed from output. Its content is kept, but the tag itself is not (so |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2678 don't go using any "tal:attributes" commands on it). This is useful for |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2679 making arbitrary blocks of HTML conditional or repeatable (very handy |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2680 for repeating multiple table rows, which would otherwise require an |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2681 illegal tag placement to effect the repeat). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2682 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2683 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2684 Templating Expressions |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2685 ~~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2686 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2687 Templating Expressions are covered by `Template Attribute Language |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2688 Expression Syntax`_, or TALES. The expressions you may use in the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2689 attribute values may be one of the following forms: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2690 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2691 **Path Expressions** - eg. ``item/status/checklist`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2692 These are object attribute / item accesses. Roughly speaking, the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2693 path ``item/status/checklist`` is broken into parts ``item``, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2694 ``status`` and ``checklist``. The ``item`` part is the root of the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2695 expression. We then look for a ``status`` attribute on ``item``, or |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2696 failing that, a ``status`` item (as in ``item['status']``). If that |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2697 fails, the path expression fails. When we get to the end, the object |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2698 we're left with is evaluated to get a string - if it is a method, it |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2699 is called; if it is an object, it is stringified. Path expressions |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2700 may have an optional ``path:`` prefix, but they are the default |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2701 expression type, so it's not necessary. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2702 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2703 If an expression evaluates to ``default``, then the expression is |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2704 "cancelled" - whatever HTML already exists in the template will |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2705 remain (tag content in the case of ``tal:content``, attributes in the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2706 case of ``tal:attributes``). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2707 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2708 If an expression evaluates to ``nothing`` then the target of the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2709 expression is removed (tag content in the case of ``tal:content``, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2710 attributes in the case of ``tal:attributes`` and the tag itself in |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2711 the case of ``tal:replace``). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2712 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2713 If an element in the path may not exist, then you can use the ``|`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2714 operator in the expression to provide an alternative. So, the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2715 expression ``request/form/foo/value | default`` would simply leave |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2716 the current HTML in place if the "foo" form variable doesn't exist. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2717 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2718 You may use the python function ``path``, as in |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2719 ``path("item/status")``, to embed path expressions in Python |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2720 expressions. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2721 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2722 **String Expressions** - eg. ``string:hello ${user/name}`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2723 These expressions are simple string interpolations - though they can |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2724 be just plain strings with no interpolation if you want. The |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2725 expression in the ``${ ... }`` is just a path expression as above. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2726 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2727 **Python Expressions** - eg. ``python: 1+1`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2728 These expressions give the full power of Python. All the "root level" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2729 variables are available, so ``python:item.status.checklist()`` would |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2730 be equivalent to ``item/status/checklist``, assuming that |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2731 ``checklist`` is a method. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2732 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2733 Modifiers: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2734 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2735 **structure** - eg. ``structure python:msg.content.plain(hyperlink=1)`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2736 The result of expressions are normally *escaped* to be safe for HTML |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2737 display (all "<", ">" and "&" are turned into special entities). The |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2738 ``structure`` expression modifier turns off this escaping - the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2739 result of the expression is now assumed to be HTML, which is passed |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2740 to the web browser for rendering. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2741 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2742 **not:** - eg. ``not:python:1=1`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2743 This simply inverts the logical true/false value of another |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2744 expression. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2745 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2746 .. _TALES: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2747 .. _Template Attribute Language Expression Syntax: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2748 https://pagetemplates.readthedocs.io/en/latest/history/TALESSpecification13.html |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2749 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2750 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2751 Template Macros |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2752 ~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2753 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2754 Macros are used in Roundup to save us from repeating the same common |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2755 page stuctures over and over. The most common (and probably only) macro |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2756 you'll use is the "icing" macro defined in the "page" template. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2757 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2758 Macros are generated and used inside your templates using special |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2759 attributes similar to the `basic templating actions`_. In this case, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2760 though, the attributes belong to the `Macro Expansion Template |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2761 Attribute Language`_, or METAL. The macro commands are: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2762 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2763 **metal:define-macro="macro name"** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2764 Define that the tag and its contents are now a macro that may be |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2765 inserted into other templates using the *use-macro* command. For |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2766 example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2767 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2768 <html metal:define-macro="page"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2769 ... |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2770 </html> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2771 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2772 defines a macro called "page" using the ``<html>`` tag and its |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2773 contents. Once defined, macros are stored on the template they're |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2774 defined on in the ``macros`` attribute. You can access them later on |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2775 through the ``templates`` variable, eg. the most common |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2776 ``templates/page/macros/icing`` to access the "page" macro of the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2777 "page" template. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2778 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2779 **metal:use-macro="path expression"** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2780 Use a macro, which is identified by the path expression (see above). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2781 This will replace the current tag with the identified macro contents. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2782 For example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2783 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2784 <tal:block metal:use-macro="templates/page/macros/icing"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2785 ... |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2786 </tal:block> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2787 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2788 will replace the tag and its contents with the "page" macro of the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2789 "page" template. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2790 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2791 **metal:define-slot="slot name"** and **metal:fill-slot="slot name"** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2792 To define *dynamic* parts of the macro, you define "slots" which may |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2793 be filled when the macro is used with a *use-macro* command. For |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2794 example, the ``templates/page/macros/icing`` macro defines a slot like |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2795 so:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2796 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2797 <title metal:define-slot="head_title">title goes here</title> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2798 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2799 In your *use-macro* command, you may now use a *fill-slot* command |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2800 like this:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2801 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2802 <title metal:fill-slot="head_title">My Title</title> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2803 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2804 where the tag that fills the slot completely replaces the one defined |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2805 as the slot in the macro. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2806 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2807 Note that you may not mix `METAL`_ and `TAL`_ commands on the same tag, but |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2808 TAL commands may be used freely inside METAL-using tags (so your |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2809 *fill-slots* tags may have all manner of TAL inside them). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2810 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2811 .. _METAL: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2812 .. _Macro Expansion Template Attribute Language: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2813 https://pagetemplates.readthedocs.io/en/latest/history/TALESSpecification13.html |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2814 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2815 Information available to templates |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2816 ---------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2817 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2818 This is implemented by ``roundup.cgi.templating.RoundupPageTemplate`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2819 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2820 The following variables are available to templates. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2821 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2822 **context** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2823 The current context. This is either None, a `hyperdb class wrapper`_ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2824 or a `hyperdb item wrapper`_ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2825 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2826 **request** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2827 Includes information about the current request, including: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2828 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2829 - the current index information (``filterspec``, ``filter`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2830 args, ``properties``, etc) parsed out of the form. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2831 - methods for easy filterspec link generation |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2832 - "form" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2833 The current CGI form information as a mapping of form argument name |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2834 to value (specifically a cgi.FieldStorage) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2835 - "env" the CGI environment variables |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2836 - "base" the base URL for this instance |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2837 - "user" a HTMLItem instance for the current user |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2838 - "language" as determined by the browser or config |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2839 - "classname" the current classname (possibly None) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2840 - "template" the current template (suffix, also possibly None) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2841 **config** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2842 This variable holds all the values defined in the tracker config.ini |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2843 file (eg. TRACKER_NAME, etc.) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2844 **db** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2845 The current database, used to access arbitrary database items. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2846 **templates** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2847 Access to all the tracker templates by name. Used mainly in |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2848 *use-macro* commands. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2849 **utils** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2850 This variable makes available some utility functions like batching. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2851 **nothing** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2852 This is a special variable - if an expression evaluates to this, then |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2853 the tag (in the case of a ``tal:replace``), its contents (in the case |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2854 of ``tal:content``) or some attributes (in the case of |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2855 ``tal:attributes``) will not appear in the the output. So, for |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2856 example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2857 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2858 <span tal:attributes="class nothing">Hello, World!</span> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2859 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2860 would result in:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2861 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2862 <span>Hello, World!</span> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2863 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2864 **default** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2865 Also a special variable - if an expression evaluates to this, then the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2866 existing HTML in the template will not be replaced or removed, it will |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2867 remain. So:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2868 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2869 <span tal:replace="default">Hello, World!</span> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2870 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2871 would result in:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2872 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2873 <span>Hello, World!</span> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2874 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2875 **true**, **false** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2876 Boolean constants that may be used in `templating expressions`_ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2877 instead of ``python:1`` and ``python:0``. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2878 **i18n** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2879 Internationalization service, providing two string translation methods: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2880 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2881 **gettext** (*message*) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2882 Return the localized translation of message |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2883 **ngettext** (*singular*, *plural*, *number*) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2884 Like ``gettext()``, but consider plural forms. If a translation |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2885 is found, apply the plural formula to *number*, and return the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2886 resulting message (some languages have more than two plural forms). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2887 If no translation is found, return singular if *number* is 1; |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2888 return plural otherwise. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2889 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2890 The context variable |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2891 ~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2892 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2893 The *context* variable is one of three things based on the current |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2894 context (see `determining web context`_ for how we figure this out): |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2895 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2896 1. if we're looking at a "home" page, then it's None |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2897 2. if we're looking at a specific hyperdb class, it's a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2898 `hyperdb class wrapper`_. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2899 3. if we're looking at a specific hyperdb item, it's a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2900 `hyperdb item wrapper`_. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2901 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2902 If the context is not None, we can access the properties of the class or |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2903 item. The only real difference between cases 2 and 3 above are: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2904 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2905 1. the properties may have a real value behind them, and this will |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2906 appear if the property is displayed through ``context/property`` or |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2907 ``context/property/field``. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2908 2. the context's "id" property will be a false value in the second case, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2909 but a real, or true value in the third. Thus we can determine whether |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2910 we're looking at a real item from the hyperdb by testing |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2911 "context/id". |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2912 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2913 Hyperdb class wrapper |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2914 ::::::::::::::::::::: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2915 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2916 This is implemented by the ``roundup.cgi.templating.HTMLClass`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2917 class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2918 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2919 This wrapper object provides access to a hyperdb class. It is used |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2920 primarily in both index view and new item views, but it's also usable |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2921 anywhere else that you wish to access information about a class, or the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2922 items of a class, when you don't have a specific item of that class in |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2923 mind. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2924 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2925 We allow access to properties. There will be no "id" property. The value |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2926 accessed through the property will be the current value of the same name |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2927 from the CGI form. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2928 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2929 There are several methods available on these wrapper objects: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2930 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2931 =========== ============================================================= |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2932 Method Description |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2933 =========== ============================================================= |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2934 properties return a `hyperdb property wrapper`_ for all of this class's |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2935 properties that are searchable by the user. You can use |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2936 the argument cansearch=False to get all properties. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2937 list lists all of the active (not retired) items in the class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2938 csv return the items of this class as a chunk of CSV text. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2939 propnames lists the names of the properties of this class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2940 filter lists of items from this class, filtered and sorted. Two |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2941 options are available for sorting: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2942 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2943 1. by the current *request* filterspec/filter/sort/group args |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2944 2. by the "filterspec", "sort" and "group" keyword args. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2945 "filterspec" is ``{propname: value(s)}``. "sort" and |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2946 "group" are an optionally empty list ``[(dir, prop)]`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2947 where dir is '+', '-' or None |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2948 and prop is a prop name or None. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2949 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2950 The propname in filterspec and prop in a sort/group spec |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2951 may be transitive, i.e., it may contain properties of |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2952 the form link.link.link.name. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2953 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2954 eg. All issues with a priority of "1" with messages added in |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2955 the last week, sorted by activity date: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2956 ``issue.filter(filterspec={"priority": "1", |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2957 'messages.creation' : '.-1w;'}, sort=[('activity', '+')])`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2958 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2959 Note that when searching for Link and Multilink values, the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2960 special value '-1' searches for empty Link or Multilink |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2961 values. For both, Links and Multilinks, multiple values |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2962 given in a filter call are combined with 'OR' by default. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2963 For Multilinks a postfix expression syntax using negative ID |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2964 numbers (as strings) as operators is supported. Each |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2965 non-negative number (or '-1') is pushed on an operand stack. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2966 A negative number pops the required number of arguments from |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2967 the stack, applies the operator, and pushes the result. The |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2968 following operators are supported: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2969 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2970 - '-2' stands for 'NOT' and takes one argument |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2971 - '-3' stands for 'AND' and takes two arguments |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2972 - '-4' stands for 'OR' and takes two arguments |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2973 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2974 Note that this special handling of ID arguments is applied only |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2975 when a negative number smaller than -1 is encountered as an ID |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2976 in the filter call. Otherwise the implicit OR default |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2977 applies. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2978 Examples of using Multilink expressions would be |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2979 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2980 - '1', '2', '-4', '3', '4', '-4', '-3' |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2981 would search for IDs (1 or 2) and (3 or 4) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2982 - '-1' '-2' would search for all non-empty Multilinks |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2983 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2984 filter_sql **Only in SQL backends** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2985 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2986 Lists the items that match the SQL provided. The SQL is a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2987 complete "select" statement. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2988 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2989 The SQL select must include the item id as the first column. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2990 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2991 This function **does not** filter out retired items, add |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2992 on a where clause "__retired__ <> 1" if you don't want |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2993 retired nodes. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2994 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2995 classhelp display a link to a javascript popup containing this class' |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2996 "help" template. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2997 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2998 This generates a link to a popup window which displays the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2999 properties indicated by "properties" of the class named by |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3000 "classname". The "properties" should be a comma-separated list |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3001 (eg. 'id,name,description'). Properties defaults to all the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3002 properties of a class (excluding id, creator, created and |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3003 activity). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3004 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3005 You may optionally override the "label" displayed, the "width", |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3006 the "height", the number of items per page ("pagesize") and |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3007 the field on which the list is sorted ("sort"). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3008 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3009 With the "filter" arg it is possible to specify a filter for |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3010 which items are supposed to be displayed. It has to be of |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3011 the format "<field>=<values>;<field>=<values>;...". |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3012 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3013 The popup window will be resizable and scrollable. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3014 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3015 If the "property" arg is given, it's passed through to the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3016 javascript help_window function. This allows updating of a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3017 property in the calling HTML page. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3018 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3019 If the "form" arg is given, it's passed through to the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3020 javascript help_window function - it's the name of the form |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3021 the "property" belongs to. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3022 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3023 submit generate a submit button (and action and @csrf hidden elements) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3024 renderWith render this class with the given template. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3025 history returns 'New node - no history' :) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3026 is_edit_ok is the user allowed to Edit the current class? |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3027 is_view_ok is the user allowed to View the current class? |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3028 =========== ============================================================= |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3029 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3030 Note that if you have a property of the same name as one of the above |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3031 methods, you'll need to access it using a python "item access" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3032 expression. For example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3033 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3034 python:context['list'] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3035 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3036 will access the "list" property, rather than the list method. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3037 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3038 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3039 Hyperdb item wrapper |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3040 :::::::::::::::::::: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3041 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3042 This is implemented by the ``roundup.cgi.templating.HTMLItem`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3043 class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3044 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3045 This wrapper object provides access to a hyperdb item. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3046 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3047 We allow access to properties. There will be no "id" property. The value |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3048 accessed through the property will be the current value of the same name |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3049 from the CGI form. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3050 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3051 There are several methods available on these wrapper objects: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3052 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3053 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3054 Method Description |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3055 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3056 submit generate a submit button (and action and @csrf hidden elements) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3057 journal return the journal of the current item (**not |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3058 implemented**) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3059 history render the journal of the current item as |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3060 HTML. By default properties marked as "quiet" (see |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3061 `design documentation`_) are not shown unless the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3062 function is called with the showall=True parameter. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3063 Properties that are not Viewable to the user are not |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3064 shown. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3065 renderQueryForm specific to the "query" class - render the search form |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3066 for the query |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3067 hasPermission specific to the "user" class - determine whether the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3068 user has a Permission. The signature is:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3069 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3070 hasPermission(self, permission, [classname=], |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3071 [property=], [itemid=]) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3072 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3073 where the classname defaults to the current context. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3074 hasRole specific to the "user" class - determine whether the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3075 user has a Role. The signature is:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3076 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3077 hasRole(self, rolename) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3078 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3079 is_edit_ok is the user allowed to Edit the current item? |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3080 is_view_ok is the user allowed to View the current item? |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3081 is_retired is the item retired? |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3082 download_url generate a url-quoted link for download of FileClass |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3083 item contents (ie. file<id>/<name>) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3084 copy_url generate a url-quoted link for creating a copy |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3085 of this item. By default, the copy will acquire |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3086 all properties of the current item except for |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3087 ``messages`` and ``files``. This can be overridden |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3088 by passing ``exclude`` argument which contains a list |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3089 (or any iterable) of property names that shall not be |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3090 copied. Database-driven properties like ``id`` or |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3091 ``activity`` cannot be copied. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3092 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3093 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3094 Note that if you have a property of the same name as one of the above |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3095 methods, you'll need to access it using a python "item access" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3096 expression. For example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3097 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3098 python:context['journal'] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3099 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3100 will access the "journal" property, rather than the journal method. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3101 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3102 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3103 Hyperdb property wrapper |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3104 :::::::::::::::::::::::: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3105 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3106 This is implemented by subclasses of the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3107 ``roundup.cgi.templating.HTMLProperty`` class (``HTMLStringProperty``, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3108 ``HTMLNumberProperty``, and so on). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3109 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3110 This wrapper object provides access to a single property of a class. Its |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3111 value may be either: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3112 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3113 1. if accessed through a `hyperdb item wrapper`_, then it's a value from |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3114 the hyperdb |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3115 2. if access through a `hyperdb class wrapper`_, then it's a value from |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3116 the CGI form |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3117 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3118 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3119 The property wrapper has some useful attributes: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3120 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3121 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3122 Attribute Description |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3123 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3124 _name the name of the property |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3125 _value the value of the property if any - this is the actual |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3126 value retrieved from the hyperdb for this property |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3127 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3128 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3129 There are several methods available on these wrapper objects: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3130 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3131 =========== ================================================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3132 Method Description |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3133 =========== ================================================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3134 plain render a "plain" representation of the property. This method |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3135 may take two arguments: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3136 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3137 escape |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3138 If true, escape the text so it is HTML safe (default: no). The |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3139 reason this defaults to off is that text is usually escaped |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3140 at a later stage by the TAL commands, unless the "structure" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3141 option is used in the template. The following ``tal:content`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3142 expressions are all equivalent:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3143 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3144 "structure python:msg.content.plain(escape=1)" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3145 "python:msg.content.plain()" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3146 "msg/content/plain" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3147 "msg/content" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3148 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3149 Usually you'll only want to use the escape option in a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3150 complex expression. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3151 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3152 hyperlink |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3153 If true, turn URLs, email addresses and hyperdb item |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3154 designators in the text into hyperlinks (default: no). Note |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3155 that you'll need to use the "structure" TAL option if you |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3156 want to use this ``tal:content`` expression:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3157 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3158 "structure python:msg.content.plain(hyperlink=1)" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3159 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3160 The text is automatically HTML-escaped before the hyperlinking |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3161 transformation done in the plain() method. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3162 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3163 hyperlinked The same as msg.content.plain(hyperlink=1), but nicer:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3164 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3165 "structure msg/content/hyperlinked" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3166 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3167 field render an appropriate form edit field for the property - for |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3168 most types this is a text entry box, but for Booleans it's a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3169 tri-state yes/no/neither selection. This method may take some |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3170 arguments: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3171 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3172 size |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3173 Sets the width in characters of the edit field |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3174 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3175 format (Date properties only) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3176 Sets the format of the date in the field - uses the same |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3177 format string argument as supplied to the ``pretty`` method |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3178 below. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3179 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3180 popcal (Date properties only) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3181 Include the Javascript-based popup calendar for date |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3182 selection. Defaults to on. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3183 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3184 stext only on String properties - render the value of the property |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3185 as StructuredText (requires the StructureText module to be |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3186 installed separately) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3187 multiline only on String properties - render a multiline form edit |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3188 field for the property |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3189 email only on String properties - render the value of the property |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3190 as an obscured email address |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3191 url_quote only on String properties. It quotes any characters in the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3192 string so it is safe to use in a url. E.G. a space is |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3193 replaced with %20. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3194 confirm only on Password properties - render a second form edit field |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3195 for the property, used for confirmation that the user typed |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3196 the password correctly. Generates a field with name |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3197 "name:confirm". |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3198 now only on Date properties - return the current date as a new |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3199 property |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3200 reldate only on Date properties - render the interval between the date |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3201 and now |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3202 local only on Date properties - return this date as a new property |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3203 with some timezone offset, for example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3204 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3205 python:context.creation.local(10) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3206 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3207 will render the date with a +10 hour offset. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3208 pretty Date properties - render the date as "dd Mon YYYY" (eg. "19 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3209 Mar 2004"). Takes an optional format argument, for example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3210 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3211 python:context.activity.pretty('%Y-%m-%d') |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3212 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3213 Will format as "2004-03-19" instead. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3214 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3215 Interval properties - render the interval in a pretty |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3216 format (eg. "yesterday"). The format arguments are those used |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3217 in the standard ``strftime`` call (see the `Python Library |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3218 Reference: time module`__) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3219 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3220 Number properties - takes a printf style format argument |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3221 (default: '%0.3f') and formats the number accordingly. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3222 If the value can't be converted, '' is returned if the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3223 value is ``None`` otherwise it is converted to a string. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3224 popcal Generate a link to a popup calendar which may be used to |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3225 edit the date field, for example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3226 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3227 <span tal:replace="structure context/due/popcal" /> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3228 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3229 you still need to include the ``field`` for the property, so |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3230 typically you'd have:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3231 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3232 <span tal:replace="structure context/due/field" /> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3233 <span tal:replace="structure context/due/popcal" /> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3234 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3235 menu only on Link and Multilink properties - render a form select |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3236 list for this property. Takes a number of optional arguments |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3237 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3238 size |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3239 is used to limit the length of the list labels |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3240 height |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3241 is used to set the <select> tag's "size" attribute |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3242 showid |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3243 includes the item ids in the list labels |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3244 additional |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3245 lists properties which should be included in the label |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3246 sort_on |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3247 indicates the property to sort the list on as (direction, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3248 (direction, property) where direction is '+' or '-'. A |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3249 single string with the direction prepended may be used. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3250 For example: ('-', 'order'), '+name'. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3251 value |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3252 gives a default value to preselect in the menu |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3253 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3254 The remaining keyword arguments are used as conditions for |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3255 filtering the items in the list - they're passed as the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3256 "filterspec" argument to a Class.filter() call. For example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3257 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3258 <span tal:replace="structure context/status/menu" /> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3259 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3260 <span tal:replace="python:context.status.menu(order='+name", |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3261 value='chatting', |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3262 filterspec={'status': '1,2,3,4'}" /> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3263 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3264 sorted only on Multilink properties - produce a list of the linked |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3265 items sorted by some property, for example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3266 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3267 python:context.files.sorted('creation') |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3268 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3269 Will list the files by upload date. While:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3270 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3271 python:context.files.sorted('creation', reverse=True) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3272 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3273 Will list the files by upload date in reverse order from |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3274 the prior example. If the property can be unset, you can |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3275 use the ``NoneFirst`` parameter to sort the None/Unset |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3276 values at the front or the end of the list. For example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3277 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3278 python:context.files.sorted('creation', NoneFirst=True) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3279 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3280 will sort files by creation date with files missing a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3281 creation date at the start of the list. The default for |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3282 ``NoneFirst`` is False so these files will sort at the end |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3283 by default. (Note creation date is never unset, but you |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3284 get the idea.) If you combine NoneFirst with |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3285 ``reverse=True`` the meaning of NoneFirst is inverted: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3286 True sorts None/unset at the end and False sorts at the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3287 beginning. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3288 reverse only on Multilink properties - produce a list of the linked |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3289 items in reverse order |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3290 isset returns True if the property has been set to a value |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3291 =========== ================================================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3292 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3293 __ https://docs.python.org/2/library/time.html |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3294 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3295 All of the above functions perform checks for permissions required to |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3296 display or edit the data they are manipulating. The simplest case is |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3297 editing an issue title. Including the expression:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3298 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3299 context/title/field |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3300 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3301 Will present the user with an edit field, if they have edit permission. If |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3302 not, then they will be presented with a static display if they have view |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3303 permission. If they don't even have view permission, then an error message |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3304 is raised, preventing the display of the page, indicating that they don't |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3305 have permission to view the information. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3306 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3307 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3308 The request variable |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3309 ~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3310 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3311 This is implemented by the ``roundup.cgi.templating.HTMLRequest`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3312 class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3313 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3314 The request variable is packed with information about the current |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3315 request. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3316 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3317 .. taken from ``roundup.cgi.templating.HTMLRequest`` docstring |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3318 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3319 =========== ============================================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3320 Variable Holds |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3321 =========== ============================================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3322 form the CGI form as a cgi.FieldStorage |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3323 env the CGI environment variables |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3324 base the base URL for this tracker |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3325 user a HTMLUser instance for this user |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3326 classname the current classname (possibly None) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3327 template the current template (suffix, also possibly None) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3328 form the current CGI form variables in a FieldStorage |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3329 =========== ============================================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3330 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3331 **Index page specific variables (indexing arguments)** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3332 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3333 =========== ============================================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3334 Variable Holds |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3335 =========== ============================================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3336 columns dictionary of the columns to display in an index page |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3337 show a convenience access to columns - request/show/colname will |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3338 be true if the columns should be displayed, false otherwise |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3339 sort index sort columns [(direction, column name)] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3340 group index grouping properties [(direction, column name)] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3341 filter properties to filter the index on |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3342 filterspec values to filter the index on (property=value, eg |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3343 ``priority=1`` or ``messages.author=42`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3344 search_text text to perform a full-text search on for an index |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3345 =========== ============================================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3346 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3347 There are several methods available on the request variable: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3348 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3349 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3350 Method Description |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3351 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3352 description render a description of the request - handle for the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3353 page title |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3354 indexargs_form render the current index args as form elements |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3355 indexargs_url render the current index args as a URL |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3356 base_javascript render some javascript that is used by other components |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3357 of the templating |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3358 batch run the current index args through a filter and return a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3359 list of items (see `hyperdb item wrapper`_, and |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3360 `batching`_) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3361 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3362 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3363 The form variable |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3364 ::::::::::::::::: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3365 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3366 The form variable is a bit special because it's actually a python |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3367 FieldStorage object. That means that you have two ways to access its |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3368 contents. For example, to look up the CGI form value for the variable |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3369 "name", use the path expression:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3370 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3371 request/form/name/value |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3372 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3373 or the python expression:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3374 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3375 python:request.form['name'].value |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3376 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3377 Note the "item" access used in the python case, and also note the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3378 explicit "value" attribute we have to access. That's because the form |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3379 variables are stored as MiniFieldStorages. If there's more than one |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3380 "name" value in the form, then the above will break since |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3381 ``request/form/name`` is actually a *list* of MiniFieldStorages. So it's |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3382 best to know beforehand what you're dealing with. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3383 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3384 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3385 The db variable |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3386 ~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3387 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3388 This is implemented by the ``roundup.cgi.templating.HTMLDatabase`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3389 class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3390 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3391 Allows access to all hyperdb classes as attributes of this variable. If |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3392 you want access to the "user" class, for example, you would use:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3393 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3394 db/user |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3395 python:db.user |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3396 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3397 Also, the current id of the current user is available as |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3398 ``db.getuid()``. This isn't so useful in templates (where you have |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3399 ``request/user``), but it can be useful in detectors or interfaces. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3400 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3401 The access results in a `hyperdb class wrapper`_. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3402 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3403 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3404 The templates variable |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3405 ~~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3406 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3407 This was implemented by the ``roundup.cgi.templating.Templates`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3408 class before 1.4.20. In later versions it is the instance of appropriate |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3409 template engine loader class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3410 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3411 This variable is used to access other templates in expressions and |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3412 template macros. It doesn't have any useful methods defined. The |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3413 templates can be accessed using the following path expression:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3414 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3415 templates/name |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3416 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3417 or the python expression:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3418 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3419 templates[name] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3420 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3421 where "name" is the name of the template you wish to access. The |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3422 template has one useful attribute, namely "macros". To access a specific |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3423 macro (called "macro_name"), use the path expression:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3424 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3425 templates/name/macros/macro_name |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3426 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3427 or the python expression:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3428 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3429 templates[name].macros[macro_name] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3430 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3431 The repeat variable |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3432 ~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3433 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3434 The repeat variable holds an entry for each active iteration. That is, if |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3435 you have a ``tal:repeat="user db/users"`` command, then there will be a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3436 repeat variable entry called "user". This may be accessed as either:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3437 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3438 repeat/user |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3439 python:repeat['user'] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3440 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3441 The "user" entry has a number of methods available for information: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3442 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3443 =============== ========================================================= |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3444 Method Description |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3445 =============== ========================================================= |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3446 first True if the current item is the first in the sequence. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3447 last True if the current item is the last in the sequence. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3448 even True if the current item is an even item in the sequence. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3449 odd True if the current item is an odd item in the sequence. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3450 number Current position in the sequence, starting from 1. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3451 letter Current position in the sequence as a letter, a through |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3452 z, then aa through zz, and so on. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3453 Letter Same as letter(), except uppercase. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3454 roman Current position in the sequence as lowercase roman |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3455 numerals. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3456 Roman Same as roman(), except uppercase. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3457 =============== ========================================================= |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3458 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3459 .. _templating utilities: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3460 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3461 The utils variable |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3462 ~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3463 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3464 This is implemented by the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3465 ``roundup.cgi.templating.TemplatingUtils`` class, which may be extended |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3466 with additional methods by extensions_. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3467 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3468 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3469 Method Description |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3470 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3471 Batch return a batch object using the supplied list |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3472 url_quote quote some text as safe for a URL (ie. space, %, ...) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3473 html_quote quote some text as safe in HTML (ie. <, >, ...) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3474 html_calendar renders an HTML calendar used by the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3475 ``_generic.calendar.html`` template (itself invoked by |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3476 the popupCalendar DateHTMLProperty method |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3477 anti_csrf_nonce returns the random noncue generated for this session |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3478 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3479 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3480 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3481 Batching |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3482 :::::::: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3483 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3484 Use Batch to turn a list of items, or item ids of a given class, into a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3485 series of batches. Its usage is:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3486 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3487 python:utils.Batch(sequence, size, start, end=0, orphan=0, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3488 overlap=0) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3489 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3490 or, to get the current index batch:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3491 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3492 request/batch |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3493 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3494 The parameters are: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3495 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3496 ========= ============================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3497 Parameter Usage |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3498 ========= ============================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3499 sequence a list of HTMLItems |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3500 size how big to make the sequence. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3501 start where to start (0-indexed) in the sequence. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3502 end where to end (0-indexed) in the sequence. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3503 orphan if the next batch would contain less items than this value, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3504 then it is combined with this batch |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3505 overlap the number of items shared between adjacent batches |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3506 ========= ============================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3507 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3508 All of the parameters are assigned as attributes on the batch object. In |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3509 addition, it has several more attributes: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3510 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3511 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3512 Attribute Description |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3513 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3514 start indicates the start index of the batch. *Unlike |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3515 the argument, is a 1-based index (I know, lame)* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3516 first indicates the start index of the batch *as a 0-based |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3517 index* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3518 length the actual number of elements in the batch |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3519 sequence_length the length of the original, unbatched, sequence. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3520 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3521 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3522 And several methods: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3523 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3524 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3525 Method Description |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3526 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3527 previous returns a new Batch with the previous batch settings |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3528 next returns a new Batch with the next batch settings |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3529 propchanged detect if the named property changed on the current item |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3530 when compared to the last item |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3531 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3532 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3533 An example of batching:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3534 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3535 <table class="otherinfo"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3536 <tr><th colspan="4" class="header">Existing Keywords</th></tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3537 <tr tal:define="keywords db/keyword/list" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3538 tal:repeat="start python:range(0, len(keywords), 4)"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3539 <td tal:define="batch python:utils.Batch(keywords, 4, start)" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3540 tal:repeat="keyword batch" tal:content="keyword/name"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3541 keyword here</td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3542 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3543 </table> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3544 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3545 ... which will produce a table with four columns containing the items of |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3546 the "keyword" class (well, their "name" anyway). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3547 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3548 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3549 Translations |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3550 ~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3551 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3552 Should you wish to enable multiple languages in template content that you |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3553 create you'll need to add new locale files in the tracker home under a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3554 ``locale`` directory. Use the `translation instructions in the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3555 developer's guide <developers.html#extracting-translatable-messages>`_ to |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3556 create the locale files. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3557 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3558 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3559 Displaying Properties |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3560 --------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3561 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3562 Properties appear in the user interface in three contexts: in indices, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3563 in editors, and as search arguments. For each type of property, there |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3564 are several display possibilities. For example, in an index view, a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3565 string property may just be printed as a plain string, but in an editor |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3566 view, that property may be displayed in an editable field. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3567 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3568 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3569 Index Views |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3570 ----------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3571 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3572 This is one of the class context views. It is also the default view for |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3573 classes. The template used is "*classname*.index". |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3574 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3575 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3576 Index View Specifiers |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3577 ~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3578 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3579 An index view specifier (URL fragment) looks like this (whitespace has |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3580 been added for clarity):: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3581 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3582 /issue?status=unread,in-progress,resolved& |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3583 keyword=security,ui& |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3584 @group=priority,-status& |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3585 @sort=-activity& |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3586 @filters=status,keyword& |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3587 @columns=title,status,fixer |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3588 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3589 The index view is determined by two parts of the specifier: the layout |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3590 part and the filter part. The layout part consists of the query |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3591 parameters that begin with colons, and it determines the way that the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3592 properties of selected items are displayed. The filter part consists of |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3593 all the other query parameters, and it determines the criteria by which |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3594 items are selected for display. The filter part is interactively |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3595 manipulated with the form widgets displayed in the filter section. The |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3596 layout part is interactively manipulated by clicking on the column |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3597 headings in the table. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3598 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3599 The filter part selects the union of the sets of items with values |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3600 matching any specified Link properties and the intersection of the sets |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3601 of items with values matching any specified Multilink properties. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3602 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3603 The example specifies an index of "issue" items. Only items with a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3604 "status" of either "unread" or "in-progress" or "resolved" are |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3605 displayed, and only items with "keyword" values including both "security" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3606 and "ui" are displayed. The items are grouped by priority arranged in |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3607 ascending order and in descending order by status; and within |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3608 groups, sorted by activity, arranged in descending order. The filter |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3609 section shows filters for the "status" and "keyword" properties, and the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3610 table includes columns for the "title", "status", and "fixer" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3611 properties. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3612 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3613 ============ ============================================================= |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3614 Argument Description |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3615 ============ ============================================================= |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3616 @sort sort by prop name, optionally preceeded with '-' to give |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3617 descending or nothing for ascending sorting. Several |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3618 properties can be specified delimited with comma. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3619 Internally a search-page using several sort properties may |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3620 use @sort0, @sort1 etc. with option @sortdir0, @sortdir1 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3621 etc. for the direction of sorting (a non-empty value of |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3622 sortdir0 specifies reverse order). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3623 @group group by prop name, optionally preceeded with '-' or to sort |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3624 in descending or nothing for ascending order. Several |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3625 properties can be specified delimited with comma. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3626 Internally a search-page using several grouping properties may |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3627 use @group0, @group1 etc. with option @groupdir0, @groupdir1 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3628 etc. for the direction of grouping (a non-empty value of |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3629 groupdir0 specifies reverse order). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3630 @columns selects the columns that should be displayed. Default is |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3631 all. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3632 @filter indicates which properties are being used in filtering. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3633 Default is none. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3634 propname selects the values the item properties given by propname must |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3635 have (very basic search/filter). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3636 @search_text if supplied, performs a full-text search (message bodies, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3637 issue titles, etc) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3638 ============ ============================================================= |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3639 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3640 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3641 Searching Views |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3642 --------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3643 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3644 .. note:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3645 if you add a new column to the ``@columns`` form variable potentials |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3646 then you will need to add the column to the appropriate `index views`_ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3647 template so that it is actually displayed. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3648 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3649 This is one of the class context views. The template used is typically |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3650 "*classname*.search". The form on this page should have "search" as its |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3651 ``@action`` variable. The "search" action: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3652 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3653 - sets up additional filtering, as well as performing indexed text |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3654 searching |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3655 - sets the ``@filter`` variable correctly |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3656 - saves the query off if ``@query_name`` is set. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3657 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3658 The search page should lay out any fields that you wish to allow the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3659 user to search on. If your schema contains a large number of properties, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3660 you should be wary of making all of those properties available for |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3661 searching, as this can cause confusion. If the additional properties are |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3662 Strings, consider having their value indexed, and then they will be |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3663 searchable using the full text indexed search. This is both faster, and |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3664 more useful for the end user. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3665 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3666 If the search view does specify the "search" ``@action``, then it may also |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3667 provide an additional argument: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3668 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3669 ============ ============================================================= |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3670 Argument Description |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3671 ============ ============================================================= |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3672 @query_name if supplied, the index parameters (including @search_text) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3673 will be saved off as a the query item and registered against |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3674 the user's queries property. Note that the *classic* template |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3675 schema has this ability, but the *minimal* template schema |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3676 does not. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3677 ============ ============================================================= |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3678 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3679 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3680 Item Views |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3681 ---------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3682 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3683 The basic view of a hyperdb item is provided by the "*classname*.item" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3684 template. It generally has three sections; an "editor", a "spool" and a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3685 "history" section. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3686 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3687 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3688 Editor Section |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3689 ~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3690 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3691 The editor section is used to manipulate the item - it may be a static |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3692 display if the user doesn't have permission to edit the item. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3693 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3694 Here's an example of a basic editor template (this is the default |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3695 "classic" template issue item edit form - from the "issue.item.html" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3696 template):: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3697 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3698 <table class="form"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3699 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3700 <th>Title</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3701 <td colspan="3" tal:content="structure python:context.title.field(size=60)">title</td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3702 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3703 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3704 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3705 <th>Priority</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3706 <td tal:content="structure context/priority/menu">priority</td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3707 <th>Status</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3708 <td tal:content="structure context/status/menu">status</td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3709 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3710 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3711 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3712 <th>Superseder</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3713 <td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3714 <span tal:replace="structure python:context.superseder.field(showid=1, size=20)" /> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3715 <span tal:replace="structure python:db.issue.classhelp('id,title')" /> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3716 <span tal:condition="context/superseder"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3717 <br>View: <span tal:replace="structure python:context.superseder.link(showid=1)" /> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3718 </span> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3719 </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3720 <th>Nosy List</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3721 <td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3722 <span tal:replace="structure context/nosy/field" /> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3723 <span tal:replace="structure python:db.user.classhelp('username,realname,address,phone')" /> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3724 </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3725 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3726 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3727 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3728 <th>Assigned To</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3729 <td tal:content="structure context/assignedto/menu"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3730 assignedto menu |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3731 </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3732 <td> </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3733 <td> </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3734 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3735 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3736 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3737 <th>Change Note</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3738 <td colspan="3"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3739 <textarea name=":note" wrap="hard" rows="5" cols="60"></textarea> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3740 </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3741 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3742 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3743 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3744 <th>File</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3745 <td colspan="3"><input type="file" name=":file" size="40"></td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3746 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3747 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3748 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3749 <td> </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3750 <td colspan="3" tal:content="structure context/submit"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3751 submit button will go here |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3752 </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3753 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3754 </table> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3755 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3756 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3757 When a change is submitted, the system automatically generates a message |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3758 describing the changed properties. As shown in the example, the editor |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3759 template can use the ":note" and ":file" fields, which are added to the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3760 standard changenote message generated by Roundup. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3761 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3762 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3763 Form values |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3764 ::::::::::: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3765 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3766 We have a number of ways to pull properties out of the form in order to |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3767 meet the various needs of: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3768 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3769 1. editing the current item (perhaps an issue item) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3770 2. editing information related to the current item (eg. messages or |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3771 attached files) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3772 3. creating new information to be linked to the current item (eg. time |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3773 spent on an issue) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3774 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3775 In the following, ``<bracketed>`` values are variable, ":" may be one of |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3776 ":" or "@", and other text ("required") is fixed. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3777 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3778 Properties are specified as form variables: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3779 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3780 ``<propname>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3781 property on the current context item |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3782 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3783 ``<designator>:<propname>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3784 property on the indicated item (for editing related information) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3785 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3786 ``<classname>-<N>:<propname>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3787 property on the Nth new item of classname (generally for creating new |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3788 items to attach to the current item) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3789 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3790 Once we have determined the "propname", we check to see if it is one of |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3791 the special form values: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3792 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3793 ``@required`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3794 The named property values must be supplied or a ValueError will be |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3795 raised. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3796 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3797 ``@remove@<propname>=id(s)`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3798 The ids will be removed from the multilink property. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3799 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3800 ``:add:<propname>=id(s)`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3801 The ids will be added to the multilink property. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3802 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3803 ``:link:<propname>=<designator>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3804 Used to add a link to new items created during edit. These are |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3805 collected and returned in ``all_links``. This will result in an |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3806 additional linking operation (either Link set or Multilink append) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3807 after the edit/create is done using ``all_props`` in ``_editnodes``. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3808 The <propname> on the current item will be set/appended the id of the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3809 newly created item of class <designator> (where <designator> must be |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3810 <classname>-<N>). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3811 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3812 Any of the form variables may be prefixed with a classname or |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3813 designator. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3814 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3815 Two special form values are supported for backwards compatibility: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3816 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3817 ``:note`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3818 create a message (with content, author and date), linked to the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3819 context item. This is ALWAYS designated "msg-1". |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3820 ``:file`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3821 create a file, attached to the current item and any message created by |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3822 :note. This is ALWAYS designated "file-1". |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3823 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3824 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3825 Spool Section |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3826 ~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3827 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3828 The spool section lists related information like the messages and files |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3829 of an issue. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3830 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3831 TODO |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3832 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3833 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3834 History Section |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3835 ~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3836 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3837 The final section displayed is the history of the item - its database |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3838 journal. This is generally generated with the template:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3839 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3840 <tal:block tal:replace="structure context/history" /> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3841 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3842 or:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3843 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3844 <tal:block |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3845 tal:replace="structure python:context.history(showall=True)" /> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3846 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3847 if you want to show history entries for quiet properties. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3848 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3849 *To be done:* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3850 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3851 *The actual history entries of the item may be accessed for manual |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3852 templating through the "journal" method of the item*:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3853 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3854 <tal:block tal:repeat="entry context/journal"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3855 a journal entry |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3856 </tal:block> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3857 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3858 *where each journal entry is an HTMLJournalEntry.* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3859 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3860 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3861 Defining new web actions |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3862 ------------------------ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3863 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3864 You may define new actions to be triggered by the ``@action`` form variable. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3865 These are added to the tracker ``extensions`` directory and registered |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3866 using ``instance.registerAction``. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3867 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3868 All the existing Actions are defined in ``roundup.cgi.actions``. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3869 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3870 Adding action classes takes three steps; first you `define the new |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3871 action class`_, then you `register the action class`_ with the cgi |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3872 interface so it may be triggered by the ``@action`` form variable. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3873 Finally you `use the new action`_ in your HTML form. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3874 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3875 See `setting up a "wizard" (or "druid") for controlled adding of |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3876 issues |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3877 <customizing.html#setting-up-a-wizard-or-druid-for-controlled-adding-of-issues>`_ for an example. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3878 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3879 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3880 Define the new action class |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3881 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3882 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3883 Create a new action class in your tracker's ``extensions`` directory, for |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3884 example ``myaction.py``:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3885 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3886 from roundup.cgi.actions import Action |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3887 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3888 class MyAction(Action): |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3889 def handle(self): |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3890 ''' Perform some action. No return value is required. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3891 ''' |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3892 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3893 The *self.client* attribute is an instance of ``roundup.cgi.client.Client``. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3894 See the docstring of that class for details of what it can do. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3895 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3896 The method will typically check the ``self.form`` variable's contents. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3897 It may then: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3898 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3899 - add information to ``self.client._ok_message`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3900 or ``self.client._error_message`` (by using ``self.client.add_ok_message`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3901 or ``self.client.add_error_message``, respectively) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3902 - change the ``self.client.template`` variable to alter what the user will see |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3903 next |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3904 - raise Unauthorised, SendStaticFile, SendFile, NotFound or Redirect |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3905 exceptions (import them from roundup.cgi.exceptions) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3906 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3907 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3908 Register the action class |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3909 ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3910 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3911 The class is now written, but isn't available to the user until you register |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3912 it with the following code appended to your ``myaction.py`` file:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3913 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3914 def init(instance): |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3915 instance.registerAction('myaction', myActionClass) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3916 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3917 This maps the action name "myaction" to the action class we defined. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3918 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3919 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3920 Use the new action |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3921 ~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3922 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3923 In your HTML form, add a hidden form element like so:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3924 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3925 <input type="hidden" name="@action" value="myaction"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3926 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3927 where "myaction" is the name you registered in the previous step. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3928 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3929 Actions may return content to the user |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3930 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3931 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3932 Actions generally perform some database manipulation and then pass control |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3933 on to the rendering of a template in the current context (see `Determining |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3934 web context`_ for how that works.) Some actions will want to generate the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3935 actual content returned to the user. Action methods may return their own |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3936 content string to be displayed to the user, overriding the templating step. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3937 In this situation, we assume that the content is HTML by default. You may |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3938 override the content type indicated to the user by calling ``setHeader``:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3939 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3940 self.client.setHeader('Content-Type', 'text/csv') |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3941 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3942 This example indicates that the value sent back to the user is actually |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3943 comma-separated value content (eg. something to be loaded into a |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3944 spreadsheet or database). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3945 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3946 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3947 8-bit character set support in Web interface |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3948 -------------------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3949 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3950 The web interface uses UTF-8 default. It may be overridden in both forms |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3951 and a browser cookie. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3952 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3953 - In forms, use the ``@charset`` variable. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3954 - To use the cookie override, have the ``roundup_charset`` cookie set. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3955 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3956 In both cases, the value is a valid charset name (eg. ``utf-8`` or |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3957 ``kio8-r``). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3958 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3959 Inside Roundup, all strings are stored and processed in utf-8. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3960 Unfortunately, some older browsers do not work properly with |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3961 utf-8-encoded pages (e.g. Netscape Navigator 4 displays wrong |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3962 characters in form fields). This version allows one to change |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3963 the character set for http transfers. To do so, you may add |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3964 the following code to your ``page.html`` template:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3965 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3966 <tal:block define="uri string:${request/base}${request/env/PATH_INFO}"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3967 <a tal:attributes="href python:request.indexargs_url(uri, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3968 {'@charset':'utf-8'})">utf-8</a> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3969 <a tal:attributes="href python:request.indexargs_url(uri, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3970 {'@charset':'koi8-r'})">koi8-r</a> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3971 </tal:block> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3972 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3973 (substitute ``koi8-r`` with appropriate charset for your language). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3974 Charset preference is kept in the browser cookie ``roundup_charset``. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3975 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3976 ``meta http-equiv`` lines added to the tracker templates in version 0.6.0 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3977 should be changed to include actual character set name:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3978 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3979 <meta http-equiv="Content-Type" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3980 tal:attributes="content string:text/html;; charset=${request/client/charset}" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3981 /> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3982 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3983 The charset is also sent in the http header. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3984 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3985 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3986 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3987 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3988 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3989 Debugging Trackers |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3990 ================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3991 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3992 There are three switches in tracker configs that turn on debugging in |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3993 Roundup: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3994 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3995 1. web :: debug |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3996 2. mail :: debug |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3997 3. logging :: level |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3998 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3999 See the config.ini file or the `tracker configuration`_ section for |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4000 more information. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4001 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4002 Additionally, the ``roundup-server.py`` script has its own debugging mode |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4003 in which it reloads edited templates immediately when they are changed, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4004 rather than requiring a web server restart. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4005 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4006 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4007 .. _`design documentation`: design.html |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4008 .. _change the rate limiting method: rest.html#creating-custom-rate-limits |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4009 .. _`directions in the rest interface documentation`: rest.html#enabling-the-rest-api |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4010 .. _`xmlrpc interface documentation`: xmlrpc.html#through-roundup |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
4011 |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
4012 .. allow line breaks in term definitions. |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
4013 .. |br| raw:: html |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
4014 |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
4015 <br/> |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
4016 |
