1 :tocdepth: 2
3 ===================
4 Customising Roundup
5 ===================
7 .. This document borrows from the ZopeBook section on ZPT. The original is at:
8 http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
10 .. contents::
11 :depth: 1
13 What You Can Do
14 ===============
16 Before you get too far, it's probably worth having a quick read of the Roundup
17 `design documentation`_.
19 Customisation of Roundup can take one of six forms:
21 1. `tracker configuration`_ changes
22 2. database, or `tracker schema`_ changes
23 3. "definition" class `database content`_ changes
24 4. behavioural changes, through detectors_
25 5. `security / access controls`_
26 6. change the `web interface`_
28 The third case is special because it takes two distinctly different forms
29 depending upon whether the tracker has been initialised or not. The other two
30 may be done at any time, before or after tracker initialisation. Yes, this
31 includes adding or removing properties from classes.
34 Trackers in a Nutshell
35 ======================
37 Trackers have the following structure:
39 =================== ========================================================
40 Tracker File Description
41 =================== ========================================================
42 config.ini Holds the basic `tracker configuration`_
43 schema.py Holds the `tracker schema`_
44 initial_data.py Holds any data to be entered into the database when the
45 tracker is initialised.
46 db/ Holds the tracker's database
47 db/files/ Holds the tracker's upload files and messages
48 db/backend_name Names the database back-end for the tracker
49 detectors/ Auditors and reactors for this tracker
50 extensions/ Additional web actions and templating utilities.
51 html/ Web interface templates, images and style sheets
52 lib/ optional common imports for detectors and extensions
53 =================== ========================================================
56 Tracker Configuration
57 =====================
59 The ``config.ini`` located in your tracker home contains the basic
60 configuration for the web and e-mail components of roundup's interfaces.
62 Changes to the data captured by your tracker is controlled by the `tracker
63 schema`_. Some configuration is also performed using permissions - see the
64 `security / access controls`_ section. For example, to allow users to
65 automatically register through the email interface, you must grant the
66 "Anonymous" Role the "Email Access" Permission.
68 The following is taken from the `Python Library Reference`__ (May 20, 2004)
69 section "ConfigParser -- Configuration file parser":
71 The configuration file consists of sections, led by a "[section]" header
72 and followed by "name = value" entries, with line continuations on a
73 newline with leading whitespace. Note that leading whitespace is removed
74 from values. The optional values can contain format strings which
75 refer to other values in the same section. Lines beginning with "#" or ";"
76 are ignored and may be used to provide comments.
78 For example::
80 [My Section]
81 foodir = %(dir)s/whatever
82 dir = frob
84 would resolve the "%(dir)s" to the value of "dir" ("frob" in this case)
85 resulting in "foodir" being "frob/whatever".
87 __ http://docs.python.org/lib/module-ConfigParser.html
89 Section **main**
90 database -- ``db``
91 Database directory path. The path may be either absolute or relative
92 to the directory containig this config file.
94 templates -- ``html``
95 Path to the HTML templates directory. The path may be either absolute
96 or relative to the directory containig this config file.
98 static_files -- default *blank*
99 Path to directory holding additional static files available via Web
100 UI. This directory may contain sitewide images, CSS stylesheets etc.
101 and is searched for these files prior to the TEMPLATES directory
102 specified above. If this option is not set, all static files are
103 taken from the TEMPLATES directory The path may be either absolute or
104 relative to the directory containig this config file.
106 admin_email -- ``roundup-admin``
107 Email address that roundup will complain to if it runs into trouble. If
108 the email address doesn't contain an ``@`` part, the MAIL_DOMAIN defined
109 below is used.
111 dispatcher_email -- ``roundup-admin``
112 The 'dispatcher' is a role that can get notified of new items to the
113 database. It is used by the ERROR_MESSAGES_TO config setting. If the
114 email address doesn't contain an ``@`` part, the MAIL_DOMAIN defined
115 below is used.
117 email_from_tag -- default *blank*
118 Additional text to include in the "name" part of the From: address used
119 in nosy messages. If the sending user is "Foo Bar", the From: line
120 is usually: ``"Foo Bar" <issue_tracker@tracker.example>``
121 the EMAIL_FROM_TAG goes inside the "Foo Bar" quotes like so:
122 ``"Foo Bar EMAIL_FROM_TAG" <issue_tracker@tracker.example>``
124 new_web_user_roles -- ``User``
125 Roles that a user gets when they register with Web User Interface.
126 This is a comma-separated list of role names (e.g. ``Admin,User``).
128 new_email_user_roles -- ``User``
129 Roles that a user gets when they register with Email Gateway.
130 This is a comma-separated string of role names (e.g. ``Admin,User``).
132 error_messages_to -- ``user``
133 Send error message emails to the ``dispatcher``, ``user``, or ``both``?
134 The dispatcher is configured using the DISPATCHER_EMAIL setting.
135 Allowed values: ``dispatcher``, ``user``, or ``both``
137 html_version -- ``html4``
138 HTML version to generate. The templates are ``html4`` by default.
139 If you wish to make them xhtml, then you'll need to change this
140 var to ``xhtml`` too so all auto-generated HTML is compliant.
141 Allowed values: ``html4``, ``xhtml``
143 timezone -- ``0``
144 Numeric timezone offset used when users do not choose their own
145 in their settings.
147 instant_registration -- ``yes``
148 Register new users instantly, or require confirmation via
149 email?
150 Allowed values: ``yes``, ``no``
152 email_registration_confirmation -- ``yes``
153 Offer registration confirmation by email or only through the web?
154 Allowed values: ``yes``, ``no``
156 indexer_stopwords -- default *blank*
157 Additional stop-words for the full-text indexer specific to
158 your tracker. See the indexer source for the default list of
159 stop-words (e.g. ``A,AND,ARE,AS,AT,BE,BUT,BY, ...``).
161 umask -- ``02``
162 Defines the file creation mode mask.
164 Section **tracker**
165 name -- ``Roundup issue tracker``
166 A descriptive name for your roundup instance.
168 web -- ``http://host.example/demo/``
169 The web address that the tracker is viewable at.
170 This will be included in information sent to users of the tracker.
171 The URL MUST include the cgi-bin part or anything else
172 that is required to get to the home page of the tracker.
173 You MUST include a trailing '/' in the URL.
175 email -- ``issue_tracker``
176 Email address that mail to roundup should go to.
178 language -- default *blank*
179 Default locale name for this tracker. If this option is not set, the
180 language is determined by the environment variable LANGUAGE, LC_ALL,
181 LC_MESSAGES, or LANG, in that order of preference.
183 Section **web**
184 allow_html_file -- ``no``
185 Setting this option enables Roundup to serve uploaded HTML
186 file content *as HTML*. This is a potential security risk
187 and is therefore disabled by default. Set to 'yes' if you
188 trust *all* users uploading content to your tracker.
190 http_auth -- ``yes``
191 Whether to use HTTP Basic Authentication, if present.
192 Roundup will use either the REMOTE_USER or HTTP_AUTHORIZATION
193 variables supplied by your web server (in that order).
194 Set this option to 'no' if you do not wish to use HTTP Basic
195 Authentication in your web interface.
197 use_browser_language -- ``yes``
198 Whether to use HTTP Accept-Language, if present.
199 Browsers send a language-region preference list.
200 It's usually set in the client's browser or in their
201 Operating System.
202 Set this option to 'no' if you want to ignore it.
204 debug -- ``no``
205 Setting this option makes Roundup display error tracebacks
206 in the user's browser rather than emailing them to the
207 tracker admin."),
209 Section **rdbms**
210 Settings in this section are used by Postgresql and MySQL backends only
212 name -- ``roundup``
213 Name of the database to use.
215 host -- ``localhost``
216 Database server host.
218 port -- default *blank*
219 TCP port number of the database server. Postgresql usually resides on
220 port 5432 (if any), for MySQL default port number is 3306. Leave this
221 option empty to use backend default.
223 user -- ``roundup``
224 Database user name that Roundup should use.
226 password -- ``roundup``
227 Database user password.
229 read_default_file -- ``~/.my.cnf``
230 Name of the MySQL defaults file. Only used in MySQL connections.
232 read_default_group -- ``roundup``
233 Name of the group to use in the MySQL defaults file. Only used in
234 MySQL connections.
236 Section **logging**
237 config -- default *blank*
238 Path to configuration file for standard Python logging module. If this
239 option is set, logging configuration is loaded from specified file;
240 options 'filename' and 'level' in this section are ignored. The path may
241 be either absolute or relative to the directory containig this config file.
243 filename -- default *blank*
244 Log file name for minimal logging facility built into Roundup. If no file
245 name specified, log messages are written on stderr. If above 'config'
246 option is set, this option has no effect. The path may be either absolute
247 or relative to the directory containig this config file.
249 level -- ``ERROR``
250 Minimal severity level of messages written to log file. If above 'config'
251 option is set, this option has no effect.
252 Allowed values: ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``
254 Section **mail**
255 Outgoing email options. Used for nosy messages, password reset and
256 registration approval requests.
258 domain -- ``localhost``
259 Domain name used for email addresses.
261 host -- default *blank*
262 SMTP mail host that roundup will use to send mail
264 username -- default *blank*
265 SMTP login name. Set this if your mail host requires authenticated access.
266 If username is not empty, password (below) MUST be set!
268 password -- default *blank*
269 SMTP login password.
270 Set this if your mail host requires authenticated access.
272 port -- default *25*
273 SMTP port on mail host.
274 Set this if your mail host runs on a different port.
276 local_hostname -- default *blank*
277 The fully qualified domain name (FQDN) to use during SMTP sessions. If left
278 blank, the underlying SMTP library will attempt to detect your FQDN. If your
279 mail host requires something specific, specify the FQDN to use.
281 tls -- ``no``
282 If your SMTP mail host provides or requires TLS (Transport Layer Security)
283 then you may set this option to 'yes'.
284 Allowed values: ``yes``, ``no``
286 tls_keyfile -- default *blank*
287 If TLS is used, you may set this option to the name of a PEM formatted
288 file that contains your private key. The path may be either absolute or
289 relative to the directory containig this config file.
291 tls_certfile -- default *blank*
292 If TLS is used, you may set this option to the name of a PEM formatted
293 certificate chain file. The path may be either absolute or relative
294 to the directory containig this config file.
296 charset -- utf-8
297 Character set to encode email headers with. We use utf-8 by default, as
298 it's the most flexible. Some mail readers (eg. Eudora) can't cope with
299 that, so you might need to specify a more limited character set
300 (eg. iso-8859-1).
302 debug -- default *blank*
303 Setting this option makes Roundup to write all outgoing email messages
304 to this file *instead* of sending them. This option has the same effect
305 as environment variable SENDMAILDEBUG. Environment variable takes
306 precedence. The path may be either absolute or relative to the directory
307 containig this config file.
309 add_authorinfo -- ``yes``
310 Add a line with author information at top of all messages send by
311 roundup.
313 add_authoremail -- ``yes``
314 Add the mail address of the author to the author information at the
315 top of all messages. If this is false but add_authorinfo is true,
316 only the name of the actor is added which protects the mail address
317 of the actor from being exposed at mail archives, etc.
319 Section **mailgw**
320 Roundup Mail Gateway options
322 keep_quoted_text -- ``yes``
323 Keep email citations when accepting messages. Setting this to ``no`` strips
324 out "quoted" text from the message. Signatures are also stripped.
325 Allowed values: ``yes``, ``no``
327 leave_body_unchanged -- ``no``
328 Preserve the email body as is - that is, keep the citations *and*
329 signatures.
330 Allowed values: ``yes``, ``no``
332 default_class -- ``issue``
333 Default class to use in the mailgw if one isn't supplied in email subjects.
334 To disable, leave the value blank.
336 language -- default *blank*
337 Default locale name for the tracker mail gateway. If this option is
338 not set, mail gateway will use the language of the tracker instance.
340 subject_prefix_parsing -- ``strict``
341 Controls the parsing of the [prefix] on subject lines in incoming emails.
342 ``strict`` will return an error to the sender if the [prefix] is not
343 recognised. ``loose`` will attempt to parse the [prefix] but just
344 pass it through as part of the issue title if not recognised. ``none``
345 will always pass any [prefix] through as part of the issue title.
347 subject_suffix_parsing -- ``strict``
348 Controls the parsing of the [suffix] on subject lines in incoming emails.
349 ``strict`` will return an error to the sender if the [suffix] is not
350 recognised. ``loose`` will attempt to parse the [suffix] but just
351 pass it through as part of the issue title if not recognised. ``none``
352 will always pass any [suffix] through as part of the issue title.
354 subject_suffix_delimiters -- ``[]``
355 Defines the brackets used for delimiting the commands suffix in a subject
356 line.
358 subject_content_match -- ``always``
359 Controls matching of the incoming email subject line against issue titles
360 in the case where there is no designator [prefix]. ``never`` turns off
361 matching. ``creation + interval`` or ``activity + interval`` will match
362 an issue for the interval after the issue's creation or last activity.
363 The interval is a standard Roundup interval.
365 refwd_re -- ``(\s*\W?\s*(fw|fwd|re|aw|sv|ang)\W)+``
366 Regular expression matching a single reply or forward prefix
367 prepended by the mailer. This is explicitly stripped from the
368 subject during parsing. Value is Python Regular Expression
369 (UTF8-encoded).
371 origmsg_re -- `` ^[>|\s]*-----\s?Original Message\s?-----$``
372 Regular expression matching start of an original message if quoted
373 the in body. Value is Python Regular Expression (UTF8-encoded).
375 sign_re -- ``^[>|\s]*-- ?$``
376 Regular expression matching the start of a signature in the message
377 body. Value is Python Regular Expression (UTF8-encoded).
379 eol_re -- ``[\r\n]+``
380 Regular expression matching end of line. Value is Python Regular
381 Expression (UTF8-encoded).
383 blankline_re -- ``[\r\n]+\s*[\r\n]+``
384 Regular expression matching a blank line. Value is Python Regular
385 Expression (UTF8-encoded).
387 Section **pgp**
388 OpenPGP mail processing options
390 enable -- ``no``
391 Enable PGP processing. Requires pyme.
393 roles -- default *blank*
394 If specified, a comma-separated list of roles to perform PGP
395 processing on. If not specified, it happens for all users.
397 homedir -- default *blank*
398 Location of PGP directory. Defaults to $HOME/.gnupg if not
399 specified.
401 Section **nosy**
402 Nosy messages sending
404 messages_to_author -- ``no``
405 Send nosy messages to the author of the message.
406 Allowed values: ``yes``, ``no``, ``new``
408 signature_position -- ``bottom``
409 Where to place the email signature.
410 Allowed values: ``top``, ``bottom``, ``none``
412 add_author -- ``new``
413 Does the author of a message get placed on the nosy list automatically?
414 If ``new`` is used, then the author will only be added when a message
415 creates a new issue. If ``yes``, then the author will be added on
416 followups too. If ``no``, they're never added to the nosy.
417 Allowed values: ``yes``, ``no``, ``new``
419 add_recipients -- ``new``
420 Do the recipients (``To:``, ``Cc:``) of a message get placed on the nosy
421 list? If ``new`` is used, then the recipients will only be added when a
422 message creates a new issue. If ``yes``, then the recipients will be added
423 on followups too. If ``no``, they're never added to the nosy.
424 Allowed values: ``yes``, ``no``, ``new``
426 email_sending -- ``single``
427 Controls the email sending from the nosy reactor. If ``multiple`` then
428 a separate email is sent to each recipient. If ``single`` then a single
429 email is sent with each recipient as a CC address.
431 max_attachment_size -- ``2147483647``
432 Attachments larger than the given number of bytes won't be attached
433 to nosy mails. They will be replaced by a link to the tracker's
434 download page for the file.
437 You may generate a new default config file using the ``roundup-admin
438 genconfig`` command.
440 Configuration variables may be referred to in lower or upper case. In code,
441 variables not in the "main" section are referred to using their section and
442 name, so "domain" in the section "mail" becomes MAIL_DOMAIN. The
443 configuration variables available are:
445 Extending the configuration file
446 --------------------------------
448 You can't add new variables to the config.ini file in the tracker home but
449 you can add two new config.ini files:
451 - a config.ini in the ``extensions`` directory will be loaded and attached
452 to the config variable as "ext".
453 - a config.ini in the ``detectors`` directory will be loaded and attached
454 to the config variable as "detectors".
456 For example, the following in ``detectors/config.ini``::
458 [main]
459 qa_recipients = email@example.com
461 is accessible as::
463 db.config.detectors['QA_RECIPIENTS']
465 Note that the name grouping applied to the main configuration file is
466 applied to the extension config files, so if you instead have::
468 [qa]
469 recipients = email@example.com
471 then the above ``db.config.detectors['QA_RECIPIENTS']`` will still work.
474 Tracker Schema
475 ==============
477 .. note::
478 if you modify the schema, you'll most likely need to edit the
479 `web interface`_ HTML template files and `detectors`_ to reflect
480 your changes.
482 A tracker schema defines what data is stored in the tracker's database.
483 Schemas are defined using Python code in the ``schema.py`` module of your
484 tracker.
486 The ``schema.py`` module
487 ------------------------
489 The ``schema.py`` module contains two functions:
491 **open**
492 This function defines what your tracker looks like on the inside, the
493 **schema** of the tracker. It defines the **Classes** and **properties**
494 on each class. It also defines the **security** for those Classes. The
495 next few sections describe how schemas work and what you can do with
496 them.
497 **init**
498 This function is responsible for setting up the initial state of your
499 tracker. It's called exactly once - but the ``roundup-admin initialise``
500 command. See the start of the section on `database content`_ for more
501 info about how this works.
504 The "classic" schema
505 --------------------
507 The "classic" schema looks like this (see section `setkey(property)`_
508 below for the meaning of ``'setkey'`` -- you may also want to look into
509 the sections `setlabelprop(property)`_ and `setorderprop(property)`_ for
510 specifying (default) labelling and ordering of classes.)::
512 pri = Class(db, "priority", name=String(), order=String())
513 pri.setkey("name")
515 stat = Class(db, "status", name=String(), order=String())
516 stat.setkey("name")
518 keyword = Class(db, "keyword", name=String())
519 keyword.setkey("name")
521 user = Class(db, "user", username=String(), organisation=String(),
522 password=String(), address=String(), realname=String(),
523 phone=String(), alternate_addresses=String(),
524 queries=Multilink('query'), roles=String(), timezone=String())
525 user.setkey("username")
527 msg = FileClass(db, "msg", author=Link("user"), summary=String(),
528 date=Date(), recipients=Multilink("user"),
529 files=Multilink("file"), messageid=String(), inreplyto=String())
531 file = FileClass(db, "file", name=String())
533 issue = IssueClass(db, "issue", keyword=Multilink("keyword"),
534 status=Link("status"), assignedto=Link("user"),
535 priority=Link("priority"))
536 issue.setkey('title')
539 What you can't do to the schema
540 -------------------------------
542 You must never:
544 **Remove the users class**
545 This class is the only *required* class in Roundup.
547 **Remove the "username", "address", "password" or "realname" user properties**
548 Various parts of Roundup require these properties. Don't remove them.
550 **Change the type of a property**
551 Property types must *never* be changed - the database simply doesn't take
552 this kind of action into account. Note that you can't just remove a
553 property and re-add it as a new type either. If you wanted to make the
554 assignedto property a Multilink, you'd need to create a new property
555 assignedto_list and remove the old assignedto property.
558 What you can do to the schema
559 -----------------------------
561 Your schema may be changed at any time before or after the tracker has been
562 initialised (or used). You may:
564 **Add new properties to classes, or add whole new classes**
565 This is painless and easy to do - there are generally no repurcussions
566 from adding new information to a tracker's schema.
568 **Remove properties**
569 Removing properties is a little more tricky - you need to make sure that
570 the property is no longer used in the `web interface`_ *or* by the
571 detectors_.
575 Classes and Properties - creating a new information store
576 ---------------------------------------------------------
578 In the tracker above, we've defined 7 classes of information:
580 priority
581 Defines the possible levels of urgency for issues.
583 status
584 Defines the possible states of processing the issue may be in.
586 keyword
587 Initially empty, will hold keywords useful for searching issues.
589 user
590 Initially holding the "admin" user, will eventually have an entry
591 for all users using roundup.
593 msg
594 Initially empty, will hold all e-mail messages sent to or
595 generated by roundup.
597 file
598 Initially empty, will hold all files attached to issues.
600 issue
601 Initially empty, this is where the issue information is stored.
603 We define the "priority" and "status" classes to allow two things:
604 reduction in the amount of information stored on the issue and more
605 powerful, accurate searching of issues by priority and status. By only
606 requiring a link on the issue (which is stored as a single number) we
607 reduce the chance that someone mis-types a priority or status - or
608 simply makes a new one up.
611 Class and Items
612 ~~~~~~~~~~~~~~~
614 A Class defines a particular class (or type) of data that will be stored
615 in the database. A class comprises one or more properties, which gives
616 the information about the class items.
618 The actual data entered into the database, using ``class.create()``, are
619 called items. They have a special immutable property called ``'id'``. We
620 sometimes refer to this as the *itemid*.
623 Properties
624 ~~~~~~~~~~
626 A Class is comprised of one or more properties of the following types:
628 * String properties are for storing arbitrary-length strings.
629 * Password properties are for storing encoded arbitrary-length strings.
630 The default encoding is defined on the ``roundup.password.Password``
631 class.
632 * Date properties store date-and-time stamps. Their values are Timestamp
633 objects.
634 * Number properties store numeric values.
635 * Boolean properties store on/off, yes/no, true/false values.
636 * A Link property refers to a single other item selected from a
637 specified class. The class is part of the property; the value is an
638 integer, the id of the chosen item.
639 * A Multilink property refers to possibly many items in a specified
640 class. The value is a list of integers.
642 All Classes automatically have a number of properties by default:
644 *creator*
645 Link to the user that created the item.
646 *creation*
647 Date the item was created.
648 *actor*
649 Link to the user that last modified the item.
650 *activity*
651 Date the item was last modified.
654 FileClass
655 ~~~~~~~~~
657 FileClasses save their "content" attribute off in a separate file from
658 the rest of the database. This reduces the number of large entries in
659 the database, which generally makes databases more efficient, and also
660 allows us to use command-line tools to operate on the files. They are
661 stored in the files sub-directory of the ``'db'`` directory in your
662 tracker. FileClasses also have a "type" attribute to store the MIME
663 type of the file.
666 IssueClass
667 ~~~~~~~~~~
669 IssueClasses automatically include the "messages", "files", "nosy", and
670 "superseder" properties.
672 The messages and files properties list the links to the messages and
673 files related to the issue. The nosy property is a list of links to
674 users who wish to be informed of changes to the issue - they get "CC'ed"
675 e-mails when messages are sent to or generated by the issue. The nosy
676 reactor (in the ``'detectors'`` directory) handles this action. The
677 superseder link indicates an issue which has superseded this one.
679 They also have the dynamically generated "creation", "activity" and
680 "creator" properties.
682 The value of the "creation" property is the date when an item was
683 created, and the value of the "activity" property is the date when any
684 property on the item was last edited (equivalently, these are the dates
685 on the first and last records in the item's journal). The "creator"
686 property holds a link to the user that created the issue.
689 setkey(property)
690 ~~~~~~~~~~~~~~~~
692 Select a String property of the class to be the key property. The key
693 property must be unique, and allows references to the items in the class
694 by the content of the key property. That is, we can refer to users by
695 their username: for example, let's say that there's an issue in roundup,
696 issue 23. There's also a user, richard, who happens to be user 2. To
697 assign an issue to him, we could do either of::
699 roundup-admin set issue23 assignedto=2
701 or::
703 roundup-admin set issue23 assignedto=richard
705 Note, the same thing can be done in the web and e-mail interfaces.
707 setlabelprop(property)
708 ~~~~~~~~~~~~~~~~~~~~~~
710 Select a property of the class to be the label property. The label
711 property is used whereever an item should be uniquely identified, e.g.,
712 when displaying a link to an item. If setlabelprop is not specified for
713 a class, the following values are tried for the label:
715 * the key of the class (see the `setkey(property)`_ section above)
716 * the "name" property
717 * the "title" property
718 * the first property from the sorted property name list
720 So in most cases you can get away without specifying setlabelprop
721 explicitly.
723 setorderprop(property)
724 ~~~~~~~~~~~~~~~~~~~~~~
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
729 interface, the order property of class B is used for sorting. If
730 setorderprop is not specified for a class, the following values are tried
731 for the order property:
733 * the property named "order"
734 * the label property (see `setlabelprop(property)`_ above)
736 So in most cases you can get away without specifying setorderprop
737 explicitly.
739 create(information)
740 ~~~~~~~~~~~~~~~~~~~
742 Create an item in the database. This is generally used to create items
743 in the "definitional" classes like "priority" and "status".
746 A note about ordering
747 ~~~~~~~~~~~~~~~~~~~~~
749 When we sort items in the hyperdb, we use one of a number of methods,
750 depending on the properties being sorted on:
752 1. If it's a String, Number, Date or Interval property, we just sort the
753 scalar value of the property. Strings are sorted case-sensitively.
754 2. If it's a Link property, we sort by either the linked item's "order"
755 property (if it has one) or the linked item's "id".
756 3. Mulitlinks sort similar to #2, but we start with the first Multilink
757 list item, and if they're the same, we sort by the second item, and
758 so on.
760 Note that if an "order" property is defined on a Class that is used for
761 sorting, all items of that Class *must* have a value against the "order"
762 property, or sorting will result in random ordering.
765 Examples of adding to your schema
766 ---------------------------------
768 The Roundup wiki has examples of how schemas can be customised to add
769 new functionality.
772 Detectors - adding behaviour to your tracker
773 ============================================
774 .. _detectors:
776 Detectors are initialised every time you open your tracker database, so
777 you're free to add and remove them any time, even after the database is
778 initialised via the ``roundup-admin initialise`` command.
780 The detectors in your tracker fire *before* (**auditors**) and *after*
781 (**reactors**) changes to the contents of your database. They are Python
782 modules that sit in your tracker's ``detectors`` directory. You will
783 have some installed by default - have a look. You can write new
784 detectors or modify the existing ones. The existing detectors installed
785 for you are:
787 **nosyreaction.py**
788 This provides the automatic nosy list maintenance and email sending.
789 The nosy reactor (``nosyreaction``) fires when new messages are added
790 to issues. The nosy auditor (``updatenosy``) fires when issues are
791 changed, and figures out what changes need to be made to the nosy list
792 (such as adding new authors, etc.)
793 **statusauditor.py**
794 This provides the ``chatty`` auditor which changes the issue status
795 from ``unread`` or ``closed`` to ``chatting`` if new messages appear.
796 It also provides the ``presetunread`` auditor which pre-sets the
797 status to ``unread`` on new items if the status isn't explicitly
798 defined.
799 **messagesummary.py**
800 Generates the ``summary`` property for new messages based on the message
801 content.
802 **userauditor.py**
803 Verifies the content of some of the user fields (email addresses and
804 roles lists).
806 If you don't want this default behaviour, you're completely free to change
807 or remove these detectors.
809 See the detectors section in the `design document`__ for details of the
810 interface for detectors.
812 __ design.html
815 Detector API
816 ------------
818 Auditors are called with the arguments::
820 audit(db, cl, itemid, newdata)
822 where ``db`` is the database, ``cl`` is an instance of Class or
823 IssueClass within the database, and ``newdata`` is a dictionary mapping
824 property names to values.
826 For a ``create()`` operation, the ``itemid`` argument is None and
827 newdata contains all of the initial property values with which the item
828 is about to be created.
830 For a ``set()`` operation, newdata contains only the names and values of
831 properties that are about to be changed.
833 For a ``retire()`` or ``restore()`` operation, newdata is None.
835 Reactors are called with the arguments::
837 react(db, cl, itemid, olddata)
839 where ``db`` is the database, ``cl`` is an instance of Class or
840 IssueClass within the database, and ``olddata`` is a dictionary mapping
841 property names to values.
843 For a ``create()`` operation, the ``itemid`` argument is the id of the
844 newly-created item and ``olddata`` is None.
846 For a ``set()`` operation, ``olddata`` contains the names and previous
847 values of properties that were changed.
849 For a ``retire()`` or ``restore()`` operation, ``itemid`` is the id of
850 the retired or restored item and ``olddata`` is None.
853 Additional Detectors Ready For Use
854 ----------------------------------
856 Sample additional detectors that have been found useful will appear in
857 the ``'detectors'`` directory of the Roundup distribution. If you want
858 to use one, copy it to the ``'detectors'`` of your tracker instance:
860 **newissuecopy.py**
861 This detector sends an email to a team address whenever a new issue is
862 created. The address is hard-coded into the detector, so edit it
863 before you use it (look for the text 'team@team.host') or you'll get
864 email errors!
865 **creator_resolution.py**
866 Catch attempts to set the status to "resolved" - if the assignedto
867 user isn't the creator, then set the status to "confirm-done". Note that
868 "classic" Roundup doesn't have that status, so you'll have to add it. If
869 you don't want to though, it'll just use "in-progress" instead.
870 **email_auditor.py**
871 If a file added to an issue is of type message/rfc822, we tack on the
872 extension .eml.
873 The reason for this is that Microsoft Internet Explorer will not open
874 things with a .eml attachment, as they deem it 'unsafe'. Worse yet,
875 they'll just give you an incomprehensible error message. For more
876 information, see the detector code - it has a length explanation.
879 Auditor or Reactor?
880 -------------------
882 Generally speaking, the following rules should be observed:
884 **Auditors**
885 Are used for `vetoing creation of or changes to items`_. They might
886 also make automatic changes to item properties.
887 **Reactors**
888 Detect changes in the database and react accordingly. They should avoid
889 making changes to the database where possible, as this could create
890 detector loops.
893 Vetoing creation of or changes to items
894 ---------------------------------------
896 Auditors may raise the ``Reject`` exception to prevent the creation of
897 or changes to items in the database. The mail gateway, for example, will
898 not attach files or messages to issues when the creation of those files or
899 messages are prevented through the ``Reject`` exception. It'll also not create
900 users if that creation is ``Reject``'ed too.
902 To use, simply add at the top of your auditor::
904 from roundup.exceptions import Reject
906 And then when your rejection criteria have been detected, simply::
908 raise Reject
911 Generating email from Roundup
912 -----------------------------
914 The module ``roundup.mailer`` contains most of the nuts-n-bolts required
915 to generate email messages from Roundup.
917 In addition, the ``IssueClass`` methods ``nosymessage()`` and
918 ``send_message()`` are used to generate nosy messages, and may generate
919 messages which only consist of a change note (ie. the message id parameter
920 is not required - this is referred to as a "System Message" because it
921 comes from "the system" and not a user).
924 Database Content
925 ================
927 .. note::
928 If you modify the content of definitional classes, you'll most
929 likely need to edit the tracker `detectors`_ to reflect your changes.
931 Customisation of the special "definitional" classes (eg. status,
932 priority, resolution, ...) may be done either before or after the
933 tracker is initialised. The actual method of doing so is completely
934 different in each case though, so be careful to use the right one.
936 **Changing content before tracker initialisation**
937 Edit the initial_data.py module in your tracker to alter the items
938 created using the ``create( ... )`` methods.
940 **Changing content after tracker initialisation**
941 As the "admin" user, click on the "class list" link in the web
942 interface to bring up a list of all database classes. Click on the
943 name of the class you wish to change the content of.
945 You may also use the ``roundup-admin`` interface's create, set and
946 retire methods to add, alter or remove items from the classes in
947 question.
949 See "`adding a new field to the classic schema`_" for an example that
950 requires database content changes.
953 Security / Access Controls
954 ==========================
956 A set of Permissions is built into the security module by default:
958 - Create (everything)
959 - Edit (everything)
960 - View (everything)
961 - Register (User class only)
963 These are assigned to the "Admin" Role by default, and allow a user to do
964 anything. Every Class you define in your `tracker schema`_ also gets an
965 Create, Edit and View Permission of its own. The web and email interfaces
966 also define:
968 *Email Access*
969 If defined, the user may use the email interface. Used by default to deny
970 Anonymous users access to the email interface. When granted to the
971 Anonymous user, they will be automatically registered by the email
972 interface (see also the ``new_email_user_roles`` configuration option).
973 *Web Access*
974 If defined, the user may use the web interface. All users are able to see
975 the login form, regardless of this setting (thus enabling logging in).
976 *Web Roles*
977 Controls user access to editing the "roles" property of the "user" class.
978 TODO: deprecate in favour of a property-based control.
980 These are hooked into the default Roles:
982 - Admin (Create, Edit, View and everything; Web Roles)
983 - User (Web Access; Email Access)
984 - Anonymous (Web Access)
986 And finally, the "admin" user gets the "Admin" Role, and the "anonymous"
987 user gets "Anonymous" assigned when the tracker is installed.
989 For the "User" Role, the "classic" tracker defines:
991 - Create, Edit and View issue, file, msg, query, keyword
992 - View priority, status
993 - View user
994 - Edit their own user record
996 And the "Anonymous" Role is defined as:
998 - Web interface access
999 - Register user (for registration)
1000 - View issue, file, msg, query, keyword, priority, status
1002 Put together, these settings appear in the tracker's ``schema.py`` file::
1004 #
1005 # TRACKER SECURITY SETTINGS
1006 #
1007 # See the configuration and customisation document for information
1008 # about security setup.
1010 #
1011 # REGULAR USERS
1012 #
1013 # Give the regular users access to the web and email interface
1014 db.security.addPermissionToRole('User', 'Web Access')
1015 db.security.addPermissionToRole('User', 'Email Access')
1017 # Assign the access and edit Permissions for issue, file and message
1018 # to regular users now
1019 for cl in 'issue', 'file', 'msg', 'query', 'keyword':
1020 db.security.addPermissionToRole('User', 'View', cl)
1021 db.security.addPermissionToRole('User', 'Edit', cl)
1022 db.security.addPermissionToRole('User', 'Create', cl)
1023 for cl in 'priority', 'status':
1024 db.security.addPermissionToRole('User', 'View', cl)
1026 # May users view other user information? Comment these lines out
1027 # if you don't want them to
1028 db.security.addPermissionToRole('User', 'View', 'user')
1030 # Users should be able to edit their own details -- this permission
1031 # is limited to only the situation where the Viewed or Edited item
1032 # is their own.
1033 def own_record(db, userid, itemid):
1034 '''Determine whether the userid matches the item being accessed.'''
1035 return userid == itemid
1036 p = db.security.addPermission(name='View', klass='user', check=own_record,
1037 description="User is allowed to view their own user details")
1038 db.security.addPermissionToRole('User', p)
1039 p = db.security.addPermission(name='Edit', klass='user', check=own_record,
1040 description="User is allowed to edit their own user details")
1041 db.security.addPermissionToRole('User', p)
1043 #
1044 # ANONYMOUS USER PERMISSIONS
1045 #
1046 # Let anonymous users access the web interface. Note that almost all
1047 # trackers will need this Permission. The only situation where it's not
1048 # required is in a tracker that uses an HTTP Basic Authenticated front-end.
1049 db.security.addPermissionToRole('Anonymous', 'Web Access')
1051 # Let anonymous users access the email interface (note that this implies
1052 # that they will be registered automatically, hence they will need the
1053 # "Create" user Permission below)
1054 # This is disabled by default to stop spam from auto-registering users on
1055 # public trackers.
1056 #db.security.addPermissionToRole('Anonymous', 'Email Access')
1058 # Assign the appropriate permissions to the anonymous user's Anonymous
1059 # Role. Choices here are:
1060 # - Allow anonymous users to register
1061 db.security.addPermissionToRole('Anonymous', 'Create', 'user')
1063 # Allow anonymous users access to view issues (and the related, linked
1064 # information)
1065 for cl in 'issue', 'file', 'msg', 'keyword', 'priority', 'status':
1066 db.security.addPermissionToRole('Anonymous', 'View', cl)
1068 # [OPTIONAL]
1069 # Allow anonymous users access to create or edit "issue" items (and the
1070 # related file and message items)
1071 #for cl in 'issue', 'file', 'msg':
1072 # db.security.addPermissionToRole('Anonymous', 'Create', cl)
1073 # db.security.addPermissionToRole('Anonymous', 'Edit', cl)
1076 Automatic Permission Checks
1077 ---------------------------
1079 Permissions are automatically checked when information is rendered
1080 through the web. This includes:
1082 1. View checks for properties when being rendered via the ``plain()`` or
1083 similar methods. If the check fails, the text "[hidden]" will be
1084 displayed.
1085 2. Edit checks for properties when the edit field is being rendered via
1086 the ``field()`` or similar methods. If the check fails, the property
1087 will be rendered via the ``plain()`` method (see point 1. for subsequent
1088 checking performed)
1089 3. View checks are performed in index pages for each item being displayed
1090 such that if the user does not have permission, the row is not rendered.
1091 4. View checks are performed at the top of item pages for the Item being
1092 displayed. If the user does not have permission, the text "You are not
1093 allowed to view this page." will be displayed.
1094 5. View checks are performed at the top of index pages for the Class being
1095 displayed. If the user does not have permission, the text "You are not
1096 allowed to view this page." will be displayed.
1099 New User Roles
1100 --------------
1102 New users are assigned the Roles defined in the config file as:
1104 - NEW_WEB_USER_ROLES
1105 - NEW_EMAIL_USER_ROLES
1107 The `users may only edit their issues`_ example shows customisation of
1108 these parameters.
1111 Changing Access Controls
1112 ------------------------
1114 You may alter the configuration variables to change the Role that new
1115 web or email users get, for example to not give them access to the web
1116 interface if they register through email.
1118 You may use the ``roundup-admin`` "``security``" command to display the
1119 current Role and Permission configuration in your tracker.
1122 Adding a new Permission
1123 ~~~~~~~~~~~~~~~~~~~~~~~
1125 When adding a new Permission, you will need to:
1127 1. add it to your tracker's ``schema.py`` so it is created, using
1128 ``security.addPermission``, for example::
1130 self.security.addPermission(name="View", klass='frozzle',
1131 description="User is allowed to access frozzles")
1133 will set up a new "View" permission on the Class "frozzle".
1134 2. enable it for the Roles that should have it (verify with
1135 "``roundup-admin security``")
1136 3. add it to the relevant HTML interface templates
1137 4. add it to the appropriate xxxPermission methods on in your tracker
1138 interfaces module
1140 The ``addPermission`` method takes a couple of optional parameters:
1142 **properties**
1143 A sequence of property names that are the only properties to apply the
1144 new Permission to (eg. ``... klass='user', properties=('name',
1145 'email') ...``)
1146 **check**
1147 A function to be execute which returns boolean determining whether the
1148 Permission is allowed. The function has the signature ``check(db, userid,
1149 itemid)`` where ``db`` is a handle on the open database, ``userid`` is
1150 the user attempting access and ``itemid`` is the specific item being
1151 accessed.
1153 Example Scenarios
1154 ~~~~~~~~~~~~~~~~~
1156 See the `examples`_ section for longer examples of customisation.
1158 **anonymous access through the e-mail gateway**
1159 Give the "anonymous" user the "Email Access", ("Edit", "issue") and
1160 ("Create", "msg") Permissions but do not not give them the ("Create",
1161 "user") Permission. This means that when an unknown user sends email
1162 into the tracker, they're automatically logged in as "anonymous".
1163 Since they don't have the ("Create", "user") Permission, they won't
1164 be automatically registered, but since "anonymous" has permission to
1165 use the gateway, they'll still be able to submit issues. Note that
1166 the Sender information - their email address - will not be available
1167 - they're *anonymous*.
1169 **automatic registration of users in the e-mail gateway**
1170 By giving the "anonymous" user the ("Register", "user") Permission, any
1171 unidentified user will automatically be registered with the tracker
1172 (with no password, so they won't be able to log in through
1173 the web until an admin sets their password). By default new Roundup
1174 trackers don't allow this as it opens them up to spam. It may be enabled
1175 by uncommenting the appropriate addPermissionToRole in your tracker's
1176 ``schema.py`` file. The new user is given the Roles list defined in the
1177 "new_email_user_roles" config variable.
1179 **only developers may be assigned issues**
1180 Create a new Permission called "Fixer" for the "issue" class. Create a
1181 new Role "Developer" which has that Permission, and assign that to the
1182 appropriate users. Filter the list of users available in the assignedto
1183 list to include only those users. Enforce the Permission with an
1184 auditor. See the example
1185 `restricting the list of users that are assignable to a task`_.
1187 **only managers may sign off issues as complete**
1188 Create a new Permission called "Closer" for the "issue" class. Create a
1189 new Role "Manager" which has that Permission, and assign that to the
1190 appropriate users. In your web interface, only display the "resolved"
1191 issue state option when the user has the "Closer" Permissions. Enforce
1192 the Permission with an auditor. This is very similar to the previous
1193 example, except that the web interface check would look like::
1195 <option tal:condition="python:request.user.hasPermission('Closer')"
1196 value="resolved">Resolved</option>
1198 **don't give web access to users who register through email**
1199 Create a new Role called "Email User" which has all the Permissions of
1200 the normal "User" Role minus the "Web Access" Permission. This will
1201 allow users to send in emails to the tracker, but not access the web
1202 interface.
1204 **let some users edit the details of all users**
1205 Create a new Role called "User Admin" which has the Permission for
1206 editing users::
1208 db.security.addRole(name='User Admin', description='Managing users')
1209 p = db.security.getPermission('Edit', 'user')
1210 db.security.addPermissionToRole('User Admin', p)
1212 and assign the Role to the users who need the permission.
1215 Web Interface
1216 =============
1218 .. contents::
1219 :local:
1221 The web interface is provided by the ``roundup.cgi.client`` module and
1222 is used by ``roundup.cgi``, ``roundup-server`` and ``ZRoundup``
1223 (``ZRoundup`` is broken, until further notice). In all cases, we
1224 determine which tracker is being accessed (the first part of the URL
1225 path inside the scope of the CGI handler) and pass control on to the
1226 ``roundup.cgi.client.Client`` class - which handles the rest of the
1227 access through its ``main()`` method. This means that you can do pretty
1228 much anything you want as a web interface to your tracker.
1232 Repercussions of changing the tracker schema
1233 ---------------------------------------------
1235 If you choose to change the `tracker schema`_ you will need to ensure
1236 the web interface knows about it:
1238 1. Index, item and search pages for the relevant classes may need to
1239 have properties added or removed,
1240 2. The "page" template may require links to be changed, as might the
1241 "home" page's content arguments.
1244 How requests are processed
1245 --------------------------
1247 The basic processing of a web request proceeds as follows:
1249 1. figure out who we are, defaulting to the "anonymous" user
1250 2. figure out what the request is for - we call this the "context"
1251 3. handle any requested action (item edit, search, ...)
1252 4. render the template requested by the context, resulting in HTML
1253 output
1255 In some situations, exceptions occur:
1257 - HTTP Redirect (generally raised by an action)
1258 - SendFile (generally raised by ``determine_context``)
1259 here we serve up a FileClass "content" property
1260 - SendStaticFile (generally raised by ``determine_context``)
1261 here we serve up a file from the tracker "html" directory
1262 - Unauthorised (generally raised by an action)
1263 here the action is cancelled, the request is rendered and an error
1264 message is displayed indicating that permission was not granted for
1265 the action to take place
1266 - NotFound (raised wherever it needs to be)
1267 this exception percolates up to the CGI interface that called the
1268 client
1271 Determining web context
1272 -----------------------
1274 To determine the "context" of a request, we look at the URL and the
1275 special request variable ``@template``. The URL path after the tracker
1276 identifier is examined. Typical URL paths look like:
1278 1. ``/tracker/issue``
1279 2. ``/tracker/issue1``
1280 3. ``/tracker/@@file/style.css``
1281 4. ``/cgi-bin/roundup.cgi/tracker/file1``
1282 5. ``/cgi-bin/roundup.cgi/tracker/file1/kitten.png``
1284 where the "tracker identifier" is "tracker" in the above cases. That means
1285 we're looking at "issue", "issue1", "@@file/style.css", "file1" and
1286 "file1/kitten.png" in the cases above. The path is generally only one
1287 entry long - longer paths are handled differently.
1289 a. if there is no path, then we are in the "home" context. See `the "home"
1290 context`_ below for more information about how it may be used.
1291 b. if the path starts with "@@file" (as in example 3,
1292 "/tracker/@@file/style.css"), then the additional path entry,
1293 "style.css" specifies the filename of a static file we're to serve up
1294 from the tracker TEMPLATES (or STATIC_FILES, if configured) directory.
1295 This is usually the tracker's "html" directory. Raises a SendStaticFile
1296 exception.
1297 c. if there is something in the path (as in example 1, "issue"), it
1298 identifies the tracker class we're to display.
1299 d. if the path is an item designator (as in examples 2 and 4, "issue1"
1300 and "file1"), then we're to display a specific item.
1301 e. if the path starts with an item designator and is longer than one
1302 entry (as in example 5, "file1/kitten.png"), then we're assumed to be
1303 handling an item of a ``FileClass``, and the extra path information
1304 gives the filename that the client is going to label the download
1305 with (i.e. "file1/kitten.png" is nicer to download than "file1").
1306 This raises a ``SendFile`` exception.
1308 Both b. and e. stop before we bother to determine the template we're
1309 going to use. That's because they don't actually use templates.
1311 The template used is specified by the ``@template`` CGI variable, which
1312 defaults to:
1314 - only classname suplied: "index"
1315 - full item designator supplied: "item"
1318 The "home" Context
1319 ------------------
1321 The "home" context is special because it allows you to add templated
1322 pages to your tracker that don't rely on a class or item (ie. an issues
1323 list or specific issue).
1325 Let's say you wish to add frames to control the layout of your tracker's
1326 interface. You'd probably have:
1328 - A top-level frameset page. This page probably wouldn't be templated, so
1329 it could be served as a static file (see `serving static content`_)
1330 - A sidebar frame that is templated. Let's call this page
1331 "home.navigation.html" in your tracker's "html" directory. To load that
1332 page up, you use the URL:
1334 <tracker url>/home?@template=navigation
1337 Serving static content
1338 ----------------------
1340 See the previous section `determining web context`_ where it describes
1341 ``@@file`` paths.
1344 Performing actions in web requests
1345 ----------------------------------
1347 When a user requests a web page, they may optionally also request for an
1348 action to take place. As described in `how requests are processed`_, the
1349 action is performed before the requested page is generated. Actions are
1350 triggered by using a ``@action`` CGI variable, where the value is one
1351 of:
1353 **login**
1354 Attempt to log a user in.
1356 **logout**
1357 Log the user out - make them "anonymous".
1359 **register**
1360 Attempt to create a new user based on the contents of the form and then
1361 log them in.
1363 **edit**
1364 Perform an edit of an item in the database. There are some `special form
1365 variables`_ you may use.
1367 **new**
1368 Add a new item to the database. You may use the same `special form
1369 variables`_ as in the "edit" action.
1371 **retire**
1372 Retire the item in the database.
1374 **editCSV**
1375 Performs an edit of all of a class' items in one go. See also the
1376 *class*.csv templating method which generates the CSV data to be
1377 edited, and the ``'_generic.index'`` template which uses both of these
1378 features.
1380 **search**
1381 Mangle some of the form variables:
1383 - Set the form ":filter" variable based on the values of the filter
1384 variables - if they're set to anything other than "dontcare" then add
1385 them to :filter.
1387 - Also handle the ":queryname" variable and save off the query to the
1388 user's query list.
1390 Each of the actions is implemented by a corresponding ``*XxxAction*`` (where
1391 "Xxx" is the name of the action) class in the ``roundup.cgi.actions`` module.
1392 These classes are registered with ``roundup.cgi.client.Client``. If you need
1393 to define new actions, you may add them there (see `defining new
1394 web actions`_).
1396 Each action class also has a ``*permission*`` method which determines whether
1397 the action is permissible given the current user. The base permission checks
1398 for each action are:
1400 **login**
1401 Determine whether the user has the "Web Access" Permission.
1402 **logout**
1403 No permission checks are made.
1404 **register**
1405 Determine whether the user has the ("Create", "user") Permission.
1406 **edit**
1407 Determine whether the user has permission to edit this item. If we're
1408 editing the "user" class, users are allowed to edit their own details -
1409 unless they try to edit the "roles" property, which requires the
1410 special Permission "Web Roles".
1411 **new**
1412 Determine whether the user has permission to create this item. No
1413 additional property checks are made. Additionally, new user items may
1414 be created if the user has the ("Create", "user") Permission.
1415 **editCSV**
1416 Determine whether the user has permission to edit this class.
1417 **search**
1418 Determine whether the user has permission to view this class.
1421 Special form variables
1422 ----------------------
1424 Item properties and their values are edited with html FORM
1425 variables and their values. You can:
1427 - Change the value of some property of the current item.
1428 - Create a new item of any class, and edit the new item's
1429 properties,
1430 - Attach newly created items to a multilink property of the
1431 current item.
1432 - Remove items from a multilink property of the current item.
1433 - Specify that some properties are required for the edit
1434 operation to be successful.
1435 - Set up user interface locale.
1437 These operations will only take place if the form action (the
1438 ``@action`` variable) is "edit" or "new".
1440 In the following, <bracketed> values are variable, "@" may be
1441 either ":" or "@", and other text "required" is fixed.
1443 Two special form variables are used to specify user language preferences:
1445 ``@language``
1446 value may be locale name or ``none``. If this variable is set to
1447 locale name, web interface language is changed to given value
1448 (provided that appropriate translation is available), the value
1449 is stored in the browser cookie and will be used for all following
1450 requests. If value is ``none`` the cookie is removed and the
1451 language is changed to the tracker default, set up in the tracker
1452 configuration or OS environment.
1454 ``@charset``
1455 value may be character set name or ``none``. Character set name
1456 is stored in the browser cookie and sets output encoding for all
1457 HTML pages generated by Roundup. If value is ``none`` the cookie
1458 is removed and HTML output is reset to Roundup internal encoding
1459 (UTF-8).
1461 Most properties are specified as form variables:
1463 ``<propname>``
1464 property on the current context item
1466 ``<designator>"@"<propname>``
1467 property on the indicated item (for editing related information)
1469 Designators name a specific item of a class.
1471 ``<classname><N>``
1472 Name an existing item of class <classname>.
1474 ``<classname>"-"<N>``
1475 Name the <N>th new item of class <classname>. If the form
1476 submission is successful, a new item of <classname> is
1477 created. Within the submitted form, a particular
1478 designator of this form always refers to the same new
1479 item.
1481 Once we have determined the "propname", we look at it to see
1482 if it's special:
1484 ``@required``
1485 The associated form value is a comma-separated list of
1486 property names that must be specified when the form is
1487 submitted for the edit operation to succeed.
1489 When the <designator> is missing, the properties are
1490 for the current context item. When <designator> is
1491 present, they are for the item specified by
1492 <designator>.
1494 The "@required" specifier must come before any of the
1495 properties it refers to are assigned in the form.
1497 ``@remove@<propname>=id(s)`` or ``@add@<propname>=id(s)``
1498 The "@add@" and "@remove@" edit actions apply only to
1499 Multilink properties. The form value must be a
1500 comma-separate list of keys for the class specified by
1501 the simple form variable. The listed items are added
1502 to (respectively, removed from) the specified
1503 property.
1505 ``@link@<propname>=<designator>``
1506 If the edit action is "@link@", the simple form
1507 variable must specify a Link or Multilink property.
1508 The form value is a comma-separated list of
1509 designators. The item corresponding to each
1510 designator is linked to the property given by simple
1511 form variable.
1513 None of the above (ie. just a simple form value)
1514 The value of the form variable is converted
1515 appropriately, depending on the type of the property.
1517 For a Link('klass') property, the form value is a
1518 single key for 'klass', where the key field is
1519 specified in schema.py.
1521 For a Multilink('klass') property, the form value is a
1522 comma-separated list of keys for 'klass', where the
1523 key field is specified in schema.py.
1525 Note that for simple-form-variables specifiying Link
1526 and Multilink properties, the linked-to class must
1527 have a key field.
1529 For a String() property specifying a filename, the
1530 file named by the form value is uploaded. This means we
1531 try to set additional properties "filename" and "type" (if
1532 they are valid for the class). Otherwise, the property
1533 is set to the form value.
1535 For Date(), Interval(), Boolean(), and Number()
1536 properties, the form value is converted to the
1537 appropriate
1539 Any of the form variables may be prefixed with a classname or
1540 designator.
1542 Two special form values are supported for backwards compatibility:
1544 @note
1545 This is equivalent to::
1547 @link@messages=msg-1
1548 msg-1@content=value
1550 except that in addition, the "author" and "date" properties of
1551 "msg-1" are set to the userid of the submitter, and the current
1552 time, respectively.
1554 @file
1555 This is equivalent to::
1557 @link@files=file-1
1558 file-1@content=value
1560 The String content value is handled as described above for file
1561 uploads.
1563 If both the "@note" and "@file" form variables are
1564 specified, the action::
1566 @link@msg-1@files=file-1
1568 is also performed.
1570 We also check that FileClass items have a "content" property with
1571 actual content, otherwise we remove them from all_props before
1572 returning.
1575 Default templates
1576 -----------------
1578 The default templates are html4 compliant. If you wish to change them to be
1579 xhtml compliant, you'll need to change the ``html_version`` configuration
1580 variable in ``config.ini`` to ``'xhtml'`` instead of ``'html4'``.
1582 Most customisation of the web view can be done by modifying the
1583 templates in the tracker ``'html'`` directory. There are several types
1584 of files in there. The *minimal* template includes:
1586 **page.html**
1587 This template usually defines the overall look of your tracker. When
1588 you view an issue, it appears inside this template. When you view an
1589 index, it also appears inside this template. This template defines a
1590 macro called "icing" which is used by almost all other templates as a
1591 coating for their content, using its "content" slot. It also defines
1592 the "head_title" and "body_title" slots to allow setting of the page
1593 title.
1594 **home.html**
1595 the default page displayed when no other page is indicated by the user
1596 **home.classlist.html**
1597 a special version of the default page that lists the classes in the
1598 tracker
1599 **classname.item.html**
1600 displays an item of the *classname* class
1601 **classname.index.html**
1602 displays a list of *classname* items
1603 **classname.search.html**
1604 displays a search page for *classname* items
1605 **_generic.index.html**
1606 used to display a list of items where there is no
1607 ``*classname*.index`` available
1608 **_generic.help.html**
1609 used to display a "class help" page where there is no
1610 ``*classname*.help``
1611 **user.register.html**
1612 a special page just for the user class, that renders the registration
1613 page
1614 **style.css.html**
1615 a static file that is served up as-is
1617 The *classic* template has a number of additional templates.
1619 Remember that you can create any template extension you want to,
1620 so if you just want to play around with the templating for new issues,
1621 you can copy the current "issue.item" template to "issue.test", and then
1622 access the test template using the "@template" URL argument::
1624 http://your.tracker.example/tracker/issue?@template=test
1626 and it won't affect your users using the "issue.item" template.
1629 How the templates work
1630 ----------------------
1633 Basic Templating Actions
1634 ~~~~~~~~~~~~~~~~~~~~~~~~
1636 Roundup's templates consist of special attributes on the HTML tags.
1637 These attributes form the `Template Attribute Language`_, or TAL.
1638 The basic TAL commands are:
1640 **tal:define="variable expression; variable expression; ..."**
1641 Define a new variable that is local to this tag and its contents. For
1642 example::
1644 <html tal:define="title request/description">
1645 <head><title tal:content="title"></title></head>
1646 </html>
1648 In this example, the variable "title" is defined as the result of the
1649 expression "request/description". The "tal:content" command inside the
1650 <html> tag may then use the "title" variable.
1652 **tal:condition="expression"**
1653 Only keep this tag and its contents if the expression is true. For
1654 example::
1656 <p tal:condition="python:request.user.hasPermission('View', 'issue')">
1657 Display some issue information.
1658 </p>
1660 In the example, the <p> tag and its contents are only displayed if
1661 the user has the "View" permission for issues. We consider the number
1662 zero, a blank string, an empty list, and the built-in variable
1663 nothing to be false values. Nearly every other value is true,
1664 including non-zero numbers, and strings with anything in them (even
1665 spaces!).
1667 **tal:repeat="variable expression"**
1668 Repeat this tag and its contents for each element of the sequence
1669 that the expression returns, defining a new local variable and a
1670 special "repeat" variable for each element. For example::
1672 <tr tal:repeat="u user/list">
1673 <td tal:content="u/id"></td>
1674 <td tal:content="u/username"></td>
1675 <td tal:content="u/realname"></td>
1676 </tr>
1678 The example would iterate over the sequence of users returned by
1679 "user/list" and define the local variable "u" for each entry. Using
1680 the repeat command creates a new variable called "repeat" which you
1681 may access to gather information about the iteration. See the section
1682 below on `the repeat variable`_.
1684 **tal:replace="expression"**
1685 Replace this tag with the result of the expression. For example::
1687 <span tal:replace="request/user/realname" />
1689 The example would replace the <span> tag and its contents with the
1690 user's realname. If the user's realname was "Bruce", then the
1691 resultant output would be "Bruce".
1693 **tal:content="expression"**
1694 Replace the contents of this tag with the result of the expression.
1695 For example::
1697 <span tal:content="request/user/realname">user's name appears here
1698 </span>
1700 The example would replace the contents of the <span> tag with the
1701 user's realname. If the user's realname was "Bruce" then the
1702 resultant output would be "<span>Bruce</span>".
1704 **tal:attributes="attribute expression; attribute expression; ..."**
1705 Set attributes on this tag to the results of expressions. For
1706 example::
1708 <a tal:attributes="href string:user${request/user/id}">My Details</a>
1710 In the example, the "href" attribute of the <a> tag is set to the
1711 value of the "string:user${request/user/id}" expression, which will
1712 be something like "user123".
1714 **tal:omit-tag="expression"**
1715 Remove this tag (but not its contents) if the expression is true. For
1716 example::
1718 <span tal:omit-tag="python:1">Hello, world!</span>
1720 would result in output of::
1722 Hello, world!
1724 Note that the commands on a given tag are evaulated in the order above,
1725 so *define* comes before *condition*, and so on.
1727 Additionally, you may include tags such as <tal:block>, which are
1728 removed from output. Its content is kept, but the tag itself is not (so
1729 don't go using any "tal:attributes" commands on it). This is useful for
1730 making arbitrary blocks of HTML conditional or repeatable (very handy
1731 for repeating multiple table rows, which would othewise require an
1732 illegal tag placement to effect the repeat).
1734 .. _TAL:
1735 .. _Template Attribute Language:
1736 http://dev.zope.org/Wikis/DevSite/Projects/ZPT/TAL%20Specification%201.4
1739 Templating Expressions
1740 ~~~~~~~~~~~~~~~~~~~~~~
1742 Templating Expressions are covered by `Template Attribute Language
1743 Expression Syntax`_, or TALES. The expressions you may use in the
1744 attribute values may be one of the following forms:
1746 **Path Expressions** - eg. ``item/status/checklist``
1747 These are object attribute / item accesses. Roughly speaking, the
1748 path ``item/status/checklist`` is broken into parts ``item``,
1749 ``status`` and ``checklist``. The ``item`` part is the root of the
1750 expression. We then look for a ``status`` attribute on ``item``, or
1751 failing that, a ``status`` item (as in ``item['status']``). If that
1752 fails, the path expression fails. When we get to the end, the object
1753 we're left with is evaluated to get a string - if it is a method, it
1754 is called; if it is an object, it is stringified. Path expressions
1755 may have an optional ``path:`` prefix, but they are the default
1756 expression type, so it's not necessary.
1758 If an expression evaluates to ``default``, then the expression is
1759 "cancelled" - whatever HTML already exists in the template will
1760 remain (tag content in the case of ``tal:content``, attributes in the
1761 case of ``tal:attributes``).
1763 If an expression evaluates to ``nothing`` then the target of the
1764 expression is removed (tag content in the case of ``tal:content``,
1765 attributes in the case of ``tal:attributes`` and the tag itself in
1766 the case of ``tal:replace``).
1768 If an element in the path may not exist, then you can use the ``|``
1769 operator in the expression to provide an alternative. So, the
1770 expression ``request/form/foo/value | default`` would simply leave
1771 the current HTML in place if the "foo" form variable doesn't exist.
1773 You may use the python function ``path``, as in
1774 ``path("item/status")``, to embed path expressions in Python
1775 expressions.
1777 **String Expressions** - eg. ``string:hello ${user/name}``
1778 These expressions are simple string interpolations - though they can
1779 be just plain strings with no interpolation if you want. The
1780 expression in the ``${ ... }`` is just a path expression as above.
1782 **Python Expressions** - eg. ``python: 1+1``
1783 These expressions give the full power of Python. All the "root level"
1784 variables are available, so ``python:item.status.checklist()`` would
1785 be equivalent to ``item/status/checklist``, assuming that
1786 ``checklist`` is a method.
1788 Modifiers:
1790 **structure** - eg. ``structure python:msg.content.plain(hyperlink=1)``
1791 The result of expressions are normally *escaped* to be safe for HTML
1792 display (all "<", ">" and "&" are turned into special entities). The
1793 ``structure`` expression modifier turns off this escaping - the
1794 result of the expression is now assumed to be HTML, which is passed
1795 to the web browser for rendering.
1797 **not:** - eg. ``not:python:1=1``
1798 This simply inverts the logical true/false value of another
1799 expression.
1801 .. _TALES:
1802 .. _Template Attribute Language Expression Syntax:
1803 http://dev.zope.org/Wikis/DevSite/Projects/ZPT/TALES%20Specification%201.3
1806 Template Macros
1807 ~~~~~~~~~~~~~~~
1809 Macros are used in Roundup to save us from repeating the same common
1810 page stuctures over and over. The most common (and probably only) macro
1811 you'll use is the "icing" macro defined in the "page" template.
1813 Macros are generated and used inside your templates using special
1814 attributes similar to the `basic templating actions`_. In this case,
1815 though, the attributes belong to the `Macro Expansion Template
1816 Attribute Language`_, or METAL. The macro commands are:
1818 **metal:define-macro="macro name"**
1819 Define that the tag and its contents are now a macro that may be
1820 inserted into other templates using the *use-macro* command. For
1821 example::
1823 <html metal:define-macro="page">
1824 ...
1825 </html>
1827 defines a macro called "page" using the ``<html>`` tag and its
1828 contents. Once defined, macros are stored on the template they're
1829 defined on in the ``macros`` attribute. You can access them later on
1830 through the ``templates`` variable, eg. the most common
1831 ``templates/page/macros/icing`` to access the "page" macro of the
1832 "page" template.
1834 **metal:use-macro="path expression"**
1835 Use a macro, which is identified by the path expression (see above).
1836 This will replace the current tag with the identified macro contents.
1837 For example::
1839 <tal:block metal:use-macro="templates/page/macros/icing">
1840 ...
1841 </tal:block>
1843 will replace the tag and its contents with the "page" macro of the
1844 "page" template.
1846 **metal:define-slot="slot name"** and **metal:fill-slot="slot name"**
1847 To define *dynamic* parts of the macro, you define "slots" which may
1848 be filled when the macro is used with a *use-macro* command. For
1849 example, the ``templates/page/macros/icing`` macro defines a slot like
1850 so::
1852 <title metal:define-slot="head_title">title goes here</title>
1854 In your *use-macro* command, you may now use a *fill-slot* command
1855 like this::
1857 <title metal:fill-slot="head_title">My Title</title>
1859 where the tag that fills the slot completely replaces the one defined
1860 as the slot in the macro.
1862 Note that you may not mix `METAL`_ and `TAL`_ commands on the same tag, but
1863 TAL commands may be used freely inside METAL-using tags (so your
1864 *fill-slots* tags may have all manner of TAL inside them).
1866 .. _METAL:
1867 .. _Macro Expansion Template Attribute Language:
1868 http://dev.zope.org/Wikis/DevSite/Projects/ZPT/METAL%20Specification%201.0
1870 Information available to templates
1871 ----------------------------------
1873 This is implemented by ``roundup.cgi.templating.RoundupPageTemplate``
1875 The following variables are available to templates.
1877 **context**
1878 The current context. This is either None, a `hyperdb class wrapper`_
1879 or a `hyperdb item wrapper`_
1880 **request**
1881 Includes information about the current request, including:
1882 - the current index information (``filterspec``, ``filter`` args,
1883 ``properties``, etc) parsed out of the form.
1884 - methods for easy filterspec link generation
1885 - "form"
1886 The current CGI form information as a mapping of form argument name
1887 to value (specifically a cgi.FieldStorage)
1888 - "env" the CGI environment variables
1889 - "base" the base URL for this instance
1890 - "user" a HTMLItem instance for the current user
1891 - "language" as determined by the browser or config
1892 - "classname" the current classname (possibly None)
1893 - "template" the current template (suffix, also possibly None)
1894 **config**
1895 This variable holds all the values defined in the tracker config.ini
1896 file (eg. TRACKER_NAME, etc.)
1897 **db**
1898 The current database, used to access arbitrary database items.
1899 **templates**
1900 Access to all the tracker templates by name. Used mainly in
1901 *use-macro* commands.
1902 **utils**
1903 This variable makes available some utility functions like batching.
1904 **nothing**
1905 This is a special variable - if an expression evaluates to this, then
1906 the tag (in the case of a ``tal:replace``), its contents (in the case
1907 of ``tal:content``) or some attributes (in the case of
1908 ``tal:attributes``) will not appear in the the output. So, for
1909 example::
1911 <span tal:attributes="class nothing">Hello, World!</span>
1913 would result in::
1915 <span>Hello, World!</span>
1917 **default**
1918 Also a special variable - if an expression evaluates to this, then the
1919 existing HTML in the template will not be replaced or removed, it will
1920 remain. So::
1922 <span tal:replace="default">Hello, World!</span>
1924 would result in::
1926 <span>Hello, World!</span>
1928 **true**, **false**
1929 Boolean constants that may be used in `templating expressions`_
1930 instead of ``python:1`` and ``python:0``.
1931 **i18n**
1932 Internationalization service, providing two string translation methods:
1934 **gettext** (*message*)
1935 Return the localized translation of message
1936 **ngettext** (*singular*, *plural*, *number*)
1937 Like ``gettext()``, but consider plural forms. If a translation
1938 is found, apply the plural formula to *number*, and return the
1939 resulting message (some languages have more than two plural forms).
1940 If no translation is found, return singular if *number* is 1;
1941 return plural otherwise.
1943 This function requires python2.3; in earlier python versions
1944 may not work as expected.
1946 The context variable
1947 ~~~~~~~~~~~~~~~~~~~~
1949 The *context* variable is one of three things based on the current
1950 context (see `determining web context`_ for how we figure this out):
1952 1. if we're looking at a "home" page, then it's None
1953 2. if we're looking at a specific hyperdb class, it's a
1954 `hyperdb class wrapper`_.
1955 3. if we're looking at a specific hyperdb item, it's a
1956 `hyperdb item wrapper`_.
1958 If the context is not None, we can access the properties of the class or
1959 item. The only real difference between cases 2 and 3 above are:
1961 1. the properties may have a real value behind them, and this will
1962 appear if the property is displayed through ``context/property`` or
1963 ``context/property/field``.
1964 2. the context's "id" property will be a false value in the second case,
1965 but a real, or true value in the third. Thus we can determine whether
1966 we're looking at a real item from the hyperdb by testing
1967 "context/id".
1969 Hyperdb class wrapper
1970 :::::::::::::::::::::
1972 This is implemented by the ``roundup.cgi.templating.HTMLClass``
1973 class.
1975 This wrapper object provides access to a hyperb class. It is used
1976 primarily in both index view and new item views, but it's also usable
1977 anywhere else that you wish to access information about a class, or the
1978 items of a class, when you don't have a specific item of that class in
1979 mind.
1981 We allow access to properties. There will be no "id" property. The value
1982 accessed through the property will be the current value of the same name
1983 from the CGI form.
1985 There are several methods available on these wrapper objects:
1987 =========== =============================================================
1988 Method Description
1989 =========== =============================================================
1990 properties return a `hyperdb property wrapper`_ for all of this class's
1991 properties.
1992 list lists all of the active (not retired) items in the class.
1993 csv return the items of this class as a chunk of CSV text.
1994 propnames lists the names of the properties of this class.
1995 filter lists of items from this class, filtered and sorted. Two
1996 options are avaible for sorting:
1998 1. by the current *request* filterspec/filter/sort/group args
1999 2. by the "filterspec", "sort" and "group" keyword args.
2000 "filterspec" is ``{propname: value(s)}``. "sort" and
2001 "group" are an optionally empty list ``[(dir, prop)]``
2002 where dir is '+', '-' or None
2003 and prop is a prop name or None.
2005 The propname in filterspec and prop in a sort/group spec
2006 may be transitive, i.e., it may contain properties of
2007 the form link.link.link.name.
2009 eg. All issues with a priority of "1" with messages added in
2010 the last week, sorted by activity date:
2011 ``issue.filter(filterspec={"priority": "1",
2012 'messages.creation' : '.-1w;'}, sort=[('activity', '+')])``
2014 filter_sql **Only in SQL backends**
2016 Lists the items that match the SQL provided. The SQL is a
2017 complete "select" statement.
2019 The SQL select must include the item id as the first column.
2021 This function **does not** filter out retired items, add
2022 on a where clause "__retired__ <> 1" if you don't want
2023 retired nodes.
2025 classhelp display a link to a javascript popup containing this class'
2026 "help" template.
2028 This generates a link to a popup window which displays the
2029 properties indicated by "properties" of the class named by
2030 "classname". The "properties" should be a comma-separated list
2031 (eg. 'id,name,description'). Properties defaults to all the
2032 properties of a class (excluding id, creator, created and
2033 activity).
2035 You may optionally override the "label" displayed, the "width",
2036 the "height", the number of items per page ("pagesize") and
2037 the field on which the list is sorted ("sort").
2039 With the "filter" arg it is possible to specify a filter for
2040 which items are supposed to be displayed. It has to be of
2041 the format "<field>=<values>;<field>=<values>;...".
2043 The popup window will be resizable and scrollable.
2045 If the "property" arg is given, it's passed through to the
2046 javascript help_window function. This allows updating of a
2047 property in the calling HTML page.
2049 If the "form" arg is given, it's passed through to the
2050 javascript help_window function - it's the name of the form
2051 the "property" belongs to.
2053 submit generate a submit button (and action hidden element)
2054 renderWith render this class with the given template.
2055 history returns 'New node - no history' :)
2056 is_edit_ok is the user allowed to Edit the current class?
2057 is_view_ok is the user allowed to View the current class?
2058 =========== =============================================================
2060 Note that if you have a property of the same name as one of the above
2061 methods, you'll need to access it using a python "item access"
2062 expression. For example::
2064 python:context['list']
2066 will access the "list" property, rather than the list method.
2069 Hyperdb item wrapper
2070 ::::::::::::::::::::
2072 This is implemented by the ``roundup.cgi.templating.HTMLItem``
2073 class.
2075 This wrapper object provides access to a hyperb item.
2077 We allow access to properties. There will be no "id" property. The value
2078 accessed through the property will be the current value of the same name
2079 from the CGI form.
2081 There are several methods available on these wrapper objects:
2083 =============== ========================================================
2084 Method Description
2085 =============== ========================================================
2086 submit generate a submit button (and action hidden element)
2087 journal return the journal of the current item (**not
2088 implemented**)
2089 history render the journal of the current item as HTML
2090 renderQueryForm specific to the "query" class - render the search form
2091 for the query
2092 hasPermission specific to the "user" class - determine whether the
2093 user has a Permission. The signature is::
2095 hasPermission(self, permission, [classname=],
2096 [property=], [itemid=])
2098 where the classname defaults to the current context.
2099 hasRole specific to the "user" class - determine whether the
2100 user has a Role. The signature is::
2102 hasRole(self, rolename)
2104 is_edit_ok is the user allowed to Edit the current item?
2105 is_view_ok is the user allowed to View the current item?
2106 is_retired is the item retired?
2107 download_url generate a url-quoted link for download of FileClass
2108 item contents (ie. file<id>/<name>)
2109 copy_url generate a url-quoted link for creating a copy
2110 of this item. By default, the copy will acquire
2111 all properties of the current item except for
2112 ``messages`` and ``files``. This can be overridden
2113 by passing ``exclude`` argument which contains a list
2114 (or any iterable) of property names that shall not be
2115 copied. Database-driven properties like ``id`` or
2116 ``activity`` cannot be copied.
2117 =============== ========================================================
2119 Note that if you have a property of the same name as one of the above
2120 methods, you'll need to access it using a python "item access"
2121 expression. For example::
2123 python:context['journal']
2125 will access the "journal" property, rather than the journal method.
2128 Hyperdb property wrapper
2129 ::::::::::::::::::::::::
2131 This is implemented by subclasses of the
2132 ``roundup.cgi.templating.HTMLProperty`` class (``HTMLStringProperty``,
2133 ``HTMLNumberProperty``, and so on).
2135 This wrapper object provides access to a single property of a class. Its
2136 value may be either:
2138 1. if accessed through a `hyperdb item wrapper`_, then it's a value from
2139 the hyperdb
2140 2. if access through a `hyperdb class wrapper`_, then it's a value from
2141 the CGI form
2144 The property wrapper has some useful attributes:
2146 =============== ========================================================
2147 Attribute Description
2148 =============== ========================================================
2149 _name the name of the property
2150 _value the value of the property if any - this is the actual
2151 value retrieved from the hyperdb for this property
2152 =============== ========================================================
2154 There are several methods available on these wrapper objects:
2156 =========== ================================================================
2157 Method Description
2158 =========== ================================================================
2159 plain render a "plain" representation of the property. This method
2160 may take two arguments:
2162 escape
2163 If true, escape the text so it is HTML safe (default: no). The
2164 reason this defaults to off is that text is usually escaped
2165 at a later stage by the TAL commands, unless the "structure"
2166 option is used in the template. The following ``tal:content``
2167 expressions are all equivalent::
2169 "structure python:msg.content.plain(escape=1)"
2170 "python:msg.content.plain()"
2171 "msg/content/plain"
2172 "msg/content"
2174 Usually you'll only want to use the escape option in a
2175 complex expression.
2177 hyperlink
2178 If true, turn URLs, email addresses and hyperdb item
2179 designators in the text into hyperlinks (default: no). Note
2180 that you'll need to use the "structure" TAL option if you
2181 want to use this ``tal:content`` expression::
2183 "structure python:msg.content.plain(hyperlink=1)"
2185 The text is automatically HTML-escaped before the hyperlinking
2186 transformation done in the plain() method.
2188 hyperlinked The same as msg.content.plain(hyperlink=1), but nicer::
2190 "structure msg/content/hyperlinked"
2192 field render an appropriate form edit field for the property - for
2193 most types this is a text entry box, but for Booleans it's a
2194 tri-state yes/no/neither selection. This method may take some
2195 arguments:
2197 size
2198 Sets the width in characters of the edit field
2200 format (Date properties only)
2201 Sets the format of the date in the field - uses the same
2202 format string argument as supplied to the ``pretty`` method
2203 below.
2205 popcal (Date properties only)
2206 Include the Javascript-based popup calendar for date
2207 selection. Defaults to on.
2209 stext only on String properties - render the value of the property
2210 as StructuredText (requires the StructureText module to be
2211 installed separately)
2212 multiline only on String properties - render a multiline form edit
2213 field for the property
2214 email only on String properties - render the value of the property
2215 as an obscured email address
2216 confirm only on Password properties - render a second form edit field
2217 for the property, used for confirmation that the user typed
2218 the password correctly. Generates a field with name
2219 "name:confirm".
2220 now only on Date properties - return the current date as a new
2221 property
2222 reldate only on Date properties - render the interval between the date
2223 and now
2224 local only on Date properties - return this date as a new property
2225 with some timezone offset, for example::
2227 python:context.creation.local(10)
2229 will render the date with a +10 hour offset.
2230 pretty Date properties - render the date as "dd Mon YYYY" (eg. "19
2231 Mar 2004"). Takes an optional format argument, for example::
2233 python:context.activity.pretty('%Y-%m-%d')
2235 Will format as "2004-03-19" instead.
2237 Interval properties - render the interval in a pretty
2238 format (eg. "yesterday"). The format arguments are those used
2239 in the standard ``strftime`` call (see the `Python Library
2240 Reference: time module`__)
2241 popcal Generate a link to a popup calendar which may be used to
2242 edit the date field, for example::
2244 <span tal:replace="structure context/due/popcal" />
2246 you still need to include the ``field`` for the property, so
2247 typically you'd have::
2249 <span tal:replace="structure context/due/field" />
2250 <span tal:replace="structure context/due/popcal" />
2252 menu only on Link and Multilink properties - render a form select
2253 list for this property. Takes a number of optional arguments
2255 size
2256 is used to limit the length of the list labels
2257 height
2258 is used to set the <select> tag's "size" attribute
2259 showid
2260 includes the item ids in the list labels
2261 additional
2262 lists properties which should be included in the label
2263 sort_on
2264 indicates the property to sort the list on as (direction,
2265 (direction, property) where direction is '+' or '-'. A
2266 single string with the direction prepended may be used.
2267 For example: ('-', 'order'), '+name'.
2268 value
2269 gives a default value to preselect in the menu
2271 The remaining keyword arguments are used as conditions for
2272 filtering the items in the list - they're passed as the
2273 "filterspec" argument to a Class.filter() call. For example::
2275 <span tal:replace="structure context/status/menu" />
2277 <span tal:replace="python:context.status.menu(order='+name",
2278 value='chatting',
2279 filterspec={'status': '1,2,3,4'}" />
2281 sorted only on Multilink properties - produce a list of the linked
2282 items sorted by some property, for example::
2284 python:context.files.sorted('creation')
2286 Will list the files by upload date.
2287 reverse only on Multilink properties - produce a list of the linked
2288 items in reverse order
2289 isset returns True if the property has been set to a value
2290 =========== ================================================================
2292 __ http://docs.python.org/lib/module-time.html
2294 All of the above functions perform checks for permissions required to
2295 display or edit the data they are manipulating. The simplest case is
2296 editing an issue title. Including the expression::
2298 context/title/field
2300 Will present the user with an edit field, if they have edit permission. If
2301 not, then they will be presented with a static display if they have view
2302 permission. If they don't even have view permission, then an error message
2303 is raised, preventing the display of the page, indicating that they don't
2304 have permission to view the information.
2307 The request variable
2308 ~~~~~~~~~~~~~~~~~~~~
2310 This is implemented by the ``roundup.cgi.templating.HTMLRequest``
2311 class.
2313 The request variable is packed with information about the current
2314 request.
2316 .. taken from ``roundup.cgi.templating.HTMLRequest`` docstring
2318 =========== ============================================================
2319 Variable Holds
2320 =========== ============================================================
2321 form the CGI form as a cgi.FieldStorage
2322 env the CGI environment variables
2323 base the base URL for this tracker
2324 user a HTMLUser instance for this user
2325 classname the current classname (possibly None)
2326 template the current template (suffix, also possibly None)
2327 form the current CGI form variables in a FieldStorage
2328 =========== ============================================================
2330 **Index page specific variables (indexing arguments)**
2332 =========== ============================================================
2333 Variable Holds
2334 =========== ============================================================
2335 columns dictionary of the columns to display in an index page
2336 show a convenience access to columns - request/show/colname will
2337 be true if the columns should be displayed, false otherwise
2338 sort index sort columns [(direction, column name)]
2339 group index grouping properties [(direction, column name)]
2340 filter properties to filter the index on
2341 filterspec values to filter the index on (property=value, eg
2342 ``priority=1`` or ``messages.author=42``
2343 search_text text to perform a full-text search on for an index
2344 =========== ============================================================
2346 There are several methods available on the request variable:
2348 =============== ========================================================
2349 Method Description
2350 =============== ========================================================
2351 description render a description of the request - handle for the
2352 page title
2353 indexargs_form render the current index args as form elements
2354 indexargs_url render the current index args as a URL
2355 base_javascript render some javascript that is used by other components
2356 of the templating
2357 batch run the current index args through a filter and return a
2358 list of items (see `hyperdb item wrapper`_, and
2359 `batching`_)
2360 =============== ========================================================
2362 The form variable
2363 :::::::::::::::::
2365 The form variable is a bit special because it's actually a python
2366 FieldStorage object. That means that you have two ways to access its
2367 contents. For example, to look up the CGI form value for the variable
2368 "name", use the path expression::
2370 request/form/name/value
2372 or the python expression::
2374 python:request.form['name'].value
2376 Note the "item" access used in the python case, and also note the
2377 explicit "value" attribute we have to access. That's because the form
2378 variables are stored as MiniFieldStorages. If there's more than one
2379 "name" value in the form, then the above will break since
2380 ``request/form/name`` is actually a *list* of MiniFieldStorages. So it's
2381 best to know beforehand what you're dealing with.
2384 The db variable
2385 ~~~~~~~~~~~~~~~
2387 This is implemented by the ``roundup.cgi.templating.HTMLDatabase``
2388 class.
2390 Allows access to all hyperdb classes as attributes of this variable. If
2391 you want access to the "user" class, for example, you would use::
2393 db/user
2394 python:db.user
2396 Also, the current id of the current user is available as
2397 ``db.getuid()``. This isn't so useful in templates (where you have
2398 ``request/user``), but it can be useful in detectors or interfaces.
2400 The access results in a `hyperdb class wrapper`_.
2403 The templates variable
2404 ~~~~~~~~~~~~~~~~~~~~~~
2406 This is implemented by the ``roundup.cgi.templating.Templates``
2407 class.
2409 This variable doesn't have any useful methods defined. It supports being
2410 used in expressions to access the templates, and consequently the
2411 template macros. You may access the templates using the following path
2412 expression::
2414 templates/name
2416 or the python expression::
2418 templates[name]
2420 where "name" is the name of the template you wish to access. The
2421 template has one useful attribute, namely "macros". To access a specific
2422 macro (called "macro_name"), use the path expression::
2424 templates/name/macros/macro_name
2426 or the python expression::
2428 templates[name].macros[macro_name]
2430 The repeat variable
2431 ~~~~~~~~~~~~~~~~~~~
2433 The repeat variable holds an entry for each active iteration. That is, if
2434 you have a ``tal:repeat="user db/users"`` command, then there will be a
2435 repeat variable entry called "user". This may be accessed as either::
2437 repeat/user
2438 python:repeat['user']
2440 The "user" entry has a number of methods available for information:
2442 =============== =========================================================
2443 Method Description
2444 =============== =========================================================
2445 first True if the current item is the first in the sequence.
2446 last True if the current item is the last in the sequence.
2447 even True if the current item is an even item in the sequence.
2448 odd True if the current item is an odd item in the sequence.
2449 number Current position in the sequence, starting from 1.
2450 letter Current position in the sequence as a letter, a through
2451 z, then aa through zz, and so on.
2452 Letter Same as letter(), except uppercase.
2453 roman Current position in the sequence as lowercase roman
2454 numerals.
2455 Roman Same as roman(), except uppercase.
2456 =============== =========================================================
2459 The utils variable
2460 ~~~~~~~~~~~~~~~~~~
2462 This is implemented by the
2463 ``roundup.cgi.templating.TemplatingUtils`` class, but it may be extended
2464 as described below.
2466 =============== ========================================================
2467 Method Description
2468 =============== ========================================================
2469 Batch return a batch object using the supplied list
2470 url_quote quote some text as safe for a URL (ie. space, %, ...)
2471 html_quote quote some text as safe in HTML (ie. <, >, ...)
2472 html_calendar renders an HTML calendar used by the
2473 ``_generic.calendar.html`` template (itself invoked by
2474 the popupCalendar DateHTMLProperty method
2475 =============== ========================================================
2477 You may add additional utility methods by writing them in your tracker
2478 ``extensions`` directory and registering them with the templating system
2479 using ``instance.registerUtil`` (see `adding a time log to your issues`_ for
2480 an example of this).
2483 Batching
2484 ::::::::
2486 Use Batch to turn a list of items, or item ids of a given class, into a
2487 series of batches. Its usage is::
2489 python:utils.Batch(sequence, size, start, end=0, orphan=0,
2490 overlap=0)
2492 or, to get the current index batch::
2494 request/batch
2496 The parameters are:
2498 ========= ==============================================================
2499 Parameter Usage
2500 ========= ==============================================================
2501 sequence a list of HTMLItems
2502 size how big to make the sequence.
2503 start where to start (0-indexed) in the sequence.
2504 end where to end (0-indexed) in the sequence.
2505 orphan if the next batch would contain less items than this value,
2506 then it is combined with this batch
2507 overlap the number of items shared between adjacent batches
2508 ========= ==============================================================
2510 All of the parameters are assigned as attributes on the batch object. In
2511 addition, it has several more attributes:
2513 =============== ========================================================
2514 Attribute Description
2515 =============== ========================================================
2516 start indicates the start index of the batch. *Unlike
2517 the argument, is a 1-based index (I know, lame)*
2518 first indicates the start index of the batch *as a 0-based
2519 index*
2520 length the actual number of elements in the batch
2521 sequence_length the length of the original, unbatched, sequence.
2522 =============== ========================================================
2524 And several methods:
2526 =============== ========================================================
2527 Method Description
2528 =============== ========================================================
2529 previous returns a new Batch with the previous batch settings
2530 next returns a new Batch with the next batch settings
2531 propchanged detect if the named property changed on the current item
2532 when compared to the last item
2533 =============== ========================================================
2535 An example of batching::
2537 <table class="otherinfo">
2538 <tr><th colspan="4" class="header">Existing Keywords</th></tr>
2539 <tr tal:define="keywords db/keyword/list"
2540 tal:repeat="start python:range(0, len(keywords), 4)">
2541 <td tal:define="batch python:utils.Batch(keywords, 4, start)"
2542 tal:repeat="keyword batch" tal:content="keyword/name">
2543 keyword here</td>
2544 </tr>
2545 </table>
2547 ... which will produce a table with four columns containing the items of
2548 the "keyword" class (well, their "name" anyway).
2551 Translations
2552 ~~~~~~~~~~~~
2554 Should you wish to enable multiple languages in template content that you
2555 create you'll need to add new locale files in the tracker home under a
2556 ``locale`` directory. Use the instructions in the ``developer's guide`` to
2557 create the locale files.
2560 Displaying Properties
2561 ---------------------
2563 Properties appear in the user interface in three contexts: in indices,
2564 in editors, and as search arguments. For each type of property, there
2565 are several display possibilities. For example, in an index view, a
2566 string property may just be printed as a plain string, but in an editor
2567 view, that property may be displayed in an editable field.
2570 Index Views
2571 -----------
2573 This is one of the class context views. It is also the default view for
2574 classes. The template used is "*classname*.index".
2577 Index View Specifiers
2578 ~~~~~~~~~~~~~~~~~~~~~
2580 An index view specifier (URL fragment) looks like this (whitespace has
2581 been added for clarity)::
2583 /issue?status=unread,in-progress,resolved&
2584 keyword=security,ui&
2585 @group=priority,-status&
2586 @sort=-activity&
2587 @filters=status,keyword&
2588 @columns=title,status,fixer
2590 The index view is determined by two parts of the specifier: the layout
2591 part and the filter part. The layout part consists of the query
2592 parameters that begin with colons, and it determines the way that the
2593 properties of selected items are displayed. The filter part consists of
2594 all the other query parameters, and it determines the criteria by which
2595 items are selected for display. The filter part is interactively
2596 manipulated with the form widgets displayed in the filter section. The
2597 layout part is interactively manipulated by clicking on the column
2598 headings in the table.
2600 The filter part selects the union of the sets of items with values
2601 matching any specified Link properties and the intersection of the sets
2602 of items with values matching any specified Multilink properties.
2604 The example specifies an index of "issue" items. Only items with a
2605 "status" of either "unread" or "in-progress" or "resolved" are
2606 displayed, and only items with "keyword" values including both "security"
2607 and "ui" are displayed. The items are grouped by priority arranged in
2608 ascending order and in descending order by status; and within
2609 groups, sorted by activity, arranged in descending order. The filter
2610 section shows filters for the "status" and "keyword" properties, and the
2611 table includes columns for the "title", "status", and "fixer"
2612 properties.
2614 ============ =============================================================
2615 Argument Description
2616 ============ =============================================================
2617 @sort sort by prop name, optionally preceeded with '-' to give
2618 descending or nothing for ascending sorting. Several
2619 properties can be specified delimited with comma.
2620 Internally a search-page using several sort properties may
2621 use @sort0, @sort1 etc. with option @sortdir0, @sortdir1
2622 etc. for the direction of sorting (a non-empty value of
2623 sortdir0 specifies reverse order).
2624 @group group by prop name, optionally preceeded with '-' or to sort
2625 in descending or nothing for ascending order. Several
2626 properties can be specified delimited with comma.
2627 Internally a search-page using several grouping properties may
2628 use @group0, @group1 etc. with option @groupdir0, @groupdir1
2629 etc. for the direction of grouping (a non-empty value of
2630 groupdir0 specifies reverse order).
2631 @columns selects the columns that should be displayed. Default is
2632 all.
2633 @filter indicates which properties are being used in filtering.
2634 Default is none.
2635 propname selects the values the item properties given by propname must
2636 have (very basic search/filter).
2637 @search_text if supplied, performs a full-text search (message bodies,
2638 issue titles, etc)
2639 ============ =============================================================
2642 Searching Views
2643 ---------------
2645 .. note::
2646 if you add a new column to the ``@columns`` form variable potentials
2647 then you will need to add the column to the appropriate `index views`_
2648 template so that it is actually displayed.
2650 This is one of the class context views. The template used is typically
2651 "*classname*.search". The form on this page should have "search" as its
2652 ``@action`` variable. The "search" action:
2654 - sets up additional filtering, as well as performing indexed text
2655 searching
2656 - sets the ``@filter`` variable correctly
2657 - saves the query off if ``@query_name`` is set.
2659 The search page should lay out any fields that you wish to allow the
2660 user to search on. If your schema contains a large number of properties,
2661 you should be wary of making all of those properties available for
2662 searching, as this can cause confusion. If the additional properties are
2663 Strings, consider having their value indexed, and then they will be
2664 searchable using the full text indexed search. This is both faster, and
2665 more useful for the end user.
2667 If the search view does specify the "search" ``@action``, then it may also
2668 provide an additional argument:
2670 ============ =============================================================
2671 Argument Description
2672 ============ =============================================================
2673 @query_name if supplied, the index parameters (including @search_text)
2674 will be saved off as a the query item and registered against
2675 the user's queries property. Note that the *classic* template
2676 schema has this ability, but the *minimal* template schema
2677 does not.
2678 ============ =============================================================
2681 Item Views
2682 ----------
2684 The basic view of a hyperdb item is provided by the "*classname*.item"
2685 template. It generally has three sections; an "editor", a "spool" and a
2686 "history" section.
2689 Editor Section
2690 ~~~~~~~~~~~~~~
2692 The editor section is used to manipulate the item - it may be a static
2693 display if the user doesn't have permission to edit the item.
2695 Here's an example of a basic editor template (this is the default
2696 "classic" template issue item edit form - from the "issue.item.html"
2697 template)::
2699 <table class="form">
2700 <tr>
2701 <th>Title</th>
2702 <td colspan="3" tal:content="structure python:context.title.field(size=60)">title</td>
2703 </tr>
2705 <tr>
2706 <th>Priority</th>
2707 <td tal:content="structure context/priority/menu">priority</td>
2708 <th>Status</th>
2709 <td tal:content="structure context/status/menu">status</td>
2710 </tr>
2712 <tr>
2713 <th>Superseder</th>
2714 <td>
2715 <span tal:replace="structure python:context.superseder.field(showid=1, size=20)" />
2716 <span tal:replace="structure python:db.issue.classhelp('id,title')" />
2717 <span tal:condition="context/superseder">
2718 <br>View: <span tal:replace="structure python:context.superseder.link(showid=1)" />
2719 </span>
2720 </td>
2721 <th>Nosy List</th>
2722 <td>
2723 <span tal:replace="structure context/nosy/field" />
2724 <span tal:replace="structure python:db.user.classhelp('username,realname,address,phone')" />
2725 </td>
2726 </tr>
2728 <tr>
2729 <th>Assigned To</th>
2730 <td tal:content="structure context/assignedto/menu">
2731 assignedto menu
2732 </td>
2733 <td> </td>
2734 <td> </td>
2735 </tr>
2737 <tr>
2738 <th>Change Note</th>
2739 <td colspan="3">
2740 <textarea name=":note" wrap="hard" rows="5" cols="60"></textarea>
2741 </td>
2742 </tr>
2744 <tr>
2745 <th>File</th>
2746 <td colspan="3"><input type="file" name=":file" size="40"></td>
2747 </tr>
2749 <tr>
2750 <td> </td>
2751 <td colspan="3" tal:content="structure context/submit">
2752 submit button will go here
2753 </td>
2754 </tr>
2755 </table>
2758 When a change is submitted, the system automatically generates a message
2759 describing the changed properties. As shown in the example, the editor
2760 template can use the ":note" and ":file" fields, which are added to the
2761 standard changenote message generated by Roundup.
2764 Form values
2765 :::::::::::
2767 We have a number of ways to pull properties out of the form in order to
2768 meet the various needs of:
2770 1. editing the current item (perhaps an issue item)
2771 2. editing information related to the current item (eg. messages or
2772 attached files)
2773 3. creating new information to be linked to the current item (eg. time
2774 spent on an issue)
2776 In the following, ``<bracketed>`` values are variable, ":" may be one of
2777 ":" or "@", and other text ("required") is fixed.
2779 Properties are specified as form variables:
2781 ``<propname>``
2782 property on the current context item
2784 ``<designator>:<propname>``
2785 property on the indicated item (for editing related information)
2787 ``<classname>-<N>:<propname>``
2788 property on the Nth new item of classname (generally for creating new
2789 items to attach to the current item)
2791 Once we have determined the "propname", we check to see if it is one of
2792 the special form values:
2794 ``@required``
2795 The named property values must be supplied or a ValueError will be
2796 raised.
2798 ``@remove@<propname>=id(s)``
2799 The ids will be removed from the multilink property.
2801 ``:add:<propname>=id(s)``
2802 The ids will be added to the multilink property.
2804 ``:link:<propname>=<designator>``
2805 Used to add a link to new items created during edit. These are
2806 collected and returned in ``all_links``. This will result in an
2807 additional linking operation (either Link set or Multilink append)
2808 after the edit/create is done using ``all_props`` in ``_editnodes``.
2809 The <propname> on the current item will be set/appended the id of the
2810 newly created item of class <designator> (where <designator> must be
2811 <classname>-<N>).
2813 Any of the form variables may be prefixed with a classname or
2814 designator.
2816 Two special form values are supported for backwards compatibility:
2818 ``:note``
2819 create a message (with content, author and date), linked to the
2820 context item. This is ALWAYS designated "msg-1".
2821 ``:file``
2822 create a file, attached to the current item and any message created by
2823 :note. This is ALWAYS designated "file-1".
2826 Spool Section
2827 ~~~~~~~~~~~~~
2829 The spool section lists related information like the messages and files
2830 of an issue.
2832 TODO
2835 History Section
2836 ~~~~~~~~~~~~~~~
2838 The final section displayed is the history of the item - its database
2839 journal. This is generally generated with the template::
2841 <tal:block tal:replace="structure context/history" />
2843 *To be done:*
2845 *The actual history entries of the item may be accessed for manual
2846 templating through the "journal" method of the item*::
2848 <tal:block tal:repeat="entry context/journal">
2849 a journal entry
2850 </tal:block>
2852 *where each journal entry is an HTMLJournalEntry.*
2855 Defining new web actions
2856 ------------------------
2858 You may define new actions to be triggered by the ``@action`` form variable.
2859 These are added to the tracker ``extensions`` directory and registered
2860 using ``instance.registerAction``.
2862 All the existing Actions are defined in ``roundup.cgi.actions``.
2864 Adding action classes takes three steps; first you `define the new
2865 action class`_, then you `register the action class`_ with the cgi
2866 interface so it may be triggered by the ``@action`` form variable.
2867 Finally you `use the new action`_ in your HTML form.
2869 See "`setting up a "wizard" (or "druid") for controlled adding of
2870 issues`_" for an example.
2873 Define the new action class
2874 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2876 Create a new action class in your tracker's ``extensions`` directory, for
2877 example ``myaction.py``::
2879 from roundup.cgi.actions import Action
2881 class MyAction(Action):
2882 def handle(self):
2883 ''' Perform some action. No return value is required.
2884 '''
2886 The *self.client* attribute is an instance of ``roundup.cgi.client.Client``.
2887 See the docstring of that class for details of what it can do.
2889 The method will typically check the ``self.form`` variable's contents.
2890 It may then:
2892 - add information to ``self.client.ok_message`` or ``self.client.error_message``
2893 - change the ``self.client.template`` variable to alter what the user will see
2894 next
2895 - raise Unauthorised, SendStaticFile, SendFile, NotFound or Redirect
2896 exceptions (import them from roundup.cgi.exceptions)
2899 Register the action class
2900 ~~~~~~~~~~~~~~~~~~~~~~~~~~
2902 The class is now written, but isn't available to the user until you register
2903 it with the following code appended to your ``myaction.py`` file::
2905 def init(instance):
2906 instance.registerAction('myaction', myActionClass)
2908 This maps the action name "myaction" to the action class we defined.
2911 Use the new action
2912 ~~~~~~~~~~~~~~~~~~
2914 In your HTML form, add a hidden form element like so::
2916 <input type="hidden" name="@action" value="myaction">
2918 where "myaction" is the name you registered in the previous step.
2920 Actions may return content to the user
2921 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2923 Actions generally perform some database manipulation and then pass control
2924 on to the rendering of a template in the current context (see `Determining
2925 web context`_ for how that works.) Some actions will want to generate the
2926 actual content returned to the user. Action methods may return their own
2927 content string to be displayed to the user, overriding the templating step.
2928 In this situation, we assume that the content is HTML by default. You may
2929 override the content type indicated to the user by calling ``setHeader``::
2931 self.client.setHeader('Content-Type', 'text/csv')
2933 This example indicates that the value sent back to the user is actually
2934 comma-separated value content (eg. something to be loaded into a
2935 spreadsheet or database).
2938 8-bit character set support in Web interface
2939 --------------------------------------------
2941 The web interface uses UTF-8 default. It may be overridden in both forms
2942 and a browser cookie.
2944 - In forms, use the ``@charset`` variable.
2945 - To use the cookie override, have the ``roundup_charset`` cookie set.
2947 In both cases, the value is a valid charset name (eg. ``utf-8`` or
2948 ``kio8-r``).
2950 Inside Roundup, all strings are stored and processed in utf-8.
2951 Unfortunately, some older browsers do not work properly with
2952 utf-8-encoded pages (e.g. Netscape Navigator 4 displays wrong
2953 characters in form fields). This version allows one to change
2954 the character set for http transfers. To do so, you may add
2955 the following code to your ``page.html`` template::
2957 <tal:block define="uri string:${request/base}${request/env/PATH_INFO}">
2958 <a tal:attributes="href python:request.indexargs_url(uri,
2959 {'@charset':'utf-8'})">utf-8</a>
2960 <a tal:attributes="href python:request.indexargs_url(uri,
2961 {'@charset':'koi8-r'})">koi8-r</a>
2962 </tal:block>
2964 (substitute ``koi8-r`` with appropriate charset for your language).
2965 Charset preference is kept in the browser cookie ``roundup_charset``.
2967 ``meta http-equiv`` lines added to the tracker templates in version 0.6.0
2968 should be changed to include actual character set name::
2970 <meta http-equiv="Content-Type"
2971 tal:attributes="content string:text/html;; charset=${request/client/charset}"
2972 />
2974 The charset is also sent in the http header.
2977 Examples
2978 ========
2980 .. contents::
2981 :local:
2982 :depth: 2
2985 Changing what's stored in the database
2986 --------------------------------------
2988 The following examples illustrate ways to change the information stored in
2989 the database.
2992 Adding a new field to the classic schema
2993 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2995 This example shows how to add a simple field (a due date) to the default
2996 classic schema. It does not add any additional behaviour, such as enforcing
2997 the due date, or causing automatic actions to fire if the due date passes.
2999 You add new fields by editing the ``schema.py`` file in you tracker's home.
3000 Schema changes are automatically applied to the database on the next
3001 tracker access (note that roundup-server would need to be restarted as it
3002 caches the schema).
3004 1. Modify the ``schema.py``::
3006 issue = IssueClass(db, "issue",
3007 assignedto=Link("user"), keyword=Multilink("keyword"),
3008 priority=Link("priority"), status=Link("status"),
3009 due_date=Date())
3011 2. Add an edit field to the ``issue.item.html`` template::
3013 <tr>
3014 <th>Due Date</th>
3015 <td tal:content="structure context/due_date/field" />
3016 </tr>
3018 If you want to show only the date part of due_date then do this instead::
3020 <tr>
3021 <th>Due Date</th>
3022 <td tal:content="structure python:context.due_date.field(format='%Y-%m-%d')" />
3023 </tr>
3025 3. Add the property to the ``issue.index.html`` page::
3027 (in the heading row)
3028 <th tal:condition="request/show/due_date">Due Date</th>
3029 (in the data row)
3030 <td tal:condition="request/show/due_date"
3031 tal:content="i/due_date" />
3033 If you want format control of the display of the due date you can
3034 enter the following in the data row to show only the actual due date::
3036 <td tal:condition="request/show/due_date"
3037 tal:content="python:i.due_date.pretty('%Y-%m-%d')"> </td>
3039 4. Add the property to the ``issue.search.html`` page::
3041 <tr tal:define="name string:due_date">
3042 <th i18n:translate="">Due Date:</th>
3043 <td metal:use-macro="search_input"></td>
3044 <td metal:use-macro="column_input"></td>
3045 <td metal:use-macro="sort_input"></td>
3046 <td metal:use-macro="group_input"></td>
3047 </tr>
3049 5. If you wish for the due date to appear in the standard views listed
3050 in the sidebar of the web interface then you'll need to add "due_date"
3051 to the columns and columns_showall lists in your ``page.html``::
3053 columns string:id,activity,due_date,title,creator,status;
3054 columns_showall string:id,activity,due_date,title,creator,assignedto,status;
3056 Adding a new constrained field to the classic schema
3057 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3059 This example shows how to add a new constrained property (i.e. a
3060 selection of distinct values) to your tracker.
3063 Introduction
3064 ::::::::::::
3066 To make the classic schema of Roundup useful as a TODO tracking system
3067 for a group of systems administrators, it needs an extra data field per
3068 issue: a category.
3070 This would let sysadmins quickly list all TODOs in their particular area
3071 of interest without having to do complex queries, and without relying on
3072 the spelling capabilities of other sysadmins (a losing proposition at
3073 best).
3076 Adding a field to the database
3077 ::::::::::::::::::::::::::::::
3079 This is the easiest part of the change. The category would just be a
3080 plain string, nothing fancy. To change what is in the database you need
3081 to add some lines to the ``schema.py`` file of your tracker instance.
3082 Under the comment::
3084 # add any additional database schema configuration here
3086 add::
3088 category = Class(db, "category", name=String())
3089 category.setkey("name")
3091 Here we are setting up a chunk of the database which we are calling
3092 "category". It contains a string, which we are refering to as "name" for
3093 lack of a more imaginative title. (Since "name" is one of the properties
3094 that Roundup looks for on items if you do not set a key for them, it's
3095 probably a good idea to stick with it for new classes if at all
3096 appropriate.) Then we are setting the key of this chunk of the database
3097 to be that "name". This is equivalent to an index for database types.
3098 This also means that there can only be one category with a given name.
3100 Adding the above lines allows us to create categories, but they're not
3101 tied to the issues that we are going to be creating. It's just a list of
3102 categories off on its own, which isn't much use. We need to link it in
3103 with the issues. To do that, find the lines
3104 in ``schema.py`` which set up the "issue" class, and then add a link to
3105 the category::
3107 issue = IssueClass(db, "issue", ... ,
3108 category=Multilink("category"), ... )
3110 The ``Multilink()`` means that each issue can have many categories. If
3111 you were adding something with a one-to-one relationship to issues (such
3112 as the "assignedto" property), use ``Link()`` instead.
3114 That is all you need to do to change the schema. The rest of the effort
3115 is fiddling around so you can actually use the new category.
3118 Populating the new category class
3119 :::::::::::::::::::::::::::::::::
3121 If you haven't initialised the database with the ``roundup-admin``
3122 "initialise" command, then you can add the following to the tracker
3123 ``initial_data.py`` under the comment::
3125 # add any additional database creation steps here - but only if you
3126 # haven't initialised the database with the admin "initialise" command
3128 Add::
3130 category = db.getclass('category')
3131 category.create(name="scipy")
3132 category.create(name="chaco")
3133 category.create(name="weave")
3135 If the database has already been initalised, then you need to use the
3136 ``roundup-admin`` tool::
3138 % roundup-admin -i <tracker home>
3139 Roundup <version> ready for input.
3140 Type "help" for help.
3141 roundup> create category name=scipy
3142 1
3143 roundup> create category name=chaco
3144 2
3145 roundup> create category name=weave
3146 3
3147 roundup> exit...
3148 There are unsaved changes. Commit them (y/N)? y
3151 Setting up security on the new objects
3152 ::::::::::::::::::::::::::::::::::::::
3154 By default only the admin user can look at and change objects. This
3155 doesn't suit us, as we want any user to be able to create new categories
3156 as required, and obviously everyone needs to be able to view the
3157 categories of issues for it to be useful.
3159 We therefore need to change the security of the category objects. This
3160 is also done in ``schema.py``.
3162 There are currently two loops which set up permissions and then assign
3163 them to various roles. Simply add the new "category" to both lists::
3165 # Assign the access and edit permissions for issue, file and message
3166 # to regular users now
3167 for cl in 'issue', 'file', 'msg', 'category':
3168 p = db.security.getPermission('View', cl)
3169 db.security.addPermissionToRole('User', 'View', cl)
3170 db.security.addPermissionToRole('User', 'Edit', cl)
3171 db.security.addPermissionToRole('User', 'Create', cl)
3173 These lines assign the "View" and "Edit" Permissions to the "User" role,
3174 so that normal users can view and edit "category" objects.
3176 This is all the work that needs to be done for the database. It will
3177 store categories, and let users view and edit them. Now on to the
3178 interface stuff.
3181 Changing the web left hand frame
3182 ::::::::::::::::::::::::::::::::
3184 We need to give the users the ability to create new categories, and the
3185 place to put the link to this functionality is in the left hand function
3186 bar, under the "Issues" area. The file that defines how this area looks
3187 is ``html/page.html``, which is what we are going to be editing next.
3189 If you look at this file you can see that it contains a lot of
3190 "classblock" sections which are chunks of HTML that will be included or
3191 excluded in the output depending on whether the condition in the
3192 classblock is met. We are going to add the category code at the end of
3193 the classblock for the *issue* class::
3195 <p class="classblock"
3196 tal:condition="python:request.user.hasPermission('View', 'category')">
3197 <b>Categories</b><br>
3198 <a tal:condition="python:request.user.hasPermission('Edit', 'category')"
3199 href="category?@template=item">New Category<br></a>
3200 </p>
3202 The first two lines is the classblock definition, which sets up a
3203 condition that only users who have "View" permission for the "category"
3204 object will have this section included in their output. Next comes a
3205 plain "Categories" header in bold. Everyone who can view categories will
3206 get that.
3208 Next comes the link to the editing area of categories. This link will
3209 only appear if the condition - that the user has "Edit" permissions for
3210 the "category" objects - is matched. If they do have permission then
3211 they will get a link to another page which will let the user add new
3212 categories.
3214 Note that if you have permission to *view* but not to *edit* categories,
3215 then all you will see is a "Categories" header with nothing underneath
3216 it. This is obviously not very good interface design, but will do for
3217 now. I just claim that it is so I can add more links in this section
3218 later on. However, to fix the problem you could change the condition in
3219 the classblock statement, so that only users with "Edit" permission
3220 would see the "Categories" stuff.
3223 Setting up a page to edit categories
3224 ::::::::::::::::::::::::::::::::::::
3226 We defined code in the previous section which let users with the
3227 appropriate permissions see a link to a page which would let them edit
3228 conditions. Now we have to write that page.
3230 The link was for the *item* template of the *category* object. This
3231 translates into Roundup looking for a file called ``category.item.html``
3232 in the ``html`` tracker directory. This is the file that we are going to
3233 write now.
3235 First, we add an info tag in a comment which doesn't affect the outcome
3236 of the code at all, but is useful for debugging. If you load a page in a
3237 browser and look at the page source, you can see which sections come
3238 from which files by looking for these comments::
3240 <!-- category.item -->
3242 Next we need to add in the METAL macro stuff so we get the normal page
3243 trappings::
3245 <tal:block metal:use-macro="templates/page/macros/icing">
3246 <title metal:fill-slot="head_title">Category editing</title>
3247 <td class="page-header-top" metal:fill-slot="body_title">
3248 <h2>Category editing</h2>
3249 </td>
3250 <td class="content" metal:fill-slot="content">
3252 Next we need to setup up a standard HTML form, which is the whole
3253 purpose of this file. We link to some handy javascript which sends the
3254 form through only once. This is to stop users hitting the send button
3255 multiple times when they are impatient and thus having the form sent
3256 multiple times::
3258 <form method="POST" onSubmit="return submit_once()"
3259 enctype="multipart/form-data">
3261 Next we define some code which sets up the minimum list of fields that
3262 we require the user to enter. There will be only one field - "name" - so
3263 they better put something in it, otherwise the whole form is pointless::
3265 <input type="hidden" name="@required" value="name">
3267 To get everything to line up properly we will put everything in a table,
3268 and put a nice big header on it so the user has an idea what is
3269 happening::
3271 <table class="form">
3272 <tr><th class="header" colspan="2">Category</th></tr>
3274 Next, we need the field into which the user is going to enter the new
3275 category. The ``context.name.field(size=60)`` bit tells Roundup to
3276 generate a normal HTML field of size 60, and the contents of that field
3277 will be the "name" variable of the current context (namely "category").
3278 The upshot of this is that when the user types something in
3279 to the form, a new category will be created with that name::
3281 <tr>
3282 <th>Name</th>
3283 <td tal:content="structure python:context.name.field(size=60)">
3284 name</td>
3285 </tr>
3287 Then a submit button so that the user can submit the new category::
3289 <tr>
3290 <td> </td>
3291 <td colspan="3" tal:content="structure context/submit">
3292 submit button will go here
3293 </td>
3294 </tr>
3296 Finally we finish off the tags we used at the start to do the METAL
3297 stuff::
3299 </td>
3300 </tal:block>
3302 So putting it all together, and closing the table and form we get::
3304 <!-- category.item -->
3305 <tal:block metal:use-macro="templates/page/macros/icing">
3306 <title metal:fill-slot="head_title">Category editing</title>
3307 <td class="page-header-top" metal:fill-slot="body_title">
3308 <h2>Category editing</h2>
3309 </td>
3310 <td class="content" metal:fill-slot="content">
3311 <form method="POST" onSubmit="return submit_once()"
3312 enctype="multipart/form-data">
3314 <table class="form">
3315 <tr><th class="header" colspan="2">Category</th></tr>
3317 <tr>
3318 <th>Name</th>
3319 <td tal:content="structure python:context.name.field(size=60)">
3320 name</td>
3321 </tr>
3323 <tr>
3324 <td>
3325
3326 <input type="hidden" name="@required" value="name">
3327 </td>
3328 <td colspan="3" tal:content="structure context/submit">
3329 submit button will go here
3330 </td>
3331 </tr>
3332 </table>
3333 </form>
3334 </td>
3335 </tal:block>
3337 This is quite a lot to just ask the user one simple question, but there
3338 is a lot of setup for basically one line (the form line) to do its work.
3339 To add another field to "category" would involve one more line (well,
3340 maybe a few extra to get the formatting correct).
3343 Adding the category to the issue
3344 ::::::::::::::::::::::::::::::::
3346 We now have the ability to create issues to our heart's content, but
3347 that is pointless unless we can assign categories to issues. Just like
3348 the ``html/category.item.html`` file was used to define how to add a new
3349 category, the ``html/issue.item.html`` is used to define how a new issue
3350 is created.
3352 Just like ``category.issue.html``, this file defines a form which has a
3353 table to lay things out. It doesn't matter where in the table we add new
3354 stuff, it is entirely up to your sense of aesthetics::
3356 <th>Category</th>
3357 <td>
3358 <span tal:replace="structure context/category/field" />
3359 <span tal:replace="structure python:db.category.classhelp('name',
3360 property='category', width='200')" />
3361 </td>
3363 First, we define a nice header so that the user knows what the next
3364 section is, then the middle line does what we are most interested in.
3365 This ``context/category/field`` gets replaced by a field which contains
3366 the category in the current context (the current context being the new
3367 issue).
3369 The classhelp lines generate a link (labelled "list") to a popup window
3370 which contains the list of currently known categories.
3373 Searching on categories
3374 :::::::::::::::::::::::
3376 Now we can add categories, and create issues with categories. The next
3377 obvious thing that we would like to be able to do, would be to search
3378 for issues based on their category, so that, for example, anyone working
3379 on the web server could look at all issues in the category "Web".
3381 If you look for "Search Issues" in the ``html/page.html`` file, you will
3382 find that it looks something like
3383 ``<a href="issue?@template=search">Search Issues</a>``. This shows us
3384 that when you click on "Search Issues" it will be looking for a
3385 ``issue.search.html`` file to display. So that is the file that we will
3386 change.
3388 If you look at this file it should begin to seem familiar, although it
3389 does use some new macros. You can add the new category search code anywhere you
3390 like within that form::
3392 <tr tal:define="name string:category;
3393 db_klass string:category;
3394 db_content string:name;">
3395 <th>Priority:</th>
3396 <td metal:use-macro="search_select"></td>
3397 <td metal:use-macro="column_input"></td>
3398 <td metal:use-macro="sort_input"></td>
3399 <td metal:use-macro="group_input"></td>
3400 </tr>
3402 The definitions in the ``<tr>`` opening tag are used by the macros:
3404 - ``search_select`` expands to a drop-down box with all categories using
3405 ``db_klass`` and ``db_content``.
3406 - ``column_input`` expands to a checkbox for selecting what columns
3407 should be displayed.
3408 - ``sort_input`` expands to a radio button for selecting what property
3409 should be sorted on.
3410 - ``group_input`` expands to a radio button for selecting what property
3411 should be grouped on.
3413 The category search code above would expand to the following::
3415 <tr>
3416 <th>Category:</th>
3417 <td>
3418 <select name="category">
3419 <option value="">don't care</option>
3420 <option value="">------------</option>
3421 <option value="1">scipy</option>
3422 <option value="2">chaco</option>
3423 <option value="3">weave</option>
3424 </select>
3425 </td>
3426 <td><input type="checkbox" name=":columns" value="category"></td>
3427 <td><input type="radio" name=":sort0" value="category"></td>
3428 <td><input type="radio" name=":group0" value="category"></td>
3429 </tr>
3431 Adding category to the default view
3432 :::::::::::::::::::::::::::::::::::
3434 We can now add categories, add issues with categories, and search for
3435 issues based on categories. This is everything that we need to do;
3436 however, there is some more icing that we would like. I think the
3437 category of an issue is important enough that it should be displayed by
3438 default when listing all the issues.
3440 Unfortunately, this is a bit less obvious than the previous steps. The
3441 code defining how the issues look is in ``html/issue.index.html``. This
3442 is a large table with a form down at the bottom for redisplaying and so
3443 forth.
3445 Firstly we need to add an appropriate header to the start of the table::
3447 <th tal:condition="request/show/category">Category</th>
3449 The *condition* part of this statement is to avoid displaying the
3450 Category column if the user has selected not to see it.
3452 The rest of the table is a loop which will go through every issue that
3453 matches the display criteria. The loop variable is "i" - which means
3454 that every issue gets assigned to "i" in turn.
3456 The new part of code to display the category will look like this::
3458 <td tal:condition="request/show/category"
3459 tal:content="i/category"></td>
3461 The condition is the same as above: only display the condition when the
3462 user hasn't asked for it to be hidden. The next part is to set the
3463 content of the cell to be the category part of "i" - the current issue.
3465 Finally we have to edit ``html/page.html`` again. This time, we need to
3466 tell it that when the user clicks on "Unassigned Issues" or "All Issues",
3467 the category column should be included in the resulting list. If you
3468 scroll down the page file, you can see the links with lots of options.
3469 The option that we are interested in is the ``:columns=`` one which
3470 tells roundup which fields of the issue to display. Simply add
3471 "category" to that list and it all should work.
3473 Adding a time log to your issues
3474 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3476 We want to log the dates and amount of time spent working on issues, and
3477 be able to give a summary of the total time spent on a particular issue.
3479 1. Add a new class to your tracker ``schema.py``::
3481 # storage for time logging
3482 timelog = Class(db, "timelog", period=Interval())
3484 Note that we automatically get the date of the time log entry
3485 creation through the standard property "creation".
3487 You will need to grant "Creation" permission to the users who are
3488 allowed to add timelog entries. You may do this with::
3490 db.security.addPermissionToRole('User', 'Create', 'timelog')
3491 db.security.addPermissionToRole('User', 'View', 'timelog')
3493 If users are also able to *edit* timelog entries, then also include::
3495 db.security.addPermissionToRole('User', 'Edit', 'timelog')
3497 2. Link to the new class from your issue class (again, in
3498 ``schema.py``)::
3500 issue = IssueClass(db, "issue",
3501 assignedto=Link("user"), keyword=Multilink("keyword"),
3502 priority=Link("priority"), status=Link("status"),
3503 times=Multilink("timelog"))
3505 the "times" property is the new link to the "timelog" class.
3507 3. We'll need to let people add in times to the issue, so in the web
3508 interface we'll have a new entry field. This is a special field
3509 because unlike the other fields in the ``issue.item`` template, it
3510 affects a different item (a timelog item) and not the template's
3511 item (an issue). We have a special syntax for form fields that affect
3512 items other than the template default item (see the cgi
3513 documentation on `special form variables`_). In particular, we add a
3514 field to capture a new timelog item's period::
3516 <tr>
3517 <th>Time Log</th>
3518 <td colspan=3><input type="text" name="timelog-1@period" />
3519 (enter as '3y 1m 4d 2:40:02' or parts thereof)
3520 </td>
3521 </tr>
3523 and another hidden field that links that new timelog item (new
3524 because it's marked as having id "-1") to the issue item. It looks
3525 like this::
3527 <input type="hidden" name="@link@times" value="timelog-1" />
3529 On submission, the "-1" timelog item will be created and assigned a
3530 real item id. The "times" property of the issue will have the new id
3531 added to it.
3533 The full entry will now look like this::
3535 <tr>
3536 <th>Time Log</th>
3537 <td colspan=3><input type="text" name="timelog-1@period" />
3538 (enter as '3y 1m 4d 2:40:02' or parts thereof)
3539 <input type="hidden" name="@link@times" value="timelog-1" />
3540 </td>
3541 </tr>
3544 4. We want to display a total of the timelog times that have been
3545 accumulated for an issue. To do this, we'll need to actually write
3546 some Python code, since it's beyond the scope of PageTemplates to
3547 perform such calculations. We do this by adding a module ``timespent.py``
3548 to the ``extensions`` directory in our tracker. The contents of this
3549 file is as follows::
3551 from roundup import date
3553 def totalTimeSpent(times):
3554 ''' Call me with a list of timelog items (which have an
3555 Interval "period" property)
3556 '''
3557 total = date.Interval('0d')
3558 for time in times:
3559 total += time.period._value
3560 return total
3562 def init(instance):
3563 instance.registerUtil('totalTimeSpent', totalTimeSpent)
3565 We will now be able to access the ``totalTimeSpent`` function via the
3566 ``utils`` variable in our templates, as shown in the next step.
3568 5. Display the timelog for an issue::
3570 <table class="otherinfo" tal:condition="context/times">
3571 <tr><th colspan="3" class="header">Time Log
3572 <tal:block
3573 tal:replace="python:utils.totalTimeSpent(context.times)" />
3574 </th></tr>
3575 <tr><th>Date</th><th>Period</th><th>Logged By</th></tr>
3576 <tr tal:repeat="time context/times">
3577 <td tal:content="time/creation"></td>
3578 <td tal:content="time/period"></td>
3579 <td tal:content="time/creator"></td>
3580 </tr>
3581 </table>
3583 I put this just above the Messages log in my issue display. Note our
3584 use of the ``totalTimeSpent`` method which will total up the times
3585 for the issue and return a new Interval. That will be automatically
3586 displayed in the template as text like "+ 1y 2:40" (1 year, 2 hours
3587 and 40 minutes).
3589 6. If you're using a persistent web server - ``roundup-server`` or
3590 ``mod_python`` for example - then you'll need to restart that to pick up
3591 the code changes. When that's done, you'll be able to use the new
3592 time logging interface.
3594 An extension of this modification attaches the timelog entries to any
3595 change message entered at the time of the timelog entry:
3597 A. Add a link to the timelog to the msg class in ``schema.py``:
3599 msg = FileClass(db, "msg",
3600 author=Link("user", do_journal='no'),
3601 recipients=Multilink("user", do_journal='no'),
3602 date=Date(),
3603 summary=String(),
3604 files=Multilink("file"),
3605 messageid=String(),
3606 inreplyto=String(),
3607 times=Multilink("timelog"))
3609 B. Add a new hidden field that links that new timelog item (new
3610 because it's marked as having id "-1") to the new message.
3611 The link is placed in ``issue.item.html`` in the same section that
3612 handles the timelog entry.
3614 It looks like this after this addition::
3616 <tr>
3617 <th>Time Log</th>
3618 <td colspan=3><input type="text" name="timelog-1@period" />
3619 (enter as '3y 1m 4d 2:40:02' or parts thereof)
3620 <input type="hidden" name="@link@times" value="timelog-1" />
3621 <input type="hidden" name="msg-1@link@times" value="timelog-1" />
3622 </td>
3623 </tr>
3625 The "times" property of the message will have the new id added to it.
3627 C. Add the timelog listing from step 5. to the ``msg.item.html`` template
3628 so that the timelog entry appears on the message view page. Note that
3629 the call to totalTimeSpent is not used here since there will only be one
3630 single timelog entry for each message.
3632 I placed it after the Date entry like this::
3634 <tr>
3635 <th i18n:translate="">Date:</th>
3636 <td tal:content="context/date"></td>
3637 </tr>
3638 </table>
3640 <table class="otherinfo" tal:condition="context/times">
3641 <tr><th colspan="3" class="header">Time Log</th></tr>
3642 <tr><th>Date</th><th>Period</th><th>Logged By</th></tr>
3643 <tr tal:repeat="time context/times">
3644 <td tal:content="time/creation"></td>
3645 <td tal:content="time/period"></td>
3646 <td tal:content="time/creator"></td>
3647 </tr>
3648 </table>
3650 <table class="messages">
3653 Tracking different types of issues
3654 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3656 Sometimes you will want to track different types of issues - developer,
3657 customer support, systems, sales leads, etc. A single Roundup tracker is
3658 able to support multiple types of issues. This example demonstrates adding
3659 a system support issue class to a tracker.
3661 1. Figure out what information you're going to want to capture. OK, so
3662 this is obvious, but sometimes it's better to actually sit down for a
3663 while and think about the schema you're going to implement.
3665 2. Add the new issue class to your tracker's ``schema.py``. Just after the
3666 "issue" class definition, add::
3668 # list our systems
3669 system = Class(db, "system", name=String(), order=Number())
3670 system.setkey("name")
3672 # store issues related to those systems
3673 support = IssueClass(db, "support",
3674 assignedto=Link("user"), keyword=Multilink("keyword"),
3675 status=Link("status"), deadline=Date(),
3676 affects=Multilink("system"))
3678 3. Copy the existing ``issue.*`` (item, search and index) templates in the
3679 tracker's ``html`` to ``support.*``. Edit them so they use the properties
3680 defined in the ``support`` class. Be sure to check for hidden form
3681 variables like "required" to make sure they have the correct set of
3682 required properties.
3684 4. Edit the modules in the ``detectors``, adding lines to their ``init``
3685 functions where appropriate. Look for ``audit`` and ``react`` registrations
3686 on the ``issue`` class, and duplicate them for ``support``.
3688 5. Create a new sidebar box for the new support class. Duplicate the
3689 existing issues one, changing the ``issue`` class name to ``support``.
3691 6. Re-start your tracker and start using the new ``support`` class.
3694 Optionally, you might want to restrict the users able to access this new
3695 class to just the users with a new "SysAdmin" Role. To do this, we add
3696 some security declarations::
3698 db.security.addPermissionToRole('SysAdmin', 'View', 'support')
3699 db.security.addPermissionToRole('SysAdmin', 'Create', 'support')
3700 db.security.addPermissionToRole('SysAdmin', 'Edit', 'support')
3702 You would then (as an "admin" user) edit the details of the appropriate
3703 users, and add "SysAdmin" to their Roles list.
3705 Alternatively, you might want to change the Edit/View permissions granted
3706 for the ``issue`` class so that it's only available to users with the "System"
3707 or "Developer" Role, and then the new class you're adding is available to
3708 all with the "User" Role.
3711 Using External User Databases
3712 -----------------------------
3714 Using an external password validation source
3715 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3717 .. note:: You will need to either have an "admin" user in your external
3718 password source *or* have one of your regular users have
3719 the Admin Role assigned. If you need to assign the Role *after*
3720 making the changes below, you may use the ``roundup-admin``
3721 program to edit a user's details.
3723 We have a centrally-managed password changing system for our users. This
3724 results in a UN*X passwd-style file that we use for verification of
3725 users. Entries in the file consist of ``name:password`` where the
3726 password is encrypted using the standard UN*X ``crypt()`` function (see
3727 the ``crypt`` module in your Python distribution). An example entry
3728 would be::
3730 admin:aamrgyQfDFSHw
3732 Each user of Roundup must still have their information stored in the Roundup
3733 database - we just use the passwd file to check their password. To do this, we
3734 need to override the standard ``verifyPassword`` method defined in
3735 ``roundup.cgi.actions.LoginAction`` and register the new class. The
3736 following is added as ``externalpassword.py`` in the tracker ``extensions``
3737 directory::
3739 import os, crypt
3740 from roundup.cgi.actions import LoginAction
3742 class ExternalPasswordLoginAction(LoginAction):
3743 def verifyPassword(self, userid, password):
3744 '''Look through the file, line by line, looking for a
3745 name that matches.
3746 '''
3747 # get the user's username
3748 username = self.db.user.get(userid, 'username')
3750 # the passwords are stored in the "passwd.txt" file in the
3751 # tracker home
3752 file = os.path.join(self.db.config.TRACKER_HOME, 'passwd.txt')
3754 # see if we can find a match
3755 for ent in [line.strip().split(':') for line in
3756 open(file).readlines()]:
3757 if ent[0] == username:
3758 return crypt.crypt(password, ent[1][:2]) == ent[1]
3760 # user doesn't exist in the file
3761 return 0
3763 def init(instance):
3764 instance.registerAction('login', ExternalPasswordLoginAction)
3766 You should also remove the redundant password fields from the ``user.item``
3767 template.
3770 Using a UN*X passwd file as the user database
3771 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3773 On some systems the primary store of users is the UN*X passwd file. It
3774 holds information on users such as their username, real name, password
3775 and primary user group.
3777 Roundup can use this store as its primary source of user information,
3778 but it needs additional information too - email address(es), roundup
3779 Roles, vacation flags, roundup hyperdb item ids, etc. Also, "retired"
3780 users must still exist in the user database, unlike some passwd files in
3781 which the users are removed when they no longer have access to a system.
3783 To make use of the passwd file, we therefore synchronise between the two
3784 user stores. We also use the passwd file to validate the user logins, as
3785 described in the previous example, `using an external password
3786 validation source`_. We keep the user lists in sync using a fairly
3787 simple script that runs once a day, or several times an hour if more
3788 immediate access is needed. In short, it:
3790 1. parses the passwd file, finding usernames, passwords and real names,
3791 2. compares that list to the current roundup user list:
3793 a. entries no longer in the passwd file are *retired*
3794 b. entries with mismatching real names are *updated*
3795 c. entries only exist in the passwd file are *created*
3797 3. send an email to administrators to let them know what's been done.
3799 The retiring and updating are simple operations, requiring only a call
3800 to ``retire()`` or ``set()``. The creation operation requires more
3801 information though - the user's email address and their Roundup Roles.
3802 We're going to assume that the user's email address is the same as their
3803 login name, so we just append the domain name to that. The Roles are
3804 determined using the passwd group identifier - mapping their UN*X group
3805 to an appropriate set of Roles.
3807 The script to perform all this, broken up into its main components, is
3808 as follows. Firstly, we import the necessary modules and open the
3809 tracker we're to work on::
3811 import sys, os, smtplib
3812 from roundup import instance, date
3814 # open the tracker
3815 tracker_home = sys.argv[1]
3816 tracker = instance.open(tracker_home)
3818 Next we read in the *passwd* file from the tracker home::
3820 # read in the users from the "passwd.txt" file
3821 file = os.path.join(tracker_home, 'passwd.txt')
3822 users = [x.strip().split(':') for x in open(file).readlines()]
3824 Handle special users (those to ignore in the file, and those who don't
3825 appear in the file)::
3827 # users to not keep ever, pre-load with the users I know aren't
3828 # "real" users
3829 ignore = ['ekmmon', 'bfast', 'csrmail']
3831 # users to keep - pre-load with the roundup-specific users
3832 keep = ['comment_pool', 'network_pool', 'admin', 'dev-team',
3833 'cs_pool', 'anonymous', 'system_pool', 'automated']
3835 Now we map the UN*X group numbers to the Roles that users should have::
3837 roles = {
3838 '501': 'User,Tech', # tech
3839 '502': 'User', # finance
3840 '503': 'User,CSR', # customer service reps
3841 '504': 'User', # sales
3842 '505': 'User', # marketing
3843 }
3845 Now we do all the work. Note that the body of the script (where we have
3846 the tracker database open) is wrapped in a ``try`` / ``finally`` clause,
3847 so that we always close the database cleanly when we're finished. So, we
3848 now do all the work::
3850 # open the database
3851 db = tracker.open('admin')
3852 try:
3853 # store away messages to send to the tracker admins
3854 msg = []
3856 # loop over the users list read in from the passwd file
3857 for user,passw,uid,gid,real,home,shell in users:
3858 if user in ignore:
3859 # this user shouldn't appear in our tracker
3860 continue
3861 keep.append(user)
3862 try:
3863 # see if the user exists in the tracker
3864 uid = db.user.lookup(user)
3866 # yes, they do - now check the real name for correctness
3867 if real != db.user.get(uid, 'realname'):
3868 db.user.set(uid, realname=real)
3869 msg.append('FIX %s - %s'%(user, real))
3870 except KeyError:
3871 # nope, the user doesn't exist
3872 db.user.create(username=user, realname=real,
3873 address='%s@ekit-inc.com'%user, roles=roles[gid])
3874 msg.append('ADD %s - %s (%s)'%(user, real, roles[gid]))
3876 # now check that all the users in the tracker are also in our
3877 # "keep" list - retire those who aren't
3878 for uid in db.user.list():
3879 user = db.user.get(uid, 'username')
3880 if user not in keep:
3881 db.user.retire(uid)
3882 msg.append('RET %s'%user)
3884 # if we did work, then send email to the tracker admins
3885 if msg:
3886 # create the email
3887 msg = '''Subject: %s user database maintenance
3889 %s
3890 '''%(db.config.TRACKER_NAME, '\n'.join(msg))
3892 # send the email
3893 smtp = smtplib.SMTP(db.config.MAILHOST)
3894 addr = db.config.ADMIN_EMAIL
3895 smtp.sendmail(addr, addr, msg)
3897 # now we're done - commit the changes
3898 db.commit()
3899 finally:
3900 # always close the database cleanly
3901 db.close()
3903 And that's it!
3906 Using an LDAP database for user information
3907 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3909 A script that reads users from an LDAP store using
3910 http://python-ldap.sf.net/ and then compares the list to the users in the
3911 roundup user database would be pretty easy to write. You'd then have it run
3912 once an hour / day (or on demand if you can work that into your LDAP store
3913 workflow). See the example `Using a UN*X passwd file as the user database`_
3914 for more information about doing this.
3916 To authenticate off the LDAP store (rather than using the passwords in the
3917 Roundup user database) you'd use the same python-ldap module inside an
3918 extension to the cgi interface. You'd do this by overriding the method called
3919 ``verifyPassword`` on the ``LoginAction`` class in your tracker's
3920 ``extensions`` directory (see `using an external password validation
3921 source`_). The method is implemented by default as::
3923 def verifyPassword(self, userid, password):
3924 ''' Verify the password that the user has supplied
3925 '''
3926 stored = self.db.user.get(self.userid, 'password')
3927 if password == stored:
3928 return 1
3929 if not password and not stored:
3930 return 1
3931 return 0
3933 So you could reimplement this as something like::
3935 def verifyPassword(self, userid, password):
3936 ''' Verify the password that the user has supplied
3937 '''
3938 # look up some unique LDAP information about the user
3939 username = self.db.user.get(self.userid, 'username')
3940 # now verify the password supplied against the LDAP store
3943 Changes to Tracker Behaviour
3944 ----------------------------
3946 Preventing SPAM
3947 ~~~~~~~~~~~~~~~
3949 The following detector code may be installed in your tracker's
3950 ``detectors`` directory. It will block any messages being created that
3951 have HTML attachments (a very common vector for spam and phishing)
3952 and any messages that have more than 2 HTTP URLs in them. Just copy
3953 the following into ``detectors/anti_spam.py`` in your tracker::
3955 from roundup.exceptions import Reject
3957 def reject_html(db, cl, nodeid, newvalues):
3958 if newvalues['type'] == 'text/html':
3959 raise Reject, 'not allowed'
3961 def reject_manylinks(db, cl, nodeid, newvalues):
3962 content = newvalues['content']
3963 if content.count('http://') > 2:
3964 raise Reject, 'not allowed'
3966 def init(db):
3967 db.file.audit('create', reject_html)
3968 db.msg.audit('create', reject_manylinks)
3970 You may also wish to block image attachments if your tracker does not
3971 need that ability::
3973 if newvalues['type'].startswith('image/'):
3974 raise Reject, 'not allowed'
3977 Stop "nosy" messages going to people on vacation
3978 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3980 When users go on vacation and set up vacation email bouncing, you'll
3981 start to see a lot of messages come back through Roundup "Fred is on
3982 vacation". Not very useful, and relatively easy to stop.
3984 1. add a "vacation" flag to your users::
3986 user = Class(db, "user",
3987 username=String(), password=Password(),
3988 address=String(), realname=String(),
3989 phone=String(), organisation=String(),
3990 alternate_addresses=String(),
3991 roles=String(), queries=Multilink("query"),
3992 vacation=Boolean())
3994 2. So that users may edit the vacation flags, add something like the
3995 following to your ``user.item`` template::
3997 <tr>
3998 <th>On Vacation</th>
3999 <td tal:content="structure context/vacation/field">vacation</td>
4000 </tr>
4002 3. edit your detector ``nosyreactor.py`` so that the ``nosyreaction()``
4003 consists of::
4005 def nosyreaction(db, cl, nodeid, oldvalues):
4006 users = db.user
4007 messages = db.msg
4008 # send a copy of all new messages to the nosy list
4009 for msgid in determineNewMessages(cl, nodeid, oldvalues):
4010 try:
4011 # figure the recipient ids
4012 sendto = []
4013 seen_message = {}
4014 recipients = messages.get(msgid, 'recipients')
4015 for recipid in messages.get(msgid, 'recipients'):
4016 seen_message[recipid] = 1
4018 # figure the author's id, and indicate they've received
4019 # the message
4020 authid = messages.get(msgid, 'author')
4022 # possibly send the message to the author, as long as
4023 # they aren't anonymous
4024 if (db.config.MESSAGES_TO_AUTHOR == 'yes' and
4025 users.get(authid, 'username') != 'anonymous'):
4026 sendto.append(authid)
4027 seen_message[authid] = 1
4029 # now figure the nosy people who weren't recipients
4030 nosy = cl.get(nodeid, 'nosy')
4031 for nosyid in nosy:
4032 # Don't send nosy mail to the anonymous user (that
4033 # user shouldn't appear in the nosy list, but just
4034 # in case they do...)
4035 if users.get(nosyid, 'username') == 'anonymous':
4036 continue
4037 # make sure they haven't seen the message already
4038 if not seen_message.has_key(nosyid):
4039 # send it to them
4040 sendto.append(nosyid)
4041 recipients.append(nosyid)
4043 # generate a change note
4044 if oldvalues:
4045 note = cl.generateChangeNote(nodeid, oldvalues)
4046 else:
4047 note = cl.generateCreateNote(nodeid)
4049 # we have new recipients
4050 if sendto:
4051 # filter out the people on vacation
4052 sendto = [i for i in sendto
4053 if not users.get(i, 'vacation', 0)]
4055 # map userids to addresses
4056 sendto = [users.get(i, 'address') for i in sendto]
4058 # update the message's recipients list
4059 messages.set(msgid, recipients=recipients)
4061 # send the message
4062 cl.send_message(nodeid, msgid, note, sendto)
4063 except roundupdb.MessageSendError, message:
4064 raise roundupdb.DetectorError, message
4066 Note that this is the standard nosy reaction code, with the small
4067 addition of::
4069 # filter out the people on vacation
4070 sendto = [i for i in sendto if not users.get(i, 'vacation', 0)]
4072 which filters out the users that have the vacation flag set to true.
4074 Adding in state transition control
4075 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4077 Sometimes tracker admins want to control the states to which users may
4078 move issues. You can do this by following these steps:
4080 1. make "status" a required variable. This is achieved by adding the
4081 following to the top of the form in the ``issue.item.html``
4082 template::
4084 <input type="hidden" name="@required" value="status">
4086 This will force users to select a status.
4088 2. add a Multilink property to the status class::
4090 stat = Class(db, "status", ... , transitions=Multilink('status'),
4091 ...)
4093 and then edit the statuses already created, either:
4095 a. through the web using the class list -> status class editor, or
4096 b. using the ``roundup-admin`` "set" command.
4098 3. add an auditor module ``checktransition.py`` in your tracker's
4099 ``detectors`` directory, for example::
4101 def checktransition(db, cl, nodeid, newvalues):
4102 ''' Check that the desired transition is valid for the "status"
4103 property.
4104 '''
4105 if not newvalues.has_key('status'):
4106 return
4107 current = cl.get(nodeid, 'status')
4108 new = newvalues['status']
4109 if new == current:
4110 return
4111 ok = db.status.get(current, 'transitions')
4112 if new not in ok:
4113 raise ValueError, 'Status not allowed to move from "%s" to "%s"'%(
4114 db.status.get(current, 'name'), db.status.get(new, 'name'))
4116 def init(db):
4117 db.issue.audit('set', checktransition)
4119 4. in the ``issue.item.html`` template, change the status editing bit
4120 from::
4122 <th>Status</th>
4123 <td tal:content="structure context/status/menu">status</td>
4125 to::
4127 <th>Status</th>
4128 <td>
4129 <select tal:condition="context/id" name="status">
4130 <tal:block tal:define="ok context/status/transitions"
4131 tal:repeat="state db/status/list">
4132 <option tal:condition="python:state.id in ok"
4133 tal:attributes="
4134 value state/id;
4135 selected python:state.id == context.status.id"
4136 tal:content="state/name"></option>
4137 </tal:block>
4138 </select>
4139 <tal:block tal:condition="not:context/id"
4140 tal:replace="structure context/status/menu" />
4141 </td>
4143 which displays only the allowed status to transition to.
4146 Blocking issues that depend on other issues
4147 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4149 We needed the ability to mark certain issues as "blockers" - that is,
4150 they can't be resolved until another issue (the blocker) they rely on is
4151 resolved. To achieve this:
4153 1. Create a new property on the ``issue`` class:
4154 ``blockers=Multilink("issue")``. To do this, edit the definition of
4155 this class in your tracker's ``schema.py`` file. Change this::
4157 issue = IssueClass(db, "issue",
4158 assignedto=Link("user"), keyword=Multilink("keyword"),
4159 priority=Link("priority"), status=Link("status"))
4161 to this, adding the blockers entry::
4163 issue = IssueClass(db, "issue",
4164 blockers=Multilink("issue"),
4165 assignedto=Link("user"), keyword=Multilink("keyword"),
4166 priority=Link("priority"), status=Link("status"))
4168 2. Add the new ``blockers`` property to the ``issue.item.html`` edit
4169 page, using something like::
4171 <th>Waiting On</th>
4172 <td>
4173 <span tal:replace="structure python:context.blockers.field(showid=1,
4174 size=20)" />
4175 <span tal:replace="structure python:db.issue.classhelp('id,title',
4176 property='blockers')" />
4177 <span tal:condition="context/blockers"
4178 tal:repeat="blk context/blockers">
4179 <br>View: <a tal:attributes="href string:issue${blk/id}"
4180 tal:content="blk/id"></a>
4181 </span>
4182 </td>
4184 You'll need to fiddle with your item page layout to find an
4185 appropriate place to put it - I'll leave that fun part up to you.
4186 Just make sure it appears in the first table, possibly somewhere near
4187 the "superseders" field.
4189 3. Create a new detector module (see below) which enforces the rules:
4191 - issues may not be resolved if they have blockers
4192 - when a blocker is resolved, it's removed from issues it blocks
4194 The contents of the detector should be something like this::
4197 def blockresolution(db, cl, nodeid, newvalues):
4198 ''' If the issue has blockers, don't allow it to be resolved.
4199 '''
4200 if nodeid is None:
4201 blockers = []
4202 else:
4203 blockers = cl.get(nodeid, 'blockers')
4204 blockers = newvalues.get('blockers', blockers)
4206 # don't do anything if there's no blockers or the status hasn't
4207 # changed
4208 if not blockers or not newvalues.has_key('status'):
4209 return
4211 # get the resolved state ID
4212 resolved_id = db.status.lookup('resolved')
4214 # format the info
4215 u = db.config.TRACKER_WEB
4216 s = ', '.join(['<a href="%sissue%s">%s</a>'%(
4217 u,id,id) for id in blockers])
4218 if len(blockers) == 1:
4219 s = 'issue %s is'%s
4220 else:
4221 s = 'issues %s are'%s
4223 # ok, see if we're trying to resolve
4224 if newvalues['status'] == resolved_id:
4225 raise ValueError, "This issue can't be resolved until %s resolved."%s
4228 def resolveblockers(db, cl, nodeid, oldvalues):
4229 ''' When we resolve an issue that's a blocker, remove it from the
4230 blockers list of the issue(s) it blocks.
4231 '''
4232 newstatus = cl.get(nodeid,'status')
4234 # no change?
4235 if oldvalues.get('status', None) == newstatus:
4236 return
4238 resolved_id = db.status.lookup('resolved')
4240 # interesting?
4241 if newstatus != resolved_id:
4242 return
4244 # yes - find all the blocked issues, if any, and remove me from
4245 # their blockers list
4246 issues = cl.find(blockers=nodeid)
4247 for issueid in issues:
4248 blockers = cl.get(issueid, 'blockers')
4249 if nodeid in blockers:
4250 blockers.remove(nodeid)
4251 cl.set(issueid, blockers=blockers)
4253 def init(db):
4254 # might, in an obscure situation, happen in a create
4255 db.issue.audit('create', blockresolution)
4256 db.issue.audit('set', blockresolution)
4258 # can only happen on a set
4259 db.issue.react('set', resolveblockers)
4261 Put the above code in a file called "blockers.py" in your tracker's
4262 "detectors" directory.
4264 4. Finally, and this is an optional step, modify the tracker web page
4265 URLs so they filter out issues with any blockers. You do this by
4266 adding an additional filter on "blockers" for the value "-1". For
4267 example, the existing "Show All" link in the "page" template (in the
4268 tracker's "html" directory) looks like this::
4270 <a href="#"
4271 tal:attributes="href python:request.indexargs_url('issue', {
4272 '@sort': '-activity',
4273 '@group': 'priority',
4274 '@filter': 'status',
4275 '@columns': columns_showall,
4276 '@search_text': '',
4277 'status': status_notresolved,
4278 '@dispname': i18n.gettext('Show All'),
4279 })"
4280 i18n:translate="">Show All</a><br>
4282 modify it to add the "blockers" info to the URL (note, both the
4283 "@filter" *and* "blockers" values must be specified)::
4285 <a href="#"
4286 tal:attributes="href python:request.indexargs_url('issue', {
4287 '@sort': '-activity',
4288 '@group': 'priority',
4289 '@filter': 'status,blockers',
4290 '@columns': columns_showall,
4291 '@search_text': '',
4292 'status': status_notresolved,
4293 'blockers': '-1',
4294 '@dispname': i18n.gettext('Show All'),
4295 })"
4296 i18n:translate="">Show All</a><br>
4298 The above examples are line-wrapped on the trailing & and should
4299 be unwrapped.
4301 That's it. You should now be able to set blockers on your issues. Note
4302 that if you want to know whether an issue has any other issues dependent
4303 on it (i.e. it's in their blockers list) you can look at the journal
4304 history at the bottom of the issue page - look for a "link" event to
4305 another issue's "blockers" property.
4307 Add users to the nosy list based on the keyword
4308 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4310 Let's say we need the ability to automatically add users to the nosy
4311 list based
4312 on the occurance of a keyword. Every user should be allowed to edit their
4313 own list of keywords for which they want to be added to the nosy list.
4315 Below, we'll show that this change can be done with minimal
4316 understanding of the Roundup system, using only copy and paste.
4318 This requires three changes to the tracker: a change in the database to
4319 allow per-user recording of the lists of keywords for which he wants to
4320 be put on the nosy list, a change in the user view allowing them to edit
4321 this list of keywords, and addition of an auditor which updates the nosy
4322 list when a keyword is set.
4324 Adding the nosy keyword list
4325 ::::::::::::::::::::::::::::
4327 The change to make in the database, is that for any user there should be a list
4328 of keywords for which he wants to be put on the nosy list. Adding a
4329 ``Multilink`` of ``keyword`` seems to fullfill this. As such, all that has to
4330 be done is to add a new field to the definition of ``user`` within the file
4331 ``schema.py``. We will call this new field ``nosy_keywords``, and the updated
4332 definition of user will be::
4334 user = Class(db, "user",
4335 username=String(), password=Password(),
4336 address=String(), realname=String(),
4337 phone=String(), organisation=String(),
4338 alternate_addresses=String(),
4339 queries=Multilink('query'), roles=String(),
4340 timezone=String(),
4341 nosy_keywords=Multilink('keyword'))
4343 Changing the user view to allow changing the nosy keyword list
4344 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
4346 We want any user to be able to change the list of keywords for which
4347 he will by default be added to the nosy list. We choose to add this
4348 to the user view, as is generated by the file ``html/user.item.html``.
4349 We can easily
4350 see that the keyword field in the issue view has very similar editing
4351 requirements as our nosy keywords, both being lists of keywords. As
4352 such, we look for Keywords in ``issue.item.html``, and extract the
4353 associated parts from there. We add this to ``user.item.html`` at the
4354 bottom of the list of viewed items (i.e. just below the 'Alternate
4355 E-mail addresses' in the classic template)::
4357 <tr>
4358 <th>Nosy Keywords</th>
4359 <td>
4360 <span tal:replace="structure context/nosy_keywords/field" />
4361 <span tal:replace="structure python:db.keyword.classhelp(property='nosy_keywords')" />
4362 </td>
4363 </tr>
4366 Addition of an auditor to update the nosy list
4367 ::::::::::::::::::::::::::::::::::::::::::::::
4369 The more difficult part is the logic to add
4370 the users to the nosy list when required.
4371 We choose to perform this action whenever the keywords on an
4372 item are set (this includes the creation of items).
4373 Here we choose to start out with a copy of the
4374 ``detectors/nosyreaction.py`` detector, which we copy to the file
4375 ``detectors/nosy_keyword_reaction.py``.
4376 This looks like a good start as it also adds users
4377 to the nosy list. A look through the code reveals that the
4378 ``nosyreaction`` function actually sends the e-mail.
4379 We don't need this. Therefore, we can change the ``init`` function to::
4381 def init(db):
4382 db.issue.audit('create', update_kw_nosy)
4383 db.issue.audit('set', update_kw_nosy)
4385 After that, we rename the ``updatenosy`` function to ``update_kw_nosy``.
4386 The first two blocks of code in that function relate to setting
4387 ``current`` to a combination of the old and new nosy lists. This
4388 functionality is left in the new auditor. The following block of
4389 code, which handled adding the assignedto user(s) to the nosy list in
4390 ``updatenosy``, should be replaced by a block of code to add the
4391 interested users to the nosy list. We choose here to loop over all
4392 new keywords, than looping over all users,
4393 and assign the user to the nosy list when the keyword occurs in the user's
4394 ``nosy_keywords``. The next part in ``updatenosy`` -- adding the author
4395 and/or recipients of a message to the nosy list -- is obviously not
4396 relevant here and is thus deleted from the new auditor. The last
4397 part, copying the new nosy list to ``newvalues``, can stay as is.
4398 This results in the following function::
4400 def update_kw_nosy(db, cl, nodeid, newvalues):
4401 '''Update the nosy list for changes to the keywords
4402 '''
4403 # nodeid will be None if this is a new node
4404 current = {}
4405 if nodeid is None:
4406 ok = ('new', 'yes')
4407 else:
4408 ok = ('yes',)
4409 # old node, get the current values from the node if they haven't
4410 # changed
4411 if not newvalues.has_key('nosy'):
4412 nosy = cl.get(nodeid, 'nosy')
4413 for value in nosy:
4414 if not current.has_key(value):
4415 current[value] = 1
4417 # if the nosy list changed in this transaction, init from the new value
4418 if newvalues.has_key('nosy'):
4419 nosy = newvalues.get('nosy', [])
4420 for value in nosy:
4421 if not db.hasnode('user', value):
4422 continue
4423 if not current.has_key(value):
4424 current[value] = 1
4426 # add users with keyword in nosy_keywords to the nosy list
4427 if newvalues.has_key('keyword') and newvalues['keyword'] is not None:
4428 keyword_ids = newvalues['keyword']
4429 for keyword in keyword_ids:
4430 # loop over all users,
4431 # and assign user to nosy when keyword in nosy_keywords
4432 for user_id in db.user.list():
4433 nosy_kw = db.user.get(user_id, "nosy_keywords")
4434 found = 0
4435 for kw in nosy_kw:
4436 if kw == keyword:
4437 found = 1
4438 if found:
4439 current[user_id] = 1
4441 # that's it, save off the new nosy list
4442 newvalues['nosy'] = current.keys()
4444 These two function are the only ones needed in the file.
4446 TODO: update this example to use the ``find()`` Class method.
4448 Caveats
4449 :::::::
4451 A few problems with the design here can be noted:
4453 Multiple additions
4454 When a user, after automatic selection, is manually removed
4455 from the nosy list, he is added to the nosy list again when the
4456 keyword list of the issue is updated. A better design might be
4457 to only check which keywords are new compared to the old list
4458 of keywords, and only add users when they have indicated
4459 interest on a new keyword.
4461 The code could also be changed to only trigger on the ``create()``
4462 event, rather than also on the ``set()`` event, thus only setting
4463 the nosy list when the issue is created.
4465 Scalability
4466 In the auditor, there is a loop over all users. For a site with
4467 only few users this will pose no serious problem; however, with
4468 many users this will be a serious performance bottleneck.
4469 A way out would be to link from the keywords to the users who
4470 selected these keywords as nosy keywords. This will eliminate the
4471 loop over all users.
4473 Changes to Security and Permissions
4474 -----------------------------------
4476 Restricting the list of users that are assignable to a task
4477 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4479 1. In your tracker's ``schema.py``, create a new Role, say "Developer"::
4481 db.security.addRole(name='Developer', description='A developer')
4483 2. Just after that, create a new Permission, say "Fixer", specific to
4484 "issue"::
4486 p = db.security.addPermission(name='Fixer', klass='issue',
4487 description='User is allowed to be assigned to fix issues')
4489 3. Then assign the new Permission to your "Developer" Role::
4491 db.security.addPermissionToRole('Developer', p)
4493 4. In the issue item edit page (``html/issue.item.html`` in your tracker
4494 directory), use the new Permission in restricting the "assignedto"
4495 list::
4497 <select name="assignedto">
4498 <option value="-1">- no selection -</option>
4499 <tal:block tal:repeat="user db/user/list">
4500 <option tal:condition="python:user.hasPermission(
4501 'Fixer', context._classname)"
4502 tal:attributes="
4503 value user/id;
4504 selected python:user.id == context.assignedto"
4505 tal:content="user/realname"></option>
4506 </tal:block>
4507 </select>
4509 For extra security, you may wish to setup an auditor to enforce the
4510 Permission requirement (install this as ``assignedtoFixer.py`` in your
4511 tracker ``detectors`` directory)::
4513 def assignedtoMustBeFixer(db, cl, nodeid, newvalues):
4514 ''' Ensure the assignedto value in newvalues is used with the
4515 Fixer Permission
4516 '''
4517 if not newvalues.has_key('assignedto'):
4518 # don't care
4519 return
4521 # get the userid
4522 userid = newvalues['assignedto']
4523 if not db.security.hasPermission('Fixer', userid, cl.classname):
4524 raise ValueError, 'You do not have permission to edit %s'%cl.classname
4526 def init(db):
4527 db.issue.audit('set', assignedtoMustBeFixer)
4528 db.issue.audit('create', assignedtoMustBeFixer)
4530 So now, if an edit action attempts to set "assignedto" to a user that
4531 doesn't have the "Fixer" Permission, the error will be raised.
4534 Users may only edit their issues
4535 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4537 In this case, users registering themselves are granted Provisional
4538 access, meaning they
4539 have access to edit the issues they submit, but not others. We create a new
4540 Role called "Provisional User" which is granted to newly-registered users,
4541 and has limited access. One of the Permissions they have is the new "Edit
4542 Own" on issues (regular users have "Edit".)
4544 First up, we create the new Role and Permission structure in
4545 ``schema.py``::
4547 #
4548 # New users not approved by the admin
4549 #
4550 db.security.addRole(name='Provisional User',
4551 description='New user registered via web or email')
4553 # These users need to be able to view and create issues but only edit
4554 # and view their own
4555 db.security.addPermissionToRole('Provisional User', 'Create', 'issue')
4556 def own_issue(db, userid, itemid):
4557 '''Determine whether the userid matches the creator of the issue.'''
4558 return userid == db.issue.get(itemid, 'creator')
4559 p = db.security.addPermission(name='Edit', klass='issue',
4560 check=own_issue, description='Can only edit own issues')
4561 db.security.addPermissionToRole('Provisional User', p)
4562 p = db.security.addPermission(name='View', klass='issue',
4563 check=own_issue, description='Can only view own issues')
4564 db.security.addPermissionToRole('Provisional User', p)
4566 # Assign the Permissions for issue-related classes
4567 for cl in 'file', 'msg', 'query', 'keyword':
4568 db.security.addPermissionToRole('Provisional User', 'View', cl)
4569 db.security.addPermissionToRole('Provisional User', 'Edit', cl)
4570 db.security.addPermissionToRole('Provisional User', 'Create', cl)
4571 for cl in 'priority', 'status':
4572 db.security.addPermissionToRole('Provisional User', 'View', cl)
4574 # and give the new users access to the web and email interface
4575 db.security.addPermissionToRole('Provisional User', 'Web Access')
4576 db.security.addPermissionToRole('Provisional User', 'Email Access')
4578 # make sure they can view & edit their own user record
4579 def own_record(db, userid, itemid):
4580 '''Determine whether the userid matches the item being accessed.'''
4581 return userid == itemid
4582 p = db.security.addPermission(name='View', klass='user', check=own_record,
4583 description="User is allowed to view their own user details")
4584 db.security.addPermissionToRole('Provisional User', p)
4585 p = db.security.addPermission(name='Edit', klass='user', check=own_record,
4586 description="User is allowed to edit their own user details")
4587 db.security.addPermissionToRole('Provisional User', p)
4589 Then, in ``config.ini``, we change the Role assigned to newly-registered
4590 users, replacing the existing ``'User'`` values::
4592 [main]
4593 ...
4594 new_web_user_roles = 'Provisional User'
4595 new_email_user_roles = 'Provisional User'
4598 All users may only view and edit issues, files and messages they create
4599 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4601 Replace the standard "classic" tracker View and Edit Permission assignments
4602 for the "issue", "file" and "msg" classes with the following::
4604 def checker(klass):
4605 def check(db, userid, itemid, klass=klass):
4606 return db.getclass(klass).get(itemid, 'creator') == userid
4607 return check
4608 for cl in 'issue', 'file', 'msg':
4609 p = db.security.addPermission(name='View', klass=cl,
4610 check=checker(cl))
4611 db.security.addPermissionToRole('User', p)
4612 p = db.security.addPermission(name='Edit', klass=cl,
4613 check=checker(cl))
4614 db.security.addPermissionToRole('User', p)
4615 db.security.addPermissionToRole('User', 'Create', cl)
4618 Moderating user registration
4619 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4621 You could set up new-user moderation in a public tracker by:
4623 1. creating a new highly-restricted user role "Pending",
4624 2. set the config new_web_user_roles and/or new_email_user_roles to that
4625 role,
4626 3. have an auditor that emails you when new users are created with that
4627 role using roundup.mailer
4628 4. edit the role to "User" for valid users.
4630 Some simple javascript might help in the last step. If you have high volume
4631 you could search for all currently-Pending users and do a bulk edit of all
4632 their roles at once (again probably with some simple javascript help).
4635 Changes to the Web User Interface
4636 ---------------------------------
4638 Adding action links to the index page
4639 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4641 Add a column to the ``item.index.html`` template.
4643 Resolving the issue::
4645 <a tal:attributes="href
4646 string:issue${i/id}?:status=resolved&:action=edit">resolve</a>
4648 "Take" the issue::
4650 <a tal:attributes="href
4651 string:issue${i/id}?:assignedto=${request/user/id}&:action=edit">take</a>
4653 ... and so on.
4655 Colouring the rows in the issue index according to priority
4656 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4658 A simple ``tal:attributes`` statement will do the bulk of the work here. In
4659 the ``issue.index.html`` template, add this to the ``<tr>`` that
4660 displays the rows of data::
4662 <tr tal:attributes="class string:priority-${i/priority/plain}">
4664 and then in your stylesheet (``style.css``) specify the colouring for the
4665 different priorities, as follows::
4667 tr.priority-critical td {
4668 background-color: red;
4669 }
4671 tr.priority-urgent td {
4672 background-color: orange;
4673 }
4675 and so on, with far less offensive colours :)
4677 Editing multiple items in an index view
4678 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4680 To edit the status of all items in the item index view, edit the
4681 ``issue.item.html``:
4683 1. add a form around the listing table (separate from the existing
4684 index-page form), so at the top it reads::
4686 <form method="POST" tal:attributes="action request/classname">
4687 <table class="list">
4689 and at the bottom of that table::
4691 </table>
4692 </form
4694 making sure you match the ``</table>`` from the list table, not the
4695 navigation table or the subsequent form table.
4697 2. in the display for the issue property, change::
4699 <td tal:condition="request/show/status"
4700 tal:content="python:i.status.plain() or default"> </td>
4702 to::
4704 <td tal:condition="request/show/status"
4705 tal:content="structure i/status/field"> </td>
4707 this will result in an edit field for the status property.
4709 3. after the ``tal:block`` which lists the index items (marked by
4710 ``tal:repeat="i batch"``) add a new table row::
4712 <tr>
4713 <td tal:attributes="colspan python:len(request.columns)">
4714 <input type="submit" value=" Save Changes ">
4715 <input type="hidden" name="@action" value="edit">
4716 <tal:block replace="structure request/indexargs_form" />
4717 </td>
4718 </tr>
4720 which gives us a submit button, indicates that we are performing an edit
4721 on any changed statuses. The final ``tal:block`` will make sure that the
4722 current index view parameters (filtering, columns, etc) will be used in
4723 rendering the next page (the results of the editing).
4726 Displaying only message summaries in the issue display
4727 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4729 Alter the ``issue.item`` template section for messages to::
4731 <table class="messages" tal:condition="context/messages">
4732 <tr><th colspan="5" class="header">Messages</th></tr>
4733 <tr tal:repeat="msg context/messages">
4734 <td><a tal:attributes="href string:msg${msg/id}"
4735 tal:content="string:msg${msg/id}"></a></td>
4736 <td tal:content="msg/author">author</td>
4737 <td class="date" tal:content="msg/date/pretty">date</td>
4738 <td tal:content="msg/summary">summary</td>
4739 <td>
4740 <a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">
4741 remove</a>
4742 </td>
4743 </tr>
4744 </table>
4747 Enabling display of either message summaries or the entire messages
4748 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4750 This is pretty simple - all we need to do is copy the code from the
4751 example `displaying only message summaries in the issue display`_ into
4752 our template alongside the summary display, and then introduce a switch
4753 that shows either the one or the other. We'll use a new form variable,
4754 ``@whole_messages`` to achieve this::
4756 <table class="messages" tal:condition="context/messages">
4757 <tal:block tal:condition="not:request/form/@whole_messages/value | python:0">
4758 <tr><th colspan="3" class="header">Messages</th>
4759 <th colspan="2" class="header">
4760 <a href="?@whole_messages=yes">show entire messages</a>
4761 </th>
4762 </tr>
4763 <tr tal:repeat="msg context/messages">
4764 <td><a tal:attributes="href string:msg${msg/id}"
4765 tal:content="string:msg${msg/id}"></a></td>
4766 <td tal:content="msg/author">author</td>
4767 <td class="date" tal:content="msg/date/pretty">date</td>
4768 <td tal:content="msg/summary">summary</td>
4769 <td>
4770 <a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">remove</a>
4771 </td>
4772 </tr>
4773 </tal:block>
4775 <tal:block tal:condition="request/form/@whole_messages/value | python:0">
4776 <tr><th colspan="2" class="header">Messages</th>
4777 <th class="header">
4778 <a href="?@whole_messages=">show only summaries</a>
4779 </th>
4780 </tr>
4781 <tal:block tal:repeat="msg context/messages">
4782 <tr>
4783 <th tal:content="msg/author">author</th>
4784 <th class="date" tal:content="msg/date/pretty">date</th>
4785 <th style="text-align: right">
4786 (<a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">remove</a>)
4787 </th>
4788 </tr>
4789 <tr><td colspan="3" tal:content="msg/content"></td></tr>
4790 </tal:block>
4791 </tal:block>
4792 </table>
4795 Setting up a "wizard" (or "druid") for controlled adding of issues
4796 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4798 1. Set up the page templates you wish to use for data input. My wizard
4799 is going to be a two-step process: first figuring out what category
4800 of issue the user is submitting, and then getting details specific to
4801 that category. The first page includes a table of help, explaining
4802 what the category names mean, and then the core of the form::
4804 <form method="POST" onSubmit="return submit_once()"
4805 enctype="multipart/form-data">
4806 <input type="hidden" name="@template" value="add_page1">
4807 <input type="hidden" name="@action" value="page1_submit">
4809 <strong>Category:</strong>
4810 <tal:block tal:replace="structure context/category/menu" />
4811 <input type="submit" value="Continue">
4812 </form>
4814 The next page has the usual issue entry information, with the
4815 addition of the following form fragments::
4817 <form method="POST" onSubmit="return submit_once()"
4818 enctype="multipart/form-data"
4819 tal:condition="context/is_edit_ok"
4820 tal:define="cat request/form/category/value">
4822 <input type="hidden" name="@template" value="add_page2">
4823 <input type="hidden" name="@required" value="title">
4824 <input type="hidden" name="category" tal:attributes="value cat">
4825 .
4826 .
4827 .
4828 </form>
4830 Note that later in the form, I use the value of "cat" to decide which
4831 form elements should be displayed. For example::
4833 <tal:block tal:condition="python:cat in '6 10 13 14 15 16 17'.split()">
4834 <tr>
4835 <th>Operating System</th>
4836 <td tal:content="structure context/os/field"></td>
4837 </tr>
4838 <tr>
4839 <th>Web Browser</th>
4840 <td tal:content="structure context/browser/field"></td>
4841 </tr>
4842 </tal:block>
4844 ... the above section will only be displayed if the category is one
4845 of 6, 10, 13, 14, 15, 16 or 17.
4847 3. Determine what actions need to be taken between the pages - these are
4848 usually to validate user choices and determine what page is next. Now encode
4849 those actions in a new ``Action`` class (see `defining new web actions`_)::
4851 from roundup.cgi.actions import Action
4853 class Page1SubmitAction(Action):
4854 def handle(self):
4855 ''' Verify that the user has selected a category, and then move
4856 on to page 2.
4857 '''
4858 category = self.form['category'].value
4859 if category == '-1':
4860 self.error_message.append('You must select a category of report')
4861 return
4862 # everything's ok, move on to the next page
4863 self.template = 'add_page2'
4865 def init(instance):
4866 instance.registerAction('page1_submit', Page1SubmitAction)
4868 4. Use the usual "new" action as the ``@action`` on the final page, and
4869 you're done (the standard context/submit method can do this for you).
4872 Debugging Trackers
4873 ==================
4875 There are three switches in tracker configs that turn on debugging in
4876 Roundup:
4878 1. web :: debug
4879 2. mail :: debug
4880 3. logging :: level
4882 See the config.ini file or the `tracker configuration`_ section above for
4883 more information.
4885 Additionally, the ``roundup-server.py`` script has its own debugging mode
4886 in which it reloads edited templates immediately when they are changed,
4887 rather than requiring a web server restart.
4890 .. _`design documentation`: design.html
4891 .. _`developer's guide`: developers.html