Mercurial > p > roundup > code
annotate doc/reference.txt @ 8474:5346abcf429e
doc: spelling correction.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Fri, 07 Nov 2025 22:14:01 -0500 |
| parents | 056061cfe135 |
| children | bc3d3c54e1f0 |
| 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 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
16 This document was part of the `customisation document`_. The |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
17 customisation document was getting large and unwieldy. The |
|
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 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
19 information difficult. Questions raised on the mailing list were |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
20 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 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
32 .. This document borrows from the ZopeBook section on ZPT. The original was at: |
|
7280
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 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
52 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
53 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
54 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
55 =================== ======================================================== |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
56 Tracker File Description |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
57 =================== ======================================================== |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
58 config.ini Holds the basic `tracker configuration`_ |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
59 schema.py Holds the `tracker schema`_ |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
60 initial_data.py Loads initial data into the tracker (status, |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
61 priority ...) when initializing the tracker (optional) |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
62 interfaces.py Allows `modifying the core of Roundup`_ (optional) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
63 db/ Holds the tracker's database |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
64 db/files/ Holds the tracker's uploaded files and message |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
65 db/backend_name Names the database back-end for the tracker (obsolete). |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
66 Use the ``backend`` setting in the ``[rdbms]`` |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
67 section of ``config.ini`` instead. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
68 detectors/ `Auditors and reactors`_ for this tracker |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
69 extensions/ Additional `actions`_ and `templating utilities`_ |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
70 html/ Web interface templates, images and style sheets |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
71 lib/ optional common imports for detectors and extensions |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
72 =================== ======================================================== |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
73 |
|
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 .. index:: config.ini |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
76 .. index:: configuration; see config.ini |
|
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 Tracker Configuration |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
79 ===================== |
|
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 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
|
82 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
|
83 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
84 The `tracker schema`_ defines the data captured by your tracker. It |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
85 also defines the permissions used when accessing the data: see the |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
86 `security / access controls`_ section. For example, you must grant the |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
87 "Anonymous" Role the "Email Access" Permission to allow users to |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
88 automatically register through the email interface,. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
89 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
90 .. index:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
91 single: config.ini; sections |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
92 see: configuration; config.ini |
|
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 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
|
95 section "ConfigParser -- Configuration file parser": |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
96 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
97 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
|
98 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
|
99 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
|
100 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
|
101 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
|
102 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
|
103 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
|
104 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
|
105 used to provide comments. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
106 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
107 For example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
108 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
109 [My Section] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
110 foodir = %(dir)s/whatever |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
111 dir = frob |
|
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 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
|
114 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
|
115 |
|
7875
d4f6ba8e3c1e
doc: clarify use of DEFAULT section and interpolation in config files.
John Rouillard <rouilj@ieee.org>
parents:
7868
diff
changeset
|
116 The reference above discusses using the ``[DEFAULT]`` section and |
|
d4f6ba8e3c1e
doc: clarify use of DEFAULT section and interpolation in config files.
John Rouillard <rouilj@ieee.org>
parents:
7868
diff
changeset
|
117 interpolation. For example:: |
|
d4f6ba8e3c1e
doc: clarify use of DEFAULT section and interpolation in config files.
John Rouillard <rouilj@ieee.org>
parents:
7868
diff
changeset
|
118 |
|
d4f6ba8e3c1e
doc: clarify use of DEFAULT section and interpolation in config files.
John Rouillard <rouilj@ieee.org>
parents:
7868
diff
changeset
|
119 [DEFAULT] |
|
d4f6ba8e3c1e
doc: clarify use of DEFAULT section and interpolation in config files.
John Rouillard <rouilj@ieee.org>
parents:
7868
diff
changeset
|
120 local_admin_email = admin@example.com |
|
d4f6ba8e3c1e
doc: clarify use of DEFAULT section and interpolation in config files.
John Rouillard <rouilj@ieee.org>
parents:
7868
diff
changeset
|
121 |
|
d4f6ba8e3c1e
doc: clarify use of DEFAULT section and interpolation in config files.
John Rouillard <rouilj@ieee.org>
parents:
7868
diff
changeset
|
122 [main] |
|
d4f6ba8e3c1e
doc: clarify use of DEFAULT section and interpolation in config files.
John Rouillard <rouilj@ieee.org>
parents:
7868
diff
changeset
|
123 admin_email = %(local_admin_email)s |
|
d4f6ba8e3c1e
doc: clarify use of DEFAULT section and interpolation in config files.
John Rouillard <rouilj@ieee.org>
parents:
7868
diff
changeset
|
124 |
|
d4f6ba8e3c1e
doc: clarify use of DEFAULT section and interpolation in config files.
John Rouillard <rouilj@ieee.org>
parents:
7868
diff
changeset
|
125 will set the admin_email setting. This works when running the |
|
d4f6ba8e3c1e
doc: clarify use of DEFAULT section and interpolation in config files.
John Rouillard <rouilj@ieee.org>
parents:
7868
diff
changeset
|
126 tracker. When upgrading Roundup using ``updateconfig`` to create |
|
d4f6ba8e3c1e
doc: clarify use of DEFAULT section and interpolation in config files.
John Rouillard <rouilj@ieee.org>
parents:
7868
diff
changeset
|
127 a new ``config.ini``, the ``DEFAULT`` section is not preserved |
|
d4f6ba8e3c1e
doc: clarify use of DEFAULT section and interpolation in config files.
John Rouillard <rouilj@ieee.org>
parents:
7868
diff
changeset
|
128 and interpolation tokens (e.g. ``%(local_admin_email)s`` are |
|
d4f6ba8e3c1e
doc: clarify use of DEFAULT section and interpolation in config files.
John Rouillard <rouilj@ieee.org>
parents:
7868
diff
changeset
|
129 replaced with their values (``admin@example.com``). This may be |
|
d4f6ba8e3c1e
doc: clarify use of DEFAULT section and interpolation in config files.
John Rouillard <rouilj@ieee.org>
parents:
7868
diff
changeset
|
130 fixed in a future release of Roundup. |
|
d4f6ba8e3c1e
doc: clarify use of DEFAULT section and interpolation in config files.
John Rouillard <rouilj@ieee.org>
parents:
7868
diff
changeset
|
131 |
|
d4f6ba8e3c1e
doc: clarify use of DEFAULT section and interpolation in config files.
John Rouillard <rouilj@ieee.org>
parents:
7868
diff
changeset
|
132 Note that you can not reference settings in the ``DEFAULT`` |
|
d4f6ba8e3c1e
doc: clarify use of DEFAULT section and interpolation in config files.
John Rouillard <rouilj@ieee.org>
parents:
7868
diff
changeset
|
133 section from Roundup. They are only useful when interpolated into |
|
d4f6ba8e3c1e
doc: clarify use of DEFAULT section and interpolation in config files.
John Rouillard <rouilj@ieee.org>
parents:
7868
diff
changeset
|
134 a defined setting. |
|
d4f6ba8e3c1e
doc: clarify use of DEFAULT section and interpolation in config files.
John Rouillard <rouilj@ieee.org>
parents:
7868
diff
changeset
|
135 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
136 __ 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
|
137 |
|
7920
6aa0525187cd
doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
7875
diff
changeset
|
138 A default ``config.ini`` file broken into sections is shown below. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
139 |
|
7920
6aa0525187cd
doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
7875
diff
changeset
|
140 .. include:: tracker_config.txt |
|
6aa0525187cd
doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
7875
diff
changeset
|
141 |
|
6aa0525187cd
doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
7875
diff
changeset
|
142 Additional notes: |
|
6aa0525187cd
doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
7875
diff
changeset
|
143 |
|
6aa0525187cd
doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
7875
diff
changeset
|
144 The ``[rdbms]`` service defines the Connection Service for your |
|
6aa0525187cd
doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
7875
diff
changeset
|
145 PostgreSQL connection when using a system-wide pg_service.conf or |
|
6aa0525187cd
doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
7875
diff
changeset
|
146 ~/.pg_service.conf as discussed in |
|
6aa0525187cd
doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
7875
diff
changeset
|
147 https://www.postgresql.org/docs/current/libpq-pgservice.html. |
|
6aa0525187cd
doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
7875
diff
changeset
|
148 |
|
6aa0525187cd
doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
7875
diff
changeset
|
149 Setting this to the name of the service allows different trackers to |
|
6aa0525187cd
doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
7875
diff
changeset
|
150 connect to different services when running multiple trackers under one |
|
6aa0525187cd
doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
7875
diff
changeset
|
151 Roundup server. If you are only running one tracker, you can set the |
|
6aa0525187cd
doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
7875
diff
changeset
|
152 PGSERVICE environment variable. Note that other settings specified in |
|
6aa0525187cd
doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
7875
diff
changeset
|
153 this file (rdbms: user, password, port, host, (db)name) will override |
|
6aa0525187cd
doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
7875
diff
changeset
|
154 the corresponding connection service setting. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
155 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
156 .. 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
|
157 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
|
158 single: config.ini; create |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
159 single: config.ini; update |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
160 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
161 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
|
162 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
|
163 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
|
164 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
165 Configuration variables may be referred to in lower or upper case. In code, |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
166 refer to variables not in the "main" section using their section and |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
167 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
|
168 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
169 .. index:: pair: configuration; extensions |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
170 pair: configuration; detectors |
|
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 Extending the configuration file |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
173 -------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
174 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
175 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
|
176 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
|
177 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
178 - a config.ini in the ``extensions`` directory is loaded and attached |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
179 to the config variable as "ext". |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
180 - a config.ini in the ``detectors`` directory is loaded and attached |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
181 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
|
182 |
|
7875
d4f6ba8e3c1e
doc: clarify use of DEFAULT section and interpolation in config files.
John Rouillard <rouilj@ieee.org>
parents:
7868
diff
changeset
|
183 These configuration files support the same operations as the main |
|
d4f6ba8e3c1e
doc: clarify use of DEFAULT section and interpolation in config files.
John Rouillard <rouilj@ieee.org>
parents:
7868
diff
changeset
|
184 ``config.ini`` file. This included a ``DEFAULT`` section and |
|
d4f6ba8e3c1e
doc: clarify use of DEFAULT section and interpolation in config files.
John Rouillard <rouilj@ieee.org>
parents:
7868
diff
changeset
|
185 interpolation. Note that you can not reference settings in the |
|
d4f6ba8e3c1e
doc: clarify use of DEFAULT section and interpolation in config files.
John Rouillard <rouilj@ieee.org>
parents:
7868
diff
changeset
|
186 ``DEFAULT`` section from Roundup. They can only be used for |
|
d4f6ba8e3c1e
doc: clarify use of DEFAULT section and interpolation in config files.
John Rouillard <rouilj@ieee.org>
parents:
7868
diff
changeset
|
187 interpolation. |
|
d4f6ba8e3c1e
doc: clarify use of DEFAULT section and interpolation in config files.
John Rouillard <rouilj@ieee.org>
parents:
7868
diff
changeset
|
188 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
189 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
|
190 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
191 [main] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
192 qa_recipients = email@example.com |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
193 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
194 is accessible as:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
195 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
196 db.config.detectors['QA_RECIPIENTS'] |
|
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 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
|
199 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
|
200 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
201 [qa] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
202 recipients = email@example.com |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
203 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
204 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
|
205 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
206 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
|
207 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
|
208 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
|
209 "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
|
210 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
|
211 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
212 Also, incorrect values are discovered when the config setting is |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
213 used not set. This can be long after the tracker is |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
214 started and the error may not be seen in the logs. |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
215 |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
216 It's possible to validate these settings. Validation involves calling |
|
7920
6aa0525187cd
doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
7875
diff
changeset
|
217 the ``update_options`` method on the configuration option. This can be |
|
6aa0525187cd
doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
7875
diff
changeset
|
218 done by the ``init()`` function in the Python files implementing |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
219 extensions_ or detectors_. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
220 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
221 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
|
222 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
223 from roundup.configuration import SecretMandatoryOption |
|
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 def init(instance): |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
226 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
|
227 SecretMandatoryOption,description="Secret securing reCaptcha.") |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
228 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
229 similarly for a detector:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
230 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
231 from roundup.configuration import MailAddressOption |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
232 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
233 def init(db): |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
234 try: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
235 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
|
236 MailAddressOption, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
237 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
|
238 except KeyError: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
239 # 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
|
240 # so continue |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
241 pass |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
242 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
243 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
|
244 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
|
245 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
246 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
|
247 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
|
248 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
|
249 gateway). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
250 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
251 ``update_option`` takes 4 arguments: |
|
7352
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 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
|
254 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
|
255 (positional, mandatory) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
256 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
|
257 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
|
258 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
259 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
|
260 beginning of this section. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
261 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
262 The second argument is a class in the roundup.configuration module. |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
263 There are many of these classes: BooleanOption, |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
264 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
|
265 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
|
266 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
|
267 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
268 The third and fourth arguments are optional strings. They are printed |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
269 when there is an error and may help the user correct the problem. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
270 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
271 .. index:: ! schema |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
272 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
273 Tracker Schema |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
274 ============== |
|
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 .. note:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
277 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
|
278 `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
|
279 your changes. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
280 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
281 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
|
282 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
|
283 tracker. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
284 |
|
7482
82a0adad2ae6
Fix bad index reference. Add new ones.
John Rouillard <rouilj@ieee.org>
parents:
7459
diff
changeset
|
285 .. index:: schema; allowed changes |
|
82a0adad2ae6
Fix bad index reference. Add new ones.
John Rouillard <rouilj@ieee.org>
parents:
7459
diff
changeset
|
286 |
| 7359 | 287 What you can/can't do to the schema |
| 288 ----------------------------------- | |
| 289 | |
| 290 Your schema may be changed at any time before or after the tracker has been | |
| 291 initialised (or used). You may: | |
| 292 | |
| 293 **Add new properties to classes, or add whole new classes** | |
| 294 This is painless and easy to do - there are generally no repercussions | |
| 295 from adding new information to a tracker's schema. | |
| 296 | |
| 297 **Remove properties** | |
| 298 Removing properties is a little more tricky - you need to make sure that | |
| 299 the property is no longer used in the `web interface`_ *or* by the | |
| 300 detectors_. | |
| 301 | |
| 302 You must never: | |
| 303 | |
| 304 **Remove the user class** | |
| 305 This class is the only *required* class in Roundup. | |
| 306 | |
|
7638
f58582135861
docs: add "roles" to list of required user object properties.
John Rouillard <rouilj@ieee.org>
parents:
7559
diff
changeset
|
307 **Remove the "username", "address", "password", "roles" or "realname" user properties** |
| 7359 | 308 Various parts of Roundup require these properties. Don't remove them. |
| 309 | |
| 310 **Change the type of a property** | |
| 311 Property types must *never* [1]_ be changed - the database simply | |
| 312 doesn't take this kind of action into account. Note that you can't | |
| 313 just remove a property and re-add it as a new type either. If you | |
| 314 wanted to make the assignedto property a Multilink, you'd need to | |
| 315 create a new property assignedto_list and remove the old assignedto | |
| 316 property. | |
| 317 | |
| 318 .. [1] If you shut down the tracker, `export the database`_, modify the | |
| 319 exported csv property data to be compatible with the new type, | |
| 320 change the property type in the schema, and finally import the | |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
321 changed exported data, you can change the property type. This is |
| 7359 | 322 not trivial nor for the faint of heart. But it can be done. |
| 323 | |
| 324 .. _export the database: admin_guide.html#using-roundup-admin | |
| 325 | |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
326 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
|
327 ------------------------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
328 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
329 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
|
330 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
|
331 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
|
332 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
|
333 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
|
334 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
335 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
|
336 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
|
337 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
|
338 info about how this works. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
339 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
340 .. index:: schema; classic - description of |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
341 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
342 The "classic" schema |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
345 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
|
346 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
|
347 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
|
348 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
|
349 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
350 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
|
351 pri.setkey("name") |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
352 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
353 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
|
354 stat.setkey("name") |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
355 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
356 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
|
357 keyword.setkey("name") |
|
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 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
|
360 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
|
361 phone=String(), alternate_addresses=String(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
362 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
|
363 user.setkey("username") |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
364 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
365 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
|
366 date=Date(), recipients=Multilink("user"), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
367 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
|
368 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
369 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
|
370 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
371 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
|
372 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
|
373 priority=Link("priority")) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
374 issue.setkey('title') |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
375 |
|
7482
82a0adad2ae6
Fix bad index reference. Add new ones.
John Rouillard <rouilj@ieee.org>
parents:
7459
diff
changeset
|
376 .. 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
|
377 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
378 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
|
379 --------------------------------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
380 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
381 The tracker above, defines 7 classes of information: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
382 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
383 priority |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
384 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
|
385 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
386 status |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
387 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
|
388 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
389 keyword |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
390 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
|
391 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
392 user |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
393 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
|
394 for all users using 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 msg |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
397 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
|
398 generated by Roundup. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
399 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
400 file |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
401 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
|
402 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
403 issue |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
404 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
|
405 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
406 It defines the "priority" and "status" classes to allow two things: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
407 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
408 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
|
409 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
|
410 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
411 By requiring a link on the issue (stored as a single |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
412 number) the chance that someone mis-types a priority or |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
413 status - or makes a new one up is reduced. |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
414 |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
415 Class names access items of that class in the `REST api`_ |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
416 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
|
417 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
|
418 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
|
419 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
|
420 classes that you add. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
421 |
|
7482
82a0adad2ae6
Fix bad index reference. Add new ones.
John Rouillard <rouilj@ieee.org>
parents:
7459
diff
changeset
|
422 .. index:: |
|
82a0adad2ae6
Fix bad index reference. Add new ones.
John Rouillard <rouilj@ieee.org>
parents:
7459
diff
changeset
|
423 schema; classes |
|
82a0adad2ae6
Fix bad index reference. Add new ones.
John Rouillard <rouilj@ieee.org>
parents:
7459
diff
changeset
|
424 schema; items |
|
82a0adad2ae6
Fix bad index reference. Add new ones.
John Rouillard <rouilj@ieee.org>
parents:
7459
diff
changeset
|
425 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
426 Class and Items |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
427 ~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
428 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
429 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
|
430 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
|
431 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
|
432 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
433 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
|
434 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
|
435 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
|
436 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
437 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
438 .. index:: schema; property types |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
439 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
440 Properties |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
441 ~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
442 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
443 A Class consists of one or more properties of the following types: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
444 |
|
8255
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8165
diff
changeset
|
445 Boolean |
|
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8165
diff
changeset
|
446 properties store on/off, yes/no, true/false values. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
447 Date |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
448 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
|
449 objects. |
|
8255
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8165
diff
changeset
|
450 Integer |
|
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8165
diff
changeset
|
451 properties store integer values. (Number can store real/float values.) |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
452 Interval |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
453 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
|
454 example 2 hours. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
455 Link |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
456 properties refers to a single item selected from a |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
457 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
|
458 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
|
459 Multilink |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
460 properties refer to one or more items in a specified |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
461 class. The value is a list of integers. |
|
8255
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8165
diff
changeset
|
462 Number |
|
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8165
diff
changeset
|
463 properties store numeric values. There is an option to use |
|
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8165
diff
changeset
|
464 double-precision floating point numbers. |
|
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8165
diff
changeset
|
465 Password |
|
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8165
diff
changeset
|
466 properties store encoded arbitrary-length strings. |
|
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8165
diff
changeset
|
467 The default encoding is defined in the ``roundup.password.Password`` |
|
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8165
diff
changeset
|
468 class. |
|
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8165
diff
changeset
|
469 String |
|
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8165
diff
changeset
|
470 properties store arbitrary-length strings. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
471 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
472 Properties have attributes to change the default behaviour: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
473 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
474 .. 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
|
475 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
|
476 triple: schema; property attributes; quiet |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
477 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
478 * 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
|
479 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
480 - ``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
|
481 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
|
482 - ``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
|
483 value if the property is not set. |
|
8255
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8165
diff
changeset
|
484 - ``quiet``: see `design documentation`_. Suppresses reporting user |
|
7d72b9a9fe9c
docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents:
8165
diff
changeset
|
485 visible changes to this property. The property change is not reported: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
486 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
487 - 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
|
488 interface |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
489 - 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
|
490 - 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
|
491 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
492 This is useful when storing the state of the user interface (e.g. the |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
493 names of elements that are collapsed or hidden from the |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
494 user). Properties updates as an indirect result of |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
495 a user's change (e.g. updating a blockers property, counting |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
496 number of times an issue is reopened or reassigned etc.) should |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
497 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
|
498 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
499 .. 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
|
500 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
501 * String properties have an ``indexme`` attribute. The default is |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
502 'no'. Setting it to 'yes' includes the property in the full text |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
503 index. |
|
7352
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 .. 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
|
506 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
507 * 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
|
508 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
|
509 * 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
|
510 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
511 .. 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
|
512 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
513 - ``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
|
514 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
|
515 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
|
516 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
|
517 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
|
518 events. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
519 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
520 .. 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
|
521 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
522 - ``try_id_parsing`` is turned on by default. If a number is entered |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
523 into a Link or Multilink field, Roundup interprets this number as |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
524 an ID of the item to link to. Sometimes items can have numeric |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
525 names (e.g., product codes). For these Roundup needs to |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
526 match the numeric name and should never match an ID. In this case |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
527 you can set ``try_id_parsing='no'``. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
528 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
529 .. 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
|
530 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
531 - 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
|
532 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
|
533 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
|
534 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
|
535 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
|
536 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
|
537 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
|
538 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
|
539 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
540 As a example, suppose you want to group multiple issues into a |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
541 super issue. Each issue can be part of one super issue. It is |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
542 inefficient to find all of the issues linked to the super issue by |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
543 searching through all issues in the system looking at the part_of |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
544 link property. To make this more efficient, you can declare an |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
545 issue's part_of property as:: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
546 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
547 issue = IssueClass(db, "issue", |
|
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 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
|
550 ... ) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
551 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
552 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
|
553 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
|
554 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
|
555 declared the class as:: |
|
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 issue = IssueClass(db, "issue", |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
558 ... |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
559 part_of = Link("issue"), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
560 components = Multilink("issue"), |
|
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 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
|
564 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
|
565 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
|
566 ``components`` multilink. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
567 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
568 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
|
569 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
|
570 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
|
571 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
|
572 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
|
573 is that when a linked node is retired, the node vanishes from the |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
574 multilink. In the example above, when issue 1234 with ``part_of`` |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
575 set to issue 5678 is retired, 1234 vanishes from the |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
576 ``components`` multilink of issue 5678. |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
577 |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
578 You can also link between different classes. If the issue |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
579 definition includes:: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
580 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
581 issue = IssueClass(db, "issue", |
|
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 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
|
584 ... ) |
|
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 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
|
587 for (aka assigned_to). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
588 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
589 .. 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
|
590 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
591 - 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
|
592 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
|
593 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
|
594 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
595 X-Roundup-issue-prop: value |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
596 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
597 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
|
598 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
|
599 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
|
600 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
601 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
|
602 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
603 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
|
604 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
605 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
|
606 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
607 ``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
|
608 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
609 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
|
610 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
|
611 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
612 X-Roundup-issue-assigned_to: ... |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
613 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
614 so that the mail recipients can filter emails where |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
615 ``X-Roundup-issue-assigned_to: name`` contains their |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
616 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
|
617 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
618 user = Class(db, "user", |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
619 username=String(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
620 password=Password(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
621 address=String(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
622 realname=String(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
623 phone=String(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
624 organisation=String(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
625 alternate_addresses=String(), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
626 queries=Multilink('query'), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
627 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
|
628 timezone=String()) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
629 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
630 Because the user class does not have a ``name`` parameter, no |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
631 header will be written. Setting:: |
|
7352
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 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
|
634 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
635 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
|
636 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
|
637 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
638 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
|
639 username=joe_user, setting:: |
|
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 msg_header_property="username" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
642 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
643 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
|
644 form:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
645 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
646 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
|
647 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
648 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
|
649 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
650 If this property is set to the empty string "", no header will be |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
651 generated on outgoing mail. |
|
7352
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:: triple: schema; class property; creator |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
654 triple: schema; class property; creation |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
655 triple: schema; class property; actor |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
656 triple: schema; class property; activity |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
657 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
658 All Classes automatically have four properties by default: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
659 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
660 *creator* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
661 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
|
662 *creation* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
663 Date the item was created. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
664 *actor* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
665 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
|
666 *activity* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
667 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
|
668 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
669 |
| 7359 | 670 .. index:: double: schema; class methods |
| 671 | |
| 672 Methods | |
| 673 ~~~~~~~ | |
| 674 | |
| 675 All classes have the following methods. | |
| 676 | |
| 677 .. index:: triple: schema; class method; setkey | |
| 678 | |
| 679 setkey(property) | |
| 680 :::::::::::::::: | |
| 681 | |
| 682 .. index:: roundup-admin; setting assignedto on an issue | |
| 683 | |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
684 Set the key property of a class to a string property. The key property |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
685 must be unique. References to the items in the class can be done by |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
686 the content of the key property. For example, you can refer to users by |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
687 their username. Let's say that there's an issue in |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
688 Roundup, issue 23. There's also a user, richard, who happens to be |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
689 user 2. To assign an issue to him, we could do use:: |
| 7359 | 690 |
| 691 roundup-admin set issue23 assignedto=2 | |
| 692 | |
| 693 or:: | |
| 694 | |
| 695 roundup-admin set issue23 assignedto=richard | |
| 696 | |
| 697 Note, the same thing can be done in the web and e-mail interfaces. | |
| 698 | |
| 699 .. index:: triple: schema; class method; setlabelprop | |
| 700 | |
| 701 setlabelprop(property) | |
| 702 :::::::::::::::::::::: | |
| 703 | |
| 704 Select a property of the class to be the label property. The label | |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
705 property is used whenever an item should be uniquely identified, e.g., |
| 7359 | 706 when displaying a link to an item. If setlabelprop is not specified for |
| 707 a class, the following values are tried for the label: | |
| 708 | |
| 709 * the key of the class (see the `setkey(property)`_ section above) | |
| 710 * the "name" property | |
| 711 * the "title" property | |
| 712 * the first property from the sorted property name list | |
| 713 | |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
714 In most cases you can get away without specifying setlabelprop |
| 7359 | 715 explicitly. |
| 716 | |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
717 Users should have View access to this property or the id property for |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
718 a class. If the property can not be viewed by a user, looping over |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
719 items in the class (e.g. messages attached to an issue) will not work. |
| 7359 | 720 |
| 721 .. index:: triple: schema; class method; setorderprop | |
| 722 | |
| 723 setorderprop(property) | |
| 724 :::::::::::::::::::::: | |
| 725 | |
| 726 Select a property of the class to be the order property. The order | |
| 727 property is used whenever using a default sort order for the class, | |
| 728 e.g., when grouping or sorting class A by a link to class B in the user | |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
729 interface, the order property of class B is used for sorting. If |
| 7359 | 730 setorderprop is not specified for a class, the following values are tried |
| 731 for the order property: | |
| 732 | |
| 733 * the property named "order" | |
| 734 * the label property (see `setlabelprop(property)`_ above) | |
| 735 | |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
736 Usually you can get away without specifying setorderprop |
| 7359 | 737 explicitly. |
| 738 | |
| 739 .. index:: triple: schema; class method; create | |
| 740 | |
| 741 create(information) | |
| 742 ::::::::::::::::::: | |
| 743 | |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
744 Create an item in the database. This is 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
|
745 in the :term:`definitional class` like "priority" and "status". |
| 7359 | 746 |
|
8264
09e8d1a4c796
docs: clarify wording, fix index, add superseder link
John Rouillard <rouilj@ieee.org>
parents:
8263
diff
changeset
|
747 .. index:: triple: schema; class property; messages |
|
09e8d1a4c796
docs: clarify wording, fix index, add superseder link
John Rouillard <rouilj@ieee.org>
parents:
8263
diff
changeset
|
748 triple: schema; class property; files |
|
09e8d1a4c796
docs: clarify wording, fix index, add superseder link
John Rouillard <rouilj@ieee.org>
parents:
8263
diff
changeset
|
749 triple: schema; class property; nosy |
|
09e8d1a4c796
docs: clarify wording, fix index, add superseder link
John Rouillard <rouilj@ieee.org>
parents:
8263
diff
changeset
|
750 triple: schema; class property; superseder |
|
09e8d1a4c796
docs: clarify wording, fix index, add superseder link
John Rouillard <rouilj@ieee.org>
parents:
8263
diff
changeset
|
751 |
| 7359 | 752 IssueClass |
| 753 ~~~~~~~~~~ | |
| 754 | |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
755 IssueClass automatically includes the "messages", "files", "nosy", and |
| 7359 | 756 "superseder" properties. |
| 757 | |
| 758 The messages and files properties list the links to the messages and | |
| 759 files related to the issue. The nosy property is a list of links to | |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
760 users to tell about changes to the issue. They get "CC'ed" |
| 7359 | 761 e-mails when messages are sent to or generated by the issue. The nosy |
| 762 reactor (in the ``'detectors'`` directory) handles this action. The | |
| 763 superseder link indicates an issue which has superseded this one. | |
|
8264
09e8d1a4c796
docs: clarify wording, fix index, add superseder link
John Rouillard <rouilj@ieee.org>
parents:
8263
diff
changeset
|
764 It is better described in the |
|
09e8d1a4c796
docs: clarify wording, fix index, add superseder link
John Rouillard <rouilj@ieee.org>
parents:
8263
diff
changeset
|
765 `original document <original_overview.html#roundupdb>`_. |
| 7359 | 766 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
767 They also have the default "creation", "activity" and "creator" |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
768 properties. |
| 7359 | 769 |
| 770 The value of the "creation" property is the date when an item was | |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
771 created. The value of the "activity" property is the date when any |
| 7359 | 772 property on the item was last edited (equivalently, these are the dates |
| 773 on the first and last records in the item's journal). The "creator" | |
| 774 property holds a link to the user that created the issue. | |
| 775 | |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
776 .. 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
|
777 triple: schema; class property; type |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
778 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
779 FileClass |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
780 ~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
781 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
782 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
|
783 the rest of the database. This reduces the number of large entries in |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
784 the database, which makes databases more efficient. Also web servers, |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
785 image processing applications, and command line tools can operate on |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
786 the files. The content is stored in the ``files`` sub-directory of the |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
787 ``'db'`` directory in your tracker. FileClasses also have a "type" |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
788 attribute to store the file's MIME type. |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
789 |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
790 Roundup, by default, considers the contents of the file |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
791 immutable. This assists in maintaining an accurate record of |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
792 correspondence. The distributed tracker templates do not enforce |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
793 this. If you have access to the Roundup tracker directory, you can |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
794 edit the files (make sure to preserve mode, owner and group) to remove |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
795 information. You may need to do this if somebody includes a password |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
796 or you need to redact proprietary information. The journal for the |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
797 message/file won't report that the file has changed. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
798 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
799 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
|
800 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
|
801 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
802 [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
|
803 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
804 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
|
805 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
806 [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
|
807 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
808 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
|
809 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
|
810 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
|
811 (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
|
812 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
|
813 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
|
814 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
|
815 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
|
816 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
|
817 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
|
818 command line interface. |
|
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 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
|
821 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
|
822 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
|
823 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
|
824 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
825 $ curl -u demo:demo -s |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
826 -H "X-requested-with: rest" \ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
827 -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
|
828 -X GET \ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
829 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
|
830 { |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
831 "data": { |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
832 "id": "30", |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
833 "type": "<class 'str'>", |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
834 "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
|
835 "data": "hello3", |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
836 "@etag": "\"3f2f8063dbce5b6bd43567e6f4f3c671\"" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
837 } |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
838 } |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
839 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
840 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
|
841 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
842 $ curl -u demo:demo -s |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
843 -H "X-requested-with: rest" \ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
844 -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
|
845 -H 'If-Match: "3f2f8063dbce5b6bd43567e6f4f3c671"' \ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
846 -X PUT \ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
847 -F "data=@hello" \ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
848 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
|
849 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
850 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
|
851 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
852 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
|
853 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
|
854 property. The auditor could also add a journal entry so that a change |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
855 via the Roundup mechanism is reported. Using a mixin (see: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
856 https://wiki.roundup-tracker.org/MixinClassFileClass) to augment the |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
857 file class allows for other possibilities including: |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
858 |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
859 * signing the file, |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
860 * recording a checksum in the database and validating the file |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
861 contents at the time it gets read. This allows detection of changes |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
862 done on the filesystem outside of the Roundup mechanism. |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
863 * keeping multiple revisions of the file. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
864 |
| 7359 | 865 .. index:: schema; item ordering |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
866 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
867 A note about ordering |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
868 ~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
869 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
870 When we sort items in the hyperdb, we use one of three methods, |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
871 depending on the property type: |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
872 |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
873 1. String, Integer, Number, Date or Interval property, sort the scalar |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
874 value of the property. Strings sort case-sensitively. |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
875 2. a Link property, sort by either the linked item's "order" |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
876 property (if it has one) or the linked item's "id". |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
877 3. Mulitlinks sort similar to #2, starting with the first Multilink |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
878 list item, and if they are the same, sort by the second item, and |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
879 so on. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
880 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
881 Note that if an "order" property is defined for a class, all items of |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
882 that Class *must* have a value for the "order" property, or |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
883 sorting will result in random ordering. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
884 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
885 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
886 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
|
887 --------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
888 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
889 See :ref:`CustomExamples` for examples. |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
890 |
|
8412
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
891 The `Roundup wiki CategorySchema`_ provides a list of additional |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
892 examples of how to customize schemas to add new functionality. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
893 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
894 .. _Roundup wiki CategorySchema: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
895 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
|
896 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
897 .. index:: !detectors |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
898 .. _detectors: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
899 .. _Auditors and reactors: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
900 |
|
7459
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
901 |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
902 Schema Integrity |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
903 ---------------- |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
904 |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
905 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
|
906 contains a representation of the current schema and the current |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
907 Roundup schema version. Roundup will exit if the version is not supported |
|
7459
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
908 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
|
909 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
|
910 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
|
911 |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
912 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
|
913 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
|
914 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
|
915 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
|
916 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
|
917 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
|
918 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
|
919 |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
920 Postgres |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
921 .. code:: |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
922 |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
923 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
|
924 '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
|
925 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
|
926 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
|
927 |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
928 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
|
929 ``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
|
930 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
|
931 |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
932 SQLite |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
933 .. code:: |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
934 |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
935 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
|
936 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
|
937 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
|
938 |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
939 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
|
940 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
|
941 version. |
|
2e3b5c10c502
Add section on schema integrity, use of schema table in rdbms backends
John Rouillard <rouilj@ieee.org>
parents:
7457
diff
changeset
|
942 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
943 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
|
944 ============================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
945 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
946 Detectors are Python modules that sit in your tracker's ``detectors`` |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
947 directory. You are free to add and remove them any time, even after |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
948 the database is initialised via the ``roundup-admin initialise`` |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
949 command. |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
950 |
|
8412
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
951 There are two types of detectors: |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
952 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
953 1. *auditors* are run before changes are made to the database |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
954 2. *reactors* are run after the change has been committed to the database |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
955 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
956 .. index:: auditors; rules for use |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
957 single: reactors; rules for use |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
958 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
959 Auditor or Reactor? |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
960 ------------------- |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
961 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
962 Generally speaking, you should observe the following rules: |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
963 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
964 **Auditors** |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
965 Are used for `vetoing creation of or changes to items`_. They might |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
966 also make automatic changes to item properties. They can raise the |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
967 ``Reject`` or ``CheckId`` exceptions to control database changes. |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
968 **Reactors** |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
969 Detect changes in the database and react accordingly. They should avoid |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
970 making changes to the database where possible, as this could create |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
971 detector loops. |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
972 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
973 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
974 Detectors Installed by Default |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
975 ------------------------------ |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
976 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
977 You will have some detectors installed by default - have a look in the |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
978 ``detectors`` subdirectory of your tracker home. You can write new |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
979 detectors or modify the existing ones. The existing detectors |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
980 installed for you are: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
981 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
982 .. index:: detectors; installed |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
983 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
984 **nosyreaction.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
985 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
|
986 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
|
987 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
|
988 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
|
989 (such as adding new authors, etc.) |
|
8412
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
990 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
991 If you are running a tracker started with ``roundup-demo`` or the |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
992 ``demo.py`` script, this detector will be missing.This is |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
993 intentional to prevent email from being sent from a demo |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
994 tracker. You can find the nosyreaction.py detector in the |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
995 :term:`template directory (meaning 3) <template>` and copy it into |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
996 your tracker if you want email to be sent. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
997 **statusauditor.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
998 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
|
999 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
|
1000 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
|
1001 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
|
1002 defined. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1003 **messagesummary.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1004 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
|
1005 content. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1006 **userauditor.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1007 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
|
1008 roles lists). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1009 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1010 If you don't want this default behaviour, you are completely free to change |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1011 or remove these detectors. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1012 |
|
8412
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1013 The rest of this section includes much of the information from the |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1014 `detectors section in the design document`_. But there are some |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1015 details of the detector interface that are only in the design |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1016 document. Also the design document `includes examples`_ of a project |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1017 that requires three approvals before it can be processed and rejecting |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1018 an email to create an issue if it doesn't have an attached patch. |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1019 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1020 .. _`detectors section in the design document`: design.html#detector-interface |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1021 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1022 .. _`includes examples`: design.html#detector-example |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1023 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1024 Registering Detectors |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1025 --------------------- |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1026 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1027 Detectors are registered using the ``audit`` or ``react`` methods of a |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1028 database schema class. Each detector file must define an ``init(db)`` |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1029 function. This function is run to register the detectors. For example |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1030 this registers two auditors for changes made to the user class in the |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1031 database:: |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1032 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1033 def init(db): |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1034 # fire before changes are made |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1035 db.user.audit('set', audit_user_fields) |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1036 db.user.audit('create', audit_user_fields) |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1037 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1038 while this registers two auditors and two reactors for the issue |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1039 class:: |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1040 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1041 def init(db): |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1042 db.issue.react('create', nosyreaction) |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1043 db.issue.react('set', nosyreaction) |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1044 db.issue.audit('create', updatenosy) |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1045 db.issue.audit('set', updatenosy) |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1046 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1047 The arguments for ``audit`` and ``react`` are the same: |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1048 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1049 * operation - one of ``create``, ``set``, ``retire``, or ``restore`` |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1050 * function name - use the function name without ``()`` after |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1051 it. (You want the function name not the result of calling the |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1052 function.) |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1053 * priority - (optional default 100) the priority allows you to order |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1054 the application order of the detectors. |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1055 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1056 A detector with a priority of 110 will run after a detector with |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1057 the default priority of 100. A detector with a priority of 90 will |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1058 run before a detector with the default priority of 100. |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1059 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1060 Detectors with the same priority are run in an undefined |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1061 order. All the examples above use the default priority of 100. |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1062 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1063 If no auditor raises an exception, the changes are committed to the |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1064 database. Then all the reactors registered for the operation are run. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1065 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1066 .. index:: detectors; writing api |
|
8412
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1067 .. _detector_api: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1068 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1069 Detector API |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1070 ------------ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1071 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1072 .. index:: pair: detectors; auditors |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1073 single: auditors; function signature |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1074 single: auditors; defining |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1075 single: auditors; arguments |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1076 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1077 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
|
1078 |
|
8412
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1079 an_auditor(db, cl, itemid, newdata) |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1080 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1081 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
|
1082 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
|
1083 property names to values. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1084 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1085 For a ``create()`` operation, the ``itemid`` argument is None and |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1086 ``newdata`` contains all the initial property values that will be |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1087 used to create the item |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1088 |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1089 For a ``set()`` operation, ``newdata`` contains only the names and |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1090 values of properties that are about to be changed. |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1091 |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1092 For a ``retire()`` or ``restore()`` operation, ``newdata`` is None. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1093 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1094 .. index:: pair: detectors; reactor |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1095 single: reactors; function signature |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1096 single: reactors; defining |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1097 single: reactors; arguments |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1098 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1099 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
|
1100 |
|
8412
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1101 a_reactor(db, cl, itemid, olddata) |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1102 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1103 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
|
1104 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
|
1105 property names to values. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1106 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1107 For a ``create()`` operation, the ``itemid`` argument is the id of the |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1108 newly created item and ``olddata`` is None. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1109 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1110 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
|
1111 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
|
1112 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1113 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
|
1114 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
|
1115 |
|
8412
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1116 Your auditor can raise one of two exceptions: |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1117 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1118 ``Reject('Reason for rejection')`` |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1119 indicates that the change is rejected. The user should see the same |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1120 page they used to make the change with a the 'Reason for rejection' |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1121 message displayed in the error feedback section of the page. See |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1122 :ref:`vetoing creation of or changes to items` for an example. |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1123 ``Reauth('Reason for confirmation')`` |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1124 indicates that the user needs to enter their password or other |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1125 identity confirming information (e.g. a one time key) before the |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1126 change will be committed. This can be used when a user's password or |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1127 email address are changed. This can prevent an attacker from changing |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1128 the information by providing confirmation of the person making the |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1129 change. This addition confirmation step is recommended in the `OWASP |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1130 Authentication Cheat Sheet`_. An example can be found at |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1131 :ref:`sensitive_changes`. See :ref:`Confirming the User` for details |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1132 and warnings. |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1133 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1134 .. _`OWASP Authentication Cheat Sheet`: |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1135 https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html#require-re-authentication-for-sensitive-features |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1136 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1137 .. index:: detectors; additional |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1138 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1139 Additional Detectors Ready For Use |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1140 ---------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1141 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1142 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
|
1143 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
|
1144 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
|
1145 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1146 **irker.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1147 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
|
1148 (http://www.catb.org/esr/irker/) when issues are created or messages |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1149 are added. To use it you need to install irker, start the |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1150 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
|
1151 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
|
1152 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
|
1153 **newissuecopy.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1154 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
|
1155 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
|
1156 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
|
1157 email errors! |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1158 **creator_resolution.py** |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1159 When the status is set to "resolved" this auditor checks the user |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1160 performing the action. If the user is not the creator, it sets the |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1161 status to "confirm-done". Note that "classic" Roundup doesn't have |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1162 that status, so you'll have to add it. If you don't want to though, |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1163 it'll just use "in-progress" instead. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1164 **email_auditor.py** |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1165 If a file added to an issue is of type message/rfc822, tack on the |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1166 extension .eml. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1167 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
|
1168 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
|
1169 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
|
1170 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
|
1171 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1172 |
|
8412
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1173 .. _`Vetoing creation of or changes to items`: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1174 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1175 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
|
1176 --------------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1177 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1178 Auditors may raise the ``Reject`` exception to prevent the creation of |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1179 or changes to items in the database. The mail gateway, for example, will |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1180 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
|
1181 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
|
1182 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
|
1183 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1184 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
|
1185 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1186 from roundup.exceptions import Reject |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1187 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1188 And then when your rejection criteria have been detected, use:: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1189 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1190 raise Reject('Description of error') |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1191 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1192 Error messages raised with ``Reject`` automatically have any HTML |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1193 content escaped before being displayed to the user. To display an |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1194 error message to the user without performing any HTML escaping |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1195 the ``RejectRaw`` should be used. All security implications |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1196 should be carefully considering before using ``RejectRaw``. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1197 |
|
8412
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1198 .. _`Confirming the User`: |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1199 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1200 Confirming the User |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1201 ------------------- |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1202 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1203 Being able to add a user confirmation step in a workflow is useful. |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1204 In an auditor adding:: |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1205 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1206 from roundup.cgi.exceptions import Reauth |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1207 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1208 at the top of the file and then adding:: |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1209 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1210 if 'password' in newvalues and not hasattr(db, 'reauth_done'): |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1211 raise Reauth('Add an optional message to the user') |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1212 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1213 will present the user with an authorization page. The optional message |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1214 will be shown at the top of the page. The user will enter their |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1215 password (or other verification token) and submit the page to commit |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1216 the change. This section describes the mechanism used. |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1217 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1218 The ``Reauth`` exception is handled by the core code in the |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1219 ``Client.reauth()`` method. It modifies the current request's context |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1220 cleaning up some fields and saving the current action and template for |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1221 later use. Then it sets the template to ``reauth`` which is used to |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1222 render the next page. |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1223 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1224 The page is rendered using the standard template mechanism. You can |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1225 create a ``user.reauth.html`` template that is displayed when |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1226 requiring reauth for a user. However most users will probably just use |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1227 the default ``_generic.reauth.html`` template provided with Roundup. |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1228 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1229 Look at the generic template to understand what has to be in a new |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1230 template. The basic idea is to get the password from the user into the |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1231 ``@reauth_password`` input field. Also the form that is generated |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1232 embeds a bunch of hidden fields that record the information that |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1233 triggered the reauth request. |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1234 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1235 If you are not using reauth in a workflow that can upload files, you |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1236 are all set. The embedding of the hidden fields just works. |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1237 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1238 If you need to support reauth on a form that allows file uploads, the |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1239 generic template supports handling file uploads. It requires |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1240 JavaScript in the browser to support files. Since browsers don't allow |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1241 a server to assign values to a file input, the template uses a |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1242 workaround. The reauth template encodes the contents of each uploaded |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1243 file as a base64 encoded string. It then embeds this string inside a |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1244 hidden ``<pre>`` tag. This encoded string is about 1/3 larger than the |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1245 size of the original file(s). |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1246 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1247 When the page is loaded, a Javascript function runs and turns the |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1248 tagged base64 strings back into file objects with their original |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1249 content. It then creates a file input element and assigns these files |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1250 to it. This allows the files to be submitted with the rest of the |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1251 form. If JavaScript is not enabled, these files will not be submitted |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1252 to the server. |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1253 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1254 **Future ideas for handling disabled JavaScript** - The `server could |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1255 detect disabled JavaScript on the browser |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1256 <https://wiki.roundup-tracker.org/IsJavascriptAvailable>`_ and |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1257 generate a warning. Alternatively, allowing the browser to submit all |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1258 the file data by replacing the ``<pre>`` tag with a ``<textarea>`` tag |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1259 and a name attribute like ``@filecontents-1``, |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1260 ``@filecontents-2``. Along with this, the current ``data-`` |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1261 attributes on the ``<pre>`` tag need to move to hidden inputs with |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1262 names like: ``@filecontents-1.mimetype``, |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1263 ``@filecontents-1.filename``. Submitting the form will include all |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1264 this data that Roundup could use to pretend the files were submitted |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1265 as a proper file input. |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1266 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1267 When the reauth page is submitted, it invokes the ``reauth`` action |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1268 (using the ``@action`` parameter). Verification is done by the |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1269 :ref:`ReauthAction <ReauthAction_pydoc>` class in |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1270 ``roundup.cgi.actions``. By default |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1271 ``ReauthAction.verifyPassword()`` calls:: |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1272 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1273 roundup.cgi.actions:LoginAction::verifyPassword() |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1274 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1275 to verify the user's password against the one stored in the database. |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1276 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1277 You can change the verification command using `interfaces.py`_. Adding |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1278 the following code to ``interfaces.py``:: |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1279 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1280 from roundup.cgi.actions import ReauthAction |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1281 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1282 old_verify = ReauthAction.verifyPassword |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1283 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1284 def new_verify_password(self): |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1285 if self.form['@reauth_password'].value == 'LetMeIn': |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1286 return True |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1287 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1288 return old_verify(self) |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1289 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1290 ReauthAction.verifyPassword = new_verify_password |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1291 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1292 will accept the passphrase ``LetMeIn`` as well as the user's |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1293 password. This example (which you should not use as is) could be |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1294 adapted to verify a `Time-based One-Time Password (TOTP)`_. An example |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1295 of `implementing a TOTP for Roundup is available on the wiki`_. |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1296 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1297 .. _`Time-based One-Time Password (TOTP)`: |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1298 https://en.wikipedia.org/wiki/Time-based_One-Time_Password |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1299 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1300 .. _`implementing a TOTP for Roundup is available on the wiki`: |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1301 https://wiki.roundup-tracker.org/OneTimePasswords |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1302 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1303 If the verification succeeds, the original action (e.g. edit) is |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1304 invoked on the data sent with the reauth request. To prevent the |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1305 auditor from triggering another Reauth, the attribute ``reauth_done`` |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1306 is added to the db object. As a result, the ``hasattr`` call shown |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1307 above will return True and the Reauth exception is not raised. (Note |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1308 that the value of the ``reauth_done`` attribute is True, so |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1309 ``getattr(db, "reauth_done", False)`` will return True when reauth is |
|
8474
5346abcf429e
doc: spelling correction.
John Rouillard <rouilj@ieee.org>
parents:
8430
diff
changeset
|
1310 done and the defile value of False if the attribute is missing. If the |
|
8412
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1311 default is not set, `getattr` raises an ``AttributeError`` which might |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1312 be useful for flow control.) |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1313 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1314 There is only one reauth for a submitted change. You cannot Reauth |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1315 multiple properties separately. If you need to reauth multiple |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1316 properties separately, you need to reject the change and force the |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1317 user to submit each sensitive property separately. For example:: |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1318 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1319 if 'password' in newvalues and 'realname' in newvalues: |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1320 raise Reject('Changing the username and the realname ' |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1321 'at the same time is not allowed. Please ' |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1322 'submit two changes.') |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1323 |
|
8430
056061cfe135
doc: add check for db.tx_Source to Reauth examples
John Rouillard <rouilj@ieee.org>
parents:
8412
diff
changeset
|
1324 if db.tx_Source not in ("web"): |
|
056061cfe135
doc: add check for db.tx_Source to Reauth examples
John Rouillard <rouilj@ieee.org>
parents:
8412
diff
changeset
|
1325 # the user is using rest, xmlrpc, command line, |
|
056061cfe135
doc: add check for db.tx_Source to Reauth examples
John Rouillard <rouilj@ieee.org>
parents:
8412
diff
changeset
|
1326 # email (unlikely) which don't support interactive |
|
056061cfe135
doc: add check for db.tx_Source to Reauth examples
John Rouillard <rouilj@ieee.org>
parents:
8412
diff
changeset
|
1327 # verification |
|
056061cfe135
doc: add check for db.tx_Source to Reauth examples
John Rouillard <rouilj@ieee.org>
parents:
8412
diff
changeset
|
1328 return |
|
056061cfe135
doc: add check for db.tx_Source to Reauth examples
John Rouillard <rouilj@ieee.org>
parents:
8412
diff
changeset
|
1329 |
|
8412
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1330 if 'password' in newvalues and not hasattr(db, 'reauth_done'): |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1331 raise Reauth() |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1332 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1333 if 'realname' in newvalues and not hasattr(db, 'reauth_done'): |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1334 raise Reauth() |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1335 |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1336 See also: client.py:Client:reauth(self, exception) which can be |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1337 changed using interfaces.py in your tracker if you have some special |
|
0663a7bcef6c
feat: finish reauth docs, enhance code.
John Rouillard <rouilj@ieee.org>
parents:
8411
diff
changeset
|
1338 handling that must be done. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1339 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1340 Generating email from Roundup |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1341 ----------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1342 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1343 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
|
1344 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
|
1345 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1346 Also, the ``IssueClass`` methods ``nosymessage()`` and |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1347 ``send_message()`` generate nosy messages, and may generate |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1348 messages which only consist of a change note (i.e. the message id |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1349 parameter is not required - this is referred to as a "System |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1350 Message" because it comes from "the system" and not a user). |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1351 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1352 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1353 .. index:: extensions |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1354 .. 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
|
1355 .. _extensions: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1356 .. _actions: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1357 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1358 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
|
1359 ================================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1360 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1361 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
|
1362 objects, `extensions` add new actions and utilities to Roundup, which |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1363 are mostly used to enhance the web interface. |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1364 |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1365 You can create an extension by creating Python file in your |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1366 tracker ``extensions`` directory. The tracker loads all the files |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1367 from this directory, at which point it calls ``init(instance)`` from |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1368 each file supplying itself as a first argument. |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1369 |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1370 Note that at this point web interface is not loaded, but |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1371 extensions still can register actions for it in the tracker |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1372 instance. This may be fixed in Roundup 1.6 by introducing |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1373 ``init_web(client)`` callback or a more flexible extension point |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1374 mechanism. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1375 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1376 * ``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
|
1377 (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
|
1378 <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
|
1379 |
|
8262
2a7c3eeaf167
feat: add templating utils method dynamically; method to set http code
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
1380 * ``instance.registerUtilMethod`` is also used for adding `templating |
|
8354
586e49dda652
docs: fix doc for registerUtilMethod; style tweak for internal docs.
John Rouillard <rouilj@ieee.org>
parents:
8301
diff
changeset
|
1381 utilities`_, and provides a TemplatingUtils instance by default to |
|
586e49dda652
docs: fix doc for registerUtilMethod; style tweak for internal docs.
John Rouillard <rouilj@ieee.org>
parents:
8301
diff
changeset
|
1382 the function. This makes more complex templating actions easier to |
|
8262
2a7c3eeaf167
feat: add templating utils method dynamically; method to set http code
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
1383 use. (see :ref:`dynamic_csp` for an example) |
|
2a7c3eeaf167
feat: add templating utils method dynamically; method to set http code
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
1384 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1385 * ``instance.registerAction`` is used to add more actions to the |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1386 instance and to web interface. See `Defining new web actions`_ |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1387 for details. Generic action can be added by inheriting from |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1388 ``action.Action`` instead of ``cgi.action.Action``. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1389 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1390 .. _interfaces.py: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1391 .. _modifying the core of Roundup: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1392 |
|
7853
03c1b7ae3a68
issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents:
7836
diff
changeset
|
1393 .. index:: single: interfaces.py; hooking into the roundup core |
|
03c1b7ae3a68
issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents:
7836
diff
changeset
|
1394 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1395 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
|
1396 ================================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1397 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1398 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
|
1399 this you can: |
|
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 * modify class data structures |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1402 * 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
|
1403 * modify the email gateway |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1404 * add new rest endpoints |
|
7375
9bd7ed918121
issue2551253 - Modify password PBKDF2 method to use SHA512
John Rouillard <rouilj@ieee.org>
parents:
7371
diff
changeset
|
1405 * 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
|
1406 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1407 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
|
1408 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1409 Interfaces.py has existed since the earliest releases of Roundup |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1410 and was 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
|
1411 modern Roundup, the extensions_ mechanism is used to `add actions |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1412 <#defining-new-web-actions>`_ and `templating utilities`_. But |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1413 there are places where interfaces.py is still useful. Note that |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1414 the tracker directories are not on the Python system path when |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1415 interfaces.py is evaluated. You need to add library directories |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1416 explicitly by modifying sys.path. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1417 |
|
7688
c09192e21faa
doc: add statement on less stable nature of using interfaces.py
John Rouillard <rouilj@ieee.org>
parents:
7658
diff
changeset
|
1418 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
|
1419 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
|
1420 (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
|
1421 more likely to need modification when upgrading from version to |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1422 version. While the developers attempt to keep the examples working, |
|
7688
c09192e21faa
doc: add statement on less stable nature of using interfaces.py
John Rouillard <rouilj@ieee.org>
parents:
7658
diff
changeset
|
1423 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
|
1424 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
|
1425 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1426 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
|
1427 <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
|
1428 of using interfaces.py. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1429 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1430 Database Content |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1431 ================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1432 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1433 .. note:: |
|
7369
15bb0d177632
use glossary directive and link some terms to the glossary.
John Rouillard <rouilj@ieee.org>
parents:
7368
diff
changeset
|
1434 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
|
1435 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
|
1436 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
|
1437 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
|
1438 "working", you need to change the check.) |
|
f37c1df6de34
Glossary updates and more term refs.
John Rouillard <rouilj@ieee.org>
parents:
7369
diff
changeset
|
1439 |
|
f37c1df6de34
Glossary updates and more term refs.
John Rouillard <rouilj@ieee.org>
parents:
7369
diff
changeset
|
1440 Customisation of the special :term:`definitional classes <definitional |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1441 class>` (e.g. status, |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1442 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
|
1443 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
|
1444 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
|
1445 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1446 **Changing content before tracker initialisation** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1447 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
|
1448 created using the ``create( ... )`` methods. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1449 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1450 **Changing content after tracker initialisation** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1451 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
|
1452 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
|
1453 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
|
1454 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1455 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
|
1456 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
|
1457 question. |
|
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 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
|
1460 <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
|
1461 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
|
1462 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1463 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1464 Security / Access Controls |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1465 ========================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1466 |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1467 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
|
1468 each Class defined in the tracker schema, the following permissions |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1469 are defined: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1470 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1471 - Create (everything) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1472 - Edit (everything) |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1473 - Search (everything) - (used if View does not permit access) |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1474 - Retire (everything) |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1475 - Restore (everything) |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1476 - View (everything) |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1477 |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1478 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
|
1479 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
|
1480 also define: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1481 |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1482 Email Access |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1483 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
|
1484 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
|
1485 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
|
1486 interface (see also the ``new_email_user_roles`` configuration option). |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1487 |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1488 Web Access |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1489 If defined, the user may use the web interface. This is |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1490 assigned to the Anonymous role to allow authorized users to |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1491 access the form based login. If your tracker uses some other |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1492 authorization mode (basic auth, Single Sign On (SSO), etc.) Web |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1493 Access can be removed from the Anonymous user. |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1494 |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1495 Web Roles |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1496 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
|
1497 TODO: deprecate in favour of a property-based control. |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1498 |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1499 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
|
1500 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
|
1501 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
|
1502 `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
|
1503 `xmlrpc interface documentation`_. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1504 |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1505 Register |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1506 This enables automatic user registration by email or web. It is |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1507 assigned to the anonymous user. |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1508 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1509 These are assigned into the default Roles: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1510 |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1511 - 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
|
1512 - User (Web Access; Email Access) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1513 - Anonymous (Web Access) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1514 |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1515 Finally, the "admin" user gets the "Admin" Role, and the "anonymous" |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1516 user gets the "Anonymous" Role. The "Admin" and "Anonymous" roles |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1517 are created when the tracker is initialized. |
|
7352
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 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
|
1520 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1521 - 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
|
1522 - View priority, status |
|
8137
f5aa7853abda
doc: document Search permission ignores a check clause.
John Rouillard <rouilj@ieee.org>
parents:
8111
diff
changeset
|
1523 - View user (limited properties) |
|
f5aa7853abda
doc: document Search permission ignores a check clause.
John Rouillard <rouilj@ieee.org>
parents:
8111
diff
changeset
|
1524 - View their own user record |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1525 - Edit their own user record |
|
8137
f5aa7853abda
doc: document Search permission ignores a check clause.
John Rouillard <rouilj@ieee.org>
parents:
8111
diff
changeset
|
1526 - Search queries |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1527 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1528 And the "Anonymous" Role has the following permissions: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1529 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1530 - Web interface access |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1531 - Register user (for registration) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1532 - 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
|
1533 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1534 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
|
1535 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1536 # |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1537 # TRACKER SECURITY SETTINGS |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1538 # |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1539 # 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
|
1540 # about security setup. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1541 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1542 # |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1543 # REGULAR USERS |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1544 # |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1545 # 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
|
1546 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
|
1547 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
|
1548 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
|
1549 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
|
1550 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1551 # 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
|
1552 # to regular users now |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1553 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
|
1554 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
|
1555 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
|
1556 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
|
1557 for cl in 'priority', 'status': |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1558 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
|
1559 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1560 # 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
|
1561 # 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
|
1562 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
|
1563 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
|
1564 'username')) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1565 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1566 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1567 # 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
|
1568 # 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
|
1569 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
|
1570 '''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
|
1571 return userid == itemid |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1572 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
|
1573 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
|
1574 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1575 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
|
1576 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
|
1577 'organisation', 'alternate_addresses', 'queries', 'timezone'), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1578 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
|
1579 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1580 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1581 # 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
|
1582 # 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
|
1583 # 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
|
1584 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
|
1585 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
|
1586 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
|
1587 return userid == private_for |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1588 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
|
1589 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
|
1590 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
|
1591 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
|
1592 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1593 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
|
1594 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1595 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
|
1596 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
|
1597 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1598 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
|
1599 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
|
1600 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1601 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
|
1602 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
|
1603 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1604 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
|
1605 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
|
1606 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1607 |
|
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 # ANONYMOUS USER PERMISSIONS |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1610 # |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1611 # 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
|
1612 # 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
|
1613 # 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
|
1614 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
|
1615 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1616 # 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
|
1617 # 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
|
1618 # "Create" user Permission below) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1619 # 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
|
1620 # public trackers. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1621 #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
|
1622 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1623 # 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
|
1624 # Role. Choices here are: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1625 # - Allow anonymous users to register |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1626 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
|
1627 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1628 # 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
|
1629 # information) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1630 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
|
1631 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
|
1632 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1633 # 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
|
1634 # 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
|
1635 # 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
|
1636 # 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
|
1637 # 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
|
1638 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
|
1639 db.security.addPermissionToRole ('Anonymous', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1640 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1641 # [OPTIONAL] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1642 # 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
|
1643 # related file and message items) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1644 #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
|
1645 # 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
|
1646 # 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
|
1647 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1648 .. index:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1649 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
|
1650 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1651 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
|
1652 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
|
1653 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
|
1654 cause baffling permission issues. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1655 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1656 Automatic Permission Checks |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1657 --------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1658 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1659 Permissions are automatically checked when rendering information |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1660 through the web. This includes: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1661 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1662 1. View checks for properties when rendered via the ``plain()`` or |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1663 similar methods. If the check fails, the text "[hidden]" is |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1664 displayed. |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1665 2. Edit checks for properties when the edit field is rendered via |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1666 the ``field()`` or similar methods. If the check fails, the property |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1667 is rendered via the ``plain()`` method (see point 1. for subsequent |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1668 checking performed) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1669 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
|
1670 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
|
1671 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
|
1672 displayed. If the user does not have permission, the text "You are not |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1673 allowed to view this page." is displayed. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1674 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
|
1675 displayed. If the user does not have permission, the text "You are not |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1676 allowed to view this page." is displayed. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1677 |
|
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 New User Roles |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1680 -------------- |
|
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 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
|
1683 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1684 - NEW_WEB_USER_ROLES |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1685 - NEW_EMAIL_USER_ROLES |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1686 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1687 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
|
1688 <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
|
1689 customisation of these parameters. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1690 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1691 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1692 Changing Access Controls |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1695 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
|
1696 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
|
1697 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
|
1698 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1699 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
|
1700 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
|
1701 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1702 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1703 Adding a New Permission |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1704 ~~~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1705 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1706 When adding a new Permission, you need to: |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1707 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1708 1. create it in your tracker's ``schema.py`` using |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1709 ``security.addPermission``. For example:: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1710 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1711 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
|
1712 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
|
1713 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1714 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
|
1715 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
|
1716 "``roundup-admin security``") |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1717 3. check it in the relevant HTML interface templates |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1718 4. check it in the appropriate hasPermission methods in your tracker's |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1719 extensions/detectors/interfaces.py modules |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1720 |
|
8133
7b6615fb37fc
Add documentation for the filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8111
diff
changeset
|
1721 The ``addPermission`` method takes a four optional parameters: |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1722 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1723 **check** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1724 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
|
1725 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
|
1726 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
|
1727 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
|
1728 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1729 check(db, userid, itemid) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1730 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1731 or:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1732 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1733 check(db, userid, itemid, **ctx) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1734 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1735 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
|
1736 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
|
1737 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
|
1738 defined with the following values:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1739 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1740 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
|
1741 it's a class check. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1742 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1743 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
|
1744 (issue, query ....). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1745 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1746 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
|
1747 |
|
8137
f5aa7853abda
doc: document Search permission ignores a check clause.
John Rouillard <rouilj@ieee.org>
parents:
8111
diff
changeset
|
1748 The second form is preferred as it makes it easier to implement more |
|
f5aa7853abda
doc: document Search permission ignores a check clause.
John Rouillard <rouilj@ieee.org>
parents:
8111
diff
changeset
|
1749 complex permission schemes. An `example in upgrading.html |
|
f5aa7853abda
doc: document Search permission ignores a check clause.
John Rouillard <rouilj@ieee.org>
parents:
8111
diff
changeset
|
1750 <upgrading.html#enhancement-to-check-command-for-permissions>`_ |
|
f5aa7853abda
doc: document Search permission ignores a check clause.
John Rouillard <rouilj@ieee.org>
parents:
8111
diff
changeset
|
1751 shows the use of ``ctx``. |
|
f5aa7853abda
doc: document Search permission ignores a check clause.
John Rouillard <rouilj@ieee.org>
parents:
8111
diff
changeset
|
1752 |
|
f5aa7853abda
doc: document Search permission ignores a check clause.
John Rouillard <rouilj@ieee.org>
parents:
8111
diff
changeset
|
1753 Note that the check option is not supported for the Search |
|
f5aa7853abda
doc: document Search permission ignores a check clause.
John Rouillard <rouilj@ieee.org>
parents:
8111
diff
changeset
|
1754 permission. When searching there is no item defined, so a check |
| 8138 | 1755 function does not make any sense. |
|
7861
90abf3721fcc
doc: Add a missing line fix sphinx error.
John Rouillard <rouilj@ieee.org>
parents:
7858
diff
changeset
|
1756 |
|
8159
3f720edd9594
markup fixes and word typo fix.
John Rouillard <rouilj@ieee.org>
parents:
8154
diff
changeset
|
1757 **filter** |
| 8162 | 1758 This optional function returns parameters for the ``filter`` method |
| 1759 when getting ``Class`` items (users, issues etc.) from the | |
| 1760 database. It filters items at the database level (using SQL where | |
| 1761 possible). This pre-filters the number of items returned from the | |
| 1762 database when displaying results in an ``index`` template. This | |
| 1763 filtering is usually faster than calling a ``check`` method (see | |
| 1764 previous argument) on *each individual result*. | |
| 1765 | |
| 1766 The ``filter`` method has the signature:: | |
|
8154
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1767 |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1768 filter(db, userid, klass) |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1769 |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1770 where ``db`` is the database handle, ``userid`` is the user attempting |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1771 access and ``klass`` is the ``Class`` in the schema. |
| 8162 | 1772 |
| 1773 The ``filter`` function must return a *list* of dictionaries of | |
| 1774 parameters of the | |
|
8164
dd60d604a852
Document that filter() can return more than just filterspec params
John Rouillard <rouilj@ieee.org>
parents:
8163
diff
changeset
|
1775 `Class.filter <design.html#:~:text=search_matches>`_ call. |
|
dd60d604a852
Document that filter() can return more than just filterspec params
John Rouillard <rouilj@ieee.org>
parents:
8163
diff
changeset
|
1776 This includes filterspec, retired and exact_match_specs. |
|
dd60d604a852
Document that filter() can return more than just filterspec params
John Rouillard <rouilj@ieee.org>
parents:
8163
diff
changeset
|
1777 Note that sort and group parameters of the filter call should |
|
dd60d604a852
Document that filter() can return more than just filterspec params
John Rouillard <rouilj@ieee.org>
parents:
8163
diff
changeset
|
1778 not be set by filter method (they will be overwritten) and the |
|
dd60d604a852
Document that filter() can return more than just filterspec params
John Rouillard <rouilj@ieee.org>
parents:
8163
diff
changeset
|
1779 parameter search_matches must not be set. |
|
dd60d604a852
Document that filter() can return more than just filterspec params
John Rouillard <rouilj@ieee.org>
parents:
8163
diff
changeset
|
1780 |
|
dd60d604a852
Document that filter() can return more than just filterspec params
John Rouillard <rouilj@ieee.org>
parents:
8163
diff
changeset
|
1781 The query executed by an index template is modified by the |
|
dd60d604a852
Document that filter() can return more than just filterspec params
John Rouillard <rouilj@ieee.org>
parents:
8163
diff
changeset
|
1782 parameters computed by the ``filter`` function. An |
| 8162 | 1783 empty list of filter parameters (``[]``) indicates no access. When |
| 1784 using a filter, a check function is still needed to test each | |
| 1785 individual item for visibility. When the filter function is defined | |
| 1786 but a check function is not defined, a check function is | |
| 1787 manufactured automatically from the ``filter`` function. | |
|
8154
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1788 |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1789 Note that the filter option is not supported for the Search |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1790 permission. Since the filter function is called *after* the search was |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1791 already performed a filter function does not make any sense. |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1792 |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1793 An example ``filter`` function for the ``view_query`` check function |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1794 in the query checks above would look like:: |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1795 |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1796 def filter_query(db, userid, klass): |
|
8163
d3a1094b15eb
unwrap examples; clarify text
John Rouillard <rouilj@ieee.org>
parents:
8162
diff
changeset
|
1797 return [{'filterspec': { |
|
d3a1094b15eb
unwrap examples; clarify text
John Rouillard <rouilj@ieee.org>
parents:
8162
diff
changeset
|
1798 'private_for': ['-1', userid] |
|
d3a1094b15eb
unwrap examples; clarify text
John Rouillard <rouilj@ieee.org>
parents:
8162
diff
changeset
|
1799 }}] |
|
8154
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1800 |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1801 This would be called by the framework for all queries found when |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1802 displaying queries. It filters for all queries where the |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1803 ``private_for`` field is the userid or empty. This matches the |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1804 definition of the ``view_query`` function above where permission is |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1805 granted if the ``private_for`` field indicates the query is owned by |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1806 the user, or the ``private_for`` field is empty indicating that the |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1807 query is public. If we want to modify the check to also allow acess if |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1808 the user is the ``creator`` of a query we would change the filter |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1809 function to:: |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1810 |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1811 def filter_query(db, userid, klass): |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1812 f1 = {'filterspec': {'private_for': ['-1', userid]}} |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1813 f2 = {'filterspec': {'creator': userid}} |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1814 return [f1, f2] |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1815 |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1816 This is an example where we need multiple filter calls to model an |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1817 "or" condition, the user has access if either the ``private_for`` |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1818 check passes *or* the user is the creator of the query. |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1819 |
|
8163
d3a1094b15eb
unwrap examples; clarify text
John Rouillard <rouilj@ieee.org>
parents:
8162
diff
changeset
|
1820 Consider an example where we have a class structure where both the |
|
d3a1094b15eb
unwrap examples; clarify text
John Rouillard <rouilj@ieee.org>
parents:
8162
diff
changeset
|
1821 ``issue`` class and the ``user`` class include a reference to an |
|
d3a1094b15eb
unwrap examples; clarify text
John Rouillard <rouilj@ieee.org>
parents:
8162
diff
changeset
|
1822 ``organization`` class. Users are permitted to view only those |
|
d3a1094b15eb
unwrap examples; clarify text
John Rouillard <rouilj@ieee.org>
parents:
8162
diff
changeset
|
1823 issues that are associated with their respective organizations. A |
|
d3a1094b15eb
unwrap examples; clarify text
John Rouillard <rouilj@ieee.org>
parents:
8162
diff
changeset
|
1824 check function or this could look like:: |
|
8154
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1825 |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1826 def view_issue(db, userid, itemid): |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1827 user = db.user.getnode(userid) |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1828 if not user.organisation: |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1829 return False |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1830 issue = db.issue.getnode(itemid) |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1831 if user.organisation == issue.organisation: |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1832 return True |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1833 |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1834 The corresponding ``filter`` function:: |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1835 |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1836 def filter_issue(db, userid, klass): |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1837 user = db.user.getnode(userid) |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1838 if not user.organisation: |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1839 return [] |
|
8163
d3a1094b15eb
unwrap examples; clarify text
John Rouillard <rouilj@ieee.org>
parents:
8162
diff
changeset
|
1840 return [{'filterspec': { |
|
d3a1094b15eb
unwrap examples; clarify text
John Rouillard <rouilj@ieee.org>
parents:
8162
diff
changeset
|
1841 'organisation': user.organisation |
|
d3a1094b15eb
unwrap examples; clarify text
John Rouillard <rouilj@ieee.org>
parents:
8162
diff
changeset
|
1842 }}] |
|
8154
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1843 |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1844 This filters for all issues where the organisation is the same as the |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1845 organisation of the user. Note how the filter fails early returning an |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1846 empty list (meaning "no access") if the user happens to not have an |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1847 organisation. |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1848 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1849 **properties** |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1850 A sequence of property names that are the only properties to apply the |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1851 new Permission to (eg. ``... klass='user', properties=('name', |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1852 'email') ...``) |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1853 **props_only** |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1854 A boolean value (set to false by default) that is a new feature |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1855 in Roundup 1.6. |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1856 A permission defined using: |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1857 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1858 ``properties=('list', 'of', 'property', 'names')`` |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1859 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1860 determines access for things other than just those |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1861 properties. For example a check for View permission on the |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1862 issue class or an issue item can use any View permission for |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1863 the issue class even if that permission has a property |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1864 list. This makes sense if you understand that a user can't |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1865 access the properties of a class if they can't access the |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1866 class. The ability to access class properties implies class |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1867 access. |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1868 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1869 This eliminates the need to create a duplicate View permission |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1870 without properties to allow access to the View properties |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1871 permission. Even though it makes sense, it can be confusing and |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1872 surprising. |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1873 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1874 You would think that a permission including properties would be |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1875 used only for determining the access permission when checking |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1876 properties. But that is not the case. |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1877 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1878 Setting ``props_only=True`` will prevent the permission |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1879 from being used unless the check include properties. |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1880 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1881 If you use a lot of permissions with property checks, it can be |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1882 difficult to change all of them. Calling the function: |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1883 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1884 db.security.set_props_only_default(True) |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1885 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1886 at the top of ``schema.py`` will make every permission creation |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1887 behave as though props_only is True. Note that you may |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1888 need to add new View permissions without properties to allow |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1889 property only checks to take effect. |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1890 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1891 ``roundup-admin security`` will report invalid properties for the |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1892 class. For example a permission with an invalid summary property is |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1893 presented as:: |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1894 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1895 Allowed to see content of object regardless of spam status |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1896 (View for "file": ('content', 'summary') only) |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1897 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1898 **Invalid properties for file: ['summary'] |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1899 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1900 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1901 Example Scenarios |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1902 ~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1903 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1904 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
|
1905 examples of customisation. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1906 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1907 **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
|
1908 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
|
1909 ("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
|
1910 "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
|
1911 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
|
1912 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
|
1913 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
|
1914 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
|
1915 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
|
1916 - they're *anonymous*. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1917 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1918 **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
|
1919 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
|
1920 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
|
1921 (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
|
1922 the web until an admin sets their password). By default new Roundup |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1923 trackers don't enable "Email Access" for "anonymous" as it opens |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1924 them up to spam. It may be enabled |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1925 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
|
1926 ``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
|
1927 "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
|
1928 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1929 **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
|
1930 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
|
1931 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
|
1932 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
|
1933 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
|
1934 auditor. See the example |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1935 `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
|
1936 <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
|
1937 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1938 **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
|
1939 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
|
1940 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
|
1941 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
|
1942 issue state option when the user has the "Closer" Permissions. Enforce |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1943 the Permission with an auditor. This is similar to the previous |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1944 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
|
1945 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1946 <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
|
1947 value="resolved">Resolved</option> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1948 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1949 **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
|
1950 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
|
1951 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
|
1952 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
|
1953 interface. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1954 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1955 **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
|
1956 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
|
1957 editing users:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1958 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1959 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
|
1960 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
|
1961 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
|
1962 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1963 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
|
1964 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1965 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1966 Web Interface |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1967 ============= |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1968 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1969 .. contents:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1970 :local: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1971 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1972 The 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
|
1973 is used by ``roundup.cgi``, ``roundup-server`` and ``ZRoundup`` |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1974 (``ZRoundup`` is broken, until further notice). In all cases, Roundup |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1975 determines which tracker is accessed (the first part of the URL |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1976 path inside the scope of the CGI handler) and pass control on to the |
|
8263
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
1977 :py:class:`roundup.cgi.client.Client` class - which handles the rest of the |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1978 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
|
1979 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
|
1980 |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1983 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
|
1984 --------------------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1985 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1986 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
|
1987 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
|
1988 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1989 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
|
1990 have properties added or removed, |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1991 2. The "page" template may require changing links, as might the |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1992 "home" page's content arguments. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1993 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1994 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1995 How requests are processed |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1996 -------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1997 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1998 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
|
1999 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2000 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
|
2001 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
|
2002 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
|
2003 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
|
2004 output |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2005 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2006 In some situations, exceptions occur: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2007 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2008 - HTTP Redirect (generally raised by an action) |
|
7368
8aa1a5639aef
add explanatory info for HTTP Redirect
John Rouillard <rouilj@ieee.org>
parents:
7363
diff
changeset
|
2009 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
|
2010 - 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
|
2011 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
|
2012 - 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
|
2013 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
|
2014 - 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
|
2015 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
|
2016 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
|
2017 the action to take place |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2018 - 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
|
2019 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
|
2020 client |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2023 Roundup URL design |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2024 ------------------ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2025 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2026 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
|
2027 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
|
2028 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2029 1. ``/`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2030 2. ``/index`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2031 3. ``/home`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2032 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2033 The following prefix accesses static resources: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2034 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2035 4. ``/@@file/`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2036 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2037 Two url's are used for the API's. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2038 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
|
2039 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2040 5. ``/rest/`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2041 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2042 .. _`REST api`: rest.html |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2043 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2044 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
|
2045 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2046 6. ``/xmlrpc`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2047 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2048 .. _`XMLRPC api`: xmlrpc.html |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2049 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2050 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
|
2051 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
|
2052 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
|
2053 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2054 7. ``/issue`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2055 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2056 Shows a listings of class items, usually in a table. The URL for |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2057 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
|
2058 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2059 8. ``/issue1`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2060 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2061 .. _strip_zeros: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2062 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2063 Note that Roundup strips a leading string of 0's 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
|
2064 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
|
2065 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
|
2066 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
|
2067 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2068 Determining web context |
|
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 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2071 To determine the "context" of a request (what request is for), |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2072 Roundup looks at the URL path after the tracker root and at |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2073 ``@template`` request parameter. Typical URL paths look like: |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2074 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2075 1. ``/tracker/`` |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2076 2. ``/tracker/issue`` |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2077 3. ``/tracker/issue1`` |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2078 4. ``/tracker/@@file/style.css`` |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2079 5. ``/cgi-bin/roundup.cgi/tracker/file1`` |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2080 6. ``/cgi-bin/roundup.cgi/tracker/file1/kitten.png`` |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2081 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2082 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
|
2083 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
|
2084 "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
|
2085 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2086 1. with no path Roundup is in the "home" context. See `the "home" |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2087 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
|
2088 to switch into "home" context. |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2089 2. if there is something in the path (as in example 2, "issue"), it |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2090 identifies the tracker class to display. |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2091 3. if the path is an item designator (as in examples 3 and 5, "issue1" |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2092 and "file1"), then we're to display a specific item. |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2093 :ref:`Note. <strip_zeros>` |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2094 4. for paths starting with "@@file" the additional path entry ("style.css" |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2095 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
|
2096 from the tracker TEMPLATES directory (or STATIC_FILES, if configured). |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2097 The TEMPLATES directory is usually the tracker's "html" |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2098 directory. Internally this works by raising SendStaticFile exception. |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2099 5. A file can have additional path components (as in example |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2100 6). Without the additional components, the metadata for the |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2101 file is displayed. |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2102 6. if the path starts with an item designator and is longer than one |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2103 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
|
2104 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
|
2105 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
|
2106 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
|
2107 This raises a ``SendFile`` exception. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2108 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2109 Neither 4. or 6. use templates and stop before the template is |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2110 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
|
2111 ``@template`` variable, which defaults to: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2112 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2113 - only classname supplied: "index" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2114 - full item designator supplied: "item" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2115 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2116 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2117 The "home" Context |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2118 ------------------ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2119 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2120 The "home" context is special because it allows you to add templated |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2121 pages to your tracker that don't rely on a class or item (e.g. an issues |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2122 list or specific issue). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2123 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2124 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
|
2125 interface. You'd probably have: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2126 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2127 - 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
|
2128 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
|
2129 - 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
|
2130 "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
|
2131 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
|
2132 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2133 <tracker url>/home?@template=navigation |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2134 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2135 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2136 Serving static content |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2139 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
|
2140 ``@@file`` paths. |
|
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 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
|
2143 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
|
2144 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2145 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
|
2146 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
|
2147 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
|
2148 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
|
2149 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
|
2150 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2151 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
|
2152 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2153 Performing actions in web requests |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2154 ---------------------------------- |
|
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 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
|
2157 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
|
2158 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
|
2159 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
|
2160 of: |
|
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 **login** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2163 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
|
2164 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2165 **logout** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2166 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
|
2167 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2168 **register** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2169 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
|
2170 log them in. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2171 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2172 **edit** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2173 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
|
2174 variables`_ you may use. Also you can set the ``__redirect_to`` form |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2175 variable to the URL to display after the edit is successfully |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2176 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
|
2177 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
|
2178 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2179 **new** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2180 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
|
2181 variables`_ as in the "edit" action. Also you can set the |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2182 ``__redirect_to`` form variable to the URL to display after |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2183 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
|
2184 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
|
2185 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2186 **retire** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2187 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
|
2188 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2189 **editCSV** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2190 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
|
2191 *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
|
2192 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
|
2193 features. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2194 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2195 **search** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2196 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
|
2197 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2198 - Set the form ":filter" variable based on the values of the filter |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2199 variables - if they are set to anything other than "dontcare" then add |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2200 them to :filter. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2201 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2202 - 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
|
2203 user's query list. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2204 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2205 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
|
2206 "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
|
2207 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
|
2208 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
|
2209 web actions`_). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2210 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2211 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
|
2212 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
|
2213 for each action are: |
|
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 **login** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2216 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
|
2217 **logout** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2218 No permission checks are made. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2219 **register** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2220 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
|
2221 **edit** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2222 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
|
2223 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
|
2224 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
|
2225 special Permission "Web Roles". |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2226 **new** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2227 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
|
2228 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
|
2229 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
|
2230 **editCSV** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2231 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
|
2232 **search** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2233 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
|
2234 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2235 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
|
2236 --------------------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2237 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2238 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
|
2239 (CSRF). Malicious code running in the browser can making a |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2240 request to Roundup while you are logged into Roundup. The |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2241 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
|
2242 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
|
2243 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
|
2244 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2245 * Referer, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2246 * Origin, and |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2247 * Host or |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2248 * X-Forwarded-Host |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2249 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2250 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
|
2251 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
|
2252 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2253 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
|
2254 the tracker using the ``csrf_enforce_token`` option in |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2255 config.ini. When enabled, Roundup will check a hidden form field |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2256 called ``@csrf``. If the field's value matches a token in the |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2257 database, the validation passes and the token is deleted. If the |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2258 validation fails because the token is not found (e.g. if the |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2259 token is used more than once) the request is rejected. The |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2260 ``@csrf`` input field is added automatically when calling the |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2261 ``submit`` function/path. It can also be added manually by |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2262 calling anti_csrf_nonce() directly. For example:: |
|
7352
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 <input name="@csrf" type="hidden" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2265 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
|
2266 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2267 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
|
2268 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
|
2269 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
|
2270 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2271 Search for @csrf in this document for more examples. More |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2272 examples and information is provided in ``upgrading.txt``. |
|
7352
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 The token protects you because malicious code supplied by another |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2275 site is unable to obtain the token. Thus any attempt they make |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2276 to submit a request is rejected. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2277 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2278 The protection on the xmlrpc interface is untested, but is based |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2279 on a valid header check against the Roundup URL and the presence |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2280 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
|
2281 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
|
2282 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2283 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
|
2284 that file for details. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2285 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2286 Special form variables |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2287 ---------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2288 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2289 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
|
2290 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
|
2291 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2292 - 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
|
2293 - 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
|
2294 properties, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2295 - 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
|
2296 current item. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2297 - 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
|
2298 - 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
|
2299 operation to be successful. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2300 - 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
|
2301 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
|
2302 created item. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2303 - Set up user interface locale. |
|
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 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
|
2306 ``@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
|
2307 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2308 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
|
2309 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
|
2310 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2311 .. index:: |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2312 single: i18n; set from web interface |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2313 single: internationalization; set from web interface |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2314 single: language; set from web interface |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2315 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2316 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
|
2317 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2318 ``@language`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2319 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
|
2320 locale name, web interface language is changed to given value |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2321 (if the appropriate translation is available). The value |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2322 is stored in a browser cookie and is used for all following |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2323 requests. If value is ``none`` the cookie is removed and the |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2324 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
|
2325 configuration or OS environment. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2326 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2327 ``@charset`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2328 value may be character set name or ``none``. Character set name |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2329 is stored in a browser cookie and sets output encoding for all |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2330 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
|
2331 is removed and HTML output is reset to Roundup internal encoding |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2332 (UTF-8). This is unlikely to be needed with modern web browsers |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2333 and is left over from the early days of the web. It will |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2334 be removed at some future date. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2335 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2336 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
|
2337 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2338 ``<propname>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2339 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
|
2340 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2341 ``<designator>"@"<propname>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2342 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
|
2343 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2344 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
|
2345 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2346 ``<classname><N>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2347 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
|
2348 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2349 ``<classname>"-"<N>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2350 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
|
2351 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
|
2352 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
|
2353 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
|
2354 item. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2355 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2356 Once we have determined the "propname", we check to see |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2357 if it's special: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2358 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2359 ``@required`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2360 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
|
2361 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
|
2362 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
|
2363 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2364 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
|
2365 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
|
2366 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
|
2367 <designator>. |
|
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 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
|
2370 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
|
2371 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2372 ``@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
|
2373 The "@add@" and "@remove@" edit actions apply only to |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2374 Multilink properties. The form value must be a |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2375 comma-separate list of keys for the class specified by |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2376 the simple form variable. The listed items are added |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2377 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
|
2378 property. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2379 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2380 ``@link@<propname>=<designator>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2381 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
|
2382 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
|
2383 The form value is a comma-separated list of |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2384 designators. The item corresponding to each |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2385 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
|
2386 form variable. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2387 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2388 None of the above (i.e. just a simple form value) |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2389 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
|
2390 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
|
2391 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2392 For a Link('klass') property, the form value is a |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2393 single key (or id number) for 'klass', |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2394 where the key field is specified in schema.py. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2395 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2396 For a Multilink('klass') property, the form value is a |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2397 comma-separated list of keys (or id nummber) for 'klass', where the |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2398 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
|
2399 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2400 Note that for simple-form-variables specifying Link |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2401 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
|
2402 have a key field. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2403 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2404 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
|
2405 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
|
2406 try to set additional properties "filename" and "type" (if |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2407 they are defined for the class). Otherwise, the property |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2408 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
|
2409 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2410 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
|
2411 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
|
2412 appropriate value. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2413 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2414 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
|
2415 designator. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2416 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2417 Setting the form variable: ``__redirect_to=`` to a url when |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2418 ``@action=new`` redirects the user to the specified url after |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2419 successfully creating the new item. This is useful if you want |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2420 the user to create another item rather than edit the newly |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2421 created item. Note that the url assigned to ``__redirect_to`` |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2422 must be url encoded/quoted and be under the tracker's base |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2423 url. If the base_url uses http, you can set the url to https. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2424 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2425 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
|
2426 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2427 @note |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2428 This is equivalent to:: |
|
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 @link@messages=msg-1 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2431 msg-1@content=value |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2432 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2433 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
|
2434 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2435 <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
|
2436 <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
|
2437 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2438 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
|
2439 "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
|
2440 time, respectively. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2441 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2442 @file |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2443 This is equivalent to:: |
|
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 @link@files=file-1 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2446 file-1@content=value |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2447 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2448 by adding the HTML:: |
|
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 <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
|
2451 <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
|
2452 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2453 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
|
2454 uploads. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2455 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2456 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
|
2457 specified, the action:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2458 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2459 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
|
2460 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2461 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
|
2462 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2463 <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
|
2464 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2465 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
|
2466 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
|
2467 returning. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2468 |
|
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 Default templates |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2471 ----------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2472 |
|
7456
cdb81976b8bc
Fix another xhtml reference.
John Rouillard <rouilj@ieee.org>
parents:
7378
diff
changeset
|
2473 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
|
2474 be phased out so leave the ``html_version`` configuration |
|
cdb81976b8bc
Fix another xhtml reference.
John Rouillard <rouilj@ieee.org>
parents:
7378
diff
changeset
|
2475 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
|
2476 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2477 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
|
2478 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
|
2479 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
|
2480 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2481 **page.html** |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2482 This template defines the overall look of your tracker. When |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2483 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
|
2484 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
|
2485 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
|
2486 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
|
2487 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
|
2488 title. |
|
8028
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2489 |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2490 This page also defines macros for use in search pages. |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2491 |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2492 * th_label - defines a label for a search field |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2493 * search_input - defines a text input field |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2494 * search_date - defines a text input field with popup calendar link |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2495 * search_popup - defines a text input with popup classhelper link |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2496 * search_select - defines a select/dropdown element for selecting |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2497 a single item from a class |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2498 * search_select_keywords - defines a dropdown with a keyword |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2499 search expression builder link |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2500 * search_select_translated - like search_Select but it translates |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2501 the items in the dropdown |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2502 * search_multiselect - text input with multiselect classhelper |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2503 popup link |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2504 * search_checkboxes - display selection items as checkbox items |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2505 * column_input - a checkbox element used to select an element for |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2506 display in a search result (sets the @columns property) |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2507 * sort_input - a radiobutton element used to select sorting |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2508 * group_input - a radiobutton element used to select grouping |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2509 |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2510 and the user.item.html page: |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2511 |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2512 * user_src_input - takes a long name and splits it into parts (first/last) |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2513 * user_normal_input - takes a name without splitting it for reuse |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2514 * user_pw_input - a password input for the user |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2515 * user_confirm_input - a password input marked so the back end |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2516 confirms it against the password submitted through the user_pw_input |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2517 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2518 **home.html** |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2519 the default page displayed when in `the "home" context`_ and no |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2520 other page is requested using the ``@template`` parameter |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2521 **home.classlist.html** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2522 a special version of the default page that lists the classes in the |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2523 tracker. It is requested in the "home" context using ``@template=classlist`` |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2524 **classname.item.html** |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2525 displays an item of the *classname* class given a :term:`designator` |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2526 **classname.index.html** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2527 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
|
2528 **classname.search.html** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2529 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
|
2530 **_generic.index.html** |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2531 used to display a list of items when there is no |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2532 ``*classname*.index`` available |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2533 **_generic.help.html** |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2534 used to display a "class help" page when there is no |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2535 ``*classname*.help`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2536 **user.register.html** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2537 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
|
2538 page |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2539 **style.css** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2540 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
|
2541 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2542 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
|
2543 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2544 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
|
2545 so if you just want to play around with the templating for new issues, |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2546 you can copy the current "issue.item.html" template to |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2547 "issue.test" (or "issue.test.html"), and then |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2548 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
|
2549 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2550 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
|
2551 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2552 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
|
2553 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2554 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
|
2555 directory. So if you specify:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2556 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2557 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
|
2558 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2559 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
|
2560 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
|
2561 ``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
|
2562 it will return an error. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2563 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2564 Implementing Modal Editing Using @template |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2565 ------------------------------------------ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2566 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2567 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
|
2568 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
|
2569 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
|
2570 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2571 However, you may want a modal edit. A modal edit requires the |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2572 user to take some action (click a button or follow a link) to |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2573 shift from display mode to edit mode. Submitting the changes |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2574 ends edit mode and the user returns to display |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2575 mode. |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2576 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2577 To build a modal edit for an item, move the (editable) |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2578 issue.item.html template to issue.item_edit.html. Then create a new |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2579 issue.item.html template that only displays information. Add an |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2580 edit link that calls the display url, but adds ``@template=item_edit`` |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2581 to the link. |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2582 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2583 This will now display the edit page. On the edit page you want to |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2584 add a hidden text field to your form named ``@template`` with the |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2585 value: ``item|item_edit``. When the form is submitted, it is |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2586 validated. If the form is correct the user will see the item |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2587 rendered using the item template. If there is an error |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2588 (validation failed) the item will be rendered using the |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2589 ``item_edit`` template. The rendered ``item_edit`` template will |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2590 display all the changes that the user made to the form before it |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2591 was submitted. The user can correct the error and resubmit the |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2592 changes until the form validates. |
|
7352
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 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
|
2595 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
|
2596 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
|
2597 the edits again. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2598 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2599 In general, modal workflows are not implemented by the default |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2600 templates because they slow down the edit cycle. For some |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2601 specific workflows a modal edit is useful. For example, a batch |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2602 edit mode allows the user to edit multiple issues in one |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2603 form. It can result in a modal workflow of: |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2604 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2605 * search for issues to modify |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2606 * switch to edit mode and change values |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2607 * exit back to the results of the search |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2608 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2609 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2610 How the templates work |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2613 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2614 Templating engines |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2615 ~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2616 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2617 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
|
2618 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2619 * 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
|
2620 * 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
|
2621 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
|
2622 same syntax, but they are not 100% compatible. The major (and most |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2623 likely the only) incompatibility is the default expression type of |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2624 ``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
|
2625 differences" section of `Chameleon documentation`__. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2626 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2627 Version 1.5.0 added support for the `jinja2`_ templating |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2628 language. You must install the `jinja2`_ module to use it. The |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2629 ``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
|
2630 to use ``jinja2`` rather than TAL. A number of trackers are running |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2631 using ``jinja2`` templating so it is less experimental than |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2632 Chameleon templating. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2633 |
|
8111
394f72021dad
docs: replace redirecting url's with target
John Rouillard <rouilj@ieee.org>
parents:
8099
diff
changeset
|
2634 .. _jinja2: https://palletsprojects.com/projects/jinja/ |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2635 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2636 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2637 **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
|
2638 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
|
2639 resolve the path expressions. A Chameleon-based, z3c.pt, that is fully |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2640 compatible with the old TAL implementation, is planned for a |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2641 future release. |
|
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 **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
|
2644 recommended for production use. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2645 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2646 .. _Chameleon: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2647 https://pypi.org/project/Chameleon/ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2648 .. _z3c.pt: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2649 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
|
2650 __ 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
|
2651 .. _TAL: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2652 .. _Template Attribute Language: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2653 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
|
2654 |
|
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 Basic Templating Actions |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2657 ~~~~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2658 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2659 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
|
2660 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
|
2661 The basic TAL commands are: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2662 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2663 **tal:define="variable expression; variable expression; ..."** |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2664 Define a new local variable for this tag and its contents. For |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2665 example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2666 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2667 <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
|
2668 <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
|
2669 </html> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2670 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2671 In this example, the variable "title" is defined by the |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2672 expression "request/description". The "tal:content" command |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2673 inside the <html> tag may then use the "title" variable. |
|
7352
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:condition="expression"** |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2676 Keep this tag and its contents if the expression is true. For |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2677 example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2678 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2679 <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
|
2680 Display some issue information. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2681 </p> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2682 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2683 In the example, the <p> tag and its contents are displayed |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2684 only if the user has the "View" permission for issues. We |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2685 consider the number zero, a blank string, an empty list, and |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2686 the built-in variable nothing to be false values. Nearly every |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2687 other value is true, including non-zero numbers, and strings |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2688 with anything in them (even spaces!). |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2689 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2690 **tal:repeat="variable expression"** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2691 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
|
2692 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
|
2693 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
|
2694 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2695 <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
|
2696 <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
|
2697 <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
|
2698 <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
|
2699 </tr> |
|
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 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
|
2702 "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
|
2703 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
|
2704 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
|
2705 below on `the repeat variable`_. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2706 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2707 **tal:replace="expression"** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2708 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
|
2709 |
|
8383
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2710 <span tal:replace="request/user/id" /> |
|
7352
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 The example would replace the <span> tag and its contents with the |
|
8383
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2713 user's id. If the user's id was "3" the resulting output would be |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2714 "3". |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2715 |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2716 You need to be a little careful with ``tal:replace``. Unlike |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2717 ``tal:content``, it doesn't always escape the output. For example |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2718 if you used:: |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2719 |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2720 <tal:x tal:replace="request/user/realname" /> |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2721 |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2722 it would replace the contents with the value of the user's |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2723 realname. The realname is something the user can control. The user |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2724 could include something like:: |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2725 |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2726 Bruce<script>alert("hello there");</script> |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2727 |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2728 This would result in an alert box popping up when the page was |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2729 loaded. Attackers could use this `XSS exploit`_ for malicious |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2730 purposes. |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2731 |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2732 Generally you would use tal:replace when calling a utility function |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2733 using a :ref:`Python expression <python expression>` that generates |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2734 trusted HTML. |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2735 |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2736 If you are inserting untrusted content, it is better to use |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2737 ``tal:content`` with tags that disappear as described below. |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2738 |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2739 .. _`XSS exploit`: https://owasp.org/www-community/attacks/xss/ |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2740 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2741 **tal:content="expression"** |
|
8383
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2742 Replace the contents of this tag (but not the tag itself) with the |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2743 result of the expression. For example:: |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2744 |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2745 <span tal:content="request/user/realname">user's name appears here |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2746 </span> |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2747 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2748 This example would replace the contents of the ``<span>`` tag with the |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2749 user's realname. If the user's realname was "Bruce" then the |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2750 output will be ``<span>Bruce</span>``. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2751 |
|
8383
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2752 ``tal:content`` replaces special HTML claracters like ``<`` with an |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2753 HTML entitity ``<``. This makes it safer to use when inserting |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2754 untrusted data. To have ``tal:content`` insert unescaped HTML, you |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2755 need to use the `structure modifier`_. |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2756 |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2757 If the tag is an unknown ``tal:`` tag, TAL removes the tag. So |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2758 evaulating: |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2759 |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2760 <tal:x tal:replace="request/user/realname" /> |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2761 |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2762 results in ``Bruce``. |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2763 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2764 **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
|
2765 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
|
2766 example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2767 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2768 <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
|
2769 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2770 In the example, the "href" attribute of the ``<a>`` tag is set |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2771 to the value of the expression "string:user${request/user/id}", |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2772 which will look like "user123". |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2773 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2774 **tal:omit-tag="expression"** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2775 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
|
2776 example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2777 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2778 <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
|
2779 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2780 would result in output of:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2781 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2782 Hello, world! |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2783 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2784 Note that TAL evaluates the commands on a given tag in the order above. |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2785 *define* is evaluated before *condition*, and so on. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2786 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2787 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
|
2788 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
|
2789 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
|
2790 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
|
2791 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
|
2792 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
|
2793 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2794 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2795 Templating Expressions |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2796 ~~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2797 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2798 Templating Expressions are covered by `Template Attribute |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2799 Language Expression Syntax`_ (TALES). The expressions you use in |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2800 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
|
2801 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2802 **Path Expressions** - e.g. ``item/status/checklist`` |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2803 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
|
2804 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
|
2805 ``status`` and ``checklist``. The ``item`` part is the root of the |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2806 expression. It then looks for a ``status`` attribute on ``item``, or |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2807 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
|
2808 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
|
2809 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
|
2810 is called; if it is an object, it is stringified. Path expressions |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2811 may have an optional ``path:`` prefix, but path is the default |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2812 expression type for TAL. In Chameleon you must include the |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2813 ``path:`` prefix. |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2814 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2815 If an element in the path may not exist, you can use the ``|`` |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2816 operator in the expression to provide an alternative. The |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2817 expression ``request/form/foo/value | default`` would simply |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2818 leave the current HTML in place if the "foo" form variable |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2819 doesn't exist. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2820 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2821 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
|
2822 "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
|
2823 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
|
2824 case of ``tal:attributes``). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2825 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2826 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
|
2827 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
|
2828 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
|
2829 the case of ``tal:replace``). |
|
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 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
|
2832 ``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
|
2833 expressions. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2834 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2835 **String Expressions** - e.g. ``string:hello ${user/name}`` These |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2836 expressions are string interpolations - though they can be |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2837 just plain strings with no interpolation if you want. The |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2838 expression in the interpolation decorator ``${ ... }`` is a |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2839 path expression as above. |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2840 |
|
8383
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2841 .. _`python expression`: |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2842 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2843 **Python Expressions** - e.g. ``python: 1+1`` |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2844 These expressions give the full power of Python. All the "root level" |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2845 variables are available, so ``python:item.status.checklist()`` is |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2846 the same as ``item/status/checklist``, assuming that |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2847 ``checklist`` is a method. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2848 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2849 Modifiers: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2850 |
|
8383
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2851 .. _`structure modifier`: |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2852 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2853 **structure** - e.g. ``structure python:msg.content.plain(hyperlink=1)`` |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2854 The result of expressions are *escaped* to be safe for HTML |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2855 display (all "<", ">" and "&" are replaced with entities |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2856 (e.g. ``<``). The ``structure`` expression modifier turns |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2857 off this escaping - the result of the expression is now |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2858 assumed to be HTML, which is passed to the web browser for |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2859 rendering. |
|
7352
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 **not:** - eg. ``not:python:1=1`` |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2862 This inverts the logical true/false value of another |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2863 expression. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2864 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2865 .. _TALES: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2866 .. _Template Attribute Language Expression Syntax: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2867 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
|
2868 |
|
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 Template Macros |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2871 ~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2872 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2873 Roundup uses macros to save us from repeating the same common |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2874 page structures over and over. The most common (and probably only) macro |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2875 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
|
2876 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2877 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
|
2878 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
|
2879 though, the attributes belong to the `Macro Expansion Template |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2880 Attribute Language`_, (METAL). The macro commands are: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2881 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2882 **metal:define-macro="macro name"** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2883 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
|
2884 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
|
2885 example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2886 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2887 <html metal:define-macro="page"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2888 ... |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2889 </html> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2890 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2891 defines a macro called "page" using the ``<html>`` tag and its |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2892 contents. Once defined, macros are stored in the ``macros`` |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2893 attribute of the template they are defined on. You can access |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2894 them later on through the ``templates`` variable. Use the path |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2895 expression ``templates/page/macros/icing`` to access the |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2896 "icing" macro defined in the "page.html" template. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2897 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2898 **metal:use-macro="path expression"** |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2899 Use a macro, identified by the path expression. This replaces |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2900 the current tag with the identified macro contents. For |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2901 example:: |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2902 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2903 <tal:block metal:use-macro="templates/page/macros/icing"> |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2904 ... |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2905 </tal:block> |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2906 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2907 will replace the tag and its contents with the "icing" macro |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2908 from the "page" template. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2909 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2910 **metal:define-slot="slot name"** and **metal:fill-slot="slot name"** |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2911 To define *dynamic* parts of the macro, you define "slots" |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2912 which are filled when the macro is used with a *use-macro* |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2913 command. For example, the ``templates/page/macros/icing`` macro |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2914 defines a ``head_title`` slot like so:: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2915 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2916 <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
|
2917 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2918 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
|
2919 like this:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2920 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2921 <tal:block metal:use-macro="templates/page/macros/icing"> |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2922 <title class="big" metal:fill-slot="head_title">My Title</title> |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2923 </tal:block> |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2924 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2925 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
|
2926 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
|
2927 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2928 Note that you may not mix `METAL`_ and `TAL`_ commands on the |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2929 same tag. But TAL commands can be used freely inside METAL-using |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2930 tags (so your *fill-slots* tags may have all manner of TAL inside |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2931 them). |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2932 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2933 .. _METAL: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2934 .. _Macro Expansion Template Attribute Language: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2935 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
|
2936 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2937 Information available to templates |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2938 ---------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2939 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2940 This is implemented by |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2941 ``roundup.cgi.templating.RoundupPageTemplate``. Documentation in |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2942 the installed file ``roundup/cgi/templating.py`` supplements this |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2943 documentation. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2944 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2945 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
|
2946 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2947 **context** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2948 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
|
2949 or a `hyperdb item wrapper`_ |
|
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 **request** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2952 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
|
2953 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2954 - the current index information (``filterspec``, ``filter`` |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2955 arguments, ``properties``, etc) parsed out of the form. |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2956 - methods for filterspec link generation (indexargs_url) |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2957 - "form" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2958 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
|
2959 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
|
2960 - "env" the CGI environment variables |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2961 - "base" the base URL of this instance |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2962 - "user" a HTMLItem instance for the current user |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2963 - "language" as determined by the browser or configuration |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2964 - "classname" the current classname (possibly None) |
|
8384
e0e3212c1e80
doc: better document the template property in the request object.
John Rouillard <rouilj@ieee.org>
parents:
8383
diff
changeset
|
2965 - "template" the current template (e.g. for the ``issue.item.html`` |
|
e0e3212c1e80
doc: better document the template property in the request object.
John Rouillard <rouilj@ieee.org>
parents:
8383
diff
changeset
|
2966 template the template would be the ``item`` suffix on the |
|
e0e3212c1e80
doc: better document the template property in the request object.
John Rouillard <rouilj@ieee.org>
parents:
8383
diff
changeset
|
2967 classname. It can also be the empty string (e.g. with the |
|
e0e3212c1e80
doc: better document the template property in the request object.
John Rouillard <rouilj@ieee.org>
parents:
8383
diff
changeset
|
2968 ``home.html`` template). |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2969 **config** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2970 This variable holds all the values defined in the tracker config.ini |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2971 file (e.g. TRACKER_NAME, etc.) |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2972 **db** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2973 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
|
2974 **templates** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2975 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
|
2976 *use-macro* commands. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2977 **utils** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2978 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
|
2979 **nothing** |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2980 This is a special variable - if an expression evaluates to |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2981 this, then the tag (when used with ``tal:replace``), its |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2982 contents (in the case of ``tal:content``) or some attributes |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2983 (when used with ``tal:attributes``) will not appear in the |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2984 output. For example:: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2985 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2986 <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
|
2987 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2988 would result in:: |
|
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 <span>Hello, World!</span> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2991 **default** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2992 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
|
2993 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
|
2994 remain. So:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2995 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2996 <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
|
2997 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2998 would result in:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2999 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3000 <span>Hello, World!</span> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3001 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3002 and:: |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3003 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3004 <a href="foo" tal:attributes"href nope | default">H</a> |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3005 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3006 when ``nope`` is not defined results in:: |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3007 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3008 <a href="foo">H</a> |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3009 **true**, **false** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3010 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
|
3011 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
|
3012 **i18n** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3013 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
|
3014 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3015 **gettext** (*message*) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3016 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
|
3017 **ngettext** (*singular*, *plural*, *number*) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3018 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
|
3019 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
|
3020 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
|
3021 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
|
3022 return plural otherwise. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3023 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3024 The context variable |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3025 ~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3026 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3027 The *context* variable can contain one of three things based on the |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3028 current context (see `determining web context`_ for how Roundup figures |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3029 this out). If Roundup is: |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3030 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3031 1. at a "home" page, then it's None |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3032 2. at a specific hyperdb class, it's a `hyperdb class wrapper`_. |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3033 3. at a specific hyperdb item, it's a `hyperdb item wrapper`_. |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3034 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3035 If the context is not None, you can access the properties of the class or |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3036 item. The only real difference between cases 2 and 3 are: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3037 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3038 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
|
3039 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
|
3040 ``context/property/field``. |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3041 2. the context's "id" property will be a false value in case 2, |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3042 but a real, or true value in case 3. Thus we can determine whether |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3043 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
|
3044 "context/id". |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3045 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3046 Hyperdb class wrapper |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3049 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
|
3050 class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3051 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3052 This wrapper object provides access to a hyperdb class. It is used |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3053 primarily in both index view and new item views, but it is usable |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3054 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
|
3055 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
|
3056 mind. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3057 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3058 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
|
3059 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
|
3060 from the CGI form. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3061 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3062 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
|
3063 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3064 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3065 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3066 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3067 =========== ============================================================= |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3068 Method Description |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3069 =========== ============================================================= |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3070 properties return a `hyperdb property wrapper`_ for all of this class's |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3071 properties that are searchable by the user. You can use |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3072 the argument cansearch=False to get all properties. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3073 list lists all of the active (not retired) items in the class. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3074 csv return the items of this class as a chunk of CSV text. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3075 propnames lists the names of the properties of this class. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3076 filter lists of items from this class, filtered and sorted. Two |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3077 options are available for sorting: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3078 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3079 1. by the current *request* filterspec/filter/sort/group args |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3080 2. by the "filterspec", "sort" and "group" keyword args. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3081 "filterspec" is ``{propname: value(s)}``. "sort" and |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3082 "group" are an optionally empty list ``[(dir, prop)]`` |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3083 where dir is '+', '-' or None |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3084 and prop is a prop name or None. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3085 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3086 The propname in filterspec and prop in a sort/group spec |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3087 may be transitive, i.e., it may contain properties of |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3088 the form link.link.link.name. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3089 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3090 e.g. All issues with a priority of "1" with messages added in |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3091 the last week, sorted by activity date: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3092 ``issue.filter(filterspec={"priority": "1", |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3093 'messages.creation' : '.-1w;'}, sort=[('activity', '+')])`` |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3094 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3095 Note that when searching for Link and Multilink values, the |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3096 special value '-1' searches for empty Link or Multilink |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3097 values. For both Links and Multilinks, multiple values |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3098 given in a filter call are combined with 'OR' by default. |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3099 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3100 Both Link and Multilinks support a postfix |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3101 expression syntax using negative ID numbers (as |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3102 strings) as operators. Each |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3103 non-negative number (or '-1') is pushed on an |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3104 operand stack. A negative number pops the required |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3105 number of arguments from the stack, applies the |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3106 operator, and pushes the result. The following |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3107 operators are supported: |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3108 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3109 - '-2' stands for 'NOT' and takes one argument |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3110 - '-3' stands for 'AND' and takes two arguments |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3111 - '-4' stands for 'OR' and takes two arguments |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3112 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3113 Note that this special handling of ID arguments is |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3114 applied only when a negative number smaller than -1 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3115 is encountered as an ID in the filter |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3116 call. Otherwise the implicit OR default applies. |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3117 Examples of using Multilink expressions would be |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3118 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3119 - '1', '2', '-4', '3', '4', '-4', '-3' |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3120 would search for IDs (1 or 2) and (3 or 4) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3121 - '-1' '-2' would search for all non-empty Multilinks |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3122 - The URL fragment |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3123 ``filter=assignedto&assignedto=-1,-2`` |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3124 would find all issues that are assigned (where |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3125 the assignedto field is not empty). |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3126 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3127 Note that 'NOT', (``-2``) is the only useful |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3128 operand for links. By default, a multi-value search |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3129 uses 'OR', so '-4' is redundant. Since a link only |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3130 has a single value, the 'AND' operand will return |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3131 an empty result. |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3132 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3133 filter_sql **Only in SQL backends** |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3134 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3135 Lists the items that match the SQL provided. The SQL is a |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3136 complete "select" statement. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3137 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3138 The SQL select must include the item id as the first column. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3139 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3140 This function **does not** filter out retired items, add |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3141 on a where clause "__retired__ <> 1" if you don't want |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3142 retired nodes. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3143 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3144 classhelp display a link to a JavaScript popup containing this class' |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3145 "help" template. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3146 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3147 This generates a link to a popup window which displays the |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3148 properties indicated by "properties" of the class named by |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3149 "classname". The "properties" should be a comma-separated list |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3150 (e.g. 'id,name,description'). Properties defaults to all the |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3151 properties of a class (excluding id, creator, created and |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3152 activity). |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3153 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3154 You may optionally override the "label" displayed, the "width", |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3155 the "height", the number of items per page ("pagesize") and |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3156 the field on which the list is sorted ("sort"). |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3157 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3158 With the "filter" arg it is possible to specify a filter for |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3159 which items are supposed to be displayed. It has to be of |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3160 the format "<field>=<values>;<field>=<values>;...". |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3161 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3162 The popup window is resizable and scrollable. |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3163 |
|
7928
c05ea62b4c7a
fix: issue2551347 - make _generic.help.html work without property settings
John Rouillard <rouilj@ieee.org>
parents:
7920
diff
changeset
|
3164 If the "property" arg is given, it's passed through to |
|
c05ea62b4c7a
fix: issue2551347 - make _generic.help.html work without property settings
John Rouillard <rouilj@ieee.org>
parents:
7920
diff
changeset
|
3165 the JavaScript help_window function. This allows |
|
c05ea62b4c7a
fix: issue2551347 - make _generic.help.html work without property settings
John Rouillard <rouilj@ieee.org>
parents:
7920
diff
changeset
|
3166 updating of a property in the calling HTML |
|
c05ea62b4c7a
fix: issue2551347 - make _generic.help.html work without property settings
John Rouillard <rouilj@ieee.org>
parents:
7920
diff
changeset
|
3167 page. "property" is optional. If not provided, the |
|
c05ea62b4c7a
fix: issue2551347 - make _generic.help.html work without property settings
John Rouillard <rouilj@ieee.org>
parents:
7920
diff
changeset
|
3168 resulting window will be read only. This is useful for |
|
c05ea62b4c7a
fix: issue2551347 - make _generic.help.html work without property settings
John Rouillard <rouilj@ieee.org>
parents:
7920
diff
changeset
|
3169 Link properties where selection can be done by drop-down, |
|
c05ea62b4c7a
fix: issue2551347 - make _generic.help.html work without property settings
John Rouillard <rouilj@ieee.org>
parents:
7920
diff
changeset
|
3170 but descriptions of the values can be seen in the popup. |
|
c05ea62b4c7a
fix: issue2551347 - make _generic.help.html work without property settings
John Rouillard <rouilj@ieee.org>
parents:
7920
diff
changeset
|
3171 Note that some tracker templates may generate an error |
|
c05ea62b4c7a
fix: issue2551347 - make _generic.help.html work without property settings
John Rouillard <rouilj@ieee.org>
parents:
7920
diff
changeset
|
3172 if the property is missing. Version 2.4.0 of Roundup |
|
c05ea62b4c7a
fix: issue2551347 - make _generic.help.html work without property settings
John Rouillard <rouilj@ieee.org>
parents:
7920
diff
changeset
|
3173 fixed these templates. |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3174 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3175 If the "form" arg is given, it's passed through to the |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3176 JavaScript help_window function - it's the name of the form |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3177 the "property" belongs to. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3178 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3179 submit generate a submit button (and action and @csrf hidden elements) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3180 renderWith render this class with the given template. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3181 history returns 'New node - no history' :) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3182 is_edit_ok is the user allowed to Edit the current class? |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3183 is_view_ok is the user allowed to View the current class? |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3184 =========== ============================================================= |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3185 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3186 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
|
3187 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
|
3188 expression. For example:: |
|
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 python:context['list'] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3191 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3192 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
|
3193 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3194 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3195 Hyperdb item wrapper |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3196 :::::::::::::::::::: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3197 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3198 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
|
3199 class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3200 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3201 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
|
3202 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3203 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
|
3204 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
|
3205 from the CGI form. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3206 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3207 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
|
3208 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3209 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3210 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3211 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3212 =============== ======================================================== |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3213 Method Description |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3214 =============== ======================================================== |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3215 submit generate a submit button (and action and @csrf hidden elements) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3216 journal return the journal of the current item (**not |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3217 implemented**) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3218 history render the journal of the current item as |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3219 HTML. By default properties marked as "quiet" (see |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3220 `design documentation`_) are not shown unless the |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3221 function is called with the ``showall=True`` parameter. |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3222 Properties that are not Viewable to the user are not |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3223 shown. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3224 renderQueryForm specific to the "query" class - render the search form |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3225 for the query |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3226 hasPermission specific to the "user" class - determine whether the |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3227 user has a Permission. The signature is:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3228 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3229 hasPermission(self, permission, [classname=], |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3230 [property=], [itemid=]) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3231 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3232 where the classname defaults to the current context. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3233 hasRole specific to the "user" class - determine whether the |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3234 user has a Role. The signature is:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3235 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3236 hasRole(self, rolename) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3237 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3238 is_edit_ok is the user allowed to Edit the current item? |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3239 is_view_ok is the user allowed to View the current item? |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3240 is_retired is the item retired? |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3241 download_url generate a url-quoted link for download of FileClass |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3242 item contents (ie. file<id>/<name>) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3243 copy_url generate a url-quoted link for creating a copy |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3244 of this item. By default, the copy will acquire |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3245 all properties of the current item except for |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3246 ``messages`` and ``files``. This can be overridden |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3247 by passing ``exclude`` argument which contains a list |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3248 (or any iterable) of property names that shall not be |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3249 copied. Database-driven properties like ``id`` or |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3250 ``activity`` cannot be copied. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3251 =============== ======================================================== |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3252 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3253 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
|
3254 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
|
3255 expression. For example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3256 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3257 python:context['journal'] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3258 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3259 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
|
3260 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3261 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3262 Hyperdb property wrapper |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3265 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
|
3266 ``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
|
3267 ``HTMLNumberProperty``, and so on). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3268 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3269 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
|
3270 value may be either: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3271 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3272 1. if accessed through a `hyperdb item wrapper`_, then it is a value from |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3273 the hyperdb |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3274 2. if access through a `hyperdb class wrapper`_, then it is a value from |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3275 the CGI form |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3276 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3277 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3278 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
|
3279 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3280 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3281 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3282 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3283 =============== ======================================================== |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3284 Attribute Description |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3285 =============== ======================================================== |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3286 _name the name of the property |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3287 _value the value of the property if any - this is the actual |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3288 value retrieved from the hyperdb for this property |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3289 =============== ======================================================== |
|
7352
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 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
|
3292 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3293 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3294 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3295 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3296 =========== ================================================================ |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3297 Method Description |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3298 =========== ================================================================ |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3299 plain render a "plain" representation of the property. This method |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3300 may take two arguments: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3301 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3302 escape |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3303 If true, escape the text so it is HTML safe (default: no). The |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3304 reason this defaults to off is that text is usually escaped |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3305 at a later stage by the TAL commands, unless the "structure" |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3306 option is used in the template. The following ``tal:content`` |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3307 expressions are all equivalent:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3308 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3309 "structure python:msg.content.plain(escape=1)" |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3310 "python:msg.content.plain()" |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3311 "msg/content/plain" |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3312 "msg/content" |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3313 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3314 Usually you'll only want to use the escape option in a |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3315 complex expression. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3316 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3317 hyperlink |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3318 If true, turn URLs, email addresses and hyperdb item |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3319 designators in the text into hyperlinks (default: no). Note |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3320 that you'll need to use the "structure" TAL option if you |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3321 want to use this ``tal:content`` expression:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3322 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3323 "structure python:msg.content.plain(hyperlink=1)" |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3324 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3325 The text is automatically HTML-escaped before the hyperlinking |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3326 transformation done in the plain() method. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3327 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3328 hyperlinked The same as msg.content.plain(hyperlink=1), but nicer:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3329 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3330 "structure msg/content/hyperlinked" |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3331 |
|
7864
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3332 wrapped Wraps long lines on the nearest whitespace. Like |
|
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3333 plain(), it takes ``escape`` and ``hyperlink`` |
|
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3334 arguments. However, the defaults are to enable both |
|
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3335 escape and hyperlinks. It also takes a ``columns`` |
|
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3336 argument set by default to 80. |
|
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3337 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3338 field render an appropriate form edit field for the property - for |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3339 most types this is a text entry box, but for |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3340 Booleans it is a |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3341 tri-state yes/no/neither selection. This method may take some |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3342 arguments: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3343 |
|
8300
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3344 display_time (Date properties only) |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3345 By default this uses the display_time paramter of the |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3346 Date property (which by default is True) and displays |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3347 date and time for Date properties. You can set this to |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3348 False for displaying only the date. |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3349 |
|
8301
3ba8078843db
Add "form" parameter for Date field method
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8300
diff
changeset
|
3350 form (Date properties only) |
|
3ba8078843db
Add "form" parameter for Date field method
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8300
diff
changeset
|
3351 When using a popup calendar (see popcal below) and the |
|
3ba8078843db
Add "form" parameter for Date field method
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8300
diff
changeset
|
3352 enclosing form name is different from "itemSynopsis", |
|
3ba8078843db
Add "form" parameter for Date field method
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8300
diff
changeset
|
3353 the form name must be specified for the field. |
|
3ba8078843db
Add "form" parameter for Date field method
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8300
diff
changeset
|
3354 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3355 format (Date properties only) |
|
8285
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
3356 Sets the format of the date in the field - uses the |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
3357 same format string argument as supplied to the |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
3358 ``pretty`` method below. If you use this, it will |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
3359 prevent the use of browser native date inputs. It is |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
3360 useful if you want partial dates. For example using |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
3361 ``format="%Y-%m"`` with ``type="text"`` will display a |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
3362 text edit box with the year and month part of your |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
3363 date. |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
3364 |
|
8300
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3365 labelfirst (Boolean properties only) |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3366 place the labels before the radio buttons |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3367 |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3368 popcal (Date properties only) |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3369 Include a link to the JavaScript-based popup calendar |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3370 for date selection. Defaults to off/False when browser |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3371 native dates are in use and on/True otherwise because |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3372 browser native dates support a date popup on most |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3373 browsers. |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3374 |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3375 size (default 30) |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3376 Sets the width in characters of the edit field |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3377 |
|
8285
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
3378 type (depends on property type) |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
3379 Sets the type property of the input. To change a date |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
3380 property field from a native date input to a text |
|
8300
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3381 input you would use ``type="text"``. For Date properties |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3382 the type cannot be set by the user and is enforced via |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3383 the configuration (if browser native date input should |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3384 be used). |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3385 |
|
7865
ee586ff074ed
doc: add documention for boolean field() arguments.
John Rouillard <rouilj@ieee.org>
parents:
7864
diff
changeset
|
3386 y_label, n_label, u_label (Boolean properties only) |
|
ee586ff074ed
doc: add documention for boolean field() arguments.
John Rouillard <rouilj@ieee.org>
parents:
7864
diff
changeset
|
3387 Set the labels for the true/false/undefined |
|
7867
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3388 states. If u_label is defined, it produces a |
|
7865
ee586ff074ed
doc: add documention for boolean field() arguments.
John Rouillard <rouilj@ieee.org>
parents:
7864
diff
changeset
|
3389 tri-state radio button selector. Otherwise, it |
|
8264
09e8d1a4c796
docs: clarify wording, fix index, add superseder link
John Rouillard <rouilj@ieee.org>
parents:
8263
diff
changeset
|
3390 allows selection of true/yes or false/no only. |
|
7865
ee586ff074ed
doc: add documention for boolean field() arguments.
John Rouillard <rouilj@ieee.org>
parents:
7864
diff
changeset
|
3391 |
|
8098
c6030fa9362e
docs: issue2550961 - required attribute incorrectly shown when using field()
John Rouillard <rouilj@ieee.org>
parents:
8028
diff
changeset
|
3392 Other arguments are added as properties directly on the |
|
c6030fa9362e
docs: issue2550961 - required attribute incorrectly shown when using field()
John Rouillard <rouilj@ieee.org>
parents:
8028
diff
changeset
|
3393 input tag. For example:: |
|
c6030fa9362e
docs: issue2550961 - required attribute incorrectly shown when using field()
John Rouillard <rouilj@ieee.org>
parents:
8028
diff
changeset
|
3394 |
|
c6030fa9362e
docs: issue2550961 - required attribute incorrectly shown when using field()
John Rouillard <rouilj@ieee.org>
parents:
8028
diff
changeset
|
3395 field(size=30, id='myid', required=None) |
|
c6030fa9362e
docs: issue2550961 - required attribute incorrectly shown when using field()
John Rouillard <rouilj@ieee.org>
parents:
8028
diff
changeset
|
3396 |
|
c6030fa9362e
docs: issue2550961 - required attribute incorrectly shown when using field()
John Rouillard <rouilj@ieee.org>
parents:
8028
diff
changeset
|
3397 produces:: |
|
c6030fa9362e
docs: issue2550961 - required attribute incorrectly shown when using field()
John Rouillard <rouilj@ieee.org>
parents:
8028
diff
changeset
|
3398 |
|
c6030fa9362e
docs: issue2550961 - required attribute incorrectly shown when using field()
John Rouillard <rouilj@ieee.org>
parents:
8028
diff
changeset
|
3399 <input id="myid" size="30" required> |
|
c6030fa9362e
docs: issue2550961 - required attribute incorrectly shown when using field()
John Rouillard <rouilj@ieee.org>
parents:
8028
diff
changeset
|
3400 |
|
c6030fa9362e
docs: issue2550961 - required attribute incorrectly shown when using field()
John Rouillard <rouilj@ieee.org>
parents:
8028
diff
changeset
|
3401 Note that using ``None`` as the value results in an |
|
c6030fa9362e
docs: issue2550961 - required attribute incorrectly shown when using field()
John Rouillard <rouilj@ieee.org>
parents:
8028
diff
changeset
|
3402 attribute without a value. This is useful for boolean |
|
c6030fa9362e
docs: issue2550961 - required attribute incorrectly shown when using field()
John Rouillard <rouilj@ieee.org>
parents:
8028
diff
changeset
|
3403 properties like ``required``. |
|
c6030fa9362e
docs: issue2550961 - required attribute incorrectly shown when using field()
John Rouillard <rouilj@ieee.org>
parents:
8028
diff
changeset
|
3404 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3405 rst only on String properties - render the value of the property |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3406 as ReStructuredText (requires the :ref:`Docutils |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3407 module to be installed separately<install/docutils>`). |
|
7864
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3408 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3409 stext only on String properties - render the value of the property |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3410 as StructuredText (requires the StructureText module to be |
|
7867
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3411 installed separately) (deprecated, to be removed |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3412 use rst or markdown instead). |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3413 markdown only on String properties - render the value of the property |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3414 as Markdown (requires a :ref:`Markdown module to be |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3415 installed separately<install/markdown>`). |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3416 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3417 multiline only on String properties - render a multiline form edit |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3418 field for the property |
|
7864
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3419 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3420 email only on String properties - render the value of the property |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3421 as an obscured email address |
|
7864
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3422 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3423 url_quote only on String properties. It quotes any characters in the |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3424 string so it is safe to use in a url. E.G. a space is |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3425 replaced with %20. |
|
7864
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3426 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3427 confirm only on Password properties - render a second form edit field |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3428 for the property, used for confirmation that the user typed |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3429 the password correctly. Generates a field with name |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3430 "name:confirm". |
|
7864
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3431 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3432 now only on Date properties - return the current date as a new |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3433 property |
|
7864
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3434 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3435 reldate only on Date properties - render the interval between the date |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3436 and now |
|
7864
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3437 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3438 local only on Date properties - return this date as a new property |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3439 with some timezone offset, for example:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3440 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3441 python:context.creation.local(10) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3442 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3443 will render the date with a +10 hour offset. |
|
7864
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3444 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3445 pretty Date properties - render the date as "dd Mon YYYY" (eg. "19 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3446 Mar 2004"). Takes an optional format argument, for example:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3447 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3448 python:context.activity.pretty('%Y-%m-%d') |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3449 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3450 Will format as "2004-03-19" instead. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3451 |
|
7867
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3452 Interval properties - render the interval in a |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3453 pretty format (e.g. "yesterday"). The format |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3454 arguments are those used in the standard |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3455 ``strftime`` call (see the `Python Library |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3456 Reference: time module`__) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3457 |
|
7867
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3458 Number properties - takes a printf style format |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3459 argument (default: '%0.3f') and formats the number |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3460 accordingly. If the value can't be converted, '' |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3461 is returned if the value is ``None`` otherwise it |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3462 is converted to a string. |
|
7864
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3463 |
|
8300
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3464 popcal This is deprecated with Roundup 2.5 which either uses the |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3465 native HTML5 date input or can generate a date popup with |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3466 the popcal option of the ``field`` method. The native date |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3467 input includes a calendar popup on modern broswers. |
|
8285
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
3468 |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
3469 Generate a link to a popup calendar which may be used to |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3470 edit the date field, for example:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3471 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3472 <span tal:replace="structure context/due/popcal" /> |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3473 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3474 you still need to include the ``field`` for the property, so |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3475 typically you'd have:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3476 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3477 <span tal:replace="structure context/due/field" /> |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3478 <span tal:replace="structure context/due/popcal" /> |
|
8300
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3479 |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3480 Since the ``field`` by default already produces a popup |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3481 calendar this use is deprecated. |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3482 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3483 menu only on Link and Multilink properties - render a form select |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3484 list for this property. Takes a number of optional arguments |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3485 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3486 size |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3487 is used to limit the length of the list labels |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3488 height |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3489 is used to set the <select> tag's "size" attribute |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3490 showid |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3491 includes the item ids in the list labels |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3492 additional |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3493 lists properties which should be included in the label |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3494 sort_on |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3495 indicates the property to sort the list on as (direction, |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3496 (direction, property) where direction is '+' or '-'. A |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3497 single string with the direction prepended may be used. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3498 For example: ('-', 'order'), '+name'. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3499 value |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3500 gives a default value to preselect in the menu |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3501 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3502 The remaining keyword arguments are used as conditions for |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3503 filtering the items in the list - they're passed as the |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3504 "filterspec" argument to a Class.filter() call. For example:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3505 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3506 <span tal:replace="structure context/status/menu" /> |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3507 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3508 <span tal:replace="python:context.status.menu(order='+name", |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3509 value='chatting', |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3510 filterspec={'status': '1,2,3,4'}" /> |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3511 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3512 sorted only on Multilink properties - produce a list of the linked |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3513 items sorted by some property, for example:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3514 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3515 python:context.files.sorted('creation') |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3516 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3517 Will list the files by upload date. While:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3518 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3519 python:context.files.sorted('creation', reverse=True) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3520 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3521 Will list the files by upload date in reverse order from |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3522 the prior example. If the property can be unset, you can |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3523 use the ``NoneFirst`` parameter to sort the None/Unset |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3524 values at the front or the end of the list. For example:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3525 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3526 python:context.files.sorted('creation', NoneFirst=True) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3527 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3528 will sort files by creation date with files missing a |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3529 creation date at the start of the list. The default for |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3530 ``NoneFirst`` is False so these files will sort at the end |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3531 by default. (Note creation date is never unset, but you |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3532 get the idea.) If you combine NoneFirst with |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3533 ``reverse=True`` the meaning of NoneFirst is inverted: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3534 True sorts None/unset at the end and False sorts at the |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3535 beginning. |
|
7864
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3536 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3537 reverse only on Multilink properties - produce a list of the linked |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3538 items in reverse order |
|
7864
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3539 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3540 isset returns True if the property has been set to a value |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3541 =========== ================================================================ |
|
7352
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 __ 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
|
3544 |
|
7867
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3545 All the above functions perform checks for permissions required to |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3546 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
|
3547 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
|
3548 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3549 context/title/field |
|
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 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
|
3552 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
|
3553 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
|
3554 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
|
3555 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
|
3556 |
|
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 The request variable |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3559 ~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3560 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3561 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
|
3562 class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3563 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3564 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
|
3565 request. |
|
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 .. 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
|
3568 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3569 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3570 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3571 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3572 =========== ============================================================ |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3573 Variable Holds |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3574 =========== ============================================================ |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3575 base the base URL for this tracker |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3576 classname the current classname (possibly None) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3577 env the CGI environment variables |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3578 form the current CGI form variables in a cgi.FieldStorage |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3579 template the current template (suffix, also possibly None) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3580 user a HTMLUser instance for this user |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3581 =========== ============================================================ |
|
7352
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 **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
|
3584 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3585 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3586 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3587 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3588 =========== ============================================================ |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3589 Variable Holds |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3590 =========== ============================================================ |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3591 columns dictionary of the columns to display in an index page |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3592 filter properties to filter the index on |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3593 filterspec values to filter the index on (property=value, eg |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3594 ``priority=1`` or ``messages.author=42`` |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3595 group index grouping properties [(direction, column name)] |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3596 search_text text to perform a full-text search on for an index |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3597 show a convenience access to columns - request/show/colname will |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3598 be true if the columns should be displayed, false otherwise |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3599 sort index sort columns [(direction, column name)] |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3600 =========== ============================================================ |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3601 |
|
7867
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3602 Several methods are available on the request variable: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3603 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3604 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3605 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3606 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3607 =============== ======================================================== |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3608 Method Description |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3609 =============== ======================================================== |
|
7867
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3610 base_javascript render some javascript used by other components |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3611 of the templating |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3612 batch run the current index args through a filter and return a |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3613 list of items (see `hyperdb item wrapper`_, and |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3614 `batching`_) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3615 description render a description of the request - handle for the |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3616 page title |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3617 indexargs_form render the current index args as form elements |
|
7784
74771afca2b6
doc: fix formatting for indexarg_url.
John Rouillard <rouilj@ieee.org>
parents:
7778
diff
changeset
|
3618 indexargs_url render the current index args as a URL:: |
|
74771afca2b6
doc: fix formatting for indexarg_url.
John Rouillard <rouilj@ieee.org>
parents:
7778
diff
changeset
|
3619 |
|
74771afca2b6
doc: fix formatting for indexarg_url.
John Rouillard <rouilj@ieee.org>
parents:
7778
diff
changeset
|
3620 request.indexargs_url("url", {args}) |
|
74771afca2b6
doc: fix formatting for indexarg_url.
John Rouillard <rouilj@ieee.org>
parents:
7778
diff
changeset
|
3621 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3622 If the value of an arg (in args dict) is None, |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3623 the argument is excluded from the url. If you want |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3624 an empty value use an empty string '' as the value. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3625 Use this in templates to conditionally |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3626 include an arg if it is set to a value. E.G. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3627 {..., '@queryname': request.dispname or None, ...} |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3628 will include @queryname in the url if there is a |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3629 dispname otherwise the parameter will be omitted |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3630 from the url. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3631 =============== ======================================================== |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3632 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3633 The form variable |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3636 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
|
3637 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
|
3638 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
|
3639 "name", use the path expression:: |
|
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 request/form/name/value |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3642 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3643 or the python expression:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3644 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3645 python:request.form['name'].value |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3646 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3647 Note the "item" access used in the python case, and also note the |
|
7867
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3648 explicit "value" attribute we have to access. That's because the |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3649 form variables are stored as MiniFieldStorages. If there's more |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3650 than one "name" value in the form, then the above will break |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3651 since ``request/form/name`` is actually a *list* of |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3652 MiniFieldStorages. So it is best to know beforehand what you are |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3653 dealing with. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3654 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3655 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3656 The db variable |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3659 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
|
3660 class. |
|
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 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
|
3663 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
|
3664 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3665 db/user |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3666 python:db.user |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3667 |
|
7867
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3668 Also, the id of the current user is available as |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3669 ``db.getuid()``. This isn't as useful in templates (where you have |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3670 ``request/user``), but is useful in detectors or interfaces. |
|
7352
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 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
|
3673 |
|
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 The templates variable |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3676 ~~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3677 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3678 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
|
3679 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
|
3680 template engine loader class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3681 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3682 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
|
3683 template macros. It doesn't have any useful methods defined. The |
|
7867
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3684 templates are accessed using the following path expression:: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3685 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3686 templates/name |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3687 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3688 or the python expression:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3689 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3690 templates[name] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3691 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3692 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
|
3693 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
|
3694 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
|
3695 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3696 templates/name/macros/macro_name |
|
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 or the python expression:: |
|
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 templates[name].macros[macro_name] |
|
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 The repeat variable |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3703 ~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3704 |
|
7867
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3705 The repeat variable holds an entry for each active iteration. If |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3706 you have a ``tal:repeat="myusers db/users"`` command, then there |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3707 will be a repeat variable entry called "myusers". This is accessed |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3708 as either:: |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3709 |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3710 repeat/myusers |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3711 python:repeat['myusers'] |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3712 |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3713 The "myusers" entry has nine methods available for information: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3714 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3715 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3716 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3717 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3718 =============== ========================================================= |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3719 Method Description |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3720 =============== ========================================================= |
|
7867
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3721 first True if the current item is the first in the sequence. |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3722 last True if the current item is the last in the sequence. |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3723 even True if the current item is an even item in the sequence. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3724 odd True if the current item is an odd item in the sequence. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3725 number Current position in the sequence, starting from 1. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3726 letter Current position in the sequence as a letter, a through |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3727 z, then aa through zz, and so on. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3728 Letter Same as letter(), except uppercase. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3729 roman Current position in the sequence as lowercase roman |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3730 numerals. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3731 Roman Same as roman(), except uppercase. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3732 =============== ========================================================= |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3733 |
|
7867
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3734 (Note: except for even, True above can be a truthy/falsy value not |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3735 actually True/False. Also the first item in a sequence is 0, |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3736 so it starts with even() = True when number() returns 1 as index |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3737 is 0.) |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3738 |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3739 It also has the following properties: |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3740 |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3741 .. table:: |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3742 :class: valign-top |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3743 |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3744 =============== ========================================================= |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3745 Properties Description |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3746 =============== ========================================================= |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3747 end Truthy if the current item is the last in the sequence. |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3748 index Current index in sequence starting at 0 |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3749 start Truthy if the current item is the first in the sequence. |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3750 =============== ========================================================= |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3751 |
|
7748
315f40fd0e67
doc: fix repeat section first -> start, last -> end
John Rouillard <rouilj@ieee.org>
parents:
7737
diff
changeset
|
3752 For example, this will print a comma after each element except the |
|
315f40fd0e67
doc: fix repeat section first -> start, last -> end
John Rouillard <rouilj@ieee.org>
parents:
7737
diff
changeset
|
3753 last:: |
|
315f40fd0e67
doc: fix repeat section first -> start, last -> end
John Rouillard <rouilj@ieee.org>
parents:
7737
diff
changeset
|
3754 |
|
315f40fd0e67
doc: fix repeat section first -> start, last -> end
John Rouillard <rouilj@ieee.org>
parents:
7737
diff
changeset
|
3755 <span> |
|
315f40fd0e67
doc: fix repeat section first -> start, last -> end
John Rouillard <rouilj@ieee.org>
parents:
7737
diff
changeset
|
3756 <tal:x tal:repeat="field |
|
315f40fd0e67
doc: fix repeat section first -> start, last -> end
John Rouillard <rouilj@ieee.org>
parents:
7737
diff
changeset
|
3757 python:request.form['properties'].value.split(',')"> |
|
315f40fd0e67
doc: fix repeat section first -> start, last -> end
John Rouillard <rouilj@ieee.org>
parents:
7737
diff
changeset
|
3758 <tal:x tal:replace="field"></tal:x> |
|
7867
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3759 <tal:x tal:condition="python:not repeat['field'].last()" |
|
7748
315f40fd0e67
doc: fix repeat section first -> start, last -> end
John Rouillard <rouilj@ieee.org>
parents:
7737
diff
changeset
|
3760 tal:content="string:,"></tal:x> |
|
315f40fd0e67
doc: fix repeat section first -> start, last -> end
John Rouillard <rouilj@ieee.org>
parents:
7737
diff
changeset
|
3761 </tal:x> |
|
315f40fd0e67
doc: fix repeat section first -> start, last -> end
John Rouillard <rouilj@ieee.org>
parents:
7737
diff
changeset
|
3762 </span> |
|
315f40fd0e67
doc: fix repeat section first -> start, last -> end
John Rouillard <rouilj@ieee.org>
parents:
7737
diff
changeset
|
3763 |
|
7867
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3764 The same can be done using a path expression:: |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3765 |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3766 <tal:x tal:condition="not: repeat/field/last" ... |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3767 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3768 .. _templating utilities: |
|
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 The utils variable |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3771 ~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3772 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3773 This is implemented by the |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3774 ``roundup.cgi.templating.TemplatingUtils`` class. New methods can |
|
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3775 be added to the variable by using extensions_. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3776 |
|
8263
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3777 ----- |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3778 |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3779 .. list-table:: TemplatingUtils Methods |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3780 :align: left |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3781 :header-rows: 1 |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3782 :class: valign-top captionbelow booktabs |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3783 |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3784 * - Method |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3785 - Description |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3786 * - Batch |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3787 - return a batch object using the supplied list |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3788 * - anti_csrf_nonce |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3789 - returns the random nonce generated for this session |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3790 * - :meth:`expandfile <roundup.cgi.templating.TemplatingUtils.expandfile>` |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3791 - load a file into a template and expand |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3792 '%(tokenname)s' in the file using |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3793 values from the supplied dictionary. |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3794 * - :meth:`html_calendar <roundup.cgi.templating.TemplatingUtils.html_calendar>` |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3795 - renders an HTML calendar used by the ``_generic.calendar.html`` |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3796 template (itself invoked by the popupCalendar DateHTMLProperty |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3797 method |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3798 * - :meth:`html_quote <roundup.cgi.templating.TemplatingUtils.html_quote>` |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3799 - quote some text as safe in HTML (ie. <, >, ...) |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3800 * - :meth:`readfile <roundup.cgi.templating.TemplatingUtils.readfile>` |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3801 - read JavaScript or other content in an external file |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3802 into the template. |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3803 * - :meth:`set_http_response <roundup.cgi.templating.TemplatingUtils.set_http_response>` |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3804 - set_http_response sets the HTTP response code for the request. |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3805 * - :meth:`url_quote <roundup.cgi.templating.TemplatingUtils.url_quote>` |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3806 - quote some text as safe for a URL (ie. space, %, ...) |
|
8411
ef1ea918b07a
feat(security): Add user confirmation/reauth for sensitive changes
John Rouillard <rouilj@ieee.org>
parents:
8384
diff
changeset
|
3807 * - :meth:`embed_form_fields <roundup.cgi.templating.TemplatingUtils.embed_form_fields>` |
|
ef1ea918b07a
feat(security): Add user confirmation/reauth for sensitive changes
John Rouillard <rouilj@ieee.org>
parents:
8384
diff
changeset
|
3808 - Creates a hidden input for each of the client's form fields. It |
|
ef1ea918b07a
feat(security): Add user confirmation/reauth for sensitive changes
John Rouillard <rouilj@ieee.org>
parents:
8384
diff
changeset
|
3809 also embeds base64 encoded file contents into pre tags and |
|
ef1ea918b07a
feat(security): Add user confirmation/reauth for sensitive changes
John Rouillard <rouilj@ieee.org>
parents:
8384
diff
changeset
|
3810 processes that informtion back into a file input control. |
|
ef1ea918b07a
feat(security): Add user confirmation/reauth for sensitive changes
John Rouillard <rouilj@ieee.org>
parents:
8384
diff
changeset
|
3811 |
|
8263
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3812 |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3813 ----- |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3814 |
|
7836
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3815 Additional info can be obtained by starting ``python`` with the |
|
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3816 ``roundup`` subdirectory on your PYTHONPATH and using the Python help |
|
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3817 function like:: |
|
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3818 |
|
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3819 >>> from roundup.cgi.templating import TemplatingUtils |
|
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3820 >>> help(TemplatingUtils.readfile) |
|
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3821 Help on function readfile in module roundup.cgi.templating: |
|
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3822 |
|
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3823 readfile(self, name, optional=False) |
|
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3824 Read an file in the template directory. |
|
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3825 |
|
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3826 Used to inline file content into a template. If file |
|
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3827 is not found in template directory, reports an error |
|
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3828 to the user unless optional=True. Then it returns an |
|
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3829 empty string. Useful inlining JavaScript kept in an |
|
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3830 external file where you can use linters/minifiers and |
|
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3831 |
|
8099
98ad6d786bef
docs: fix typo extra backquote.
John Rouillard <rouilj@ieee.org>
parents:
8098
diff
changeset
|
3832 (Note: ``>>>`` is the Python REPL prompt. Don't type the ``>>>``.) |
|
7352
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 Batching |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3835 :::::::: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3836 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3837 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
|
3838 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
|
3839 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3840 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
|
3841 overlap=0) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3842 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3843 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
|
3844 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3845 request/batch |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3846 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3847 The parameters are: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3848 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3849 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3850 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3851 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3852 ========= ============================================================== |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3853 Parameter Usage |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3854 ========= ============================================================== |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3855 end where to end (0-indexed) in the sequence. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3856 orphan if the next batch would contain less items than this value, |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3857 then it is combined with this batch |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3858 overlap the number of items shared between adjacent batches |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3859 sequence a list of HTMLItems |
|
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3860 size how big to make the sequence. |
|
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3861 start where to start (0-indexed) in the sequence. |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3862 ========= ============================================================== |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3863 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3864 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
|
3865 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
|
3866 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3867 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3868 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3869 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3870 =============== ======================================================== |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3871 Attribute Description |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3872 =============== ======================================================== |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3873 first indicates the start index of the batch *as a 0-based |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3874 index* |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3875 length the actual number of elements in the batch |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3876 start indicates the start index of the batch. *Unlike |
|
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3877 the argument, is a 1-based index (I know, lame)* |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3878 sequence_length the length of the original, unbatched, sequence. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3879 =============== ======================================================== |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3880 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3881 And several methods: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3882 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3883 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3884 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3885 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3886 =============== ======================================================== |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3887 Method Description |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3888 =============== ======================================================== |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3889 previous returns a new Batch with the previous batch settings |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3890 next returns a new Batch with the next batch settings |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3891 propchanged detect if the named property changed on the current item |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3892 when compared to the last item |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3893 =============== ======================================================== |
|
7352
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 An example of batching:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3896 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3897 <table class="otherinfo"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3898 <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
|
3899 <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
|
3900 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
|
3901 <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
|
3902 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
|
3903 keyword here</td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3904 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3905 </table> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3906 |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3907 will produce a table with four columns containing the items of |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3908 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
|
3909 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3910 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3911 Translations |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3914 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
|
3915 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
|
3916 ``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
|
3917 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
|
3918 create the locale files. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3919 |
|
7807
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3920 Setting the Type of the Returned Data |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3921 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3922 |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3923 Roundup processes a template and uses the name of the template to |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3924 determine the Content-Type MIME header that is returned. For |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3925 ``issue.index.html` it would return ``text/html``. Similarly a file |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3926 named ``issue.atom.xml`` (an rss feed) would have a type |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3927 of``application/xml``. A file named 'issue.json' would have type |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3928 ``application/json``. |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3929 |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3930 However as of Roundup 2.4.0 you can set the type of the file by |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3931 calling:: |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3932 |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3933 request.client.setHeader('Content-Type', 'application/atom+xml') |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3934 |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3935 from your template. For TAL based templates, something like this:: |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3936 |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3937 <tal:x tal:replace="python:request.client.setHeader( |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3938 'Content-Type', 'application/atom+xml' |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3939 )"/> |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3940 |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3941 will set the ``Content-Type`` header. The header name is case sensitive, |
|
7807
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3942 so use capital letters as shown. If you don't you end up with multiple |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3943 Content-Type definitions returned to the browser. |
|
7352
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 Displaying Properties |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3948 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
|
3949 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
|
3950 are several display possibilities. For example, in an index view, a |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3951 string property may just be printed as a plain string. In an editor |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3952 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
|
3953 |
|
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 Index Views |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3956 ----------- |
|
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 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
|
3959 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
|
3960 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3961 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3962 Index View Specifiers |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3963 ~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3964 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3965 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
|
3966 been added for clarity):: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3967 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3968 /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
|
3969 keyword=security,ui& |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3970 @group=priority,-status& |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3971 @sort=-activity& |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3972 @filters=status,keyword& |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3973 @columns=title,status,fixer |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3974 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3975 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
|
3976 part and the filter part. The layout part consists of the query |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3977 parameters that begin with the '@' character, and it determines |
|
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3978 the way that the properties of selected items are displayed. The |
|
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3979 filter part consists of all the other query parameters, and it |
|
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3980 determines the criteria by which items are selected for |
|
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3981 display. The filter part is interactively manipulated with the |
|
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3982 form widgets displayed in the filter section. The layout part is |
|
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3983 interactively manipulated by clicking on the column headings in |
|
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3984 the table. |
|
7352
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 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
|
3987 matching any specified Link properties and the intersection of the sets |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3988 of items with values matching any specified MultiLink properties. |
|
7352
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 The example specifies an index of "issue" items. Only items with a |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3991 "status" of either "unread", "in-progress" or "resolved" are |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3992 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
|
3993 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
|
3994 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
|
3995 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
|
3996 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
|
3997 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
|
3998 properties. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3999 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4000 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4001 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4002 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4003 ============ ============================================================= |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4004 Argument Description |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4005 ============ ============================================================= |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4006 @sort sort by prop name, optionally preceeded with '-' to give |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4007 descending or nothing for ascending sorting. Several |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4008 properties can be specified delimited with comma. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4009 Internally a search-page using several sort properties may |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4010 use @sort0, @sort1 etc. with option @sortdir0, @sortdir1 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4011 etc. for the direction of sorting (a non-empty value of |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4012 sortdir0 specifies reverse order). |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4013 @group group by prop name, optionally preceeded with '-' or to sort |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4014 in descending or nothing for ascending order. Several |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4015 properties can be specified delimited with comma. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4016 Internally a search-page using several grouping properties may |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4017 use @group0, @group1 etc. with option @groupdir0, @groupdir1 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4018 etc. for the direction of grouping (a non-empty value of |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4019 groupdir0 specifies reverse order). |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4020 @columns selects the columns that should be displayed. Default is |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4021 all. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4022 @filter indicates which properties are being used in filtering. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4023 Default is none. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4024 propname selects the values the item properties given by propname must |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4025 have (very basic search/filter). |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4026 @search_text if supplied, performs a full-text search (message bodies, |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4027 issue titles, etc) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4028 ============ ============================================================= |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4029 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4030 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4031 Searching Views |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4032 --------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4033 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4034 .. note:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4035 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
|
4036 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
|
4037 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
|
4038 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4039 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
|
4040 "*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
|
4041 ``@action`` variable. The "search" action: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4042 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4043 - 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
|
4044 searching |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4045 - sets the ``@filter`` variable correctly |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
4046 - saves the query to the user's query list if ``@query_name`` is set. |
|
7352
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 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
|
4049 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
|
4050 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
|
4051 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
|
4052 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
|
4053 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
|
4054 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
|
4055 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4056 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
|
4057 provide an additional argument: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4058 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4059 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4060 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4061 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4062 ============ ============================================================= |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4063 Argument Description |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4064 ============ ============================================================= |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4065 @query_name if supplied, the index parameters (including @search_text) |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
4066 will be saved as a the query item and registered against |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4067 the user's queries property. Note that the *classic* template |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4068 schema has this ability, but the *minimal* template schema |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4069 does not. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
4070 ============ ============================================================= |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4071 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4072 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4073 Item Views |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4074 ---------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4075 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4076 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
|
4077 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
|
4078 "history" section. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4079 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4080 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4081 Editor Section |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4082 ~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4083 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4084 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
|
4085 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
|
4086 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4087 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
|
4088 "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
|
4089 template):: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4090 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4091 <table class="form"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4092 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4093 <th>Title</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4094 <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
|
4095 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4096 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4097 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4098 <th>Priority</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4099 <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
|
4100 <th>Status</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4101 <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
|
4102 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4103 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4104 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4105 <th>Superseder</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4106 <td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4107 <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
|
4108 <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
|
4109 <span tal:condition="context/superseder"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4110 <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
|
4111 </span> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4112 </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4113 <th>Nosy List</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4114 <td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4115 <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
|
4116 <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
|
4117 </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4118 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4119 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4120 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4121 <th>Assigned To</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4122 <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
|
4123 assignedto menu |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4124 </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4125 <td> </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4126 <td> </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4127 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4128 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4129 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4130 <th>Change Note</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4131 <td colspan="3"> |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
4132 <textarea name="@note" wrap="hard" rows="5" cols="60"></textarea> |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4133 </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4134 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4135 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4136 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4137 <th>File</th> |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
4138 <td colspan="3"><input type="file" name="@file" size="40"></td> |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4139 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4140 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4141 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4142 <td> </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4143 <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
|
4144 submit button will go here |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4145 </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4146 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4147 </table> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4148 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4149 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4150 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
|
4151 describing the changed properties. As shown in the example, the editor |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
4152 template can use the "@note" and "@file" fields, which are added to the |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4153 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
|
4154 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4155 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4156 Form values |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4157 ::::::::::: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4158 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4159 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
|
4160 meet the various needs of: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4161 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4162 1. editing the current item (perhaps an issue item) |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
4163 2. editing information related to the current item (e.g. messages or |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4164 attached files) |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
4165 3. creating new information to be linked to the current item (e.g. time |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4166 spent on an issue) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4167 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4168 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
|
4169 ":" 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
|
4170 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4171 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
|
4172 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4173 ``<propname>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4174 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
|
4175 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4176 ``<designator>:<propname>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4177 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
|
4178 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4179 ``<classname>-<N>:<propname>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4180 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
|
4181 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
|
4182 |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
4183 Once we have determined the "propname", check to see if it is one of |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4184 the special form values: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4185 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4186 ``@required`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4187 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
|
4188 raised. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4189 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4190 ``@remove@<propname>=id(s)`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4191 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
|
4192 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4193 ``:add:<propname>=id(s)`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4194 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
|
4195 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4196 ``:link:<propname>=<designator>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4197 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
|
4198 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
|
4199 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
|
4200 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
|
4201 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
|
4202 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
|
4203 <classname>-<N>). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4204 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4205 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
|
4206 designator. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4207 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4208 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
|
4209 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4210 ``:note`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4211 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
|
4212 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
|
4213 ``:file`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4214 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
|
4215 :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
|
4216 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4217 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4218 Spool Section |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4219 ~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4220 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4221 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
|
4222 of an issue. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4223 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4224 TODO |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4225 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4226 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4227 History Section |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4228 ~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4229 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4230 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
|
4231 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
|
4232 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4233 <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
|
4234 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4235 or:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4236 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4237 <tal:block |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4238 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
|
4239 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4240 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
|
4241 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4242 *To be done:* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4243 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4244 *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
|
4245 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
|
4246 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4247 <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
|
4248 a journal entry |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4249 </tal:block> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4250 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4251 *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
|
4252 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4253 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4254 Defining new web actions |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4255 ------------------------ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4256 |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
4257 You may define new actions triggered by the ``@action`` form variable. |
|
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
4258 These defined in the tracker's ``extensions`` directory and registered |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4259 using ``instance.registerAction``. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4260 |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
4261 All the pre-existing Actions are defined in ``roundup.cgi.actions``. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4262 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4263 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
|
4264 action class`_, then you `register the action class`_ with the cgi |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
4265 interface so it can be triggered by the ``@action`` form variable. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4266 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
|
4267 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4268 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
|
4269 issues |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4270 <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
|
4271 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4272 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4273 Define the new action class |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4274 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4275 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4276 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
|
4277 example ``myaction.py``:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4278 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4279 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
|
4280 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4281 class MyAction(Action): |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4282 def handle(self): |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4283 ''' 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
|
4284 ''' |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4285 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4286 The *self.client* attribute is an instance of ``roundup.cgi.client.Client``. |
|
8263
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
4287 See the :class:`docstring of that class <roundup.cgi.client.Client>` |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
4288 for details of what it can do. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4289 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4290 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
|
4291 It may then: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4292 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4293 - 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
|
4294 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
|
4295 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
|
4296 - 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
|
4297 next |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4298 - 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
|
4299 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
|
4300 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4301 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4302 Register the action class |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4303 ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4304 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4305 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
|
4306 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
|
4307 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4308 def init(instance): |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4309 instance.registerAction('myaction', myActionClass) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4310 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4311 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
|
4312 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4313 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4314 Use the new action |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4315 ~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4316 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4317 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
|
4318 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4319 <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
|
4320 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4321 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
|
4322 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4323 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
|
4324 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4325 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4326 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
|
4327 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
|
4328 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
|
4329 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
|
4330 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
|
4331 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
|
4332 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
|
4333 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4334 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
|
4335 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4336 This example indicates that the value sent back to the user is actually |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
4337 comma-separated value content (i.e. something to load into a |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4338 spreadsheet or database). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4339 |
|
8285
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
4340 CSS for the web interface |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
4341 ------------------------- |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
4342 |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
4343 The web interface can be completely redesigned by the admin, However |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
4344 some parts of Roundup use classes or set attributes that can be |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
4345 selected by css to change the look of the element. |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
4346 |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
4347 The ``datecopy.js`` module used to allow editing a date value with a |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
4348 text input assigns the ``mode_textdate`` class to the input when it is |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
4349 in text mode. The class is removed when it is not in text mode. |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
4350 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4351 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4352 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
|
4353 -------------------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4354 |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
4355 The web interface uses UTF-8 default. It may be overridden in |
|
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
4356 both forms and a browser cookie. In general, the UTF-8 standard |
|
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
4357 should work with all modern browsers. You shouldn't have to |
|
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
4358 make any modifications from this section. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4359 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4360 - 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
|
4361 - 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
|
4362 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4363 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
|
4364 ``kio8-r``). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4365 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4366 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
|
4367 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
|
4368 utf-8-encoded pages (e.g. Netscape Navigator 4 displays wrong |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
4369 characters in form fields). Roundup allows one to change |
|
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
4370 the character set for http transfers. To do so, you may add |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4371 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
|
4372 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4373 <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
|
4374 <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
|
4375 {'@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
|
4376 <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
|
4377 {'@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
|
4378 </tal:block> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4379 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4380 (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
|
4381 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
|
4382 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4383 ``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
|
4384 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
|
4385 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4386 <meta http-equiv="Content-Type" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4387 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
|
4388 /> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4389 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4390 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
|
4391 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4392 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4393 Debugging Trackers |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4394 ================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4395 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4396 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
|
4397 Roundup: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4398 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4399 1. web :: debug |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4400 2. mail :: debug |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4401 3. logging :: level |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4402 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4403 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
|
4404 more information. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4405 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4406 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
|
4407 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
|
4408 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
|
4409 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4410 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4411 .. _`design documentation`: design.html |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4412 .. _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
|
4413 .. _`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
|
4414 .. _`xmlrpc interface documentation`: xmlrpc.html#through-roundup |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
4415 |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
4416 .. allow line breaks in term definitions. |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
4417 .. |br| raw:: html |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
4418 |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
4419 <br/> |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
4420 |