Mercurial > p > roundup > code

comparison doc/customizing.txt @ 7364:a1d0b505766e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updates - meta description; indent examples; rework headers Remove some left over description that applies to reference.html now. Indent a couple of examples to 2 spaces. Take headers for interfaces.py and move them under Example header (down one level). Also remove Example: prefix from the headers. Add links to reference document examples. Link to CustomizationExamples on wiki.
author John Rouillard <rouilj@ieee.org>
date Tue, 16 May 2023 19:42:52 -0400
parents 0cb4541bad71
children 82bbb95e5690 a072331c843b
comparison
equal deleted inserted replaced
7363:23abe048d1de 7364:a1d0b505766e
1 .. meta:: 1 .. meta::
2 :description: 2 :description:
3 How to customize and extend the Roundup Issue 3 How to customize and extend the Roundup Issue
4 Tracker. Includes many cookbook and how-to 4 Tracker. Includes many cookbook and how-to
5 examples. Reference for the design and internals 5 examples.
6 needed to understand and extend the examples to meet
7 new needs.
8 6
9 :tocdepth: 2 7 :tocdepth: 2
10 8
11 =================== 9 ===================
12 Customising Roundup 10 Customising Roundup
78 76
79 .. index:: schema; example changes 77 .. index:: schema; example changes
80 78
81 1. Modify the ``schema.py``:: 79 1. Modify the ``schema.py``::
82 80
83 issue = IssueClass(db, "issue", 81 issue = IssueClass(db, "issue",
84 assignedto=Link("user"), keyword=Multilink("keyword"), 82 assignedto=Link("user"), keyword=Multilink("keyword"),
85 priority=Link("priority"), status=Link("status"), 83 priority=Link("priority"), status=Link("status"),
86 due_date=Date()) 84 due_date=Date())
87 85
88 2. Add an edit field to the ``issue.item.html`` template:: 86 2. Add an edit field to the ``issue.item.html`` template::
89 87
90 <tr> 88 <tr>
91 <th>Due Date</th> 89 <th>Due Date</th>
92 <td tal:content="structure context/due_date/field" /> 90 <td tal:content="structure context/due_date/field" />
93 </tr> 91 </tr>
94 92
95 If you want to show only the date part of due_date then do this instead:: 93 If you want to show only the date part of due_date then do this instead::
96 94
97 <tr> 95 <tr>
98 <th>Due Date</th> 96 <th>Due Date</th>
2121 Note the difference in the value attribute for the two submit buttons. 2119 Note the difference in the value attribute for the two submit buttons.
2122 The value "silent_change" in the button specification must match the 2120 The value "silent_change" in the button specification must match the
2123 string in the nosy reaction function. 2121 string in the nosy reaction function.
2124 2122
2125 Changing How the Core Code Works 2123 Changing How the Core Code Works
2126 ================================ 2124 --------------------------------
2127 2125
2128 Example: Changing Cache-Control headers 2126 Changing Cache-Control Headers
2129 --------------------------------------- 2127 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2130 2128
2131 The Client class in cgi/client.py has a lookup table that is used to 2129 The Client class in cgi/client.py has a lookup table that is used to
2132 set the Cache-Control headers for static files. The entries in this 2130 set the Cache-Control headers for static files. The entries in this
2133 table are set from interfaces.py using:: 2131 table are set from interfaces.py using::
2134 2132
2150 * a file named local.js will be cached for 2 hours 2148 * a file named local.js will be cached for 2 hours
2151 2149
2152 Note that a file name match overrides the mime type settings. 2150 Note that a file name match overrides the mime type settings.
2153 2151
2154 2152
2155 Example: Implement password complexity checking 2153 Implement Password Complexity Checking
2156 ----------------------------------------------- 2154 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2157 2155
2158 .. index:: tracker; lib directory (example) 2156 .. index:: tracker; lib directory (example)
2159 2157
2160 This example uses the zxcvbn_ module that you can place in the zxcvbn 2158 This example uses the zxcvbn_ module that you can place in the zxcvbn
2161 subdirectory of your tracker's lib directory. 2159 subdirectory of your tracker's lib directory.
2188 2186
2189 it replaces the setPassword method in the Password class. The new 2187 it replaces the setPassword method in the Password class. The new
2190 version validates that the password is sufficiently complex. Then it 2188 version validates that the password is sufficiently complex. Then it
2191 passes off the setting of password to the original method. 2189 passes off the setting of password to the original method.
2192 2190
2193 Example: Enhance time intervals 2191 Enhance Time Intervals Forms
2194 ------------------------------- 2192 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2195 2193
2196 To make the user interface easier to use, you may want to support 2194 To make the user interface easier to use, you may want to support
2197 other forms for intervals. For example you can support an interval 2195 other forms for intervals. For example you can support an interval
2198 like 1.5 by interpreting it the same as 1:30 (1 hour 30 minutes). 2196 like 1.5 by interpreting it the same as 1:30 (1 hour 30 minutes).
2199 Also you can allow a bare integer (e.g. 45) as a number of minutes. 2197 Also you can allow a bare integer (e.g. 45) as a number of minutes.
2235 hyperdb.Interval.from_raw = normalizeperiod 2233 hyperdb.Interval.from_raw = normalizeperiod
2236 2234
2237 any call to convert an interval from raw form now has two simpler 2235 any call to convert an interval from raw form now has two simpler
2238 (and more friendly) ways to specify common time intervals. 2236 (and more friendly) ways to specify common time intervals.
2239 2237
2240 Example: Modifying the mail gateway 2238 Modifying the Mail Gateway
2241 ----------------------------------- 2239 ~~~~~~~~~~~~~~~~~~~~~~~~~~
2242 2240
2243 One site receives email on a main gateway. The virtual alias delivery 2241 One site receives email on a main gateway. The virtual alias delivery
2244 table on the postfix server is configured with:: 2242 table on the postfix server is configured with::
2245 2243
2246 test-issues@example.com roundup-test@roundup-vm.example.com 2244 test-issues@example.com roundup-test@roundup-vm.example.com
2362 This is the most complex example section. The mail gateway is also one 2360 This is the most complex example section. The mail gateway is also one
2363 of the more complex subsystems in Roundup, and modifying it is not 2361 of the more complex subsystems in Roundup, and modifying it is not
2364 trivial. 2362 trivial.
2365 2363
2366 Other Examples 2364 Other Examples
2367 -------------- 2365 ==============
2368 2366
2369 See the `rest interface documentation`_ for instructions on how to add 2367 See the `rest interface documentation`_ for instructions on how to add
2370 new rest endpoints or `change the rate limiting method`_ using interfaces.py. 2368 new rest endpoints or `change the rate limiting method`_ using interfaces.py.
2371 2369
2370 The `reference document`_ also has examples:
2371
2372 * `Extending the configuration file
2373 <reference.html#extending-the-configuration-file>`_.
2374 * `Adding a new Permission <reference.html#adding-a-new-permission>`_
2375
2372 Examples on the Wiki 2376 Examples on the Wiki
2373 ==================== 2377 ====================
2374 2378
2375 Even more examples of customization have been contributed by 2379 Even more examples of customization have been contributed by
2376 users. They can be found on the `wiki 2380 users. They can be found on the `wiki
2377 <https://wiki.roundup-tracker.org>`_. 2381 <https://wiki.roundup-tracker.org/CustomisationExamples>`_.
2378 2382
2379 .. _`design documentation`: design.html 2383 .. _`design documentation`: design.html
2380 .. _`developer's guide`: developers.html 2384 .. _`developer's guide`: developers.html
2381 .. _`rest interface documentation`: rest.html#programming-the-rest-api 2385 .. _`rest interface documentation`: rest.html#programming-the-rest-api
2382 .. _change the rate limiting method: rest.html#creating-custom-rate-limits 2386 .. _change the rate limiting method: rest.html#creating-custom-rate-limits
Roundup Issue Tracker: http://roundup-tracker.org/