Mercurial > p > roundup > code
annotate doc/reference.txt @ 8406:e7f8b0e1dda1
merge doc fix and perf fix/warning to session_dbm.py:clean()
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Sun, 10 Aug 2025 20:35:53 -0400 |
| parents | e0e3212c1e80 |
| children | ef1ea918b07a |
| 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 |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
891 The Roundup wiki CategorySchema`_ provides a list of additional |
|
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 |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
951 Detectors in your tracker are run *before* (**auditors**) and *after* |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
952 (**reactors**) changes to the contents of your database. You will have |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
953 some installed by default - have a look. You can write new detectors |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
954 or modify the existing ones. The existing detectors installed for you |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
955 are: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
956 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
957 .. index:: detectors; installed |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
958 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
959 **nosyreaction.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
960 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
|
961 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
|
962 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
|
963 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
|
964 (such as adding new authors, etc.) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
965 **statusauditor.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
966 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
|
967 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
|
968 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
|
969 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
|
970 defined. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
971 **messagesummary.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
972 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
|
973 content. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
974 **userauditor.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
975 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
|
976 roles lists). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
977 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
978 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
|
979 or remove these detectors. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
980 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
981 See the detectors section in the `design document`__ for details of the |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
982 interface for detectors. |
|
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 __ design.html |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
985 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
986 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
987 .. index:: detectors; writing api |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
988 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
989 Detector API |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
990 ------------ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
991 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
992 .. index:: pair: detectors; auditors |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
993 single: auditors; function signature |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
994 single: auditors; defining |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
995 single: auditors; arguments |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
996 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
997 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
|
998 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
999 audit(db, cl, itemid, newdata) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1000 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1001 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
|
1002 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
|
1003 property names to values. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1004 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1005 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
|
1006 ``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
|
1007 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
|
1008 |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1009 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
|
1010 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
|
1011 |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1012 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
|
1013 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1014 .. index:: pair: detectors; reactor |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1015 single: reactors; function signature |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1016 single: reactors; defining |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1017 single: reactors; arguments |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1018 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1019 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
|
1020 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1021 react(db, cl, itemid, olddata) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1022 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1023 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
|
1024 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
|
1025 property names to values. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1026 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1027 For 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
|
1028 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
|
1029 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1030 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
|
1031 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
|
1032 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1033 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
|
1034 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
|
1035 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1036 .. index:: detectors; additional |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1037 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1038 Additional Detectors Ready For Use |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1039 ---------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1040 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1041 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
|
1042 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
|
1043 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
|
1044 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1045 **irker.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1046 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
|
1047 (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
|
1048 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
|
1049 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
|
1050 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
|
1051 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
|
1052 **newissuecopy.py** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1053 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
|
1054 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
|
1055 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
|
1056 email errors! |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1057 **creator_resolution.py** |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1058 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
|
1059 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
|
1060 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
|
1061 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
|
1062 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
|
1063 **email_auditor.py** |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1064 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
|
1065 extension .eml. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1066 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
|
1067 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
|
1068 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
|
1069 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
|
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:: auditors; rules for use |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1073 single: reactors; rules for use |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1074 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1075 Auditor or Reactor? |
|
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 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1078 Generally speaking, you should observe the following rules: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1079 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1080 **Auditors** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1081 Are used for `vetoing creation of or changes to items`_. They might |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1082 also make automatic changes to item properties. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1083 **Reactors** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1084 Detect changes in the database and react accordingly. They should avoid |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1085 making changes to the database where possible, as this could create |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1086 detector loops. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1087 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1088 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1089 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
|
1090 --------------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1091 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1092 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
|
1093 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
|
1094 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
|
1095 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
|
1096 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
|
1097 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1098 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
|
1099 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1100 from roundup.exceptions import Reject |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1101 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1102 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
|
1103 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1104 raise Reject('Description of error') |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1105 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1106 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
|
1107 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
|
1108 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
|
1109 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
|
1110 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
|
1111 |
|
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 Generating email from Roundup |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1114 ----------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1115 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1116 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
|
1117 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
|
1118 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1119 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
|
1120 ``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
|
1121 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
|
1122 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
|
1123 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
|
1124 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1125 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1126 .. index:: extensions |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1127 .. 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
|
1128 .. _extensions: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1129 .. _actions: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1130 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1131 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
|
1132 ================================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1133 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1134 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
|
1135 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
|
1136 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
|
1137 |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1138 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
|
1139 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
|
1140 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
|
1141 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
|
1142 |
|
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1143 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
|
1144 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
|
1145 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
|
1146 ``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
|
1147 mechanism. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1148 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1149 * ``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
|
1150 (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
|
1151 <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
|
1152 |
|
8262
2a7c3eeaf167
feat: add templating utils method dynamically; method to set http code
John Rouillard <rouilj@ieee.org>
parents:
8255
diff
changeset
|
1153 * ``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
|
1154 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
|
1155 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
|
1156 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
|
1157 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1158 * ``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
|
1159 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
|
1160 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
|
1161 ``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
|
1162 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1163 .. _interfaces.py: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1164 .. _modifying the core of Roundup: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1165 |
|
7853
03c1b7ae3a68
issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents:
7836
diff
changeset
|
1166 .. 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
|
1167 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1168 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
|
1169 ================================================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1170 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1171 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
|
1172 this you can: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1173 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1174 * modify class data structures |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1175 * 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
|
1176 * modify the email gateway |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1177 * add new rest endpoints |
|
7375
9bd7ed918121
issue2551253 - Modify password PBKDF2 method to use SHA512
John Rouillard <rouilj@ieee.org>
parents:
7371
diff
changeset
|
1178 * 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
|
1179 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1180 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
|
1181 |
|
7855
047c02dfa267
doc(lint): use vale to rewrite things to be clearer.
John Rouillard <rouilj@ieee.org>
parents:
7853
diff
changeset
|
1182 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
|
1183 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
|
1184 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
|
1185 <#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
|
1186 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
|
1187 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
|
1188 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
|
1189 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
|
1190 |
|
7688
c09192e21faa
doc: add statement on less stable nature of using interfaces.py
John Rouillard <rouilj@ieee.org>
parents:
7658
diff
changeset
|
1191 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
|
1192 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
|
1193 (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
|
1194 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
|
1195 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
|
1196 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
|
1197 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
|
1198 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1199 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
|
1200 <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
|
1201 of using interfaces.py. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1202 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1203 Database Content |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1204 ================ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1205 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1206 .. note:: |
|
7369
15bb0d177632
use glossary directive and link some terms to the glossary.
John Rouillard <rouilj@ieee.org>
parents:
7368
diff
changeset
|
1207 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
|
1208 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
|
1209 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
|
1210 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
|
1211 "working", you need to change the check.) |
|
f37c1df6de34
Glossary updates and more term refs.
John Rouillard <rouilj@ieee.org>
parents:
7369
diff
changeset
|
1212 |
|
f37c1df6de34
Glossary updates and more term refs.
John Rouillard <rouilj@ieee.org>
parents:
7369
diff
changeset
|
1213 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
|
1214 class>` (e.g. status, |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1215 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
|
1216 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
|
1217 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
|
1218 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1219 **Changing content before tracker initialisation** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1220 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
|
1221 created using the ``create( ... )`` methods. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1222 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1223 **Changing content after tracker initialisation** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1224 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
|
1225 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
|
1226 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
|
1227 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1228 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
|
1229 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
|
1230 question. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1231 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1232 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
|
1233 <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
|
1234 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
|
1235 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1236 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1237 Security / Access Controls |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1238 ========================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1239 |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1240 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
|
1241 each Class defined in the tracker schema, the following permissions |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1242 are defined: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1243 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1244 - Create (everything) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1245 - Edit (everything) |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1246 - Search (everything) - (used if View does not permit access) |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1247 - Retire (everything) |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1248 - Restore (everything) |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1249 - View (everything) |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1250 |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1251 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
|
1252 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
|
1253 also define: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1254 |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1255 Email Access |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1256 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
|
1257 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
|
1258 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
|
1259 interface (see also the ``new_email_user_roles`` configuration option). |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1260 |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1261 Web Access |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1262 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
|
1263 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
|
1264 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
|
1265 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
|
1266 Access can be removed from the Anonymous user. |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1267 |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1268 Web Roles |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1269 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
|
1270 TODO: deprecate in favour of a property-based control. |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1271 |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1272 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
|
1273 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
|
1274 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
|
1275 `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
|
1276 `xmlrpc interface documentation`_. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1277 |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1278 Register |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1279 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
|
1280 assigned to the anonymous user. |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1281 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1282 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
|
1283 |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1284 - 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
|
1285 - User (Web Access; Email Access) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1286 - Anonymous (Web Access) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1287 |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
1288 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
|
1289 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
|
1290 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
|
1291 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1292 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
|
1293 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1294 - 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
|
1295 - View priority, status |
|
8137
f5aa7853abda
doc: document Search permission ignores a check clause.
John Rouillard <rouilj@ieee.org>
parents:
8111
diff
changeset
|
1296 - View user (limited properties) |
|
f5aa7853abda
doc: document Search permission ignores a check clause.
John Rouillard <rouilj@ieee.org>
parents:
8111
diff
changeset
|
1297 - 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
|
1298 - Edit their own user record |
|
8137
f5aa7853abda
doc: document Search permission ignores a check clause.
John Rouillard <rouilj@ieee.org>
parents:
8111
diff
changeset
|
1299 - Search queries |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1300 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1301 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
|
1302 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1303 - Web interface access |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1304 - Register user (for registration) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1305 - 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
|
1306 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1307 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
|
1308 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1309 # |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1310 # TRACKER SECURITY SETTINGS |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1311 # |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1312 # 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
|
1313 # about security setup. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1314 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1315 # |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1316 # REGULAR USERS |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1317 # |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1318 # 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
|
1319 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
|
1320 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
|
1321 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
|
1322 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
|
1323 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1324 # 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
|
1325 # to regular users now |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1326 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
|
1327 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
|
1328 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
|
1329 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
|
1330 for cl in 'priority', 'status': |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1331 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
|
1332 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1333 # 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
|
1334 # 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
|
1335 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
|
1336 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
|
1337 'username')) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1338 db.security.addPermissionToRole('User', p) |
|
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 # 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
|
1341 # 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
|
1342 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
|
1343 '''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
|
1344 return userid == itemid |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1345 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
|
1346 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
|
1347 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1348 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
|
1349 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
|
1350 'organisation', 'alternate_addresses', 'queries', 'timezone'), |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1351 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
|
1352 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1353 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1354 # 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
|
1355 # 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
|
1356 # 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
|
1357 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
|
1358 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
|
1359 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
|
1360 return userid == private_for |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1361 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
|
1362 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
|
1363 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
|
1364 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
|
1365 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1366 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
|
1367 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1368 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
|
1369 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
|
1370 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1371 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
|
1372 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
|
1373 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1374 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
|
1375 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
|
1376 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1377 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
|
1378 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
|
1379 db.security.addPermissionToRole('User', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1380 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1381 # |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1382 # ANONYMOUS USER PERMISSIONS |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1383 # |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1384 # 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
|
1385 # 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
|
1386 # 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
|
1387 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
|
1388 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1389 # 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
|
1390 # 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
|
1391 # "Create" user Permission below) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1392 # 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
|
1393 # public trackers. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1394 #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
|
1395 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1396 # 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
|
1397 # Role. Choices here are: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1398 # - Allow anonymous users to register |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1399 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
|
1400 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1401 # 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
|
1402 # information) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1403 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
|
1404 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
|
1405 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1406 # 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
|
1407 # 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
|
1408 # 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
|
1409 # 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
|
1410 # 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
|
1411 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
|
1412 db.security.addPermissionToRole ('Anonymous', p) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1413 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1414 # [OPTIONAL] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1415 # 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
|
1416 # related file and message items) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1417 #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
|
1418 # 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
|
1419 # 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
|
1420 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1421 .. index:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1422 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
|
1423 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1424 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
|
1425 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
|
1426 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
|
1427 cause baffling permission issues. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1428 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1429 Automatic Permission Checks |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1430 --------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1431 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1432 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
|
1433 through the web. This includes: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1434 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1435 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
|
1436 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
|
1437 displayed. |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1438 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
|
1439 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
|
1440 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
|
1441 checking performed) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1442 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
|
1443 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
|
1444 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
|
1445 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
|
1446 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
|
1447 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
|
1448 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
|
1449 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
|
1450 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1451 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1452 New User Roles |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1453 -------------- |
|
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 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
|
1456 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1457 - NEW_WEB_USER_ROLES |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1458 - NEW_EMAIL_USER_ROLES |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1459 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1460 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
|
1461 <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
|
1462 customisation of these parameters. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1463 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1464 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1465 Changing Access Controls |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1466 ------------------------ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1467 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1468 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
|
1469 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
|
1470 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
|
1471 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1472 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
|
1473 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
|
1474 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1475 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1476 Adding a New Permission |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1477 ~~~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1478 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1479 When adding a new Permission, you need to: |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1480 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1481 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
|
1482 ``security.addPermission``. For example:: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1483 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1484 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
|
1485 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
|
1486 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1487 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
|
1488 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
|
1489 "``roundup-admin security``") |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1490 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
|
1491 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
|
1492 extensions/detectors/interfaces.py modules |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1493 |
|
8133
7b6615fb37fc
Add documentation for the filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8111
diff
changeset
|
1494 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
|
1495 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1496 **check** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1497 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
|
1498 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
|
1499 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
|
1500 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
|
1501 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1502 check(db, userid, itemid) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1503 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1504 or:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1505 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1506 check(db, userid, itemid, **ctx) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1507 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1508 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
|
1509 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
|
1510 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
|
1511 defined with the following values:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1512 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1513 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
|
1514 it's a class check. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1515 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1516 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
|
1517 (issue, query ....). |
|
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 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
|
1520 |
|
8137
f5aa7853abda
doc: document Search permission ignores a check clause.
John Rouillard <rouilj@ieee.org>
parents:
8111
diff
changeset
|
1521 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
|
1522 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
|
1523 <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
|
1524 shows the use of ``ctx``. |
|
f5aa7853abda
doc: document Search permission ignores a check clause.
John Rouillard <rouilj@ieee.org>
parents:
8111
diff
changeset
|
1525 |
|
f5aa7853abda
doc: document Search permission ignores a check clause.
John Rouillard <rouilj@ieee.org>
parents:
8111
diff
changeset
|
1526 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
|
1527 permission. When searching there is no item defined, so a check |
| 8138 | 1528 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
|
1529 |
|
8159
3f720edd9594
markup fixes and word typo fix.
John Rouillard <rouilj@ieee.org>
parents:
8154
diff
changeset
|
1530 **filter** |
| 8162 | 1531 This optional function returns parameters for the ``filter`` method |
| 1532 when getting ``Class`` items (users, issues etc.) from the | |
| 1533 database. It filters items at the database level (using SQL where | |
| 1534 possible). This pre-filters the number of items returned from the | |
| 1535 database when displaying results in an ``index`` template. This | |
| 1536 filtering is usually faster than calling a ``check`` method (see | |
| 1537 previous argument) on *each individual result*. | |
| 1538 | |
| 1539 The ``filter`` method has the signature:: | |
|
8154
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1540 |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1541 filter(db, userid, klass) |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1542 |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1543 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
|
1544 access and ``klass`` is the ``Class`` in the schema. |
| 8162 | 1545 |
| 1546 The ``filter`` function must return a *list* of dictionaries of | |
| 1547 parameters of the | |
|
8164
dd60d604a852
Document that filter() can return more than just filterspec params
John Rouillard <rouilj@ieee.org>
parents:
8163
diff
changeset
|
1548 `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
|
1549 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
|
1550 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
|
1551 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
|
1552 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
|
1553 |
|
dd60d604a852
Document that filter() can return more than just filterspec params
John Rouillard <rouilj@ieee.org>
parents:
8163
diff
changeset
|
1554 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
|
1555 parameters computed by the ``filter`` function. An |
| 8162 | 1556 empty list of filter parameters (``[]``) indicates no access. When |
| 1557 using a filter, a check function is still needed to test each | |
| 1558 individual item for visibility. When the filter function is defined | |
| 1559 but a check function is not defined, a check function is | |
| 1560 manufactured automatically from the ``filter`` function. | |
|
8154
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1561 |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1562 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
|
1563 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
|
1564 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
|
1565 |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1566 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
|
1567 in the query checks above would look like:: |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1568 |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1569 def filter_query(db, userid, klass): |
|
8163
d3a1094b15eb
unwrap examples; clarify text
John Rouillard <rouilj@ieee.org>
parents:
8162
diff
changeset
|
1570 return [{'filterspec': { |
|
d3a1094b15eb
unwrap examples; clarify text
John Rouillard <rouilj@ieee.org>
parents:
8162
diff
changeset
|
1571 'private_for': ['-1', userid] |
|
d3a1094b15eb
unwrap examples; clarify text
John Rouillard <rouilj@ieee.org>
parents:
8162
diff
changeset
|
1572 }}] |
|
8154
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1573 |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1574 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
|
1575 displaying queries. It filters for all queries where the |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1576 ``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
|
1577 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
|
1578 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
|
1579 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
|
1580 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
|
1581 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
|
1582 function to:: |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1583 |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1584 def filter_query(db, userid, klass): |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1585 f1 = {'filterspec': {'private_for': ['-1', userid]}} |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1586 f2 = {'filterspec': {'creator': userid}} |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1587 return [f1, f2] |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1588 |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1589 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
|
1590 "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
|
1591 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
|
1592 |
|
8163
d3a1094b15eb
unwrap examples; clarify text
John Rouillard <rouilj@ieee.org>
parents:
8162
diff
changeset
|
1593 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
|
1594 ``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
|
1595 ``organization`` class. Users are permitted to view only those |
|
d3a1094b15eb
unwrap examples; clarify text
John Rouillard <rouilj@ieee.org>
parents:
8162
diff
changeset
|
1596 issues that are associated with their respective organizations. A |
|
d3a1094b15eb
unwrap examples; clarify text
John Rouillard <rouilj@ieee.org>
parents:
8162
diff
changeset
|
1597 check function or this could look like:: |
|
8154
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1598 |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1599 def view_issue(db, userid, itemid): |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1600 user = db.user.getnode(userid) |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1601 if not user.organisation: |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1602 return False |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1603 issue = db.issue.getnode(itemid) |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1604 if user.organisation == issue.organisation: |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1605 return True |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1606 |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1607 The corresponding ``filter`` function:: |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1608 |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1609 def filter_issue(db, userid, klass): |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1610 user = db.user.getnode(userid) |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1611 if not user.organisation: |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1612 return [] |
|
8163
d3a1094b15eb
unwrap examples; clarify text
John Rouillard <rouilj@ieee.org>
parents:
8162
diff
changeset
|
1613 return [{'filterspec': { |
|
d3a1094b15eb
unwrap examples; clarify text
John Rouillard <rouilj@ieee.org>
parents:
8162
diff
changeset
|
1614 'organisation': user.organisation |
|
d3a1094b15eb
unwrap examples; clarify text
John Rouillard <rouilj@ieee.org>
parents:
8162
diff
changeset
|
1615 }}] |
|
8154
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1616 |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1617 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
|
1618 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
|
1619 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
|
1620 organisation. |
|
67a0fc4f9934
Improve section on filter function
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8133
diff
changeset
|
1621 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1622 **properties** |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1623 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
|
1624 new Permission to (eg. ``... klass='user', properties=('name', |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1625 'email') ...``) |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1626 **props_only** |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1627 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
|
1628 in Roundup 1.6. |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1629 A permission defined using: |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1630 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1631 ``properties=('list', 'of', 'property', 'names')`` |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1632 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1633 determines access for things other than just those |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1634 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
|
1635 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
|
1636 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
|
1637 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
|
1638 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
|
1639 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
|
1640 access. |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1641 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1642 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
|
1643 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
|
1644 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
|
1645 surprising. |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1646 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1647 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
|
1648 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
|
1649 properties. But that is not the case. |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1650 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1651 Setting ``props_only=True`` will prevent the permission |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1652 from being used unless the check include properties. |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1653 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1654 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
|
1655 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
|
1656 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1657 db.security.set_props_only_default(True) |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1658 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1659 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
|
1660 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
|
1661 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
|
1662 property only checks to take effect. |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1663 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1664 ``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
|
1665 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
|
1666 presented as:: |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1667 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1668 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
|
1669 (View for "file": ('content', 'summary') only) |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1670 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1671 **Invalid properties for file: ['summary'] |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1672 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1673 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1674 Example Scenarios |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1675 ~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1676 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1677 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
|
1678 examples of customisation. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1679 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1680 **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
|
1681 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
|
1682 ("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
|
1683 "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
|
1684 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
|
1685 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
|
1686 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
|
1687 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
|
1688 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
|
1689 - they're *anonymous*. |
|
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 **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
|
1692 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
|
1693 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
|
1694 (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
|
1695 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
|
1696 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
|
1697 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
|
1698 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
|
1699 ``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
|
1700 "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
|
1701 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1702 **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
|
1703 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
|
1704 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
|
1705 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
|
1706 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
|
1707 auditor. See the example |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1708 `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
|
1709 <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
|
1710 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1711 **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
|
1712 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
|
1713 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
|
1714 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
|
1715 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
|
1716 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
|
1717 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
|
1718 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1719 <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
|
1720 value="resolved">Resolved</option> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1721 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1722 **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
|
1723 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
|
1724 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
|
1725 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
|
1726 interface. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1727 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1728 **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
|
1729 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
|
1730 editing users:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1731 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1732 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
|
1733 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
|
1734 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
|
1735 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1736 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
|
1737 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1738 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1739 Web Interface |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1740 ============= |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1741 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1742 .. contents:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1743 :local: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1744 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1745 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
|
1746 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
|
1747 (``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
|
1748 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
|
1749 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
|
1750 :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
|
1751 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
|
1752 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
|
1753 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1754 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1755 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1756 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
|
1757 --------------------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1758 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1759 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
|
1760 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
|
1761 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1762 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
|
1763 have properties added or removed, |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1764 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
|
1765 "home" page's content arguments. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1766 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1767 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1768 How requests are processed |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1769 -------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1770 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1771 The 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
|
1772 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1773 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
|
1774 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
|
1775 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
|
1776 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
|
1777 output |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1778 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1779 In some situations, exceptions occur: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1780 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1781 - HTTP Redirect (generally raised by an action) |
|
7368
8aa1a5639aef
add explanatory info for HTTP Redirect
John Rouillard <rouilj@ieee.org>
parents:
7363
diff
changeset
|
1782 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
|
1783 - 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
|
1784 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
|
1785 - 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
|
1786 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
|
1787 - 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
|
1788 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
|
1789 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
|
1790 the action to take place |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1791 - 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
|
1792 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
|
1793 client |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1794 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1795 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1796 Roundup URL design |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1797 ------------------ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1798 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1799 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
|
1800 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
|
1801 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1802 1. ``/`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1803 2. ``/index`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1804 3. ``/home`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1805 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1806 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
|
1807 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1808 4. ``/@@file/`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1809 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1810 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
|
1811 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
|
1812 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1813 5. ``/rest/`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1814 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1815 .. _`REST api`: rest.html |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1816 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1817 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
|
1818 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1819 6. ``/xmlrpc`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1820 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1821 .. _`XMLRPC api`: xmlrpc.html |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1822 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1823 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
|
1824 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
|
1825 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
|
1826 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1827 7. ``/issue`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1828 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1829 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
|
1830 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
|
1831 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1832 8. ``/issue1`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1833 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1834 .. _strip_zeros: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1835 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1836 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
|
1837 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
|
1838 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
|
1839 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
|
1840 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1841 Determining web context |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1842 ----------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1843 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1844 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
|
1845 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
|
1846 ``@template`` request parameter. Typical URL paths look like: |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1847 |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1848 1. ``/tracker/`` |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1849 2. ``/tracker/issue`` |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1850 3. ``/tracker/issue1`` |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1851 4. ``/tracker/@@file/style.css`` |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1852 5. ``/cgi-bin/roundup.cgi/tracker/file1`` |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1853 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
|
1854 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1855 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
|
1856 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
|
1857 "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
|
1858 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1859 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
|
1860 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
|
1861 to switch into "home" context. |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1862 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
|
1863 identifies the tracker class to display. |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1864 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
|
1865 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
|
1866 :ref:`Note. <strip_zeros>` |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1867 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
|
1868 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
|
1869 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
|
1870 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
|
1871 directory. Internally this works by raising SendStaticFile exception. |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1872 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
|
1873 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
|
1874 file is displayed. |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1875 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
|
1876 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
|
1877 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
|
1878 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
|
1879 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
|
1880 This raises a ``SendFile`` exception. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1881 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
1882 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
|
1883 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
|
1884 ``@template`` variable, which defaults to: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1885 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1886 - only classname supplied: "index" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1887 - full item designator supplied: "item" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1888 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1889 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1890 The "home" Context |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1891 ------------------ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1892 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1893 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
|
1894 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
|
1895 list or specific issue). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1896 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1897 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
|
1898 interface. You'd probably have: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1899 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1900 - 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
|
1901 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
|
1902 - 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
|
1903 "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
|
1904 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
|
1905 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1906 <tracker url>/home?@template=navigation |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1907 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1908 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1909 Serving static content |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1910 ---------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1911 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1912 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
|
1913 ``@@file`` paths. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1914 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1915 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
|
1916 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
|
1917 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1918 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
|
1919 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
|
1920 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
|
1921 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
|
1922 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
|
1923 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1924 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
|
1925 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1926 Performing actions in web requests |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1927 ---------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1928 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1929 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
|
1930 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
|
1931 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
|
1932 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
|
1933 of: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1934 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1935 **login** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1936 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
|
1937 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1938 **logout** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1939 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
|
1940 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1941 **register** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1942 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
|
1943 log them in. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1944 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1945 **edit** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1946 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
|
1947 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
|
1948 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
|
1949 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
|
1950 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
|
1951 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1952 **new** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1953 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
|
1954 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
|
1955 ``__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
|
1956 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
|
1957 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
|
1958 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1959 **retire** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1960 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
|
1961 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1962 **editCSV** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1963 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
|
1964 *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
|
1965 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
|
1966 features. |
|
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 **search** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1969 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
|
1970 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1971 - 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
|
1972 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
|
1973 them to :filter. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1974 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1975 - 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
|
1976 user's query list. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1977 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1978 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
|
1979 "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
|
1980 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
|
1981 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
|
1982 web actions`_). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1983 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1984 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
|
1985 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
|
1986 for each action are: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1987 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1988 **login** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1989 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
|
1990 **logout** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1991 No permission checks are made. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1992 **register** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1993 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
|
1994 **edit** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1995 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
|
1996 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
|
1997 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
|
1998 special Permission "Web Roles". |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
1999 **new** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2000 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
|
2001 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
|
2002 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
|
2003 **editCSV** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2004 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
|
2005 **search** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2006 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
|
2007 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2008 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
|
2009 --------------------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2010 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2011 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
|
2012 (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
|
2013 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
|
2014 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
|
2015 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
|
2016 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
|
2017 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2018 * Referer, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2019 * Origin, and |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2020 * Host or |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2021 * X-Forwarded-Host |
|
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 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
|
2024 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
|
2025 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2026 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
|
2027 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
|
2028 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
|
2029 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
|
2030 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
|
2031 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
|
2032 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
|
2033 ``@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
|
2034 ``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
|
2035 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
|
2036 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2037 <input name="@csrf" type="hidden" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2038 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
|
2039 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2040 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
|
2041 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
|
2042 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
|
2043 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2044 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
|
2045 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
|
2046 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2047 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
|
2048 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
|
2049 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
|
2050 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2051 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
|
2052 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
|
2053 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
|
2054 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
|
2055 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2056 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
|
2057 that file for details. |
|
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 Special form variables |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2062 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
|
2063 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
|
2064 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2065 - 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
|
2066 - 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
|
2067 properties, |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2068 - 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
|
2069 current item. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2070 - 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
|
2071 - 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
|
2072 operation to be successful. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2073 - 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
|
2074 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
|
2075 created item. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2076 - Set up user interface locale. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2077 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2078 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
|
2079 ``@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
|
2080 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2081 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
|
2082 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
|
2083 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2084 .. index:: |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2085 single: i18n; set from web interface |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2086 single: internationalization; set from web interface |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2087 single: language; set from web interface |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2088 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2089 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
|
2090 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2091 ``@language`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2092 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
|
2093 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
|
2094 (if the appropriate translation is available). The value |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2095 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
|
2096 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
|
2097 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
|
2098 configuration or OS environment. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2099 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2100 ``@charset`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2101 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
|
2102 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
|
2103 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
|
2104 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
|
2105 (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
|
2106 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
|
2107 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
|
2108 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2109 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
|
2110 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2111 ``<propname>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2112 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
|
2113 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2114 ``<designator>"@"<propname>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2115 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
|
2116 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2117 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
|
2118 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2119 ``<classname><N>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2120 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
|
2121 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2122 ``<classname>"-"<N>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2123 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
|
2124 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
|
2125 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
|
2126 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
|
2127 item. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2128 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2129 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
|
2130 if it's special: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2131 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2132 ``@required`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2133 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
|
2134 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
|
2135 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
|
2136 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2137 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
|
2138 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
|
2139 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
|
2140 <designator>. |
|
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 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
|
2143 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
|
2144 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2145 ``@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
|
2146 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
|
2147 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
|
2148 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
|
2149 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
|
2150 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
|
2151 property. |
|
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 ``@link@<propname>=<designator>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2154 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
|
2155 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
|
2156 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
|
2157 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
|
2158 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
|
2159 form variable. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2160 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2161 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
|
2162 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
|
2163 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
|
2164 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2165 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
|
2166 single key (or id number) for 'klass', |
|
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2167 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
|
2168 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2169 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
|
2170 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
|
2171 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
|
2172 |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2173 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
|
2174 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
|
2175 have a key field. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2176 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2177 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
|
2178 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
|
2179 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
|
2180 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
|
2181 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
|
2182 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2183 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
|
2184 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
|
2185 appropriate value. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2186 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2187 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
|
2188 designator. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2189 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2190 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
|
2191 ``@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
|
2192 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
|
2193 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
|
2194 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
|
2195 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
|
2196 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
|
2197 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2198 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
|
2199 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2200 @note |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2201 This is equivalent to:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2202 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2203 @link@messages=msg-1 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2204 msg-1@content=value |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2205 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2206 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
|
2207 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2208 <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
|
2209 <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
|
2210 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2211 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
|
2212 "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
|
2213 time, respectively. |
|
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 @file |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2216 This is equivalent to:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2217 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2218 @link@files=file-1 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2219 file-1@content=value |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2220 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2221 by adding the HTML:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2222 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2223 <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
|
2224 <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
|
2225 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2226 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
|
2227 uploads. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2228 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2229 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
|
2230 specified, the action:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2231 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2232 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
|
2233 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2234 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
|
2235 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2236 <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
|
2237 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2238 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
|
2239 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
|
2240 returning. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2241 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2242 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2243 Default templates |
|
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 |
|
7456
cdb81976b8bc
Fix another xhtml reference.
John Rouillard <rouilj@ieee.org>
parents:
7378
diff
changeset
|
2246 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
|
2247 be phased out so leave the ``html_version`` configuration |
|
cdb81976b8bc
Fix another xhtml reference.
John Rouillard <rouilj@ieee.org>
parents:
7378
diff
changeset
|
2248 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
|
2249 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2250 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
|
2251 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
|
2252 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
|
2253 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2254 **page.html** |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2255 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
|
2256 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
|
2257 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
|
2258 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
|
2259 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
|
2260 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
|
2261 title. |
|
8028
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2262 |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2263 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
|
2264 |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2265 * 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
|
2266 * 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
|
2267 * 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
|
2268 * 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
|
2269 * 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
|
2270 a single item from a class |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2271 * 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
|
2272 search expression builder link |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2273 * 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
|
2274 the items in the dropdown |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2275 * 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
|
2276 popup link |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2277 * 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
|
2278 * 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
|
2279 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
|
2280 * 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
|
2281 * 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
|
2282 |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2283 and the user.item.html page: |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2284 |
|
14a10cc9b7b4
docs: list/describe macros defined in page.html
John Rouillard <rouilj@ieee.org>
parents:
7928
diff
changeset
|
2285 * 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
|
2286 * 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
|
2287 * 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
|
2288 * 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
|
2289 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
|
2290 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2291 **home.html** |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2292 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
|
2293 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
|
2294 **home.classlist.html** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2295 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
|
2296 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
|
2297 **classname.item.html** |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2298 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
|
2299 **classname.index.html** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2300 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
|
2301 **classname.search.html** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2302 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
|
2303 **_generic.index.html** |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2304 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
|
2305 ``*classname*.index`` available |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2306 **_generic.help.html** |
|
7858
376f70513242
doc(lint): address more vale complaints.
John Rouillard <rouilj@ieee.org>
parents:
7855
diff
changeset
|
2307 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
|
2308 ``*classname*.help`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2309 **user.register.html** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2310 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
|
2311 page |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2312 **style.css** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2313 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
|
2314 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2315 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
|
2316 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2317 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
|
2318 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
|
2319 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
|
2320 "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
|
2321 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
|
2322 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2323 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
|
2324 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2325 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
|
2326 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2327 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
|
2328 directory. So if you specify:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2329 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2330 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
|
2331 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2332 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
|
2333 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
|
2334 ``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
|
2335 it will return an error. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2336 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2337 Implementing Modal Editing Using @template |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2338 ------------------------------------------ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2339 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2340 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
|
2341 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
|
2342 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
|
2343 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2344 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
|
2345 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
|
2346 shift from display mode to edit mode. Submitting the changes |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2347 ends edit mode and the user returns to display |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2348 mode. |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2349 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2350 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
|
2351 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
|
2352 issue.item.html template that only displays information. Add an |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2353 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
|
2354 to the link. |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2355 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2356 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
|
2357 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
|
2358 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
|
2359 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
|
2360 rendered using the item template. If there is an error |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2361 (validation failed) the item will be rendered using the |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2362 ``item_edit`` template. The rendered ``item_edit`` template will |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2363 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
|
2364 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
|
2365 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
|
2366 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2367 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
|
2368 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
|
2369 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
|
2370 the edits again. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2371 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2372 In general, modal workflows are not implemented by the default |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2373 templates because they slow down the edit cycle. For some |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2374 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
|
2375 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
|
2376 form. It can result in a modal workflow of: |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2377 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2378 * search for issues to modify |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2379 * switch to edit mode and change values |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2380 * exit back to the results of the search |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2381 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2382 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2383 How the templates work |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2384 ---------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2385 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2386 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2387 Templating engines |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2388 ~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2389 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2390 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
|
2391 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2392 * 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
|
2393 * 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
|
2394 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
|
2395 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
|
2396 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
|
2397 ``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
|
2398 differences" section of `Chameleon documentation`__. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2399 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2400 Version 1.5.0 added support for the `jinja2`_ templating |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2401 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
|
2402 ``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
|
2403 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
|
2404 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
|
2405 Chameleon templating. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2406 |
|
8111
394f72021dad
docs: replace redirecting url's with target
John Rouillard <rouilj@ieee.org>
parents:
8099
diff
changeset
|
2407 .. _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
|
2408 |
|
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 **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
|
2411 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
|
2412 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
|
2413 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
|
2414 future release. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2415 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2416 **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
|
2417 recommended for production use. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2418 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2419 .. _Chameleon: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2420 https://pypi.org/project/Chameleon/ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2421 .. _z3c.pt: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2422 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
|
2423 __ 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
|
2424 .. _TAL: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2425 .. _Template Attribute Language: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2426 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
|
2427 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2428 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2429 Basic Templating Actions |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2430 ~~~~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2431 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2432 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
|
2433 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
|
2434 The basic TAL commands are: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2435 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2436 **tal:define="variable expression; variable expression; ..."** |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2437 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
|
2438 example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2439 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2440 <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
|
2441 <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
|
2442 </html> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2443 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2444 In this example, the variable "title" is defined by the |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2445 expression "request/description". The "tal:content" command |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2446 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
|
2447 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2448 **tal:condition="expression"** |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2449 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
|
2450 example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2451 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2452 <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
|
2453 Display some issue information. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2454 </p> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2455 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2456 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
|
2457 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
|
2458 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
|
2459 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
|
2460 other value is true, including non-zero numbers, and strings |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2461 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
|
2462 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2463 **tal:repeat="variable expression"** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2464 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
|
2465 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
|
2466 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
|
2467 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2468 <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
|
2469 <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
|
2470 <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
|
2471 <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
|
2472 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2473 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2474 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
|
2475 "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
|
2476 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
|
2477 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
|
2478 below on `the repeat variable`_. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2479 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2480 **tal:replace="expression"** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2481 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
|
2482 |
|
8383
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2483 <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
|
2484 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2485 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
|
2486 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
|
2487 "3". |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2488 |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2489 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
|
2490 ``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
|
2491 if you used:: |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2492 |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2493 <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
|
2494 |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2495 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
|
2496 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
|
2497 could include something like:: |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2498 |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2499 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
|
2500 |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2501 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
|
2502 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
|
2503 purposes. |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2504 |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2505 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
|
2506 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
|
2507 trusted HTML. |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2508 |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2509 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
|
2510 ``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
|
2511 |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2512 .. _`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
|
2513 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2514 **tal:content="expression"** |
|
8383
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2515 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
|
2516 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
|
2517 |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2518 <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
|
2519 </span> |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2520 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2521 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
|
2522 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
|
2523 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
|
2524 |
|
8383
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2525 ``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
|
2526 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
|
2527 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
|
2528 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
|
2529 |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2530 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
|
2531 evaulating: |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2532 |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2533 <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
|
2534 |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2535 results in ``Bruce``. |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2536 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2537 **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
|
2538 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
|
2539 example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2540 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2541 <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
|
2542 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2543 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
|
2544 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
|
2545 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
|
2546 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2547 **tal:omit-tag="expression"** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2548 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
|
2549 example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2550 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2551 <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
|
2552 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2553 would result in output of:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2554 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2555 Hello, world! |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2556 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2557 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
|
2558 *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
|
2559 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2560 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
|
2561 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
|
2562 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
|
2563 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
|
2564 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
|
2565 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
|
2566 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2567 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2568 Templating Expressions |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2569 ~~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2570 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2571 Templating Expressions are covered by `Template Attribute |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2572 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
|
2573 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
|
2574 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2575 **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
|
2576 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
|
2577 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
|
2578 ``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
|
2579 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
|
2580 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
|
2581 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
|
2582 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
|
2583 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
|
2584 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
|
2585 expression type for TAL. In Chameleon you must include the |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2586 ``path:`` prefix. |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2587 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2588 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
|
2589 operator in the expression to provide an alternative. The |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2590 expression ``request/form/foo/value | default`` would simply |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2591 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
|
2592 doesn't exist. |
|
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 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
|
2595 "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
|
2596 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
|
2597 case of ``tal:attributes``). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2598 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2599 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
|
2600 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
|
2601 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
|
2602 the case of ``tal:replace``). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2603 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2604 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
|
2605 ``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
|
2606 expressions. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2607 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2608 **String Expressions** - e.g. ``string:hello ${user/name}`` These |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2609 expressions are string interpolations - though they can be |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2610 just plain strings with no interpolation if you want. The |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2611 expression in the interpolation decorator ``${ ... }`` is a |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2612 path expression as above. |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2613 |
|
8383
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2614 .. _`python expression`: |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2615 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2616 **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
|
2617 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
|
2618 variables are available, so ``python:item.status.checklist()`` is |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2619 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
|
2620 ``checklist`` is a method. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2621 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2622 Modifiers: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2623 |
|
8383
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2624 .. _`structure modifier`: |
|
628794414f5f
doc: update doc on tal:replace and tal:content
John Rouillard <rouilj@ieee.org>
parents:
8354
diff
changeset
|
2625 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2626 **structure** - e.g. ``structure python:msg.content.plain(hyperlink=1)`` |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2627 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
|
2628 display (all "<", ">" and "&" are replaced with entities |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2629 (e.g. ``<``). The ``structure`` expression modifier turns |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2630 off this escaping - the result of the expression is now |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2631 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
|
2632 rendering. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2633 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2634 **not:** - eg. ``not:python:1=1`` |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2635 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
|
2636 expression. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2637 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2638 .. _TALES: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2639 .. _Template Attribute Language Expression Syntax: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2640 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
|
2641 |
|
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 Template Macros |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2644 ~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2645 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2646 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
|
2647 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
|
2648 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
|
2649 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2650 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
|
2651 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
|
2652 though, the attributes belong to the `Macro Expansion Template |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2653 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
|
2654 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2655 **metal:define-macro="macro name"** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2656 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
|
2657 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
|
2658 example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2659 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2660 <html metal:define-macro="page"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2661 ... |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2662 </html> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2663 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2664 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
|
2665 contents. Once defined, macros are stored in the ``macros`` |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2666 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
|
2667 them later on through the ``templates`` variable. Use the path |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2668 expression ``templates/page/macros/icing`` to access the |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2669 "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
|
2670 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2671 **metal:use-macro="path expression"** |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2672 Use a macro, identified by the path expression. This replaces |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2673 the current tag with the identified macro contents. For |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2674 example:: |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2675 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2676 <tal:block metal:use-macro="templates/page/macros/icing"> |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2677 ... |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2678 </tal:block> |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2679 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2680 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
|
2681 from the "page" template. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2682 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2683 **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
|
2684 To define *dynamic* parts of the macro, you define "slots" |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2685 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
|
2686 command. For example, the ``templates/page/macros/icing`` macro |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2687 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
|
2688 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2689 <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
|
2690 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2691 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
|
2692 like this:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2693 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2694 <tal:block metal:use-macro="templates/page/macros/icing"> |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2695 <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
|
2696 </tal:block> |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2697 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2698 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
|
2699 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
|
2700 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2701 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
|
2702 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
|
2703 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
|
2704 them). |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2705 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2706 .. _METAL: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2707 .. _Macro Expansion Template Attribute Language: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2708 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
|
2709 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2710 Information available to templates |
|
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 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2713 This is implemented by |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2714 ``roundup.cgi.templating.RoundupPageTemplate``. Documentation in |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2715 the installed file ``roundup/cgi/templating.py`` supplements this |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2716 documentation. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2717 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2718 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
|
2719 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2720 **context** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2721 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
|
2722 or a `hyperdb item wrapper`_ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2723 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2724 **request** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2725 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
|
2726 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2727 - the current index information (``filterspec``, ``filter`` |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2728 arguments, ``properties``, etc) parsed out of the form. |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2729 - 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
|
2730 - "form" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2731 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
|
2732 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
|
2733 - "env" the CGI environment variables |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2734 - "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
|
2735 - "user" a HTMLItem instance for the current user |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2736 - "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
|
2737 - "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
|
2738 - "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
|
2739 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
|
2740 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
|
2741 ``home.html`` template). |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2742 **config** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2743 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
|
2744 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
|
2745 **db** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2746 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
|
2747 **templates** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2748 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
|
2749 *use-macro* commands. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2750 **utils** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2751 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
|
2752 **nothing** |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2753 This is a special variable - if an expression evaluates to |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2754 this, then the tag (when used with ``tal:replace``), its |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2755 contents (in the case of ``tal:content``) or some attributes |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2756 (when used with ``tal:attributes``) will not appear in the |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2757 output. For example:: |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2758 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2759 <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
|
2760 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2761 would result in:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2762 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2763 <span>Hello, World!</span> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2764 **default** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2765 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
|
2766 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
|
2767 remain. So:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2768 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2769 <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
|
2770 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2771 would result in:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2772 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2773 <span>Hello, World!</span> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2774 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2775 and:: |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2776 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2777 <a href="foo" tal:attributes"href nope | default">H</a> |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2778 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2779 when ``nope`` is not defined results in:: |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2780 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2781 <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
|
2782 **true**, **false** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2783 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
|
2784 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
|
2785 **i18n** |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2786 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
|
2787 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2788 **gettext** (*message*) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2789 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
|
2790 **ngettext** (*singular*, *plural*, *number*) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2791 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
|
2792 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
|
2793 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
|
2794 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
|
2795 return plural otherwise. |
|
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 The context variable |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2798 ~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2799 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2800 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
|
2801 current context (see `determining web context`_ for how Roundup figures |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2802 this out). If Roundup is: |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2803 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2804 1. at a "home" page, then it's None |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2805 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
|
2806 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
|
2807 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2808 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
|
2809 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
|
2810 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2811 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
|
2812 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
|
2813 ``context/property/field``. |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2814 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
|
2815 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
|
2816 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
|
2817 "context/id". |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2818 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2819 Hyperdb class wrapper |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2822 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
|
2823 class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2824 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2825 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
|
2826 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
|
2827 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
|
2828 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
|
2829 mind. |
|
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 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
|
2832 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
|
2833 from the CGI form. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2834 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2835 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
|
2836 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2837 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2838 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2839 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2840 =========== ============================================================= |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2841 Method Description |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2842 =========== ============================================================= |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2843 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
|
2844 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
|
2845 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
|
2846 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
|
2847 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
|
2848 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
|
2849 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
|
2850 options are available for sorting: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2851 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2852 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
|
2853 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
|
2854 "filterspec" is ``{propname: value(s)}``. "sort" and |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2855 "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
|
2856 where dir is '+', '-' or None |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2857 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
|
2858 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2859 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
|
2860 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
|
2861 the form link.link.link.name. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2862 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2863 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
|
2864 the last week, sorted by activity date: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2865 ``issue.filter(filterspec={"priority": "1", |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2866 'messages.creation' : '.-1w;'}, sort=[('activity', '+')])`` |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2867 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2868 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
|
2869 special value '-1' searches for empty Link or Multilink |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2870 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
|
2871 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
|
2872 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2873 Both Link and Multilinks support a postfix |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2874 expression syntax using negative ID numbers (as |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2875 strings) as operators. Each |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2876 non-negative number (or '-1') is pushed on an |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2877 operand stack. A negative number pops the required |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2878 number of arguments from the stack, applies the |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2879 operator, and pushes the result. The following |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2880 operators are supported: |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2881 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2882 - '-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
|
2883 - '-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
|
2884 - '-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
|
2885 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2886 Note that this special handling of ID arguments is |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2887 applied only when a negative number smaller than -1 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2888 is encountered as an ID in the filter |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2889 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
|
2890 Examples of using Multilink expressions would be |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2891 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2892 - '1', '2', '-4', '3', '4', '-4', '-3' |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2893 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
|
2894 - '-1' '-2' would search for all non-empty Multilinks |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2895 - The URL fragment |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2896 ``filter=assignedto&assignedto=-1,-2`` |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2897 would find all issues that are assigned (where |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2898 the assignedto field is not empty). |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2899 |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2900 Note that 'NOT', (``-2``) is the only useful |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2901 operand for links. By default, a multi-value search |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2902 uses 'OR', so '-4' is redundant. Since a link only |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2903 has a single value, the 'AND' operand will return |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2904 an empty result. |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2905 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2906 filter_sql **Only in SQL backends** |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2907 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2908 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
|
2909 complete "select" statement. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2910 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2911 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
|
2912 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2913 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
|
2914 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
|
2915 retired nodes. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2916 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2917 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
|
2918 "help" template. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2919 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2920 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
|
2921 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
|
2922 "classname". The "properties" should be a comma-separated list |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2923 (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
|
2924 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
|
2925 activity). |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2926 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2927 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
|
2928 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
|
2929 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
|
2930 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2931 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
|
2932 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
|
2933 the format "<field>=<values>;<field>=<values>;...". |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2934 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2935 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
|
2936 |
|
7928
c05ea62b4c7a
fix: issue2551347 - make _generic.help.html work without property settings
John Rouillard <rouilj@ieee.org>
parents:
7920
diff
changeset
|
2937 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
|
2938 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
|
2939 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
|
2940 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
|
2941 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
|
2942 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
|
2943 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
|
2944 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
|
2945 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
|
2946 fixed these templates. |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2947 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2948 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
|
2949 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
|
2950 the "property" belongs to. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2951 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2952 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
|
2953 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
|
2954 history returns 'New node - no history' :) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2955 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
|
2956 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
|
2957 =========== ============================================================= |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2958 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2959 Note that 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
|
2960 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
|
2961 expression. For example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2962 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2963 python:context['list'] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2964 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2965 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
|
2966 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2967 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2968 Hyperdb item wrapper |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2969 :::::::::::::::::::: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2970 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2971 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
|
2972 class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2973 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2974 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
|
2975 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2976 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
|
2977 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
|
2978 from the CGI form. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2979 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
2980 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
|
2981 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2982 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2983 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2984 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2985 =============== ======================================================== |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2986 Method Description |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2987 =============== ======================================================== |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2988 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
|
2989 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
|
2990 implemented**) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2991 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
|
2992 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
|
2993 `design documentation`_) are not shown unless the |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
2994 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
|
2995 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
|
2996 shown. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2997 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
|
2998 for the query |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
2999 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
|
3000 user has a Permission. The signature is:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3001 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3002 hasPermission(self, permission, [classname=], |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3003 [property=], [itemid=]) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3004 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3005 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
|
3006 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
|
3007 user has a Role. The signature is:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3008 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3009 hasRole(self, rolename) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3010 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3011 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
|
3012 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
|
3013 is_retired is the item retired? |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3014 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
|
3015 item contents (ie. file<id>/<name>) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3016 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
|
3017 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
|
3018 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
|
3019 ``messages`` and ``files``. This can be overridden |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3020 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
|
3021 (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
|
3022 copied. Database-driven properties like ``id`` or |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3023 ``activity`` cannot be copied. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3024 =============== ======================================================== |
|
7352
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 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
|
3027 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
|
3028 expression. For example:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3029 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3030 python:context['journal'] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3031 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3032 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
|
3033 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3034 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3035 Hyperdb property wrapper |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3036 :::::::::::::::::::::::: |
|
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 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
|
3039 ``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
|
3040 ``HTMLNumberProperty``, and so on). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3041 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3042 This 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
|
3043 value may be either: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3044 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3045 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
|
3046 the hyperdb |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3047 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
|
3048 the CGI form |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3049 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3050 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3051 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
|
3052 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3053 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3054 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3055 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3056 =============== ======================================================== |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3057 Attribute Description |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3058 =============== ======================================================== |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3059 _name the name of the property |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3060 _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
|
3061 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
|
3062 =============== ======================================================== |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3063 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3064 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
|
3065 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3066 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3067 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3068 |
|
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 Method Description |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3071 =========== ================================================================ |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3072 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
|
3073 may take two arguments: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3074 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3075 escape |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3076 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
|
3077 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
|
3078 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
|
3079 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
|
3080 expressions are all equivalent:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3081 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3082 "structure python:msg.content.plain(escape=1)" |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3083 "python:msg.content.plain()" |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3084 "msg/content/plain" |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3085 "msg/content" |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3086 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3087 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
|
3088 complex expression. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3089 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3090 hyperlink |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3091 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
|
3092 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
|
3093 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
|
3094 want to use this ``tal:content`` expression:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3095 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3096 "structure python:msg.content.plain(hyperlink=1)" |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3097 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3098 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
|
3099 transformation done in the plain() method. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3100 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3101 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
|
3102 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3103 "structure msg/content/hyperlinked" |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3104 |
|
7864
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3105 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
|
3106 plain(), it takes ``escape`` and ``hyperlink`` |
|
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3107 arguments. However, the defaults are to enable both |
|
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3108 escape and hyperlinks. It also takes a ``columns`` |
|
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3109 argument set by default to 80. |
|
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3110 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3111 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
|
3112 most types this is a text entry box, but for |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3113 Booleans it is a |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3114 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
|
3115 arguments: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3116 |
|
8300
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3117 display_time (Date properties only) |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3118 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
|
3119 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
|
3120 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
|
3121 False for displaying only the date. |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3122 |
|
8301
3ba8078843db
Add "form" parameter for Date field method
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8300
diff
changeset
|
3123 form (Date properties only) |
|
3ba8078843db
Add "form" parameter for Date field method
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8300
diff
changeset
|
3124 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
|
3125 enclosing form name is different from "itemSynopsis", |
|
3ba8078843db
Add "form" parameter for Date field method
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8300
diff
changeset
|
3126 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
|
3127 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3128 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
|
3129 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
|
3130 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
|
3131 ``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
|
3132 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
|
3133 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
|
3134 ``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
|
3135 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
|
3136 date. |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
3137 |
|
8300
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3138 labelfirst (Boolean properties only) |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3139 place the labels before the radio buttons |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3140 |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3141 popcal (Date properties only) |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3142 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
|
3143 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
|
3144 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
|
3145 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
|
3146 browsers. |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3147 |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3148 size (default 30) |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3149 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
|
3150 |
|
8285
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
3151 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
|
3152 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
|
3153 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
|
3154 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
|
3155 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
|
3156 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
|
3157 be used). |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3158 |
|
7865
ee586ff074ed
doc: add documention for boolean field() arguments.
John Rouillard <rouilj@ieee.org>
parents:
7864
diff
changeset
|
3159 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
|
3160 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
|
3161 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
|
3162 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
|
3163 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
|
3164 |
|
8098
c6030fa9362e
docs: issue2550961 - required attribute incorrectly shown when using field()
John Rouillard <rouilj@ieee.org>
parents:
8028
diff
changeset
|
3165 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
|
3166 input tag. For example:: |
|
c6030fa9362e
docs: issue2550961 - required attribute incorrectly shown when using field()
John Rouillard <rouilj@ieee.org>
parents:
8028
diff
changeset
|
3167 |
|
c6030fa9362e
docs: issue2550961 - required attribute incorrectly shown when using field()
John Rouillard <rouilj@ieee.org>
parents:
8028
diff
changeset
|
3168 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
|
3169 |
|
c6030fa9362e
docs: issue2550961 - required attribute incorrectly shown when using field()
John Rouillard <rouilj@ieee.org>
parents:
8028
diff
changeset
|
3170 produces:: |
|
c6030fa9362e
docs: issue2550961 - required attribute incorrectly shown when using field()
John Rouillard <rouilj@ieee.org>
parents:
8028
diff
changeset
|
3171 |
|
c6030fa9362e
docs: issue2550961 - required attribute incorrectly shown when using field()
John Rouillard <rouilj@ieee.org>
parents:
8028
diff
changeset
|
3172 <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
|
3173 |
|
c6030fa9362e
docs: issue2550961 - required attribute incorrectly shown when using field()
John Rouillard <rouilj@ieee.org>
parents:
8028
diff
changeset
|
3174 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
|
3175 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
|
3176 properties like ``required``. |
|
c6030fa9362e
docs: issue2550961 - required attribute incorrectly shown when using field()
John Rouillard <rouilj@ieee.org>
parents:
8028
diff
changeset
|
3177 |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3178 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
|
3179 as ReStructuredText (requires the :ref:`Docutils |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3180 module to be installed separately<install/docutils>`). |
|
7864
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3181 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3182 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
|
3183 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
|
3184 installed separately) (deprecated, to be removed |
|
7862
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3185 use rst or markdown instead). |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3186 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
|
3187 as Markdown (requires a :ref:`Markdown module to be |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3188 installed separately<install/markdown>`). |
|
5cf8a7027595
doc: vale fixups; clarifications
John Rouillard <rouilj@ieee.org>
parents:
7861
diff
changeset
|
3189 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3190 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
|
3191 field for the property |
|
7864
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3192 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3193 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
|
3194 as an obscured email address |
|
7864
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3195 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3196 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
|
3197 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
|
3198 replaced with %20. |
|
7864
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3199 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3200 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
|
3201 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
|
3202 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
|
3203 "name:confirm". |
|
7864
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3204 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3205 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
|
3206 property |
|
7864
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3207 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3208 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
|
3209 and now |
|
7864
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3210 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3211 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
|
3212 with some timezone offset, for example:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3213 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3214 python:context.creation.local(10) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3215 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3216 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
|
3217 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3218 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
|
3219 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
|
3220 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3221 python:context.activity.pretty('%Y-%m-%d') |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3222 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3223 Will format as "2004-03-19" instead. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3224 |
|
7867
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3225 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
|
3226 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
|
3227 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
|
3228 ``strftime`` call (see the `Python Library |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3229 Reference: time module`__) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3230 |
|
7867
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3231 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
|
3232 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
|
3233 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
|
3234 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
|
3235 is converted to a string. |
|
7864
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3236 |
|
8300
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3237 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
|
3238 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
|
3239 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
|
3240 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
|
3241 |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
3242 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
|
3243 edit the date field, for example:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3244 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3245 <span tal:replace="structure context/due/popcal" /> |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3246 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3247 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
|
3248 typically you'd have:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3249 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3250 <span tal:replace="structure context/due/field" /> |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3251 <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
|
3252 |
|
b99e76e76496
Make native date and number elements configurable
Ralf Schlatterbeck <rsc@runtux.com>
parents:
8285
diff
changeset
|
3253 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
|
3254 calendar this use is deprecated. |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3255 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3256 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
|
3257 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
|
3258 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3259 size |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3260 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
|
3261 height |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3262 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
|
3263 showid |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3264 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
|
3265 additional |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3266 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
|
3267 sort_on |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3268 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
|
3269 (direction, property) where direction is '+' or '-'. A |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3270 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
|
3271 For example: ('-', 'order'), '+name'. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3272 value |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3273 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
|
3274 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3275 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
|
3276 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
|
3277 "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
|
3278 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3279 <span tal:replace="structure context/status/menu" /> |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3280 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3281 <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
|
3282 value='chatting', |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3283 filterspec={'status': '1,2,3,4'}" /> |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3284 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3285 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
|
3286 items sorted by some property, for example:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3287 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3288 python:context.files.sorted('creation') |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3289 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3290 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
|
3291 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3292 python:context.files.sorted('creation', reverse=True) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3293 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3294 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
|
3295 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
|
3296 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
|
3297 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
|
3298 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3299 python:context.files.sorted('creation', NoneFirst=True) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3300 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3301 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
|
3302 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
|
3303 ``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
|
3304 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
|
3305 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
|
3306 ``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
|
3307 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
|
3308 beginning. |
|
7864
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3309 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3310 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
|
3311 items in reverse order |
|
7864
b080cdb8b199
fix: document/fix wrapped HtmlProperty method.
John Rouillard <rouilj@ieee.org>
parents:
7862
diff
changeset
|
3312 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3313 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
|
3314 =========== ================================================================ |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3315 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3316 __ 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
|
3317 |
|
7867
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3318 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
|
3319 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
|
3320 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
|
3321 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3322 context/title/field |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3323 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3324 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
|
3325 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
|
3326 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
|
3327 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
|
3328 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
|
3329 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3330 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3331 The request variable |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3332 ~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3333 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3334 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
|
3335 class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3336 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3337 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
|
3338 request. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3339 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3340 .. 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
|
3341 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3342 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3343 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3344 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3345 =========== ============================================================ |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3346 Variable Holds |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3347 =========== ============================================================ |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3348 base the base URL for this tracker |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3349 classname the current classname (possibly None) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3350 env the CGI environment variables |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3351 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
|
3352 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
|
3353 user a HTMLUser instance for this user |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3354 =========== ============================================================ |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3355 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3356 **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
|
3357 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3358 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3359 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3360 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3361 =========== ============================================================ |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3362 Variable Holds |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3363 =========== ============================================================ |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3364 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
|
3365 filter properties to filter the index on |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3366 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
|
3367 ``priority=1`` or ``messages.author=42`` |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3368 group index grouping properties [(direction, column name)] |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3369 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
|
3370 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
|
3371 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
|
3372 sort index sort columns [(direction, column name)] |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3373 =========== ============================================================ |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3374 |
|
7867
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3375 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
|
3376 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3377 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3378 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3379 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3380 =============== ======================================================== |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3381 Method Description |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3382 =============== ======================================================== |
|
7867
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3383 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
|
3384 of the templating |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3385 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
|
3386 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
|
3387 `batching`_) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3388 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
|
3389 page title |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3390 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
|
3391 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
|
3392 |
|
74771afca2b6
doc: fix formatting for indexarg_url.
John Rouillard <rouilj@ieee.org>
parents:
7778
diff
changeset
|
3393 request.indexargs_url("url", {args}) |
|
74771afca2b6
doc: fix formatting for indexarg_url.
John Rouillard <rouilj@ieee.org>
parents:
7778
diff
changeset
|
3394 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3395 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
|
3396 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
|
3397 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
|
3398 Use this in templates to conditionally |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3399 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
|
3400 {..., '@queryname': request.dispname or None, ...} |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3401 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
|
3402 dispname otherwise the parameter will be omitted |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3403 from the url. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3404 =============== ======================================================== |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3405 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3406 The form variable |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3407 ::::::::::::::::: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3408 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3409 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
|
3410 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
|
3411 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
|
3412 "name", use the path expression:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3413 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3414 request/form/name/value |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3415 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3416 or the python expression:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3417 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3418 python:request.form['name'].value |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3419 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3420 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
|
3421 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
|
3422 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
|
3423 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
|
3424 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
|
3425 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
|
3426 dealing with. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3427 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3428 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3429 The db variable |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3430 ~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3431 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3432 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
|
3433 class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3434 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3435 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
|
3436 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
|
3437 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3438 db/user |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3439 python:db.user |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3440 |
|
7867
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3441 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
|
3442 ``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
|
3443 ``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
|
3444 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3445 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
|
3446 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3447 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3448 The templates variable |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3449 ~~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3450 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3451 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
|
3452 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
|
3453 template engine loader class. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3454 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3455 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
|
3456 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
|
3457 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
|
3458 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3459 templates/name |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3460 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3461 or the python expression:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3462 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3463 templates[name] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3464 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3465 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
|
3466 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
|
3467 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
|
3468 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3469 templates/name/macros/macro_name |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3470 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3471 or the python expression:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3472 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3473 templates[name].macros[macro_name] |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3474 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3475 The repeat variable |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3476 ~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3477 |
|
7867
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3478 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
|
3479 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
|
3480 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
|
3481 as either:: |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3482 |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3483 repeat/myusers |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3484 python:repeat['myusers'] |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3485 |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3486 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
|
3487 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3488 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3489 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3490 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3491 =============== ========================================================= |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3492 Method Description |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3493 =============== ========================================================= |
|
7867
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3494 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
|
3495 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
|
3496 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
|
3497 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
|
3498 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
|
3499 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
|
3500 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
|
3501 Letter Same as letter(), except uppercase. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3502 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
|
3503 numerals. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3504 Roman Same as roman(), except uppercase. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3505 =============== ========================================================= |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3506 |
|
7867
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3507 (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
|
3508 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
|
3509 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
|
3510 is 0.) |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3511 |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3512 It also has the following properties: |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3513 |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3514 .. table:: |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3515 :class: valign-top |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3516 |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3517 =============== ========================================================= |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3518 Properties Description |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3519 =============== ========================================================= |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3520 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
|
3521 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
|
3522 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
|
3523 =============== ========================================================= |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3524 |
|
7748
315f40fd0e67
doc: fix repeat section first -> start, last -> end
John Rouillard <rouilj@ieee.org>
parents:
7737
diff
changeset
|
3525 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
|
3526 last:: |
|
315f40fd0e67
doc: fix repeat section first -> start, last -> end
John Rouillard <rouilj@ieee.org>
parents:
7737
diff
changeset
|
3527 |
|
315f40fd0e67
doc: fix repeat section first -> start, last -> end
John Rouillard <rouilj@ieee.org>
parents:
7737
diff
changeset
|
3528 <span> |
|
315f40fd0e67
doc: fix repeat section first -> start, last -> end
John Rouillard <rouilj@ieee.org>
parents:
7737
diff
changeset
|
3529 <tal:x tal:repeat="field |
|
315f40fd0e67
doc: fix repeat section first -> start, last -> end
John Rouillard <rouilj@ieee.org>
parents:
7737
diff
changeset
|
3530 python:request.form['properties'].value.split(',')"> |
|
315f40fd0e67
doc: fix repeat section first -> start, last -> end
John Rouillard <rouilj@ieee.org>
parents:
7737
diff
changeset
|
3531 <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
|
3532 <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
|
3533 tal:content="string:,"></tal:x> |
|
315f40fd0e67
doc: fix repeat section first -> start, last -> end
John Rouillard <rouilj@ieee.org>
parents:
7737
diff
changeset
|
3534 </tal:x> |
|
315f40fd0e67
doc: fix repeat section first -> start, last -> end
John Rouillard <rouilj@ieee.org>
parents:
7737
diff
changeset
|
3535 </span> |
|
315f40fd0e67
doc: fix repeat section first -> start, last -> end
John Rouillard <rouilj@ieee.org>
parents:
7737
diff
changeset
|
3536 |
|
7867
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3537 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
|
3538 |
|
1774fdf2010a
doc: vale fixes, update TAL repeat object section.
John Rouillard <rouilj@ieee.org>
parents:
7865
diff
changeset
|
3539 <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
|
3540 |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3541 .. _templating utilities: |
|
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 The utils variable |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3544 ~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3545 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3546 This is implemented by the |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3547 ``roundup.cgi.templating.TemplatingUtils`` class. New methods can |
|
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3548 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
|
3549 |
|
8263
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3550 ----- |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3551 |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3552 .. list-table:: TemplatingUtils Methods |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3553 :align: left |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3554 :header-rows: 1 |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3555 :class: valign-top captionbelow booktabs |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3556 |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3557 * - Method |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3558 - Description |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3559 * - Batch |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3560 - 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
|
3561 * - anti_csrf_nonce |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3562 - 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
|
3563 * - :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
|
3564 - 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
|
3565 '%(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
|
3566 values from the supplied dictionary. |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3567 * - :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
|
3568 - 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
|
3569 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
|
3570 method |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3571 * - :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
|
3572 - 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
|
3573 * - :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
|
3574 - 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
|
3575 into the template. |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3576 * - :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
|
3577 - 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
|
3578 * - :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
|
3579 - quote some text as safe for a URL (ie. space, %, ...) |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3580 |
|
78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
John Rouillard <rouilj@ieee.org>
parents:
8262
diff
changeset
|
3581 ----- |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3582 |
|
7836
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3583 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
|
3584 ``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
|
3585 function like:: |
|
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3586 |
|
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3587 >>> from roundup.cgi.templating import TemplatingUtils |
|
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3588 >>> help(TemplatingUtils.readfile) |
|
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3589 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
|
3590 |
|
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3591 readfile(self, name, optional=False) |
|
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3592 Read an file in the template directory. |
|
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3593 |
|
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3594 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
|
3595 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
|
3596 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
|
3597 empty string. Useful inlining JavaScript kept in an |
|
219fc5804345
issue2551270 - Better templating support for JavaScript
John Rouillard <rouilj@ieee.org>
parents:
7807
diff
changeset
|
3598 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
|
3599 |
|
8099
98ad6d786bef
docs: fix typo extra backquote.
John Rouillard <rouilj@ieee.org>
parents:
8098
diff
changeset
|
3600 (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
|
3601 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3602 Batching |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3603 :::::::: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3604 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3605 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
|
3606 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
|
3607 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3608 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
|
3609 overlap=0) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3610 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3611 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
|
3612 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3613 request/batch |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3614 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3615 The parameters are: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3616 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3617 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3618 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3619 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3620 ========= ============================================================== |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3621 Parameter Usage |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3622 ========= ============================================================== |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3623 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
|
3624 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
|
3625 then it is combined with this batch |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3626 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
|
3627 sequence a list of HTMLItems |
|
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3628 size how big to make the sequence. |
|
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3629 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
|
3630 ========= ============================================================== |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3631 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3632 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
|
3633 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
|
3634 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3635 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3636 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3637 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3638 =============== ======================================================== |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3639 Attribute Description |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3640 =============== ======================================================== |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3641 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
|
3642 index* |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3643 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
|
3644 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
|
3645 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
|
3646 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
|
3647 =============== ======================================================== |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3648 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3649 And several methods: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3650 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3651 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3652 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3653 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3654 =============== ======================================================== |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3655 Method Description |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3656 =============== ======================================================== |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3657 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
|
3658 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
|
3659 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
|
3660 when compared to the last item |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3661 =============== ======================================================== |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3662 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3663 An example of batching:: |
|
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 <table class="otherinfo"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3666 <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
|
3667 <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
|
3668 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
|
3669 <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
|
3670 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
|
3671 keyword here</td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3672 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3673 </table> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3674 |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3675 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
|
3676 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
|
3677 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3678 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3679 Translations |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3680 ~~~~~~~~~~~~ |
|
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 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
|
3683 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
|
3684 ``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
|
3685 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
|
3686 create the locale files. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3687 |
|
7807
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3688 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
|
3689 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3690 |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3691 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
|
3692 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
|
3693 ``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
|
3694 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
|
3695 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
|
3696 ``application/json``. |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3697 |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3698 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
|
3699 calling:: |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3700 |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3701 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
|
3702 |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3703 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
|
3704 |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3705 <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
|
3706 '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
|
3707 )"/> |
|
6405bead6f47
doc: document how to set the Content-Type for a template.
John Rouillard <rouilj@ieee.org>
parents:
7784
diff
changeset
|
3708 |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3709 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
|
3710 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
|
3711 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
|
3712 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3713 Displaying Properties |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3714 --------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3715 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3716 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
|
3717 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
|
3718 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
|
3719 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
|
3720 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
|
3721 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3722 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3723 Index Views |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3724 ----------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3725 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3726 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
|
3727 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
|
3728 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3729 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3730 Index View Specifiers |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3731 ~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3732 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3733 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
|
3734 been added for clarity):: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3735 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3736 /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
|
3737 keyword=security,ui& |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3738 @group=priority,-status& |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3739 @sort=-activity& |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3740 @filters=status,keyword& |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3741 @columns=title,status,fixer |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3742 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3743 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
|
3744 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
|
3745 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
|
3746 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
|
3747 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
|
3748 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
|
3749 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
|
3750 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
|
3751 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
|
3752 the table. |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3753 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3754 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
|
3755 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
|
3756 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
|
3757 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3758 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
|
3759 "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
|
3760 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
|
3761 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
|
3762 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
|
3763 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
|
3764 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
|
3765 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
|
3766 properties. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3767 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3768 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3769 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3770 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3771 ============ ============================================================= |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3772 Argument Description |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3773 ============ ============================================================= |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3774 @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
|
3775 descending or nothing for ascending sorting. Several |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3776 properties can be specified delimited with comma. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3777 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
|
3778 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
|
3779 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
|
3780 sortdir0 specifies reverse order). |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3781 @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
|
3782 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
|
3783 properties can be specified delimited with comma. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3784 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
|
3785 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
|
3786 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
|
3787 groupdir0 specifies reverse order). |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3788 @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
|
3789 all. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3790 @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
|
3791 Default is none. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3792 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
|
3793 have (very basic search/filter). |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3794 @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
|
3795 issue titles, etc) |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3796 ============ ============================================================= |
|
7352
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3797 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3798 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3799 Searching Views |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3800 --------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3801 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3802 .. note:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3803 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
|
3804 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
|
3805 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
|
3806 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3807 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
|
3808 "*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
|
3809 ``@action`` variable. The "search" action: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3810 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3811 - 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
|
3812 searching |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3813 - sets the ``@filter`` variable correctly |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3814 - 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
|
3815 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3816 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
|
3817 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
|
3818 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
|
3819 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
|
3820 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
|
3821 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
|
3822 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
|
3823 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3824 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
|
3825 provide an additional argument: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3826 |
|
7778
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3827 .. table:: |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3828 :class: valign-top |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3829 |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3830 ============ ============================================================= |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3831 Argument Description |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3832 ============ ============================================================= |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3833 @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
|
3834 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
|
3835 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
|
3836 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
|
3837 does not. |
|
191a91f6a7c9
doc: make top of table columns align
John Rouillard <rouilj@ieee.org>
parents:
7748
diff
changeset
|
3838 ============ ============================================================= |
|
7352
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3841 Item Views |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3844 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
|
3845 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
|
3846 "history" section. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3847 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3848 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3849 Editor Section |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3850 ~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3851 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3852 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
|
3853 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
|
3854 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3855 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
|
3856 "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
|
3857 template):: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3858 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3859 <table class="form"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3860 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3861 <th>Title</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3862 <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
|
3863 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3864 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3865 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3866 <th>Priority</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3867 <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
|
3868 <th>Status</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3869 <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
|
3870 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3871 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3872 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3873 <th>Superseder</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3874 <td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3875 <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
|
3876 <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
|
3877 <span tal:condition="context/superseder"> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3878 <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
|
3879 </span> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3880 </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3881 <th>Nosy List</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3882 <td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3883 <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
|
3884 <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
|
3885 </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3886 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3887 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3888 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3889 <th>Assigned To</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3890 <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
|
3891 assignedto menu |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3892 </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3893 <td> </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3894 <td> </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3895 </tr> |
|
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 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3898 <th>Change Note</th> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3899 <td colspan="3"> |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3900 <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
|
3901 </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3902 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3903 |
|
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 <th>File</th> |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3906 <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
|
3907 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3908 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3909 <tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3910 <td> </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3911 <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
|
3912 submit button will go here |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3913 </td> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3914 </tr> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3915 </table> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3916 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3917 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3918 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
|
3919 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
|
3920 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
|
3921 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
|
3922 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3923 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3924 Form values |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3925 ::::::::::: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3926 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3927 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
|
3928 meet the various needs of: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3929 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3930 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
|
3931 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
|
3932 attached files) |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3933 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
|
3934 spent on an issue) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3935 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3936 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
|
3937 ":" 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
|
3938 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3939 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
|
3940 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3941 ``<propname>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3942 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
|
3943 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3944 ``<designator>:<propname>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3945 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
|
3946 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3947 ``<classname>-<N>:<propname>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3948 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
|
3949 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
|
3950 |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
3951 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
|
3952 the special form values: |
|
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 ``@required`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3955 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
|
3956 raised. |
|
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 ``@remove@<propname>=id(s)`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3959 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
|
3960 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3961 ``:add:<propname>=id(s)`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3962 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
|
3963 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3964 ``:link:<propname>=<designator>`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3965 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
|
3966 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
|
3967 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
|
3968 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
|
3969 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
|
3970 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
|
3971 <classname>-<N>). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3972 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3973 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
|
3974 designator. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3975 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3976 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
|
3977 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3978 ``:note`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3979 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
|
3980 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
|
3981 ``:file`` |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3982 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
|
3983 :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
|
3984 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3985 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3986 Spool Section |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3987 ~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3988 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3989 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
|
3990 of an issue. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3991 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3992 TODO |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3993 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3994 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3995 History Section |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3996 ~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3997 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
3998 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
|
3999 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
|
4000 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4001 <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
|
4002 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4003 or:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4004 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4005 <tal:block |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4006 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
|
4007 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4008 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
|
4009 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4010 *To be done:* |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4011 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4012 *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
|
4013 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
|
4014 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4015 <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
|
4016 a journal entry |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4017 </tal:block> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4018 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4019 *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
|
4020 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4021 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4022 Defining new web actions |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4023 ------------------------ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4024 |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
4025 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
|
4026 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
|
4027 using ``instance.registerAction``. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4028 |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
4029 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
|
4030 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4031 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
|
4032 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
|
4033 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
|
4034 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
|
4035 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4036 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
|
4037 issues |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4038 <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
|
4039 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4040 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4041 Define the new action class |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4044 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
|
4045 example ``myaction.py``:: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4046 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4047 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
|
4048 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4049 class MyAction(Action): |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4050 def handle(self): |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4051 ''' 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
|
4052 ''' |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4053 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4054 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
|
4055 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
|
4056 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
|
4057 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4058 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
|
4059 It may then: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4060 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4061 - 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
|
4062 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
|
4063 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
|
4064 - 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
|
4065 next |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4066 - 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
|
4067 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
|
4068 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4069 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4070 Register the action class |
|
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 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
|
4074 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
|
4075 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4076 def init(instance): |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4077 instance.registerAction('myaction', myActionClass) |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4078 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4079 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
|
4080 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4081 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4082 Use the new action |
|
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 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4085 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
|
4086 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4087 <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
|
4088 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4089 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
|
4090 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4091 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
|
4092 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4093 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4094 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
|
4095 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
|
4096 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
|
4097 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
|
4098 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
|
4099 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
|
4100 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
|
4101 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4102 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
|
4103 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4104 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
|
4105 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
|
4106 spreadsheet or database). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4107 |
|
8285
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
4108 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
|
4109 ------------------------- |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
4110 |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
4111 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
|
4112 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
|
4113 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
|
4114 |
|
2bf0c4e7795e
fix: issue2551390 - Replace text input/calendar popup with native date input
John Rouillard <rouilj@ieee.org>
parents:
8264
diff
changeset
|
4115 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
|
4116 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
|
4117 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
|
4118 |
|
7352
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 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
|
4121 -------------------------------------------- |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4122 |
|
7868
6c219034bf31
doc: vale corrections and some rewriting.
John Rouillard <rouilj@ieee.org>
parents:
7867
diff
changeset
|
4123 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
|
4124 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
|
4125 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
|
4126 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
|
4127 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4128 - 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
|
4129 - 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
|
4130 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4131 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
|
4132 ``kio8-r``). |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4133 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4134 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
|
4135 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
|
4136 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
|
4137 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
|
4138 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
|
4139 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
|
4140 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4141 <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
|
4142 <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
|
4143 {'@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
|
4144 <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
|
4145 {'@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
|
4146 </tal:block> |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4147 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4148 (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
|
4149 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
|
4150 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4151 ``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
|
4152 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
|
4153 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4154 <meta http-equiv="Content-Type" |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4155 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
|
4156 /> |
|
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 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
|
4159 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4160 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4161 Debugging Trackers |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4162 ================== |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4163 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4164 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
|
4165 Roundup: |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4166 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4167 1. web :: debug |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4168 2. mail :: debug |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4169 3. logging :: level |
|
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 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
|
4172 more information. |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4173 |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4174 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
|
4175 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
|
4176 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
|
4177 |
|
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 .. _`design documentation`: design.html |
|
f3c9ba5db30b
split reference out from customizing and fix all links.
John Rouillard <rouilj@ieee.org>
parents:
7280
diff
changeset
|
4180 .. _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
|
4181 .. _`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
|
4182 .. _`xmlrpc interface documentation`: xmlrpc.html#through-roundup |
|
7376
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
4183 |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
4184 .. allow line breaks in term definitions. |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
4185 .. |br| raw:: html |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
4186 |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
4187 <br/> |
|
18bae0b2e74e
Update permissions section
John Rouillard <rouilj@ieee.org>
parents:
7375
diff
changeset
|
4188 |