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