Mercurial > p > roundup > code
annotate doc/reference.txt @ 7695:2be7a8f66ea7
fix: windows install using pip mislocates share directory
The setup code that tries to make the share install path absolute
prependeds something like:
c:\program files\python_venv
to the paths. The equivalent on linux is recognized as an absolute
path. On windows this is treated oddly. This resulted in
the share files being placed in:
c:\program files\python_venv\Lib\site-packages\program files\python_venv\share
Roundup was unable to find the files there. On windows (where the
platform starts with 'win') don't make the path absolute. This puts
share in:
c:\program files\python_venv\Lib\share
and Roundup finds them.
The translations and templates are found by the roundup-server.
The docs are also installed under the share directory. The man pages
are not installed as windows doesn't have groff to format the source
documents.
This is the second fix from issues getting Roundup running on windows
discussed on mailing list by Simon Eigeldinger.
Thread starts with:
https://sourceforge.net/p/roundup/mailman/message/41557096/
subject: Installing Roundup on Windows 2023-10-05.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Sun, 05 Nov 2023 23:01:29 -0500 |
| parents | c09192e21faa |
| children | 4af0d235b570 |
| 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 |
|
7499
a072331c843b
Change customizing to customising in all variants.
John Rouillard <rouilj@ieee.org>
parents:
7482
diff
changeset
|
16 This document used to be part of the `customisation document`_. The |
|
a072331c843b
Change customizing to customising in all variants.
John Rouillard <rouilj@ieee.org>
parents:
7482
diff
changeset
|
17 customisation document was getting large and unwieldy. It was a |
|
7357
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 |
|
7499
a072331c843b
Change customizing to customising in all variants.
John Rouillard <rouilj@ieee.org>
parents:
7482
diff
changeset
|
20 were well answered in the customisation document, but finding the info |
|
7357
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 |
|
7527
b8f012c7c5a7
rework a confusing sentance.
John Rouillard <rouilj@ieee.org>
parents:
7499
diff
changeset
|
26 This document provides background for the tutorials |
|
b8f012c7c5a7
rework a confusing sentance.
John Rouillard <rouilj@ieee.org>
parents:
7499
diff
changeset
|
27 or how-tos in the customisation document. |
|
7499
a072331c843b
Change customizing to customising in all variants.
John Rouillard <rouilj@ieee.org>
parents:
7482
diff
changeset
|
28 |
|
a072331c843b
Change customizing to customising in all variants.
John Rouillard <rouilj@ieee.org>
parents:
7482
diff
changeset
|
29 .. _customisation document: customizing.html |
|
7357
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`` |
|
7658
d30e534b078a
clarify doc on dispatcher_email config setting.
John Rouillard <rouilj@ieee.org>
parents:
7638
diff
changeset
|
147 The 'dispatcher' is a role that can get notified when errors occur |
|
d30e534b078a
clarify doc on dispatcher_email config setting.
John Rouillard <rouilj@ieee.org>
parents:
7638
diff
changeset
|
148 while sending email to a user. It is used by the ERROR_MESSAGES_TO config |
|
d30e534b078a
clarify doc on dispatcher_email config setting.
John Rouillard <rouilj@ieee.org>
parents:
7638
diff
changeset
|
149 setting. If the email address doesn't contain an ``@`` part, the |
|
d30e534b078a
clarify doc on dispatcher_email config setting.
John Rouillard <rouilj@ieee.org>
parents:
7638
diff
changeset
|
150 MAIL_DOMAIN defined below is used. |
|
7352
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`` |
|
7457
d17e3dce28bc
Fix another xhtml reference.
John Rouillard <rouilj@ieee.org>
parents:
7456
diff
changeset
|
173 This setting should be left at the default value of html4. |
|
d17e3dce28bc
Fix another xhtml reference.
John Rouillard <rouilj@ieee.org>
parents:
7456
diff
changeset
|
174 Support is ending for xhtml mode. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
175 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
|
176 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
|
177 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
|
178 Allowed values: ``html4``, ``xhtml`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
179 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
180 timezone -- ``0`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
181 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
|
182 in their settings. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
183 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
184 instant_registration -- ``yes`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
185 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
|
186 email? |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
187 Allowed values: ``yes``, ``no`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
188 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
189 email_registration_confirmation -- ``yes`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
190 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
|
191 Allowed values: ``yes``, ``no`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
192 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
193 indexer_stopwords -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
194 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
|
195 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
|
196 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
|
197 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
198 umask -- ``02`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
199 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
|
200 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
201 csv_field_size -- ``131072`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
202 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
|
203 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
|
204 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
|
205 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
|
206 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
|
207 import. |
|
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 .. index:: config.ini; sections tracker |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
210 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
211 Section **tracker** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
212 name -- ``Roundup issue tracker`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
213 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
|
214 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
215 web -- ``http://host.example/demo/`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
216 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
|
217 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
|
218 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
|
219 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
|
220 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
|
221 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
222 email -- ``issue_tracker`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
223 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
|
224 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
225 language -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
226 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
|
227 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
|
228 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
|
229 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
230 .. index:: config.ini; sections web |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
231 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
232 Section **web** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
233 allow_html_file -- ``no`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
234 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
|
235 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
|
236 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
|
237 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
|
238 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
239 http_auth -- ``yes`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
240 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
|
241 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
|
242 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
|
243 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
|
244 Authentication in your web interface. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
245 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
246 use_browser_language -- ``yes`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
247 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
|
248 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
|
249 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
|
250 Operating System. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
251 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
|
252 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
253 debug -- ``no`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
254 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
|
255 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
|
256 tracker admin."), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
257 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
258 .. index:: config.ini; sections rdbms |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
259 single: config.ini; database settings |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
260 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
261 Section **rdbms** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
262 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
|
263 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
|
264 MySQL backends. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
265 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
266 .. index:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
267 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
|
268 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
|
269 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
|
270 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
|
271 see: database; postgres |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
272 see: database; mysql |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
273 see: database; sqlite |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
274 see: database; anydbm |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
275 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
276 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
|
277 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
|
278 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
279 name -- ``roundup`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
280 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
|
281 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
282 host -- ``localhost`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
283 Database server host. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
284 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
285 port -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
286 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
|
287 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
|
288 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
|
289 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
290 user -- ``roundup`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
291 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
|
292 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
293 password -- ``roundup`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
294 Database user password. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
295 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
296 read_default_file -- ``~/.my.cnf`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
297 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
|
298 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
299 read_default_group -- ``roundup`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
300 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
|
301 MySQL connections. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
302 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
303 .. index:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
304 single: sqlite; lock timeout |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
305 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
306 sqlite_timeout -- ``30`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
307 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
|
308 Used only for SQLite. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
309 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
310 cache_size -- `100` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
311 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
|
312 data in memory. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
313 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
314 .. index:: config.ini; sections logging |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
315 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
|
316 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
317 Section **logging** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
318 config -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
319 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
|
320 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
|
321 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
|
322 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
|
323 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
324 filename -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
325 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
|
326 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
|
327 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
|
328 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
|
329 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
330 level -- ``ERROR`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
331 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
|
332 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
|
333 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
|
334 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
335 .. index:: config.ini; sections mail |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
336 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
337 Section **mail** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
338 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
|
339 registration approval requests. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
340 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
341 domain -- ``localhost`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
342 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
|
343 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
344 host -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
345 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
|
346 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
347 username -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
348 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
|
349 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
|
350 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
351 password -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
352 SMTP login password. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
353 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
|
354 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
355 port -- default *25* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
356 SMTP port on mail host. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
357 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
|
358 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
359 local_hostname -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
360 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
|
361 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
|
362 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
|
363 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
364 tls -- ``no`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
365 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
|
366 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
|
367 Allowed values: ``yes``, ``no`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
368 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
369 tls_keyfile -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
370 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
|
371 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
|
372 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
|
373 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
374 tls_certfile -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
375 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
|
376 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
|
377 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
|
378 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
379 charset -- utf-8 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
380 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
|
381 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
|
382 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
|
383 (eg. iso-8859-1). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
384 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
385 debug -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
386 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
|
387 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
|
388 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
|
389 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
|
390 containig this config file. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
391 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
392 add_authorinfo -- ``yes`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
393 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
|
394 Roundup. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
395 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
396 add_authoremail -- ``yes`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
397 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
|
398 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
|
399 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
|
400 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
|
401 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
402 .. index:: config.ini; sections mailgw |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
403 single: mailgw; config |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
404 see: mail gateway; mailgw |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
405 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
406 Section **mailgw** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
407 Roundup Mail Gateway options |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
408 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
409 keep_quoted_text -- ``yes`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
410 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
|
411 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
|
412 Allowed values: ``yes``, ``no`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
413 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
414 leave_body_unchanged -- ``no`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
415 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
|
416 signatures. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
417 Allowed values: ``yes``, ``no`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
418 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
419 default_class -- ``issue`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
420 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
|
421 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
|
422 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
423 language -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
424 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
|
425 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
|
426 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
427 subject_prefix_parsing -- ``strict`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
428 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
|
429 ``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
|
430 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
|
431 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
|
432 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
|
433 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
434 subject_suffix_parsing -- ``strict`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
435 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
|
436 ``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
|
437 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
|
438 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
|
439 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
|
440 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
441 subject_suffix_delimiters -- ``[]`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
442 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
|
443 line. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
444 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
445 subject_content_match -- ``always`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
446 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
|
447 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
|
448 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
|
449 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
|
450 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
|
451 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
452 subject_updates_title -- ``yes`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
453 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
|
454 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
|
455 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
|
456 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
457 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
|
458 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
|
459 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
|
460 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
|
461 (UTF8-encoded). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
462 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
463 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
|
464 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
|
465 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
|
466 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
467 sign_re -- ``^[>|\s]*-- ?$`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
468 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
|
469 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
|
470 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
471 eol_re -- ``[\r\n]+`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
472 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
|
473 Expression (UTF8-encoded). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
474 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
475 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
|
476 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
|
477 Expression (UTF8-encoded). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
478 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
479 ignore_alternatives -- ``no`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
480 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
|
481 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
|
482 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
|
483 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
|
484 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
|
485 |
|
7559
b5dff5dd4763
Fix typo in index reference
John Rouillard <rouilj@ieee.org>
parents:
7527
diff
changeset
|
486 .. index:: config.ini; sections pgp |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
487 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
488 Section **pgp** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
489 OpenPGP mail processing options |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
490 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
491 enable -- ``no`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
492 Enable PGP processing. Requires gpg. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
493 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
494 roles -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
495 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
|
496 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
|
497 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
498 homedir -- default *blank* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
499 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
|
500 specified. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
501 |
|
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 .. index:: config.ini; sections nosy |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
504 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
505 Section **nosy** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
506 Nosy messages sending |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
507 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
508 messages_to_author -- ``no`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
509 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
|
510 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
|
511 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
|
512 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
|
513 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
|
514 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
515 signature_position -- ``bottom`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
516 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
|
517 Allowed values: ``top``, ``bottom``, ``none`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
518 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
519 add_author -- ``new`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
520 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
|
521 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
|
522 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
|
523 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
|
524 Allowed values: ``yes``, ``no``, ``new`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
525 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
526 add_recipients -- ``new`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
527 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
|
528 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
|
529 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
|
530 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
|
531 Allowed values: ``yes``, ``no``, ``new`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
532 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
533 email_sending -- ``single`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
534 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
|
535 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
|
536 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
|
537 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
538 max_attachment_size -- ``2147483647`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
539 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
|
540 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
|
541 download page for the file. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
542 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
543 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
544 .. 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
|
545 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
|
546 single: config.ini; create |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
547 single: config.ini; update |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
548 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
549 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
|
550 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
|
551 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
|
552 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
553 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
|
554 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
|
555 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
|
556 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
557 .. index:: pair: configuration; extensions |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
558 pair: configuration; detectors |
|
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 Extending the configuration file |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
561 -------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
562 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
563 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
|
564 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
|
565 |
|
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 ``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
|
567 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
|
568 - 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
|
569 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
|
570 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
571 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
|
572 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
573 [main] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
574 qa_recipients = email@example.com |
|
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 is accessible as:: |
|
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 db.config.detectors['QA_RECIPIENTS'] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
579 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
580 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
|
581 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
|
582 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
583 [qa] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
584 recipients = email@example.com |
|
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 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
|
587 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
588 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
|
589 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
|
590 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
|
591 "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
|
592 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
|
593 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
594 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
|
595 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
|
596 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
|
597 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
598 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
|
599 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
|
600 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
|
601 extensions_ or detectors_. |
|
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 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
|
604 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
605 from roundup.configuration import SecretMandatoryOption |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
606 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
607 def init(instance): |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
608 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
|
609 SecretMandatoryOption,description="Secret securing reCaptcha.") |
|
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 similarly for a detector:: |
|
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 from roundup.configuration import MailAddressOption |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
614 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
615 def init(db): |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
616 try: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
617 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
|
618 MailAddressOption, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
619 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
|
620 except KeyError: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
621 # 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
|
622 # so continue |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
623 pass |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
624 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
625 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
|
626 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
|
627 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
628 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
|
629 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
|
630 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
|
631 gateway). |
|
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 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
|
634 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
635 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
|
636 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
|
637 (positional, mandatory) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
638 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
|
639 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
|
640 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
641 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
|
642 beginning of this section. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
643 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
644 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
|
645 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
|
646 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
|
647 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
|
648 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
|
649 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
650 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
|
651 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
|
652 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
653 .. index:: ! 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 Tracker Schema |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
656 ============== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
657 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
658 .. note:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
659 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
|
660 `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
|
661 your changes. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
662 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
663 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
|
664 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
|
665 tracker. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
666 |
|
7482
82a0adad2ae6
Fix bad index reference. Add new ones.
John Rouillard <rouilj@ieee.org>
parents:
7459
diff
changeset
|
667 .. index:: schema; allowed changes |
|
82a0adad2ae6
Fix bad index reference. Add new ones.
John Rouillard <rouilj@ieee.org>
parents:
7459
diff
changeset
|
668 |
| 7359 | 669 What you can/can't do to the schema |
| 670 ----------------------------------- | |
| 671 | |
| 672 Your schema may be changed at any time before or after the tracker has been | |
| 673 initialised (or used). You may: | |
| 674 | |
| 675 **Add new properties to classes, or add whole new classes** | |
| 676 This is painless and easy to do - there are generally no repercussions | |
| 677 from adding new information to a tracker's schema. | |
| 678 | |
| 679 **Remove properties** | |
| 680 Removing properties is a little more tricky - you need to make sure that | |
| 681 the property is no longer used in the `web interface`_ *or* by the | |
| 682 detectors_. | |
| 683 | |
| 684 You must never: | |
| 685 | |
| 686 **Remove the user class** | |
| 687 This class is the only *required* class in Roundup. | |
| 688 | |
|
7638
f58582135861
docs: add "roles" to list of required user object properties.
John Rouillard <rouilj@ieee.org>
parents:
7559
diff
changeset
|
689 **Remove the "username", "address", "password", "roles" or "realname" user properties** |
| 7359 | 690 Various parts of Roundup require these properties. Don't remove them. |
| 691 | |
| 692 **Change the type of a property** | |
| 693 Property types must *never* [1]_ be changed - the database simply | |
| 694 doesn't take this kind of action into account. Note that you can't | |
| 695 just remove a property and re-add it as a new type either. If you | |
| 696 wanted to make the assignedto property a Multilink, you'd need to | |
| 697 create a new property assignedto_list and remove the old assignedto | |
| 698 property. | |
| 699 | |
| 700 .. [1] If you shut down the tracker, `export the database`_, modify the | |
| 701 exported csv property data to be compatible with the new type, | |
| 702 change the property type in the schema, and finally import the | |
| 703 changed exported data, you can change the property type. It is | |
| 704 not trivial nor for the faint of heart. But it can be done. | |
| 705 | |
| 706 .. _export the database: admin_guide.html#using-roundup-admin | |
| 707 | |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
708 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
|
709 ------------------------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
710 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
711 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
|
712 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
|
713 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
|
714 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
|
715 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
|
716 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
717 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
|
718 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
|
719 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
|
720 info about how this works. |
|
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 .. index:: schema; classic - description of |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
723 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
724 The "classic" schema |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
725 -------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
726 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
727 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
|
728 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
|
729 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
|
730 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
|
731 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
732 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
|
733 pri.setkey("name") |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
734 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
735 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
|
736 stat.setkey("name") |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
737 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
738 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
|
739 keyword.setkey("name") |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
740 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
741 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
|
742 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
|
743 phone=String(), alternate_addresses=String(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
744 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
|
745 user.setkey("username") |
|
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 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
|
748 date=Date(), recipients=Multilink("user"), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
749 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
|
750 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
751 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
|
752 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
753 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
|
754 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
|
755 priority=Link("priority")) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
756 issue.setkey('title') |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
757 |
|
7482
82a0adad2ae6
Fix bad index reference. Add new ones.
John Rouillard <rouilj@ieee.org>
parents:
7459
diff
changeset
|
758 .. index:: schema; classes and properties |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
759 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
760 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
|
761 --------------------------------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
762 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
763 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
|
764 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
765 priority |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
766 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
|
767 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
768 status |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
769 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
|
770 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
771 keyword |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
772 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
|
773 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
774 user |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
775 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
|
776 for all users using 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 msg |
|
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 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
|
780 generated by Roundup. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
781 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
782 file |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
783 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
|
784 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
785 issue |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
786 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
|
787 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
788 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
|
789 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
790 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
|
791 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
|
792 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
793 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
|
794 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
|
795 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
|
796 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
797 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
|
798 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
|
799 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
|
800 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
|
801 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
|
802 classes that you add. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
803 |
|
7482
82a0adad2ae6
Fix bad index reference. Add new ones.
John Rouillard <rouilj@ieee.org>
parents:
7459
diff
changeset
|
804 .. index:: |
|
82a0adad2ae6
Fix bad index reference. Add new ones.
John Rouillard <rouilj@ieee.org>
parents:
7459
diff
changeset
|
805 schema; classes |
|
82a0adad2ae6
Fix bad index reference. Add new ones.
John Rouillard <rouilj@ieee.org>
parents:
7459
diff
changeset
|
806 schema; items |
|
82a0adad2ae6
Fix bad index reference. Add new ones.
John Rouillard <rouilj@ieee.org>
parents:
7459
diff
changeset
|
807 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
808 Class and Items |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
809 ~~~~~~~~~~~~~~~ |
|
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 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
|
812 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
|
813 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
|
814 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
815 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
|
816 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
|
817 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
|
818 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
819 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
820 .. index:: schema; property types |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
821 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
822 Properties |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
823 ~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
824 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
825 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
|
826 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
827 String |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
828 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
|
829 Password |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
830 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
|
831 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
|
832 class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
833 Date |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
834 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
|
835 objects. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
836 Interval |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
837 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
|
838 example 2 hours. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
839 Integer |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
840 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
|
841 Number |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
842 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
|
843 double-precision floating point numbers. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
844 Boolean |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
845 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
|
846 Link |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
847 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
|
848 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
|
849 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
|
850 Multilink |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
851 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
|
852 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
|
853 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
854 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
|
855 behaviour: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
856 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
857 .. 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
|
858 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
|
859 triple: schema; property attributes; quiet |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
860 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
861 * 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
|
862 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
863 - ``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
|
864 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
|
865 - ``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
|
866 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
|
867 - ``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
|
868 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
|
869 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
870 - 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
|
871 interface |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
872 - 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
|
873 - 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
|
874 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
875 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
|
876 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
|
877 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
|
878 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
|
879 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
|
880 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
|
881 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
882 .. 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
|
883 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
884 * 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
|
885 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
|
886 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
|
887 text index. |
|
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 .. 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
|
890 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
891 * 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
|
892 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
|
893 * 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
|
894 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
895 .. 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
|
896 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
897 - ``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
|
898 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
|
899 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
|
900 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
|
901 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
|
902 events. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
903 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
904 .. 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
|
905 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
906 - ``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
|
907 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
|
908 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
|
909 (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
|
910 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
|
911 ``try_id_parsing='no'``. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
912 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
913 .. 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
|
914 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
915 - 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
|
916 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
|
917 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
|
918 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
|
919 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
|
920 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
|
921 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
|
922 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
|
923 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
924 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
|
925 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
|
926 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
|
927 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
|
928 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
|
929 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
|
930 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
931 issue = IssueClass(db, "issue", |
|
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 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
|
934 ... ) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
935 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
936 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
|
937 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
|
938 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
|
939 declared the class as:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
940 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
941 issue = IssueClass(db, "issue", |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
942 ... |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
943 part_of = Link("issue"), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
944 components = Multilink("issue"), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
945 ... ) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
946 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
947 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
|
948 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
|
949 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
|
950 ``components`` multilink. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
951 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
952 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
|
953 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
|
954 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
|
955 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
|
956 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
|
957 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
|
958 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
|
959 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
|
960 ``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
|
961 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
962 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
|
963 the issue definition to include:: |
|
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 issue = IssueClass(db, "issue", |
|
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 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
|
968 ... ) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
969 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
970 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
|
971 for (aka assigned_to). |
|
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 .. 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
|
974 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
975 - 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
|
976 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
|
977 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
|
978 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
979 X-Roundup-issue-prop: value |
|
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 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
|
982 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
|
983 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
|
984 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
985 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
|
986 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
987 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
|
988 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
989 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
|
990 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
991 ``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
|
992 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
993 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
|
994 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
|
995 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
996 X-Roundup-issue-assigned_to: ... |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
997 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
998 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
|
999 ``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
|
1000 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
|
1001 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1002 user = Class(db, "user", |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1003 username=String(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1004 password=Password(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1005 address=String(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1006 realname=String(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1007 phone=String(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1008 organisation=String(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1009 alternate_addresses=String(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1010 queries=Multilink('query'), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1011 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
|
1012 timezone=String()) |
|
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 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
|
1015 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
|
1016 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1017 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
|
1018 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1019 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
|
1020 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
|
1021 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1022 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
|
1023 username=joe_user, setting:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1024 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1025 msg_header_property="username" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1026 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1027 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
|
1028 form:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1029 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1030 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
|
1031 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1032 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
|
1033 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1034 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
|
1035 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
|
1036 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1037 .. 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
|
1038 triple: schema; class property; creation |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1039 triple: schema; class property; actor |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1040 triple: schema; class property; activity |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1041 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1042 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
|
1043 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1044 *creator* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1045 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
|
1046 *creation* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1047 Date the item was created. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1048 *actor* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1049 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
|
1050 *activity* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1051 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
|
1052 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1053 |
| 7359 | 1054 .. index:: double: schema; class methods |
| 1055 | |
| 1056 Methods | |
| 1057 ~~~~~~~ | |
| 1058 | |
| 1059 All classes have the following methods. | |
| 1060 | |
| 1061 .. index:: triple: schema; class method; setkey | |
| 1062 | |
| 1063 setkey(property) | |
| 1064 :::::::::::::::: | |
| 1065 | |
| 1066 .. index:: roundup-admin; setting assignedto on an issue | |
| 1067 | |
| 1068 Select a String property of the class to be the key property. The key | |
| 1069 property must be unique, and allows references to the items in the class | |
| 1070 by the content of the key property. That is, we can refer to users by | |
| 1071 their username: for example, let's say that there's an issue in Roundup, | |
| 1072 issue 23. There's also a user, richard, who happens to be user 2. To | |
| 1073 assign an issue to him, we could do either of:: | |
| 1074 | |
| 1075 roundup-admin set issue23 assignedto=2 | |
| 1076 | |
| 1077 or:: | |
| 1078 | |
| 1079 roundup-admin set issue23 assignedto=richard | |
| 1080 | |
| 1081 Note, the same thing can be done in the web and e-mail interfaces. | |
| 1082 | |
| 1083 .. index:: triple: schema; class method; setlabelprop | |
| 1084 | |
| 1085 setlabelprop(property) | |
| 1086 :::::::::::::::::::::: | |
| 1087 | |
| 1088 Select a property of the class to be the label property. The label | |
| 1089 property is used whereever an item should be uniquely identified, e.g., | |
| 1090 when displaying a link to an item. If setlabelprop is not specified for | |
| 1091 a class, the following values are tried for the label: | |
| 1092 | |
| 1093 * the key of the class (see the `setkey(property)`_ section above) | |
| 1094 * the "name" property | |
| 1095 * the "title" property | |
| 1096 * the first property from the sorted property name list | |
| 1097 | |
| 1098 So in most cases you can get away without specifying setlabelprop | |
| 1099 explicitly. | |
| 1100 | |
| 1101 You should make sure that users have View access to this property or | |
| 1102 the id property for a class. If the property can not be viewed by a | |
| 1103 user, looping over items in the class (e.g. messages attached to an | |
| 1104 issue) will not work. | |
| 1105 | |
| 1106 .. index:: triple: schema; class method; setorderprop | |
| 1107 | |
| 1108 setorderprop(property) | |
| 1109 :::::::::::::::::::::: | |
| 1110 | |
| 1111 Select a property of the class to be the order property. The order | |
| 1112 property is used whenever using a default sort order for the class, | |
| 1113 e.g., when grouping or sorting class A by a link to class B in the user | |
| 1114 interface, the order property of class B is used for sorting. If | |
| 1115 setorderprop is not specified for a class, the following values are tried | |
| 1116 for the order property: | |
| 1117 | |
| 1118 * the property named "order" | |
| 1119 * the label property (see `setlabelprop(property)`_ above) | |
| 1120 | |
| 1121 So in most cases you can get away without specifying setorderprop | |
| 1122 explicitly. | |
| 1123 | |
| 1124 .. index:: triple: schema; class method; create | |
| 1125 | |
| 1126 create(information) | |
| 1127 ::::::::::::::::::: | |
| 1128 | |
| 1129 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
|
1130 in the :term:`definitional class` like "priority" and "status". |
| 7359 | 1131 |
| 1132 IssueClass | |
| 1133 ~~~~~~~~~~ | |
| 1134 | |
| 1135 IssueClasses automatically include the "messages", "files", "nosy", and | |
| 1136 "superseder" properties. | |
| 1137 | |
| 1138 The messages and files properties list the links to the messages and | |
| 1139 files related to the issue. The nosy property is a list of links to | |
| 1140 users who wish to be informed of changes to the issue - they get "CC'ed" | |
| 1141 e-mails when messages are sent to or generated by the issue. The nosy | |
| 1142 reactor (in the ``'detectors'`` directory) handles this action. The | |
| 1143 superseder link indicates an issue which has superseded this one. | |
| 1144 | |
| 1145 They also have the dynamically generated "creation", "activity" and | |
| 1146 "creator" properties. | |
| 1147 | |
| 1148 The value of the "creation" property is the date when an item was | |
| 1149 created, and the value of the "activity" property is the date when any | |
| 1150 property on the item was last edited (equivalently, these are the dates | |
| 1151 on the first and last records in the item's journal). The "creator" | |
| 1152 property holds a link to the user that created the issue. | |
| 1153 | |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1154 .. 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
|
1155 triple: schema; class property; type |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1156 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1157 FileClass |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1158 ~~~~~~~~~ |
|
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 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
|
1161 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
|
1162 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
|
1163 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
|
1164 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
|
1165 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
|
1166 type of the file. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1167 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1168 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
|
1169 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
|
1170 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
|
1171 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
|
1172 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
|
1173 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
|
1174 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
|
1175 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
|
1176 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1177 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
|
1178 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
|
1179 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1180 [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
|
1181 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1182 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
|
1183 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1184 [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
|
1185 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1186 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
|
1187 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
|
1188 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
|
1189 (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
|
1190 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
|
1191 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
|
1192 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
|
1193 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
|
1194 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
|
1195 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
|
1196 command line interface. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1197 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1198 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
|
1199 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
|
1200 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
|
1201 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
|
1202 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1203 $ curl -u demo:demo -s |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1204 -H "X-requested-with: rest" \ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1205 -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
|
1206 -X GET \ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1207 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
|
1208 { |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1209 "data": { |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1210 "id": "30", |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1211 "type": "<class 'str'>", |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1212 "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
|
1213 "data": "hello3", |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1214 "@etag": "\"3f2f8063dbce5b6bd43567e6f4f3c671\"" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1215 } |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1216 } |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1217 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1218 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
|
1219 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1220 $ curl -u demo:demo -s |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1221 -H "X-requested-with: rest" \ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1222 -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
|
1223 -H 'If-Match: "3f2f8063dbce5b6bd43567e6f4f3c671"' \ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1224 -X PUT \ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1225 -F "data=@hello" \ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1226 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
|
1227 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1228 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
|
1229 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1230 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
|
1231 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
|
1232 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
|
1233 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
|
1234 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
|
1235 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
|
1236 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
|
1237 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
|
1238 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
|
1239 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1240 .. 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
|
1241 triple: schema; class property; files |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1242 triple: schema; class property; nosy |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1243 triple: schema; class property; superseder |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1244 |
| 7359 | 1245 .. index:: schema; item ordering |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1246 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1247 A note about ordering |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1248 ~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1249 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1250 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
|
1251 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
|
1252 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1253 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
|
1254 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
|
1255 case-sensitively. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1256 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
|
1257 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
|
1258 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
|
1259 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
|
1260 so on. |
|
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 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
|
1263 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
|
1264 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
|
1265 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1266 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1267 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
|
1268 --------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1269 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1270 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
|
1271 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1272 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
|
1273 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
|
1274 functionality. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1275 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1276 .. _Roundup wiki CategorySchema: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1277 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
|
1278 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1279 .. index:: !detectors |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1280 .. _detectors: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1281 .. _Auditors and reactors: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1282 |
|
7459
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1283 |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1284 Schema Integrity |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1285 ---------------- |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1286 |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1287 There is a table in all SQL based schemas called ``schema``. It |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1288 contains a representation of the current schema and the current |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1289 Roundup schema version. Roundup will exit the version is not supported |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1290 by the release. E.G. Roundup 2.1.0 will not work with a database |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1291 created by 2.3.0 as db version 8 used by 2.3.0 is not supported by |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1292 2.1.0. |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1293 |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1294 The current schema representation is automatically updated whenever a |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1295 change is made to the schema via ``schema.py``. The schema version is |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1296 upgraded when running ``roundup-admin migrate`` although it can be |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1297 upgraded automatically in some cases by run a Roundup process (mailgw, |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1298 web interface). This information is kept in one large blob in the |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1299 table. To view this in a more understandable format, you can use the |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1300 commands below (requires the jq command): |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1301 |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1302 Postgres |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1303 .. code:: |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1304 |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1305 psql -tq -d 'roundup_db' -U roundup_user -c \ |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1306 'select schema from schema;' | \ |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1307 python3 -c 'import json, sys; d = eval(sys.stdin.read()); \ |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1308 print(json.dumps(d, indent=2));' | jq . | less |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1309 |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1310 replace ``roundup_db``, ``roundup_user`` with the values from |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1311 ``config.ini`` and use a ``~/.pgpass`` file or type the database |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1312 password when prompted. |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1313 |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1314 SQLite |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1315 .. code:: |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1316 |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1317 sqlite3 demo/db/db 'select schema from schema;' | \ |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1318 python3 -c 'import json, sys; d = eval(sys.stdin.read()); \ |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1319 print(json.dumps(d, indent=2));' | jq . | less |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1320 |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1321 Something similar for MySQL can be generated as well. |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1322 Replacing ``jq .`` with ``jq .version`` will display the schema |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1323 version. |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
1324 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1325 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
|
1326 ============================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1327 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1328 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
|
1329 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
|
1330 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
|
1331 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1332 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
|
1333 (**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
|
1334 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
|
1335 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
|
1336 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
|
1337 for you are: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1338 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1339 .. index:: detectors; installed |
|
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 **nosyreaction.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1342 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
|
1343 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
|
1344 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
|
1345 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
|
1346 (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
|
1347 **statusauditor.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1348 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
|
1349 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
|
1350 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
|
1351 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
|
1352 defined. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1353 **messagesummary.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1354 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
|
1355 content. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1356 **userauditor.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1357 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
|
1358 roles lists). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1359 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1360 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
|
1361 or remove these detectors. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1362 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1363 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
|
1364 interface for detectors. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1365 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1366 __ design.html |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1369 .. index:: detectors; writing api |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1370 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1371 Detector API |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1374 .. index:: pair: detectors; auditors |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1375 single: auditors; function signature |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1376 single: auditors; defining |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1377 single: auditors; arguments |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1378 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1379 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
|
1380 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1381 audit(db, cl, itemid, newdata) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1382 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1383 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
|
1384 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
|
1385 property names to values. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1386 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1387 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
|
1388 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
|
1389 is about to be created. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1390 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1391 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
|
1392 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
|
1393 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1394 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
|
1395 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1396 .. index:: pair: detectors; reactor |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1397 single: reactors; function signature |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1398 single: reactors; defining |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1399 single: reactors; arguments |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1400 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1401 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
|
1402 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1403 react(db, cl, itemid, olddata) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1404 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1405 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
|
1406 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
|
1407 property names to values. |
|
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 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
|
1410 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
|
1411 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1412 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
|
1413 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
|
1414 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1415 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
|
1416 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
|
1417 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1418 .. index:: detectors; additional |
|
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 Additional Detectors Ready For Use |
|
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 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
|
1424 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
|
1425 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
|
1426 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1427 **irker.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1428 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
|
1429 (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
|
1430 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
|
1431 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
|
1432 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
|
1433 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
|
1434 **newissuecopy.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1435 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
|
1436 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
|
1437 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
|
1438 email errors! |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1439 **creator_resolution.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1440 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
|
1441 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
|
1442 "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
|
1443 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
|
1444 **email_auditor.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1445 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
|
1446 extension .eml. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1447 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
|
1448 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
|
1449 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
|
1450 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
|
1451 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1452 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1453 .. index:: auditors; rules for use |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1454 single: reactors; rules for use |
|
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 Auditor or Reactor? |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1457 ------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1458 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1459 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
|
1460 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1461 **Auditors** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1462 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
|
1463 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
|
1464 **Reactors** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1465 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
|
1466 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
|
1467 detector loops. |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1470 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
|
1471 --------------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1472 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1473 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
|
1474 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
|
1475 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
|
1476 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
|
1477 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
|
1478 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1479 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
|
1480 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1481 from roundup.exceptions import Reject |
|
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 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
|
1484 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1485 raise Reject('Description of error') |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1486 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1487 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
|
1488 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
|
1489 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
|
1490 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
|
1491 ``RejectRaw``. |
|
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 Generating email from Roundup |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1495 ----------------------------- |
|
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 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
|
1498 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
|
1499 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1500 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
|
1501 ``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
|
1502 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
|
1503 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
|
1504 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
|
1505 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1506 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1507 .. index:: extensions |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1508 .. 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
|
1509 .. _extensions: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1510 .. _actions: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1511 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1512 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
|
1513 ================================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1514 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1515 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
|
1516 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
|
1517 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
|
1518 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1519 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
|
1520 ``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
|
1521 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
|
1522 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
|
1523 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1524 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
|
1525 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
|
1526 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
|
1527 flexible extension point mechanism. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1528 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1529 * ``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
|
1530 (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
|
1531 <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
|
1532 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1533 * ``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
|
1534 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
|
1535 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
|
1536 instead of ``cgi.action.Action``. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1537 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1538 .. _interfaces.py: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1539 .. _modifying the core of Roundup: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1540 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1541 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
|
1542 ================================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1543 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1544 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
|
1545 this you can: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1546 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1547 * modify class data structures |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1548 * 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
|
1549 * modify the email gateway |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1550 * add new rest endpoints |
|
7375
9bd7ed918121
issue2551253 - Modify password PBKDF2 method to use SHA512
John Rouillard <rouilj@ieee.org>
parents:
7371
diff
changeset
|
1551 * 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
|
1552 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1553 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
|
1554 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1555 Interfaces.py has been around since the earliest releases of Roundup |
|
7499
a072331c843b
Change customizing to customising in all variants.
John Rouillard <rouilj@ieee.org>
parents:
7482
diff
changeset
|
1556 and used to be the main way to get a lot of customisation done. In |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1557 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
|
1558 <#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
|
1559 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
|
1560 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
|
1561 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
|
1562 modifying sys.path. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1563 |
|
7688
c09192e21faa
doc: add statement on less stable nature of using interfaces.py
John Rouillard <rouilj@ieee.org>
parents:
7658
diff
changeset
|
1564 Interfaces.py allows you to interact with any part of Roundup's |
|
c09192e21faa
doc: add statement on less stable nature of using interfaces.py
John Rouillard <rouilj@ieee.org>
parents:
7658
diff
changeset
|
1565 internals. These internals are not as stable as defined interfaces |
|
c09192e21faa
doc: add statement on less stable nature of using interfaces.py
John Rouillard <rouilj@ieee.org>
parents:
7658
diff
changeset
|
1566 (e.g. extensions. detectors, schema). So the code in interfaces.py is |
|
c09192e21faa
doc: add statement on less stable nature of using interfaces.py
John Rouillard <rouilj@ieee.org>
parents:
7658
diff
changeset
|
1567 more likely to need modification when upgrading from version to |
|
c09192e21faa
doc: add statement on less stable nature of using interfaces.py
John Rouillard <rouilj@ieee.org>
parents:
7658
diff
changeset
|
1568 version. While the developers attempt to keep the examples working, |
|
c09192e21faa
doc: add statement on less stable nature of using interfaces.py
John Rouillard <rouilj@ieee.org>
parents:
7658
diff
changeset
|
1569 it may make more sense to change the internals to make the code |
|
c09192e21faa
doc: add statement on less stable nature of using interfaces.py
John Rouillard <rouilj@ieee.org>
parents:
7658
diff
changeset
|
1570 clearer, add more features etc. |
|
c09192e21faa
doc: add statement on less stable nature of using interfaces.py
John Rouillard <rouilj@ieee.org>
parents:
7658
diff
changeset
|
1571 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1572 See `Changing How the Core Code Works |
|
7688
c09192e21faa
doc: add statement on less stable nature of using interfaces.py
John Rouillard <rouilj@ieee.org>
parents:
7658
diff
changeset
|
1573 <customizing.html#changing-how-the-core-code-works>`_ for examples |
|
c09192e21faa
doc: add statement on less stable nature of using interfaces.py
John Rouillard <rouilj@ieee.org>
parents:
7658
diff
changeset
|
1574 of using interfaces.py. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1575 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1576 Database Content |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1577 ================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1578 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1579 .. note:: |
|
7369
15bb0d177632
use glossary directive and link some terms to the glossary.
John Rouillard <rouilj@ieee.org>
parents:
7368
diff
changeset
|
1580 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
|
1581 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
|
1582 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
|
1583 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
|
1584 "working", you need to change the check.) |
|
f37c1df6de34
Glossary updates and more term refs.
John Rouillard <rouilj@ieee.org>
parents:
7369
diff
changeset
|
1585 |
|
f37c1df6de34
Glossary updates and more term refs.
John Rouillard <rouilj@ieee.org>
parents:
7369
diff
changeset
|
1586 Customisation of the special :term:`definitional classes <definitional |
|
f37c1df6de34
Glossary updates and more term refs.
John Rouillard <rouilj@ieee.org>
parents:
7369
diff
changeset
|
1587 class>` (eg. status, |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1588 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
|
1589 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
|
1590 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
|
1591 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1592 **Changing content before tracker initialisation** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1593 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
|
1594 created using the ``create( ... )`` methods. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1595 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1596 **Changing content after tracker initialisation** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1597 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
|
1598 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
|
1599 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
|
1600 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1601 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
|
1602 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
|
1603 question. |
|
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 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
|
1606 <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
|
1607 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
|
1608 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1609 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1610 Security / Access Controls |
|
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 |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1613 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
|
1614 each Class defined in the tracker schema, the following permissions |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1615 are defined: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1616 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1617 - Create (everything) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1618 - Edit (everything) |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1619 - Search (everything) - (used if View does not permit access) |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1620 - Retire (everything) |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1621 - Restore (everything) |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1622 - View (everything) |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1623 |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1624 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
|
1625 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
|
1626 also define: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1627 |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1628 Email Access |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1629 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
|
1630 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
|
1631 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
|
1632 interface (see also the ``new_email_user_roles`` configuration option). |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1633 |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1634 Web Access |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1635 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
|
1636 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
|
1637 access the form based login. If some other authorization mode (basic |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1638 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
|
1639 Anonymous user. |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1640 |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1641 Web Roles |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1642 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
|
1643 TODO: deprecate in favour of a property-based control. |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1644 |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1645 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
|
1646 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
|
1647 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
|
1648 `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
|
1649 `xmlrpc interface documentation`_. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1650 |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1651 Register |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1652 This is assigned to the anonymous user and allows automatic user |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1653 registration by email or web. |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1654 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1655 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
|
1656 |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1657 - 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
|
1658 - User (Web Access; Email Access) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1659 - Anonymous (Web Access) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1660 |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1661 Finally, the "admin" user gets the "Admin" Role, and the "anonymous" |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1662 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
|
1663 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1664 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
|
1665 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1666 - 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
|
1667 - View priority, status |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1668 - View user |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1669 - Edit their own user record |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1670 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1671 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
|
1672 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1673 - Web interface access |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1674 - Register user (for registration) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1675 - 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
|
1676 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1677 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
|
1678 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1679 # |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1680 # TRACKER SECURITY SETTINGS |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1681 # |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1682 # 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
|
1683 # about security setup. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1684 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1685 # |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1686 # REGULAR USERS |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1687 # |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1688 # 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
|
1689 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
|
1690 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
|
1691 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
|
1692 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
|
1693 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1694 # 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
|
1695 # to regular users now |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1696 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
|
1697 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
|
1698 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
|
1699 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
|
1700 for cl in 'priority', 'status': |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1701 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
|
1702 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1703 # 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
|
1704 # 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
|
1705 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
|
1706 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
|
1707 'username')) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1708 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1709 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1710 # 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
|
1711 # 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
|
1712 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
|
1713 '''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
|
1714 return userid == itemid |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1715 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
|
1716 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
|
1717 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1718 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
|
1719 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
|
1720 'organisation', 'alternate_addresses', 'queries', 'timezone'), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1721 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
|
1722 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1723 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1724 # 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
|
1725 # 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
|
1726 # 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
|
1727 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
|
1728 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
|
1729 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
|
1730 return userid == private_for |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1731 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
|
1732 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
|
1733 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
|
1734 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
|
1735 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1736 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
|
1737 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1738 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
|
1739 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
|
1740 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1741 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
|
1742 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
|
1743 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1744 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
|
1745 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
|
1746 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1747 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
|
1748 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
|
1749 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1750 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1751 # |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1752 # ANONYMOUS USER PERMISSIONS |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1753 # |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1754 # 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
|
1755 # 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
|
1756 # 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
|
1757 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
|
1758 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1759 # 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
|
1760 # 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
|
1761 # "Create" user Permission below) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1762 # 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
|
1763 # public trackers. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1764 #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
|
1765 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1766 # 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
|
1767 # Role. Choices here are: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1768 # - Allow anonymous users to register |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1769 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
|
1770 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1771 # 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
|
1772 # information) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1773 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
|
1774 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
|
1775 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1776 # 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
|
1777 # 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
|
1778 # 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
|
1779 # 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
|
1780 # 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
|
1781 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
|
1782 db.security.addPermissionToRole ('Anonymous', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1783 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1784 # [OPTIONAL] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1785 # 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
|
1786 # related file and message items) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1787 #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
|
1788 # 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
|
1789 # 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
|
1790 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1791 .. index:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1792 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
|
1793 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1794 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
|
1795 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
|
1796 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
|
1797 cause baffling permission issues. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1798 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1799 Automatic Permission Checks |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1800 --------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1801 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1802 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
|
1803 through the web. This includes: |
|
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 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
|
1806 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
|
1807 displayed. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1808 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
|
1809 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
|
1810 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
|
1811 checking performed) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1812 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
|
1813 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
|
1814 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
|
1815 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
|
1816 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
|
1817 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
|
1818 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
|
1819 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
|
1820 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1821 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1822 New User Roles |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1823 -------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1824 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1825 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
|
1826 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1827 - NEW_WEB_USER_ROLES |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1828 - NEW_EMAIL_USER_ROLES |
|
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 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
|
1831 <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
|
1832 customisation of these parameters. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1833 |
|
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 Changing Access Controls |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1836 ------------------------ |
|
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 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
|
1839 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
|
1840 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
|
1841 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1842 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
|
1843 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
|
1844 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1845 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1846 Adding a new Permission |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1847 ~~~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1848 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1849 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
|
1850 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1851 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
|
1852 ``security.addPermission``, for example:: |
|
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 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
|
1855 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
|
1856 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1857 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
|
1858 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
|
1859 "``roundup-admin security``") |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1860 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
|
1861 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
|
1862 interfaces module |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1863 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1864 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
|
1865 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1866 **properties** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1867 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
|
1868 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
|
1869 'email') ...``) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1870 **props_only** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1871 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
|
1872 in Roundup 1.6. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1873 A permission defined using: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1874 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1875 ``properties=('list', 'of', 'property', 'names')`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1876 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1877 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
|
1878 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
|
1879 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
|
1880 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
|
1881 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
|
1882 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
|
1883 access permission for those properties. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1884 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1885 ``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
|
1886 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
|
1887 presented as:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1888 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1889 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
|
1890 (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
|
1891 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1892 **Invalid properties for file: ['summary'] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1893 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1894 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
|
1895 those properties. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1896 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1897 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
|
1898 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
|
1899 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1900 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
|
1901 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1902 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
|
1903 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
|
1904 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
|
1905 **check** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1906 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
|
1907 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
|
1908 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
|
1909 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
|
1910 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1911 check(db, userid, itemid) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1912 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1913 or:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1914 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1915 check(db, userid, itemid, **ctx) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1916 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1917 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
|
1918 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
|
1919 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
|
1920 defined with the following values:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1921 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1922 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
|
1923 it's a class check. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1924 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1925 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
|
1926 (issue, query ....). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1927 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1928 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
|
1929 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1930 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
|
1931 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
|
1932 <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
|
1933 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
|
1934 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1935 Example Scenarios |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1938 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
|
1939 examples of customisation. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1940 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1941 **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
|
1942 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
|
1943 ("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
|
1944 "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
|
1945 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
|
1946 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
|
1947 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
|
1948 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
|
1949 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
|
1950 - they're *anonymous*. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1951 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1952 **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
|
1953 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
|
1954 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
|
1955 (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
|
1956 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
|
1957 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
|
1958 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
|
1959 ``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
|
1960 "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
|
1961 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1962 **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
|
1963 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
|
1964 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
|
1965 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
|
1966 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
|
1967 auditor. See the example |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1968 `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
|
1969 <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
|
1970 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1971 **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
|
1972 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
|
1973 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
|
1974 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
|
1975 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
|
1976 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
|
1977 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
|
1978 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1979 <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
|
1980 value="resolved">Resolved</option> |
|
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 **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
|
1983 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
|
1984 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
|
1985 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
|
1986 interface. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1987 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1988 **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
|
1989 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
|
1990 editing users:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1991 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1992 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
|
1993 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
|
1994 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
|
1995 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1996 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
|
1997 |
|
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 Web Interface |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2000 ============= |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2001 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2002 .. contents:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2003 :local: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2004 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2005 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
|
2006 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
|
2007 (``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
|
2008 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
|
2009 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
|
2010 ``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
|
2011 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
|
2012 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
|
2013 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2014 |
|
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 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
|
2017 --------------------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2018 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2019 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
|
2020 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
|
2021 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2022 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
|
2023 have properties added or removed, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2024 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
|
2025 "home" page's content arguments. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2026 |
|
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 How requests are processed |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2031 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
|
2032 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2033 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
|
2034 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
|
2035 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
|
2036 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
|
2037 output |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2038 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2039 In some situations, exceptions occur: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2040 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2041 - HTTP Redirect (generally raised by an action) |
|
7368
8aa1a5639aef
add explanatory info for HTTP Redirect
John Rouillard <rouilj@ieee.org>
parents:
7363
diff
changeset
|
2042 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
|
2043 - 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
|
2044 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
|
2045 - 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
|
2046 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
|
2047 - 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
|
2048 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
|
2049 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
|
2050 the action to take place |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2051 - 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
|
2052 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
|
2053 client |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2056 Roundup URL design |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2057 ------------------ |
|
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 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
|
2060 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
|
2061 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2062 1. ``/`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2063 2. ``/index`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2064 3. ``/home`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2065 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2066 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
|
2067 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2068 4. ``/@@file/`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2069 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2070 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
|
2071 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
|
2072 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2073 5. ``/rest/`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2074 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2075 .. _`REST api`: rest.html |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2076 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2077 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
|
2078 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2079 6. ``/xmlrpc`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2080 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2081 .. _`XMLRPC api`: xmlrpc.html |
|
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 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
|
2084 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
|
2085 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
|
2086 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2087 7. ``/issue`` |
|
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 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
|
2090 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
|
2091 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2092 8. ``/issue1`` |
|
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 .. _strip_zeros: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2095 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2096 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
|
2097 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
|
2098 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
|
2099 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
|
2100 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2101 Determining web context |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2104 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
|
2105 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
|
2106 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
|
2107 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2108 1. ``/tracker/issue`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2109 2. ``/tracker/issue1`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2110 3. ``/tracker/@@file/style.css`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2111 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
|
2112 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
|
2113 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2114 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
|
2115 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
|
2116 "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
|
2117 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2118 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
|
2119 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
|
2120 to switch into "home" context. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2121 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
|
2122 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
|
2123 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
|
2124 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
|
2125 by raising SendStaticFile exception. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2126 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
|
2127 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
|
2128 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
|
2129 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
|
2130 :ref:`Note. <strip_zeros>` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2131 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
|
2132 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
|
2133 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
|
2134 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
|
2135 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
|
2136 This raises a ``SendFile`` exception. |
|
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 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
|
2139 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
|
2140 ``@template`` variable, which defaults to: |
|
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 - only classname supplied: "index" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2143 - full item designator supplied: "item" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2144 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2145 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2146 The "home" Context |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2147 ------------------ |
|
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 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
|
2150 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
|
2151 list or specific issue). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2152 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2153 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
|
2154 interface. You'd probably have: |
|
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 - 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
|
2157 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
|
2158 - 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
|
2159 "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
|
2160 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
|
2161 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2162 <tracker url>/home?@template=navigation |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2163 |
|
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 Serving static content |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2166 ---------------------- |
|
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 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
|
2169 ``@@file`` paths. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2170 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2171 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
|
2172 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
|
2173 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2174 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
|
2175 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
|
2176 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
|
2177 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
|
2178 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
|
2179 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2180 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
|
2181 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2182 Performing actions in web requests |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2183 ---------------------------------- |
|
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 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
|
2186 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
|
2187 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
|
2188 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
|
2189 of: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2190 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2191 **login** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2192 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
|
2193 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2194 **logout** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2195 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
|
2196 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2197 **register** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2198 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
|
2199 log them in. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2200 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2201 **edit** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2202 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
|
2203 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
|
2204 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
|
2205 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
|
2206 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
|
2207 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2208 **new** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2209 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
|
2210 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
|
2211 ``__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
|
2212 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
|
2213 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
|
2214 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2215 **retire** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2216 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
|
2217 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2218 **editCSV** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2219 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
|
2220 *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
|
2221 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
|
2222 features. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2223 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2224 **search** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2225 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
|
2226 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2227 - 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
|
2228 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
|
2229 them to :filter. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2230 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2231 - 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
|
2232 user's query list. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2233 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2234 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
|
2235 "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
|
2236 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
|
2237 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
|
2238 web actions`_). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2239 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2240 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
|
2241 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
|
2242 for each action are: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2243 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2244 **login** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2245 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
|
2246 **logout** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2247 No permission checks are made. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2248 **register** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2249 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
|
2250 **edit** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2251 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
|
2252 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
|
2253 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
|
2254 special Permission "Web Roles". |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2255 **new** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2256 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
|
2257 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
|
2258 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
|
2259 **editCSV** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2260 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
|
2261 **search** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2262 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
|
2263 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2264 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
|
2265 --------------------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2266 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2267 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
|
2268 (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
|
2269 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
|
2270 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
|
2271 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
|
2272 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
|
2273 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2274 * Referer, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2275 * Origin, and |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2276 * Host or |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2277 * X-Forwarded-Host |
|
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 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
|
2280 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
|
2281 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2282 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
|
2283 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
|
2284 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
|
2285 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
|
2286 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
|
2287 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
|
2288 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
|
2289 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
|
2290 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2291 <input name="@csrf" type="hidden" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2292 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
|
2293 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2294 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
|
2295 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
|
2296 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
|
2297 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2298 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
|
2299 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
|
2300 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2301 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
|
2302 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
|
2303 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
|
2304 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2305 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
|
2306 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
|
2307 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
|
2308 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
|
2309 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2310 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
|
2311 that file for details. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2312 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2313 Special form variables |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2314 ---------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2315 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2316 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
|
2317 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
|
2318 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2319 - 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
|
2320 - 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
|
2321 properties, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2322 - 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
|
2323 current item. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2324 - 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
|
2325 - 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
|
2326 operation to be successful. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2327 - 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
|
2328 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
|
2329 created item. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2330 - Set up user interface locale. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2331 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2332 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
|
2333 ``@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
|
2334 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2335 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
|
2336 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
|
2337 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2338 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
|
2339 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2340 ``@language`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2341 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
|
2342 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
|
2343 (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
|
2344 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
|
2345 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
|
2346 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
|
2347 configuration or OS environment. |
|
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 ``@charset`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2350 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
|
2351 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
|
2352 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
|
2353 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
|
2354 (UTF-8). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2355 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2356 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
|
2357 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2358 ``<propname>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2359 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
|
2360 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2361 ``<designator>"@"<propname>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2362 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
|
2363 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2364 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
|
2365 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2366 ``<classname><N>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2367 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
|
2368 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2369 ``<classname>"-"<N>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2370 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
|
2371 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
|
2372 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
|
2373 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
|
2374 item. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2375 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2376 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
|
2377 if it's special: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2378 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2379 ``@required`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2380 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
|
2381 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
|
2382 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
|
2383 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2384 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
|
2385 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
|
2386 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
|
2387 <designator>. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2388 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2389 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
|
2390 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
|
2391 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2392 ``@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
|
2393 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
|
2394 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
|
2395 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
|
2396 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
|
2397 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
|
2398 property. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2399 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2400 ``@link@<propname>=<designator>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2401 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
|
2402 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
|
2403 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
|
2404 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
|
2405 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
|
2406 form variable. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2407 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2408 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
|
2409 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
|
2410 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
|
2411 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2412 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
|
2413 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
|
2414 specified in schema.py. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2415 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2416 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
|
2417 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
|
2418 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
|
2419 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2420 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
|
2421 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
|
2422 have a key field. |
|
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 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
|
2425 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
|
2426 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
|
2427 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
|
2428 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
|
2429 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2430 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
|
2431 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
|
2432 appropriate value. |
|
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 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
|
2435 designator. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2436 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2437 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
|
2438 @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
|
2439 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
|
2440 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
|
2441 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
|
2442 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
|
2443 the url to https. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2444 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2445 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
|
2446 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2447 @note |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2448 This is equivalent to:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2449 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2450 @link@messages=msg-1 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2451 msg-1@content=value |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2452 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2453 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
|
2454 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2455 <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
|
2456 <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
|
2457 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2458 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
|
2459 "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
|
2460 time, respectively. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2461 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2462 @file |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2463 This is equivalent to:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2464 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2465 @link@files=file-1 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2466 file-1@content=value |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2467 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2468 by adding the HTML:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2469 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2470 <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
|
2471 <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
|
2472 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2473 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
|
2474 uploads. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2475 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2476 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
|
2477 specified, the action:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2478 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2479 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
|
2480 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2481 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
|
2482 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2483 <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
|
2484 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2485 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
|
2486 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
|
2487 returning. |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2490 Default templates |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2491 ----------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2492 |
|
7456
cdb81976b8bc
Fix another xhtml reference.
John Rouillard <rouilj@ieee.org>
parents:
7378
diff
changeset
|
2493 The default templates are html4 compliant. Support for xhtml is due to |
|
cdb81976b8bc
Fix another xhtml reference.
John Rouillard <rouilj@ieee.org>
parents:
7378
diff
changeset
|
2494 be phased out so leave the ``html_version`` configuration |
|
cdb81976b8bc
Fix another xhtml reference.
John Rouillard <rouilj@ieee.org>
parents:
7378
diff
changeset
|
2495 variable in ``config.ini`` as ``'html'`` instead of ``'xhtml'``. |
|
7352
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 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
|
2498 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
|
2499 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
|
2500 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2501 **page.html** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2502 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
|
2503 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
|
2504 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
|
2505 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
|
2506 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
|
2507 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
|
2508 title. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2509 **home.html** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2510 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
|
2511 **home.classlist.html** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2512 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
|
2513 tracker |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2514 **classname.item.html** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2515 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
|
2516 **classname.index.html** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2517 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
|
2518 **classname.search.html** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2519 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
|
2520 **_generic.index.html** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2521 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
|
2522 ``*classname*.index`` available |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2523 **_generic.help.html** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2524 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
|
2525 ``*classname*.help`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2526 **user.register.html** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2527 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
|
2528 page |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2529 **style.css** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2530 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
|
2531 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2532 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
|
2533 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2534 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
|
2535 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
|
2536 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
|
2537 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
|
2538 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2539 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
|
2540 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2541 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
|
2542 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2543 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
|
2544 directory. So if you specify:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2545 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2546 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
|
2547 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2548 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
|
2549 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
|
2550 ``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
|
2551 it will return an error. |
|
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 Implementing Modal Editing Using @template |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2554 ------------------------------------------ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2555 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2556 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
|
2557 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
|
2558 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
|
2559 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2560 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
|
2561 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
|
2562 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
|
2563 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
|
2564 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2565 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
|
2566 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
|
2567 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
|
2568 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
|
2569 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2570 * search for issues to modify |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2571 * 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
|
2572 * 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
|
2573 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2574 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
|
2575 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
|
2576 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
|
2577 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
|
2578 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2579 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
|
2580 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
|
2581 ``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
|
2582 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
|
2583 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
|
2584 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
|
2585 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
|
2586 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
|
2587 until the form validates. |
|
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 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
|
2590 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
|
2591 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
|
2592 the edits again. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2593 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2594 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2595 How the templates work |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2598 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2599 Templating engines |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2602 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
|
2603 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2604 * 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
|
2605 * 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
|
2606 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
|
2607 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
|
2608 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
|
2609 ``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
|
2610 differences" section of `Chameleon documentation`__. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2611 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2612 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
|
2613 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
|
2614 ``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
|
2615 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
|
2616 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
|
2617 Chameleon templating. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2618 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2619 .. _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
|
2620 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2621 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2622 **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
|
2623 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
|
2624 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
|
2625 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
|
2626 future release. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2627 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2628 **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
|
2629 recommended for production use. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2630 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2631 .. _Chameleon: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2632 https://pypi.org/project/Chameleon/ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2633 .. _z3c.pt: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2634 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
|
2635 __ 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
|
2636 .. _TAL: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2637 .. _Template Attribute Language: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2638 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
|
2639 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2640 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2641 Basic Templating Actions |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2642 ~~~~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2643 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2644 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
|
2645 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
|
2646 The basic TAL commands are: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2647 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2648 **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
|
2649 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
|
2650 example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2651 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2652 <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
|
2653 <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
|
2654 </html> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2655 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2656 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
|
2657 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
|
2658 <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
|
2659 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2660 **tal:condition="expression"** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2661 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
|
2662 example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2663 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2664 <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
|
2665 Display some issue information. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2666 </p> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2667 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2668 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
|
2669 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
|
2670 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
|
2671 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
|
2672 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
|
2673 spaces!). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2674 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2675 **tal:repeat="variable expression"** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2676 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
|
2677 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
|
2678 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
|
2679 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2680 <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
|
2681 <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
|
2682 <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
|
2683 <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
|
2684 </tr> |
|
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 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
|
2687 "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
|
2688 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
|
2689 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
|
2690 below on `the repeat variable`_. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2691 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2692 **tal:replace="expression"** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2693 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
|
2694 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2695 <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
|
2696 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2697 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
|
2698 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
|
2699 resultant output would be "Bruce". |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2700 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2701 **tal:content="expression"** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2702 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
|
2703 For example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2704 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2705 <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
|
2706 </span> |
|
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 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
|
2709 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
|
2710 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
|
2711 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2712 **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
|
2713 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
|
2714 example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2715 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2716 <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
|
2717 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2718 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
|
2719 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
|
2720 be something like "user123". |
|
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 **tal:omit-tag="expression"** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2723 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
|
2724 example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2725 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2726 <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
|
2727 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2728 would result in output of:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2729 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2730 Hello, world! |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2731 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2732 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
|
2733 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
|
2734 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2735 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
|
2736 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
|
2737 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
|
2738 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
|
2739 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
|
2740 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
|
2741 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2742 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2743 Templating Expressions |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2744 ~~~~~~~~~~~~~~~~~~~~~~ |
|
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 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
|
2747 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
|
2748 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
|
2749 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2750 **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
|
2751 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
|
2752 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
|
2753 ``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
|
2754 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
|
2755 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
|
2756 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
|
2757 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
|
2758 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
|
2759 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
|
2760 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
|
2761 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2762 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
|
2763 "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
|
2764 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
|
2765 case of ``tal:attributes``). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2766 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2767 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
|
2768 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
|
2769 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
|
2770 the case of ``tal:replace``). |
|
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 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
|
2773 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
|
2774 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
|
2775 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
|
2776 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2777 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
|
2778 ``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
|
2779 expressions. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2780 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2781 **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
|
2782 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
|
2783 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
|
2784 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
|
2785 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2786 **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
|
2787 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
|
2788 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
|
2789 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
|
2790 ``checklist`` is a method. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2791 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2792 Modifiers: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2793 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2794 **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
|
2795 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
|
2796 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
|
2797 ``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
|
2798 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
|
2799 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
|
2800 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2801 **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
|
2802 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
|
2803 expression. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2804 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2805 .. _TALES: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2806 .. _Template Attribute Language Expression Syntax: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2807 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
|
2808 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2809 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2810 Template Macros |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2811 ~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2812 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2813 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
|
2814 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
|
2815 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
|
2816 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2817 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
|
2818 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
|
2819 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
|
2820 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
|
2821 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2822 **metal:define-macro="macro name"** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2823 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
|
2824 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
|
2825 example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2826 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2827 <html metal:define-macro="page"> |
|
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 </html> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2830 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2831 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
|
2832 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
|
2833 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
|
2834 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
|
2835 ``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
|
2836 "page" template. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2837 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2838 **metal:use-macro="path expression"** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2839 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
|
2840 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
|
2841 For example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2842 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2843 <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
|
2844 ... |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2845 </tal:block> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2846 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2847 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
|
2848 "page" template. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2849 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2850 **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
|
2851 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
|
2852 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
|
2853 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
|
2854 so:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2855 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2856 <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
|
2857 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2858 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
|
2859 like this:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2860 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2861 <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
|
2862 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2863 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
|
2864 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
|
2865 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2866 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
|
2867 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
|
2868 *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
|
2869 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2870 .. _METAL: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2871 .. _Macro Expansion Template Attribute Language: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2872 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
|
2873 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2874 Information available to templates |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2875 ---------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2876 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2877 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
|
2878 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2879 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
|
2880 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2881 **context** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2882 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
|
2883 or a `hyperdb item wrapper`_ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2884 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2885 **request** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2886 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
|
2887 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2888 - 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
|
2889 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
|
2890 - 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
|
2891 - "form" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2892 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
|
2893 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
|
2894 - "env" the CGI environment variables |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2895 - "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
|
2896 - "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
|
2897 - "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
|
2898 - "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
|
2899 - "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
|
2900 **config** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2901 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
|
2902 file (eg. TRACKER_NAME, etc.) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2903 **db** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2904 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
|
2905 **templates** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2906 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
|
2907 *use-macro* commands. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2908 **utils** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2909 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
|
2910 **nothing** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2911 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
|
2912 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
|
2913 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
|
2914 ``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
|
2915 example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2916 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2917 <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
|
2918 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2919 would result in:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2920 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2921 <span>Hello, World!</span> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2922 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2923 **default** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2924 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
|
2925 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
|
2926 remain. So:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2927 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2928 <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
|
2929 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2930 would result in:: |
|
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 <span>Hello, World!</span> |
|
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 **true**, **false** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2935 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
|
2936 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
|
2937 **i18n** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2938 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
|
2939 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2940 **gettext** (*message*) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2941 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
|
2942 **ngettext** (*singular*, *plural*, *number*) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2943 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
|
2944 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
|
2945 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
|
2946 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
|
2947 return plural otherwise. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2948 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2949 The context variable |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2950 ~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2951 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2952 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
|
2953 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
|
2954 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2955 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
|
2956 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
|
2957 `hyperdb class wrapper`_. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2958 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
|
2959 `hyperdb item wrapper`_. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2960 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2961 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
|
2962 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
|
2963 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2964 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
|
2965 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
|
2966 ``context/property/field``. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2967 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
|
2968 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
|
2969 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
|
2970 "context/id". |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2971 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2972 Hyperdb class wrapper |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2975 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
|
2976 class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2977 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2978 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
|
2979 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
|
2980 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
|
2981 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
|
2982 mind. |
|
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 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
|
2985 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
|
2986 from the CGI form. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2987 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2988 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
|
2989 |
|
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 Method Description |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2992 =========== ============================================================= |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2993 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
|
2994 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
|
2995 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
|
2996 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
|
2997 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
|
2998 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
|
2999 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
|
3000 options are available for sorting: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3001 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3002 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
|
3003 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
|
3004 "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
|
3005 "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
|
3006 where dir is '+', '-' or None |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3007 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
|
3008 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3009 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
|
3010 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
|
3011 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
|
3012 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3013 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
|
3014 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
|
3015 ``issue.filter(filterspec={"priority": "1", |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3016 'messages.creation' : '.-1w;'}, sort=[('activity', '+')])`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3017 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3018 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
|
3019 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
|
3020 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
|
3021 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
|
3022 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
|
3023 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
|
3024 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
|
3025 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
|
3026 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
|
3027 following operators are supported: |
|
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 - '-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
|
3030 - '-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
|
3031 - '-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
|
3032 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3033 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
|
3034 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
|
3035 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
|
3036 applies. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3037 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
|
3038 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3039 - '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
|
3040 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
|
3041 - '-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
|
3042 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3043 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
|
3044 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3045 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
|
3046 complete "select" statement. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3047 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3048 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
|
3049 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3050 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
|
3051 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
|
3052 retired nodes. |
|
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 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
|
3055 "help" template. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3056 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3057 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
|
3058 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
|
3059 "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
|
3060 (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
|
3061 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
|
3062 activity). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3063 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3064 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
|
3065 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
|
3066 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
|
3067 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3068 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
|
3069 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
|
3070 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
|
3071 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3072 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
|
3073 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3074 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
|
3075 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
|
3076 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
|
3077 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3078 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
|
3079 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
|
3080 the "property" belongs to. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3081 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3082 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
|
3083 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
|
3084 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
|
3085 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
|
3086 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
|
3087 =========== ============================================================= |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3088 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3089 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
|
3090 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
|
3091 expression. For example:: |
|
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 python:context['list'] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3094 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3095 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
|
3096 |
|
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 Hyperdb item wrapper |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3101 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
|
3102 class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3103 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3104 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
|
3105 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3106 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
|
3107 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
|
3108 from the CGI form. |
|
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 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
|
3111 |
|
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 Method Description |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3114 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3115 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
|
3116 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
|
3117 implemented**) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3118 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
|
3119 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
|
3120 `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
|
3121 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
|
3122 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
|
3123 shown. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3124 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
|
3125 for the query |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3126 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
|
3127 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
|
3128 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3129 hasPermission(self, permission, [classname=], |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3130 [property=], [itemid=]) |
|
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 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
|
3133 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
|
3134 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
|
3135 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3136 hasRole(self, rolename) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3137 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3138 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
|
3139 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
|
3140 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
|
3141 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
|
3142 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
|
3143 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
|
3144 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
|
3145 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
|
3146 ``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
|
3147 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
|
3148 (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
|
3149 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
|
3150 ``activity`` cannot be copied. |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3153 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
|
3154 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
|
3155 expression. For example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3156 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3157 python:context['journal'] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3158 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3159 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
|
3160 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3161 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3162 Hyperdb property wrapper |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3163 :::::::::::::::::::::::: |
|
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 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
|
3166 ``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
|
3167 ``HTMLNumberProperty``, and so on). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3168 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3169 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
|
3170 value may be either: |
|
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 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
|
3173 the hyperdb |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3174 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
|
3175 the CGI form |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3176 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3177 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3178 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
|
3179 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3180 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3181 Attribute Description |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3182 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3183 _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
|
3184 _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
|
3185 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
|
3186 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3187 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3188 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
|
3189 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3190 =========== ================================================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3191 Method Description |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3192 =========== ================================================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3193 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
|
3194 may take two arguments: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3195 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3196 escape |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3197 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
|
3198 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
|
3199 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
|
3200 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
|
3201 expressions are all equivalent:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3202 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3203 "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
|
3204 "python:msg.content.plain()" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3205 "msg/content/plain" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3206 "msg/content" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3207 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3208 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
|
3209 complex expression. |
|
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 hyperlink |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3212 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
|
3213 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
|
3214 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
|
3215 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
|
3216 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3217 "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
|
3218 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3219 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
|
3220 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
|
3221 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3222 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
|
3223 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3224 "structure msg/content/hyperlinked" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3225 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3226 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
|
3227 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
|
3228 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
|
3229 arguments: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3230 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3231 size |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3232 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
|
3233 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3234 format (Date properties only) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3235 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
|
3236 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
|
3237 below. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3238 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3239 popcal (Date properties only) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3240 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
|
3241 selection. Defaults to on. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3242 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3243 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
|
3244 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
|
3245 installed separately) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3246 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
|
3247 field for the property |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3248 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
|
3249 as an obscured email address |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3250 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
|
3251 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
|
3252 replaced with %20. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3253 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
|
3254 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
|
3255 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
|
3256 "name:confirm". |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3257 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
|
3258 property |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3259 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
|
3260 and now |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3261 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
|
3262 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
|
3263 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3264 python:context.creation.local(10) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3265 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3266 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
|
3267 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
|
3268 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
|
3269 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3270 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
|
3271 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3272 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
|
3273 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3274 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
|
3275 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
|
3276 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
|
3277 Reference: time module`__) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3278 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3279 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
|
3280 (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
|
3281 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
|
3282 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
|
3283 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
|
3284 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
|
3285 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3286 <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
|
3287 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3288 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
|
3289 typically you'd have:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3290 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3291 <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
|
3292 <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
|
3293 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3294 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
|
3295 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
|
3296 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3297 size |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3298 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
|
3299 height |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3300 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
|
3301 showid |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3302 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
|
3303 additional |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3304 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
|
3305 sort_on |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3306 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
|
3307 (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
|
3308 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
|
3309 For example: ('-', 'order'), '+name'. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3310 value |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3311 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
|
3312 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3313 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
|
3314 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
|
3315 "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
|
3316 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3317 <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
|
3318 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3319 <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
|
3320 value='chatting', |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3321 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
|
3322 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3323 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
|
3324 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
|
3325 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3326 python:context.files.sorted('creation') |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3327 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3328 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
|
3329 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3330 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
|
3331 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3332 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
|
3333 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
|
3334 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
|
3335 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
|
3336 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3337 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
|
3338 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3339 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
|
3340 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
|
3341 ``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
|
3342 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
|
3343 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
|
3344 ``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
|
3345 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
|
3346 beginning. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3347 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
|
3348 items in reverse order |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3349 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
|
3350 =========== ================================================================ |
|
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 __ 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
|
3353 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3354 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
|
3355 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
|
3356 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
|
3357 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3358 context/title/field |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3359 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3360 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
|
3361 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
|
3362 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
|
3363 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
|
3364 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
|
3365 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3366 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3367 The request variable |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3368 ~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3369 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3370 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
|
3371 class. |
|
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 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
|
3374 request. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3375 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3376 .. 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
|
3377 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3378 =========== ============================================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3379 Variable Holds |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3380 =========== ============================================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3381 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
|
3382 env the CGI environment variables |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3383 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
|
3384 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
|
3385 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
|
3386 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
|
3387 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
|
3388 =========== ============================================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3389 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3390 **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
|
3391 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3392 =========== ============================================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3393 Variable Holds |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3394 =========== ============================================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3395 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
|
3396 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
|
3397 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
|
3398 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
|
3399 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
|
3400 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
|
3401 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
|
3402 ``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
|
3403 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
|
3404 =========== ============================================================ |
|
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 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
|
3407 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3408 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3409 Method Description |
|
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 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
|
3412 page title |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3413 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
|
3414 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
|
3415 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
|
3416 of the templating |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3417 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
|
3418 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
|
3419 `batching`_) |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3422 The form variable |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3423 ::::::::::::::::: |
|
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 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
|
3426 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
|
3427 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
|
3428 "name", use the path expression:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3429 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3430 request/form/name/value |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3431 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3432 or the python expression:: |
|
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 python:request.form['name'].value |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3435 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3436 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
|
3437 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
|
3438 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
|
3439 "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
|
3440 ``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
|
3441 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
|
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 The db variable |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3447 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
|
3448 class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3449 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3450 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
|
3451 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
|
3452 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3453 db/user |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3454 python:db.user |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3455 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3456 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
|
3457 ``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
|
3458 ``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
|
3459 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3460 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
|
3461 |
|
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 The templates variable |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3464 ~~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3465 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3466 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
|
3467 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
|
3468 template engine loader class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3469 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3470 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
|
3471 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
|
3472 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
|
3473 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3474 templates/name |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3475 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3476 or the python expression:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3477 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3478 templates[name] |
|
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 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
|
3481 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
|
3482 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
|
3483 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3484 templates/name/macros/macro_name |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3485 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3486 or the python expression:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3487 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3488 templates[name].macros[macro_name] |
|
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 The repeat variable |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3493 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
|
3494 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
|
3495 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
|
3496 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3497 repeat/user |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3498 python:repeat['user'] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3499 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3500 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
|
3501 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3502 =============== ========================================================= |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3503 Method Description |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3504 =============== ========================================================= |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3505 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
|
3506 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
|
3507 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
|
3508 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
|
3509 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
|
3510 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
|
3511 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
|
3512 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
|
3513 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
|
3514 numerals. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3515 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
|
3516 =============== ========================================================= |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3517 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3518 .. _templating utilities: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3519 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3520 The utils variable |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3523 This is implemented by the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3524 ``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
|
3525 with additional methods by extensions_. |
|
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 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3528 Method Description |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3529 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3530 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
|
3531 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
|
3532 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
|
3533 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
|
3534 ``_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
|
3535 the popupCalendar DateHTMLProperty method |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3536 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
|
3537 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3538 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3539 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3540 Batching |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3541 :::::::: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3542 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3543 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
|
3544 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
|
3545 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3546 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
|
3547 overlap=0) |
|
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 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
|
3550 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3551 request/batch |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3552 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3553 The parameters are: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3554 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3555 ========= ============================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3556 Parameter Usage |
|
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 sequence a list of HTMLItems |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3559 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
|
3560 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
|
3561 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
|
3562 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
|
3563 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
|
3564 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
|
3565 ========= ============================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3566 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3567 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
|
3568 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
|
3569 |
|
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 Attribute Description |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3572 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3573 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
|
3574 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
|
3575 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
|
3576 index* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3577 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
|
3578 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
|
3579 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3580 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3581 And several methods: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3582 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3583 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3584 Method Description |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3585 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3586 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
|
3587 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
|
3588 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
|
3589 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
|
3590 =============== ======================================================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3591 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3592 An example of batching:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3593 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3594 <table class="otherinfo"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3595 <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
|
3596 <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
|
3597 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
|
3598 <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
|
3599 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
|
3600 keyword here</td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3601 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3602 </table> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3603 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3604 ... 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
|
3605 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
|
3606 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3607 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3608 Translations |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3609 ~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3610 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3611 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
|
3612 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
|
3613 ``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
|
3614 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
|
3615 create the locale files. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3616 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3617 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3618 Displaying Properties |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3619 --------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3620 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3621 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
|
3622 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
|
3623 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
|
3624 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
|
3625 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
|
3626 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3627 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3628 Index Views |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3629 ----------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3630 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3631 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
|
3632 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
|
3633 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3634 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3635 Index View Specifiers |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3636 ~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3637 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3638 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
|
3639 been added for clarity):: |
|
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 /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
|
3642 keyword=security,ui& |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3643 @group=priority,-status& |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3644 @sort=-activity& |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3645 @filters=status,keyword& |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3646 @columns=title,status,fixer |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3647 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3648 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
|
3649 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
|
3650 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
|
3651 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
|
3652 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
|
3653 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
|
3654 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
|
3655 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
|
3656 headings in the table. |
|
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 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
|
3659 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
|
3660 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
|
3661 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3662 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
|
3663 "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
|
3664 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
|
3665 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
|
3666 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
|
3667 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
|
3668 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
|
3669 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
|
3670 properties. |
|
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 ============ ============================================================= |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3673 Argument Description |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3674 ============ ============================================================= |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3675 @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
|
3676 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
|
3677 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
|
3678 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
|
3679 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
|
3680 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
|
3681 sortdir0 specifies reverse order). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3682 @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
|
3683 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
|
3684 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
|
3685 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
|
3686 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
|
3687 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
|
3688 groupdir0 specifies reverse order). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3689 @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
|
3690 all. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3691 @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
|
3692 Default is none. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3693 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
|
3694 have (very basic search/filter). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3695 @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
|
3696 issue titles, etc) |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3699 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3700 Searching Views |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3701 --------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3702 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3703 .. note:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3704 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
|
3705 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
|
3706 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
|
3707 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3708 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
|
3709 "*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
|
3710 ``@action`` variable. The "search" action: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3711 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3712 - 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
|
3713 searching |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3714 - sets the ``@filter`` variable correctly |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3715 - 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
|
3716 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3717 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
|
3718 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
|
3719 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
|
3720 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
|
3721 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
|
3722 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
|
3723 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
|
3724 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3725 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
|
3726 provide an additional argument: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3727 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3728 ============ ============================================================= |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3729 Argument Description |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3730 ============ ============================================================= |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3731 @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
|
3732 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
|
3733 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
|
3734 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
|
3735 does not. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3736 ============ ============================================================= |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3737 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3738 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3739 Item Views |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3740 ---------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3741 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3742 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
|
3743 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
|
3744 "history" section. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3745 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3746 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3747 Editor Section |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3748 ~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3749 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3750 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
|
3751 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
|
3752 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3753 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
|
3754 "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
|
3755 template):: |
|
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 <table class="form"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3758 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3759 <th>Title</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3760 <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
|
3761 </tr> |
|
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 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3764 <th>Priority</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3765 <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
|
3766 <th>Status</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3767 <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
|
3768 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3769 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3770 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3771 <th>Superseder</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3772 <td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3773 <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
|
3774 <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
|
3775 <span tal:condition="context/superseder"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3776 <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
|
3777 </span> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3778 </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3779 <th>Nosy List</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3780 <td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3781 <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
|
3782 <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
|
3783 </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3784 </tr> |
|
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 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3787 <th>Assigned To</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3788 <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
|
3789 assignedto menu |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3790 </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3791 <td> </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3792 <td> </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3793 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3794 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3795 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3796 <th>Change Note</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3797 <td colspan="3"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3798 <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
|
3799 </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3800 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3801 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3802 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3803 <th>File</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3804 <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
|
3805 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3806 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3807 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3808 <td> </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3809 <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
|
3810 submit button will go here |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3811 </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3812 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3813 </table> |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3816 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
|
3817 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
|
3818 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
|
3819 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
|
3820 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3821 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3822 Form values |
|
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 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
|
3826 meet the various needs of: |
|
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 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
|
3829 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
|
3830 attached files) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3831 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
|
3832 spent on an issue) |
|
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 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
|
3835 ":" 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
|
3836 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3837 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
|
3838 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3839 ``<propname>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3840 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
|
3841 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3842 ``<designator>:<propname>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3843 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
|
3844 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3845 ``<classname>-<N>:<propname>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3846 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
|
3847 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
|
3848 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3849 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
|
3850 the special form values: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3851 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3852 ``@required`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3853 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
|
3854 raised. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3855 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3856 ``@remove@<propname>=id(s)`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3857 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
|
3858 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3859 ``:add:<propname>=id(s)`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3860 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
|
3861 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3862 ``:link:<propname>=<designator>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3863 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
|
3864 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
|
3865 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
|
3866 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
|
3867 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
|
3868 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
|
3869 <classname>-<N>). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3870 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3871 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
|
3872 designator. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3873 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3874 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
|
3875 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3876 ``:note`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3877 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
|
3878 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
|
3879 ``:file`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3880 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
|
3881 :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
|
3882 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3883 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3884 Spool Section |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3887 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
|
3888 of an issue. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3889 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3890 TODO |
|
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 History Section |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3894 ~~~~~~~~~~~~~~~ |
|
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 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
|
3897 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
|
3898 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3899 <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
|
3900 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3901 or:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3902 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3903 <tal:block |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3904 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
|
3905 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3906 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
|
3907 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3908 *To be done:* |
|
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 *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
|
3911 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
|
3912 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3913 <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
|
3914 a journal entry |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3915 </tal:block> |
|
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 *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
|
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 Defining new web actions |
|
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 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
|
3924 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
|
3925 using ``instance.registerAction``. |
|
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 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
|
3928 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3929 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
|
3930 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
|
3931 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
|
3932 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
|
3933 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3934 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
|
3935 issues |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3936 <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
|
3937 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3938 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3939 Define the new action class |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3940 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
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 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
|
3943 example ``myaction.py``:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3944 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3945 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
|
3946 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3947 class MyAction(Action): |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3948 def handle(self): |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3949 ''' 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
|
3950 ''' |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3951 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3952 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
|
3953 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
|
3954 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3955 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
|
3956 It may then: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3957 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3958 - 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
|
3959 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
|
3960 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
|
3961 - 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
|
3962 next |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3963 - 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
|
3964 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
|
3965 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3966 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3967 Register the action class |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3968 ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3969 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3970 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
|
3971 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
|
3972 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3973 def init(instance): |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3974 instance.registerAction('myaction', myActionClass) |
|
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 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
|
3977 |
|
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 Use the new action |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3980 ~~~~~~~~~~~~~~~~~~ |
|
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 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
|
3983 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3984 <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
|
3985 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3986 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
|
3987 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3988 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
|
3989 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
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 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
|
3992 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
|
3993 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
|
3994 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
|
3995 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
|
3996 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
|
3997 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
|
3998 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3999 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
|
4000 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4001 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
|
4002 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
|
4003 spreadsheet or database). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4004 |
|
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 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
|
4007 -------------------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4008 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4009 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
|
4010 and a browser cookie. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4011 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4012 - 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
|
4013 - 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
|
4014 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4015 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
|
4016 ``kio8-r``). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4017 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4018 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
|
4019 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
|
4020 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
|
4021 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
|
4022 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
|
4023 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
|
4024 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4025 <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
|
4026 <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
|
4027 {'@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
|
4028 <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
|
4029 {'@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
|
4030 </tal:block> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4031 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4032 (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
|
4033 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
|
4034 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4035 ``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
|
4036 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
|
4037 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4038 <meta http-equiv="Content-Type" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4039 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
|
4040 /> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4041 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4042 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
|
4043 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4044 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4045 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4046 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4047 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4048 Debugging Trackers |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4049 ================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4050 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4051 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
|
4052 Roundup: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4053 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4054 1. web :: debug |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4055 2. mail :: debug |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4056 3. logging :: level |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4057 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4058 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
|
4059 more information. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4060 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4061 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
|
4062 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
|
4063 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
|
4064 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4065 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4066 .. _`design documentation`: design.html |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4067 .. _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
|
4068 .. _`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
|
4069 .. _`xmlrpc interface documentation`: xmlrpc.html#through-roundup |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
4070 |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
4071 .. allow line breaks in term definitions. |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
4072 .. |br| raw:: html |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
4073 |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
4074 <br/> |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
4075 |
