1 :tocdepth: 2
3 ===================
4 Customising Roundup
5 ===================
7 :Version: $Revision: 1.223 $
9 .. This document borrows from the ZopeBook section on ZPT. The original is at:
10 http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
12 .. contents::
13 :depth: 1
15 What You Can Do
16 ===============
18 Before you get too far, it's probably worth having a quick read of the Roundup
19 `design documentation`_.
21 Customisation of Roundup can take one of six forms:
23 1. `tracker configuration`_ changes
24 2. database, or `tracker schema`_ changes
25 3. "definition" class `database content`_ changes
26 4. behavioural changes, through detectors_
27 5. `security / access controls`_
28 6. change the `web interface`_
30 The third case is special because it takes two distinctly different forms
31 depending upon whether the tracker has been initialised or not. The other two
32 may be done at any time, before or after tracker initialisation. Yes, this
33 includes adding or removing properties from classes.
36 Trackers in a Nutshell
37 ======================
39 Trackers have the following structure:
41 =================== ========================================================
42 Tracker File Description
43 =================== ========================================================
44 config.ini Holds the basic `tracker configuration`_
45 schema.py Holds the `tracker schema`_
46 initial_data.py Holds any data to be entered into the database when the
47 tracker is initialised.
48 db/ Holds the tracker's database
49 db/files/ Holds the tracker's upload files and messages
50 db/backend_name Names the database back-end for the tracker
51 detectors/ Auditors and reactors for this tracker
52 extensions/ Additional web actions and templating utilities.
53 html/ Web interface templates, images and style sheets
54 lib/ optional common imports for detectors and extensions
55 =================== ========================================================
58 Tracker Configuration
59 =====================
61 The ``config.ini`` located in your tracker home contains the basic
62 configuration for the web and e-mail components of roundup's interfaces.
64 Changes to the data captured by your tracker is controlled by the `tracker
65 schema`_. Some configuration is also performed using permissions - see the
66 `security / access controls`_ section. For example, to allow users to
67 automatically register through the email interface, you must grant the
68 "Anonymous" Role the "Email Access" Permission.
70 The following is taken from the `Python Library Reference`__ (May 20, 2004)
71 section "ConfigParser -- Configuration file parser":
73 The configuration file consists of sections, led by a "[section]" header
74 and followed by "name = value" entries, with line continuations on a
75 newline with leading whitespace. Note that leading whitespace is removed
76 from values. The optional values can contain format strings which
77 refer to other values in the same section. Lines beginning with "#" or ";"
78 are ignored and may be used to provide comments.
80 For example::
82 [My Section]
83 foodir = %(dir)s/whatever
84 dir = frob
86 would resolve the "%(dir)s" to the value of "dir" ("frob" in this case)
87 resulting in "foodir" being "frob/whatever".
89 __ http://docs.python.org/lib/module-ConfigParser.html
91 Section **main**
92 database -- ``db``
93 Database directory path. The path may be either absolute or relative
94 to the directory containig this config file.
96 templates -- ``html``
97 Path to the HTML templates directory. The path may be either absolute
98 or relative to the directory containig this config file.
100 static_files -- default *blank*
101 Path to directory holding additional static files available via Web
102 UI. This directory may contain sitewide images, CSS stylesheets etc.
103 and is searched for these files prior to the TEMPLATES directory
104 specified above. If this option is not set, all static files are
105 taken from the TEMPLATES directory The path may be either absolute or
106 relative to the directory containig this config file.
108 admin_email -- ``roundup-admin``
109 Email address that roundup will complain to if it runs into trouble. If
110 the email address doesn't contain an ``@`` part, the MAIL_DOMAIN defined
111 below is used.
113 dispatcher_email -- ``roundup-admin``
114 The 'dispatcher' is a role that can get notified of new items to the
115 database. It is used by the ERROR_MESSAGES_TO config setting. If the
116 email address doesn't contain an ``@`` part, the MAIL_DOMAIN defined
117 below is used.
119 email_from_tag -- default *blank*
120 Additional text to include in the "name" part of the From: address used
121 in nosy messages. If the sending user is "Foo Bar", the From: line
122 is usually: ``"Foo Bar" <issue_tracker@tracker.example>``
123 the EMAIL_FROM_TAG goes inside the "Foo Bar" quotes like so:
124 ``"Foo Bar EMAIL_FROM_TAG" <issue_tracker@tracker.example>``
126 new_web_user_roles -- ``User``
127 Roles that a user gets when they register with Web User Interface.
128 This is a comma-separated list of role names (e.g. ``Admin,User``).
130 new_email_user_roles -- ``User``
131 Roles that a user gets when they register with Email Gateway.
132 This is a comma-separated string of role names (e.g. ``Admin,User``).
134 error_messages_to -- ``user``
135 Send error message emails to the ``dispatcher``, ``user``, or ``both``?
136 The dispatcher is configured using the DISPATCHER_EMAIL setting.
137 Allowed values: ``dispatcher``, ``user``, or ``both``
139 html_version -- ``html4``
140 HTML version to generate. The templates are ``html4`` by default.
141 If you wish to make them xhtml, then you'll need to change this
142 var to ``xhtml`` too so all auto-generated HTML is compliant.
143 Allowed values: ``html4``, ``xhtml``
145 timezone -- ``0``
146 Numeric timezone offset used when users do not choose their own
147 in their settings.
149 instant_registration -- ``yes``
150 Register new users instantly, or require confirmation via
151 email?
152 Allowed values: ``yes``, ``no``
154 email_registration_confirmation -- ``yes``
155 Offer registration confirmation by email or only through the web?
156 Allowed values: ``yes``, ``no``
158 indexer_stopwords -- default *blank*
159 Additional stop-words for the full-text indexer specific to
160 your tracker. See the indexer source for the default list of
161 stop-words (e.g. ``A,AND,ARE,AS,AT,BE,BUT,BY, ...``).
163 umask -- ``02``
164 Defines the file creation mode mask.
166 Section **tracker**
167 name -- ``Roundup issue tracker``
168 A descriptive name for your roundup instance.
170 web -- ``http://host.example/demo/``
171 The web address that the tracker is viewable at.
172 This will be included in information sent to users of the tracker.
173 The URL MUST include the cgi-bin part or anything else
174 that is required to get to the home page of the tracker.
175 You MUST include a trailing '/' in the URL.
177 email -- ``issue_tracker``
178 Email address that mail to roundup should go to.
180 language -- default *blank*
181 Default locale name for this tracker. If this option is not set, the
182 language is determined by the environment variable LANGUAGE, LC_ALL,
183 LC_MESSAGES, or LANG, in that order of preference.
185 Section **web**
186 http_auth -- ``yes``
187 Whether to use HTTP Basic Authentication, if present.
188 Roundup will use either the REMOTE_USER or HTTP_AUTHORIZATION
189 variables supplied by your web server (in that order).
190 Set this option to 'no' if you do not wish to use HTTP Basic
191 Authentication in your web interface.
193 use_browser_language -- ``yes``
194 Whether to use HTTP Accept-Language, if present.
195 Browsers send a language-region preference list.
196 It's usually set in the client's browser or in their
197 Operating System.
198 Set this option to 'no' if you want to ignore it.
200 debug -- ``no``
201 Setting this option makes Roundup display error tracebacks
202 in the user's browser rather than emailing them to the
203 tracker admin."),
205 Section **rdbms**
206 Settings in this section are used by Postgresql and MySQL backends only
208 name -- ``roundup``
209 Name of the database to use.
211 host -- ``localhost``
212 Database server host.
214 port -- default *blank*
215 TCP port number of the database server. Postgresql usually resides on
216 port 5432 (if any), for MySQL default port number is 3306. Leave this
217 option empty to use backend default.
219 user -- ``roundup``
220 Database user name that Roundup should use.
222 password -- ``roundup``
223 Database user password.
225 read_default_file -- ``~/.my.cnf``
226 Name of the MySQL defaults file. Only used in MySQL connections.
228 read_default_group -- ``roundup``
229 Name of the group to use in the MySQL defaults file. Only used in
230 MySQL connections.
232 Section **logging**
233 config -- default *blank*
234 Path to configuration file for standard Python logging module. If this
235 option is set, logging configuration is loaded from specified file;
236 options 'filename' and 'level' in this section are ignored. The path may
237 be either absolute or relative to the directory containig this config file.
239 filename -- default *blank*
240 Log file name for minimal logging facility built into Roundup. If no file
241 name specified, log messages are written on stderr. If above 'config'
242 option is set, this option has no effect. The path may be either absolute
243 or relative to the directory containig this config file.
245 level -- ``ERROR``
246 Minimal severity level of messages written to log file. If above 'config'
247 option is set, this option has no effect.
248 Allowed values: ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``
250 Section **mail**
251 Outgoing email options. Used for nosy messages, password reset and
252 registration approval requests.
254 domain -- ``localhost``
255 Domain name used for email addresses.
257 host -- default *blank*
258 SMTP mail host that roundup will use to send mail
260 username -- default *blank*
261 SMTP login name. Set this if your mail host requires authenticated access.
262 If username is not empty, password (below) MUST be set!
264 password -- default *blank*
265 SMTP login password.
266 Set this if your mail host requires authenticated access.
268 port -- default *25*
269 SMTP port on mail host.
270 Set this if your mail host runs on a different port.
272 local_hostname -- default *blank*
273 The fully qualified domain name (FQDN) to use during SMTP sessions. If left
274 blank, the underlying SMTP library will attempt to detect your FQDN. If your
275 mail host requires something specific, specify the FQDN to use.
277 tls -- ``no``
278 If your SMTP mail host provides or requires TLS (Transport Layer Security)
279 then you may set this option to 'yes'.
280 Allowed values: ``yes``, ``no``
282 tls_keyfile -- default *blank*
283 If TLS is used, you may set this option to the name of a PEM formatted
284 file that contains your private key. The path may be either absolute or
285 relative to the directory containig this config file.
287 tls_certfile -- default *blank*
288 If TLS is used, you may set this option to the name of a PEM formatted
289 certificate chain file. The path may be either absolute or relative
290 to the directory containig this config file.
292 charset -- utf-8
293 Character set to encode email headers with. We use utf-8 by default, as
294 it's the most flexible. Some mail readers (eg. Eudora) can't cope with
295 that, so you might need to specify a more limited character set
296 (eg. iso-8859-1).
298 debug -- default *blank*
299 Setting this option makes Roundup to write all outgoing email messages
300 to this file *instead* of sending them. This option has the same effect
301 as environment variable SENDMAILDEBUG. Environment variable takes
302 precedence. The path may be either absolute or relative to the directory
303 containig this config file.
305 add_authorinfo -- ``yes``
306 Add a line with author information at top of all messages send by
307 roundup.
309 add_authoremail -- ``yes``
310 Add the mail address of the author to the author information at the
311 top of all messages. If this is false but add_authorinfo is true,
312 only the name of the actor is added which protects the mail address
313 of the actor from being exposed at mail archives, etc.
315 Section **mailgw**
316 Roundup Mail Gateway options
318 keep_quoted_text -- ``yes``
319 Keep email citations when accepting messages. Setting this to ``no`` strips
320 out "quoted" text from the message. Signatures are also stripped.
321 Allowed values: ``yes``, ``no``
323 leave_body_unchanged -- ``no``
324 Preserve the email body as is - that is, keep the citations *and*
325 signatures.
326 Allowed values: ``yes``, ``no``
328 default_class -- ``issue``
329 Default class to use in the mailgw if one isn't supplied in email subjects.
330 To disable, leave the value blank.
332 language -- default *blank*
333 Default locale name for the tracker mail gateway. If this option is
334 not set, mail gateway will use the language of the tracker instance.
336 subject_prefix_parsing -- ``strict``
337 Controls the parsing of the [prefix] on subject lines in incoming emails.
338 ``strict`` will return an error to the sender if the [prefix] is not
339 recognised. ``loose`` will attempt to parse the [prefix] but just
340 pass it through as part of the issue title if not recognised. ``none``
341 will always pass any [prefix] through as part of the issue title.
343 subject_suffix_parsing -- ``strict``
344 Controls the parsing of the [suffix] on subject lines in incoming emails.
345 ``strict`` will return an error to the sender if the [suffix] is not
346 recognised. ``loose`` will attempt to parse the [suffix] but just
347 pass it through as part of the issue title if not recognised. ``none``
348 will always pass any [suffix] through as part of the issue title.
350 subject_suffix_delimiters -- ``[]``
351 Defines the brackets used for delimiting the commands suffix in a subject
352 line.
354 subject_content_match -- ``always``
355 Controls matching of the incoming email subject line against issue titles
356 in the case where there is no designator [prefix]. ``never`` turns off
357 matching. ``creation + interval`` or ``activity + interval`` will match
358 an issue for the interval after the issue's creation or last activity.
359 The interval is a standard Roundup interval.
361 refwd_re -- ``(\s*\W?\s*(fw|fwd|re|aw|sv|ang)\W)+``
362 Regular expression matching a single reply or forward prefix
363 prepended by the mailer. This is explicitly stripped from the
364 subject during parsing. Value is Python Regular Expression
365 (UTF8-encoded).
367 origmsg_re -- `` ^[>|\s]*-----\s?Original Message\s?-----$``
368 Regular expression matching start of an original message if quoted
369 the in body. Value is Python Regular Expression (UTF8-encoded).
371 sign_re -- ``^[>|\s]*-- ?$``
372 Regular expression matching the start of a signature in the message
373 body. Value is Python Regular Expression (UTF8-encoded).
375 eol_re -- ``[\r\n]+``
376 Regular expression matching end of line. Value is Python Regular
377 Expression (UTF8-encoded).
379 blankline_re -- ``[\r\n]+\s*[\r\n]+``
380 Regular expression matching a blank line. Value is Python Regular
381 Expression (UTF8-encoded).
383 Section **pgp**
384 OpenPGP mail processing options
386 enable -- ``no``
387 Enable PGP processing. Requires pyme.
389 roles -- default *blank*
390 If specified, a comma-separated list of roles to perform PGP
391 processing on. If not specified, it happens for all users.
393 homedir -- default *blank*
394 Location of PGP directory. Defaults to $HOME/.gnupg if not
395 specified.
397 Section **nosy**
398 Nosy messages sending
400 messages_to_author -- ``no``
401 Send nosy messages to the author of the message.
402 Allowed values: ``yes``, ``no``, ``new``
404 signature_position -- ``bottom``
405 Where to place the email signature.
406 Allowed values: ``top``, ``bottom``, ``none``
408 add_author -- ``new``
409 Does the author of a message get placed on the nosy list automatically?
410 If ``new`` is used, then the author will only be added when a message
411 creates a new issue. If ``yes``, then the author will be added on
412 followups too. If ``no``, they're never added to the nosy.
413 Allowed values: ``yes``, ``no``, ``new``
415 add_recipients -- ``new``
416 Do the recipients (``To:``, ``Cc:``) of a message get placed on the nosy
417 list? If ``new`` is used, then the recipients will only be added when a
418 message creates a new issue. If ``yes``, then the recipients will be added
419 on followups too. If ``no``, they're never added to the nosy.
420 Allowed values: ``yes``, ``no``, ``new``
422 email_sending -- ``single``
423 Controls the email sending from the nosy reactor. If ``multiple`` then
424 a separate email is sent to each recipient. If ``single`` then a single
425 email is sent with each recipient as a CC address.
427 max_attachment_size -- ``2147483647``
428 Attachments larger than the given number of bytes won't be attached
429 to nosy mails. They will be replaced by a link to the tracker's
430 download page for the file.
433 You may generate a new default config file using the ``roundup-admin
434 genconfig`` command.
436 Configuration variables may be referred to in lower or upper case. In code,
437 variables not in the "main" section are referred to using their section and
438 name, so "domain" in the section "mail" becomes MAIL_DOMAIN. The
439 configuration variables available are:
441 Extending the configuration file
442 --------------------------------
444 You can't add new variables to the config.ini file in the tracker home but
445 you can add two new config.ini files:
447 - a config.ini in the ``extensions`` directory will be loaded and attached
448 to the config variable as "ext".
449 - a config.ini in the ``detectors`` directory will be loaded and attached
450 to the config variable as "detectors".
452 For example, the following in ``detectors/config.ini``::
454 [main]
455 qa_recipients = email@example.com
457 is accessible as::
459 db.config.detectors['QA_RECIPIENTS']
461 Note that the name grouping applied to the main configuration file is
462 applied to the extension config files, so if you instead have::
464 [qa]
465 recipients = email@example.com
467 then the above ``db.config.detectors['QA_RECIPIENTS']`` will still work.
470 Tracker Schema
471 ==============
473 .. note::
474 if you modify the schema, you'll most likely need to edit the
475 `web interface`_ HTML template files and `detectors`_ to reflect
476 your changes.
478 A tracker schema defines what data is stored in the tracker's database.
479 Schemas are defined using Python code in the ``schema.py`` module of your
480 tracker.
482 The ``schema.py`` module
483 ------------------------
485 The ``schema.py`` module contains two functions:
487 **open**
488 This function defines what your tracker looks like on the inside, the
489 **schema** of the tracker. It defines the **Classes** and **properties**
490 on each class. It also defines the **security** for those Classes. The
491 next few sections describe how schemas work and what you can do with
492 them.
493 **init**
494 This function is responsible for setting up the initial state of your
495 tracker. It's called exactly once - but the ``roundup-admin initialise``
496 command. See the start of the section on `database content`_ for more
497 info about how this works.
500 The "classic" schema
501 --------------------
503 The "classic" schema looks like this (see section `setkey(property)`_
504 below for the meaning of ``'setkey'`` -- you may also want to look into
505 the sections `setlabelprop(property)`_ and `setorderprop(property)`_ for
506 specifying (default) labelling and ordering of classes.)::
508 pri = Class(db, "priority", name=String(), order=String())
509 pri.setkey("name")
511 stat = Class(db, "status", name=String(), order=String())
512 stat.setkey("name")
514 keyword = Class(db, "keyword", name=String())
515 keyword.setkey("name")
517 user = Class(db, "user", username=String(), organisation=String(),
518 password=String(), address=String(), realname=String(),
519 phone=String(), alternate_addresses=String(),
520 queries=Multilink('query'), roles=String(), timezone=String())
521 user.setkey("username")
523 msg = FileClass(db, "msg", author=Link("user"), summary=String(),
524 date=Date(), recipients=Multilink("user"),
525 files=Multilink("file"), messageid=String(), inreplyto=String())
527 file = FileClass(db, "file", name=String())
529 issue = IssueClass(db, "issue", keyword=Multilink("keyword"),
530 status=Link("status"), assignedto=Link("user"),
531 priority=Link("priority"))
532 issue.setkey('title')
535 What you can't do to the schema
536 -------------------------------
538 You must never:
540 **Remove the users class**
541 This class is the only *required* class in Roundup.
543 **Remove the "username", "address", "password" or "realname" user properties**
544 Various parts of Roundup require these properties. Don't remove them.
546 **Change the type of a property**
547 Property types must *never* be changed - the database simply doesn't take
548 this kind of action into account. Note that you can't just remove a
549 property and re-add it as a new type either. If you wanted to make the
550 assignedto property a Multilink, you'd need to create a new property
551 assignedto_list and remove the old assignedto property.
554 What you can do to the schema
555 -----------------------------
557 Your schema may be changed at any time before or after the tracker has been
558 initialised (or used). You may:
560 **Add new properties to classes, or add whole new classes**
561 This is painless and easy to do - there are generally no repurcussions
562 from adding new information to a tracker's schema.
564 **Remove properties**
565 Removing properties is a little more tricky - you need to make sure that
566 the property is no longer used in the `web interface`_ *or* by the
567 detectors_.
571 Classes and Properties - creating a new information store
572 ---------------------------------------------------------
574 In the tracker above, we've defined 7 classes of information:
576 priority
577 Defines the possible levels of urgency for issues.
579 status
580 Defines the possible states of processing the issue may be in.
582 keyword
583 Initially empty, will hold keywords useful for searching issues.
585 user
586 Initially holding the "admin" user, will eventually have an entry
587 for all users using roundup.
589 msg
590 Initially empty, will hold all e-mail messages sent to or
591 generated by roundup.
593 file
594 Initially empty, will hold all files attached to issues.
596 issue
597 Initially empty, this is where the issue information is stored.
599 We define the "priority" and "status" classes to allow two things:
600 reduction in the amount of information stored on the issue and more
601 powerful, accurate searching of issues by priority and status. By only
602 requiring a link on the issue (which is stored as a single number) we
603 reduce the chance that someone mis-types a priority or status - or
604 simply makes a new one up.
607 Class and Items
608 ~~~~~~~~~~~~~~~
610 A Class defines a particular class (or type) of data that will be stored
611 in the database. A class comprises one or more properties, which gives
612 the information about the class items.
614 The actual data entered into the database, using ``class.create()``, are
615 called items. They have a special immutable property called ``'id'``. We
616 sometimes refer to this as the *itemid*.
619 Properties
620 ~~~~~~~~~~
622 A Class is comprised of one or more properties of the following types:
624 * String properties are for storing arbitrary-length strings.
625 * Password properties are for storing encoded arbitrary-length strings.
626 The default encoding is defined on the ``roundup.password.Password``
627 class.
628 * Date properties store date-and-time stamps. Their values are Timestamp
629 objects.
630 * Number properties store numeric values.
631 * Boolean properties store on/off, yes/no, true/false values.
632 * A Link property refers to a single other item selected from a
633 specified class. The class is part of the property; the value is an
634 integer, the id of the chosen item.
635 * A Multilink property refers to possibly many items in a specified
636 class. The value is a list of integers.
638 All Classes automatically have a number of properties by default:
640 *creator*
641 Link to the user that created the item.
642 *creation*
643 Date the item was created.
644 *actor*
645 Link to the user that last modified the item.
646 *activity*
647 Date the item was last modified.
650 FileClass
651 ~~~~~~~~~
653 FileClasses save their "content" attribute off in a separate file from
654 the rest of the database. This reduces the number of large entries in
655 the database, which generally makes databases more efficient, and also
656 allows us to use command-line tools to operate on the files. They are
657 stored in the files sub-directory of the ``'db'`` directory in your
658 tracker. FileClasses also have a "type" attribute to store the MIME
659 type of the file.
662 IssueClass
663 ~~~~~~~~~~
665 IssueClasses automatically include the "messages", "files", "nosy", and
666 "superseder" properties.
668 The messages and files properties list the links to the messages and
669 files related to the issue. The nosy property is a list of links to
670 users who wish to be informed of changes to the issue - they get "CC'ed"
671 e-mails when messages are sent to or generated by the issue. The nosy
672 reactor (in the ``'detectors'`` directory) handles this action. The
673 superseder link indicates an issue which has superseded this one.
675 They also have the dynamically generated "creation", "activity" and
676 "creator" properties.
678 The value of the "creation" property is the date when an item was
679 created, and the value of the "activity" property is the date when any
680 property on the item was last edited (equivalently, these are the dates
681 on the first and last records in the item's journal). The "creator"
682 property holds a link to the user that created the issue.
685 setkey(property)
686 ~~~~~~~~~~~~~~~~
688 Select a String property of the class to be the key property. The key
689 property must be unique, and allows references to the items in the class
690 by the content of the key property. That is, we can refer to users by
691 their username: for example, let's say that there's an issue in roundup,
692 issue 23. There's also a user, richard, who happens to be user 2. To
693 assign an issue to him, we could do either of::
695 roundup-admin set issue23 assignedto=2
697 or::
699 roundup-admin set issue23 assignedto=richard
701 Note, the same thing can be done in the web and e-mail interfaces.
703 setlabelprop(property)
704 ~~~~~~~~~~~~~~~~~~~~~~
706 Select a property of the class to be the label property. The label
707 property is used whereever an item should be uniquely identified, e.g.,
708 when displaying a link to an item. If setlabelprop is not specified for
709 a class, the following values are tried for the label:
711 * the key of the class (see the `setkey(property)`_ section above)
712 * the "name" property
713 * the "title" property
714 * the first property from the sorted property name list
716 So in most cases you can get away without specifying setlabelprop
717 explicitly.
719 setorderprop(property)
720 ~~~~~~~~~~~~~~~~~~~~~~
722 Select a property of the class to be the order property. The order
723 property is used whenever using a default sort order for the class,
724 e.g., when grouping or sorting class A by a link to class B in the user
725 interface, the order property of class B is used for sorting. If
726 setorderprop is not specified for a class, the following values are tried
727 for the order property:
729 * the property named "order"
730 * the label property (see `setlabelprop(property)`_ above)
732 So in most cases you can get away without specifying setorderprop
733 explicitly.
735 create(information)
736 ~~~~~~~~~~~~~~~~~~~
738 Create an item in the database. This is generally used to create items
739 in the "definitional" classes like "priority" and "status".
742 A note about ordering
743 ~~~~~~~~~~~~~~~~~~~~~
745 When we sort items in the hyperdb, we use one of a number of methods,
746 depending on the properties being sorted on:
748 1. If it's a String, Number, Date or Interval property, we just sort the
749 scalar value of the property. Strings are sorted case-sensitively.
750 2. If it's a Link property, we sort by either the linked item's "order"
751 property (if it has one) or the linked item's "id".
752 3. Mulitlinks sort similar to #2, but we start with the first Multilink
753 list item, and if they're the same, we sort by the second item, and
754 so on.
756 Note that if an "order" property is defined on a Class that is used for
757 sorting, all items of that Class *must* have a value against the "order"
758 property, or sorting will result in random ordering.
761 Examples of adding to your schema
762 ---------------------------------
764 The Roundup wiki has examples of how schemas can be customised to add
765 new functionality.
768 Detectors - adding behaviour to your tracker
769 ============================================
770 .. _detectors:
772 Detectors are initialised every time you open your tracker database, so
773 you're free to add and remove them any time, even after the database is
774 initialised via the ``roundup-admin initialise`` command.
776 The detectors in your tracker fire *before* (**auditors**) and *after*
777 (**reactors**) changes to the contents of your database. They are Python
778 modules that sit in your tracker's ``detectors`` directory. You will
779 have some installed by default - have a look. You can write new
780 detectors or modify the existing ones. The existing detectors installed
781 for you are:
783 **nosyreaction.py**
784 This provides the automatic nosy list maintenance and email sending.
785 The nosy reactor (``nosyreaction``) fires when new messages are added
786 to issues. The nosy auditor (``updatenosy``) fires when issues are
787 changed, and figures out what changes need to be made to the nosy list
788 (such as adding new authors, etc.)
789 **statusauditor.py**
790 This provides the ``chatty`` auditor which changes the issue status
791 from ``unread`` or ``closed`` to ``chatting`` if new messages appear.
792 It also provides the ``presetunread`` auditor which pre-sets the
793 status to ``unread`` on new items if the status isn't explicitly
794 defined.
795 **messagesummary.py**
796 Generates the ``summary`` property for new messages based on the message
797 content.
798 **userauditor.py**
799 Verifies the content of some of the user fields (email addresses and
800 roles lists).
802 If you don't want this default behaviour, you're completely free to change
803 or remove these detectors.
805 See the detectors section in the `design document`__ for details of the
806 interface for detectors.
808 __ design.html
811 Detector API
812 ------------
814 Auditors are called with the arguments::
816 audit(db, cl, itemid, newdata)
818 where ``db`` is the database, ``cl`` is an instance of Class or
819 IssueClass within the database, and ``newdata`` is a dictionary mapping
820 property names to values.
822 For a ``create()`` operation, the ``itemid`` argument is None and
823 newdata contains all of the initial property values with which the item
824 is about to be created.
826 For a ``set()`` operation, newdata contains only the names and values of
827 properties that are about to be changed.
829 For a ``retire()`` or ``restore()`` operation, newdata is None.
831 Reactors are called with the arguments::
833 react(db, cl, itemid, olddata)
835 where ``db`` is the database, ``cl`` is an instance of Class or
836 IssueClass within the database, and ``olddata`` is a dictionary mapping
837 property names to values.
839 For a ``create()`` operation, the ``itemid`` argument is the id of the
840 newly-created item and ``olddata`` is None.
842 For a ``set()`` operation, ``olddata`` contains the names and previous
843 values of properties that were changed.
845 For a ``retire()`` or ``restore()`` operation, ``itemid`` is the id of
846 the retired or restored item and ``olddata`` is None.
849 Additional Detectors Ready For Use
850 ----------------------------------
852 Sample additional detectors that have been found useful will appear in
853 the ``'detectors'`` directory of the Roundup distribution. If you want
854 to use one, copy it to the ``'detectors'`` of your tracker instance:
856 **newissuecopy.py**
857 This detector sends an email to a team address whenever a new issue is
858 created. The address is hard-coded into the detector, so edit it
859 before you use it (look for the text 'team@team.host') or you'll get
860 email errors!
861 **creator_resolution.py**
862 Catch attempts to set the status to "resolved" - if the assignedto
863 user isn't the creator, then set the status to "confirm-done". Note that
864 "classic" Roundup doesn't have that status, so you'll have to add it. If
865 you don't want to though, it'll just use "in-progress" instead.
866 **email_auditor.py**
867 If a file added to an issue is of type message/rfc822, we tack on the
868 extension .eml.
869 The reason for this is that Microsoft Internet Explorer will not open
870 things with a .eml attachment, as they deem it 'unsafe'. Worse yet,
871 they'll just give you an incomprehensible error message. For more
872 information, see the detector code - it has a length explanation.
875 Auditor or Reactor?
876 -------------------
878 Generally speaking, the following rules should be observed:
880 **Auditors**
881 Are used for `vetoing creation of or changes to items`_. They might
882 also make automatic changes to item properties.
883 **Reactors**
884 Detect changes in the database and react accordingly. They should avoid
885 making changes to the database where possible, as this could create
886 detector loops.
889 Vetoing creation of or changes to items
890 ---------------------------------------
892 Auditors may raise the ``Reject`` exception to prevent the creation of
893 or changes to items in the database. The mail gateway, for example, will
894 not attach files or messages to issues when the creation of those files or
895 messages are prevented through the ``Reject`` exception. It'll also not create
896 users if that creation is ``Reject``'ed too.
898 To use, simply add at the top of your auditor::
900 from roundup.exceptions import Reject
902 And then when your rejection criteria have been detected, simply::
904 raise Reject
907 Generating email from Roundup
908 -----------------------------
910 The module ``roundup.mailer`` contains most of the nuts-n-bolts required
911 to generate email messages from Roundup.
913 In addition, the ``IssueClass`` methods ``nosymessage()`` and
914 ``send_message()`` are used to generate nosy messages, and may generate
915 messages which only consist of a change note (ie. the message id parameter
916 is not required - this is referred to as a "System Message" because it
917 comes from "the system" and not a user).
920 Database Content
921 ================
923 .. note::
924 If you modify the content of definitional classes, you'll most
925 likely need to edit the tracker `detectors`_ to reflect your changes.
927 Customisation of the special "definitional" classes (eg. status,
928 priority, resolution, ...) may be done either before or after the
929 tracker is initialised. The actual method of doing so is completely
930 different in each case though, so be careful to use the right one.
932 **Changing content before tracker initialisation**
933 Edit the initial_data.py module in your tracker to alter the items
934 created using the ``create( ... )`` methods.
936 **Changing content after tracker initialisation**
937 As the "admin" user, click on the "class list" link in the web
938 interface to bring up a list of all database classes. Click on the
939 name of the class you wish to change the content of.
941 You may also use the ``roundup-admin`` interface's create, set and
942 retire methods to add, alter or remove items from the classes in
943 question.
945 See "`adding a new field to the classic schema`_" for an example that
946 requires database content changes.
949 Security / Access Controls
950 ==========================
952 A set of Permissions is built into the security module by default:
954 - Create (everything)
955 - Edit (everything)
956 - View (everything)
958 These are assigned to the "Admin" Role by default, and allow a user to do
959 anything. Every Class you define in your `tracker schema`_ also gets an
960 Create, Edit and View Permission of its own. The web and email interfaces
961 also define:
963 *Email Access*
964 If defined, the user may use the email interface. Used by default to deny
965 Anonymous users access to the email interface. When granted to the
966 Anonymous user, they will be automatically registered by the email
967 interface (see also the ``new_email_user_roles`` configuration option).
968 *Web Access*
969 If defined, the user may use the web interface. All users are able to see
970 the login form, regardless of this setting (thus enabling logging in).
971 *Web Roles*
972 Controls user access to editing the "roles" property of the "user" class.
973 TODO: deprecate in favour of a property-based control.
975 These are hooked into the default Roles:
977 - Admin (Create, Edit, View and everything; Web Roles)
978 - User (Web Access; Email Access)
979 - Anonymous (Web Access)
981 And finally, the "admin" user gets the "Admin" Role, and the "anonymous"
982 user gets "Anonymous" assigned when the tracker is installed.
984 For the "User" Role, the "classic" tracker defines:
986 - Create, Edit and View issue, file, msg, query, keyword
987 - View priority, status
988 - View user
989 - Edit their own user record
991 And the "Anonymous" Role is defined as:
993 - Web interface access
994 - Create user (for registration)
995 - View issue, file, msg, query, keyword, priority, status
997 Put together, these settings appear in the tracker's ``schema.py`` file::
999 #
1000 # TRACKER SECURITY SETTINGS
1001 #
1002 # See the configuration and customisation document for information
1003 # about security setup.
1005 #
1006 # REGULAR USERS
1007 #
1008 # Give the regular users access to the web and email interface
1009 db.security.addPermissionToRole('User', 'Web Access')
1010 db.security.addPermissionToRole('User', 'Email Access')
1012 # Assign the access and edit Permissions for issue, file and message
1013 # to regular users now
1014 for cl in 'issue', 'file', 'msg', 'query', 'keyword':
1015 db.security.addPermissionToRole('User', 'View', cl)
1016 db.security.addPermissionToRole('User', 'Edit', cl)
1017 db.security.addPermissionToRole('User', 'Create', cl)
1018 for cl in 'priority', 'status':
1019 db.security.addPermissionToRole('User', 'View', cl)
1021 # May users view other user information? Comment these lines out
1022 # if you don't want them to
1023 db.security.addPermissionToRole('User', 'View', 'user')
1025 # Users should be able to edit their own details -- this permission
1026 # is limited to only the situation where the Viewed or Edited item
1027 # is their own.
1028 def own_record(db, userid, itemid):
1029 '''Determine whether the userid matches the item being accessed.'''
1030 return userid == itemid
1031 p = db.security.addPermission(name='View', klass='user', check=own_record,
1032 description="User is allowed to view their own user details")
1033 db.security.addPermissionToRole('User', p)
1034 p = db.security.addPermission(name='Edit', klass='user', check=own_record,
1035 description="User is allowed to edit their own user details")
1036 db.security.addPermissionToRole('User', p)
1038 #
1039 # ANONYMOUS USER PERMISSIONS
1040 #
1041 # Let anonymous users access the web interface. Note that almost all
1042 # trackers will need this Permission. The only situation where it's not
1043 # required is in a tracker that uses an HTTP Basic Authenticated front-end.
1044 db.security.addPermissionToRole('Anonymous', 'Web Access')
1046 # Let anonymous users access the email interface (note that this implies
1047 # that they will be registered automatically, hence they will need the
1048 # "Create" user Permission below)
1049 # This is disabled by default to stop spam from auto-registering users on
1050 # public trackers.
1051 #db.security.addPermissionToRole('Anonymous', 'Email Access')
1053 # Assign the appropriate permissions to the anonymous user's Anonymous
1054 # Role. Choices here are:
1055 # - Allow anonymous users to register
1056 db.security.addPermissionToRole('Anonymous', 'Create', 'user')
1058 # Allow anonymous users access to view issues (and the related, linked
1059 # information)
1060 for cl in 'issue', 'file', 'msg', 'keyword', 'priority', 'status':
1061 db.security.addPermissionToRole('Anonymous', 'View', cl)
1063 # [OPTIONAL]
1064 # Allow anonymous users access to create or edit "issue" items (and the
1065 # related file and message items)
1066 #for cl in 'issue', 'file', 'msg':
1067 # db.security.addPermissionToRole('Anonymous', 'Create', cl)
1068 # db.security.addPermissionToRole('Anonymous', 'Edit', cl)
1071 Automatic Permission Checks
1072 ---------------------------
1074 Permissions are automatically checked when information is rendered
1075 through the web. This includes:
1077 1. View checks for properties when being rendered via the ``plain()`` or
1078 similar methods. If the check fails, the text "[hidden]" will be
1079 displayed.
1080 2. Edit checks for properties when the edit field is being rendered via
1081 the ``field()`` or similar methods. If the check fails, the property
1082 will be rendered via the ``plain()`` method (see point 1. for subsequent
1083 checking performed)
1084 3. View checks are performed in index pages for each item being displayed
1085 such that if the user does not have permission, the row is not rendered.
1086 4. View checks are performed at the top of item pages for the Item being
1087 displayed. If the user does not have permission, the text "You are not
1088 allowed to view this page." will be displayed.
1089 5. View checks are performed at the top of index pages for the Class being
1090 displayed. If the user does not have permission, the text "You are not
1091 allowed to view this page." will be displayed.
1094 New User Roles
1095 --------------
1097 New users are assigned the Roles defined in the config file as:
1099 - NEW_WEB_USER_ROLES
1100 - NEW_EMAIL_USER_ROLES
1102 The `users may only edit their issues`_ example shows customisation of
1103 these parameters.
1106 Changing Access Controls
1107 ------------------------
1109 You may alter the configuration variables to change the Role that new
1110 web or email users get, for example to not give them access to the web
1111 interface if they register through email.
1113 You may use the ``roundup-admin`` "``security``" command to display the
1114 current Role and Permission configuration in your tracker.
1117 Adding a new Permission
1118 ~~~~~~~~~~~~~~~~~~~~~~~
1120 When adding a new Permission, you will need to:
1122 1. add it to your tracker's ``schema.py`` so it is created, using
1123 ``security.addPermission``, for example::
1125 self.security.addPermission(name="View", klass='frozzle',
1126 description="User is allowed to access frozzles")
1128 will set up a new "View" permission on the Class "frozzle".
1129 2. enable it for the Roles that should have it (verify with
1130 "``roundup-admin security``")
1131 3. add it to the relevant HTML interface templates
1132 4. add it to the appropriate xxxPermission methods on in your tracker
1133 interfaces module
1135 The ``addPermission`` method takes a couple of optional parameters:
1137 **properties**
1138 A sequence of property names that are the only properties to apply the
1139 new Permission to (eg. ``... klass='user', properties=('name',
1140 'email') ...``)
1141 **check**
1142 A function to be execute which returns boolean determining whether the
1143 Permission is allowed. The function has the signature ``check(db, userid,
1144 itemid)`` where ``db`` is a handle on the open database, ``userid`` is
1145 the user attempting access and ``itemid`` is the specific item being
1146 accessed.
1148 Example Scenarios
1149 ~~~~~~~~~~~~~~~~~
1151 See the `examples`_ section for longer examples of customisation.
1153 **anonymous access through the e-mail gateway**
1154 Give the "anonymous" user the "Email Access", ("Edit", "issue") and
1155 ("Create", "msg") Permissions but do not not give them the ("Create",
1156 "user") Permission. This means that when an unknown user sends email
1157 into the tracker, they're automatically logged in as "anonymous".
1158 Since they don't have the ("Create", "user") Permission, they won't
1159 be automatically registered, but since "anonymous" has permission to
1160 use the gateway, they'll still be able to submit issues. Note that
1161 the Sender information - their email address - will not be available
1162 - they're *anonymous*.
1164 **automatic registration of users in the e-mail gateway**
1165 By giving the "anonymous" user the ("Create", "user") Permission, any
1166 unidentified user will automatically be registered with the tracker
1167 (with no password, so they won't be able to log in through
1168 the web until an admin sets their password). By default new Roundup
1169 trackers don't allow this as it opens them up to spam. It may be enabled
1170 by uncommenting the appropriate addPermissionToRole in your tracker's
1171 ``schema.py`` file. The new user is given the Roles list defined in the
1172 "new_email_user_roles" config variable.
1174 **only developers may be assigned issues**
1175 Create a new Permission called "Fixer" for the "issue" class. Create a
1176 new Role "Developer" which has that Permission, and assign that to the
1177 appropriate users. Filter the list of users available in the assignedto
1178 list to include only those users. Enforce the Permission with an
1179 auditor. See the example
1180 `restricting the list of users that are assignable to a task`_.
1182 **only managers may sign off issues as complete**
1183 Create a new Permission called "Closer" for the "issue" class. Create a
1184 new Role "Manager" which has that Permission, and assign that to the
1185 appropriate users. In your web interface, only display the "resolved"
1186 issue state option when the user has the "Closer" Permissions. Enforce
1187 the Permission with an auditor. This is very similar to the previous
1188 example, except that the web interface check would look like::
1190 <option tal:condition="python:request.user.hasPermission('Closer')"
1191 value="resolved">Resolved</option>
1193 **don't give web access to users who register through email**
1194 Create a new Role called "Email User" which has all the Permissions of
1195 the normal "User" Role minus the "Web Access" Permission. This will
1196 allow users to send in emails to the tracker, but not access the web
1197 interface.
1199 **let some users edit the details of all users**
1200 Create a new Role called "User Admin" which has the Permission for
1201 editing users::
1203 db.security.addRole(name='User Admin', description='Managing users')
1204 p = db.security.getPermission('Edit', 'user')
1205 db.security.addPermissionToRole('User Admin', p)
1207 and assign the Role to the users who need the permission.
1210 Web Interface
1211 =============
1213 .. contents::
1214 :local:
1216 The web interface is provided by the ``roundup.cgi.client`` module and
1217 is used by ``roundup.cgi``, ``roundup-server`` and ``ZRoundup``
1218 (``ZRoundup`` is broken, until further notice). In all cases, we
1219 determine which tracker is being accessed (the first part of the URL
1220 path inside the scope of the CGI handler) and pass control on to the
1221 ``roundup.cgi.client.Client`` class - which handles the rest of the
1222 access through its ``main()`` method. This means that you can do pretty
1223 much anything you want as a web interface to your tracker.
1227 Repercussions of changing the tracker schema
1228 ---------------------------------------------
1230 If you choose to change the `tracker schema`_ you will need to ensure
1231 the web interface knows about it:
1233 1. Index, item and search pages for the relevant classes may need to
1234 have properties added or removed,
1235 2. The "page" template may require links to be changed, as might the
1236 "home" page's content arguments.
1239 How requests are processed
1240 --------------------------
1242 The basic processing of a web request proceeds as follows:
1244 1. figure out who we are, defaulting to the "anonymous" user
1245 2. figure out what the request is for - we call this the "context"
1246 3. handle any requested action (item edit, search, ...)
1247 4. render the template requested by the context, resulting in HTML
1248 output
1250 In some situations, exceptions occur:
1252 - HTTP Redirect (generally raised by an action)
1253 - SendFile (generally raised by ``determine_context``)
1254 here we serve up a FileClass "content" property
1255 - SendStaticFile (generally raised by ``determine_context``)
1256 here we serve up a file from the tracker "html" directory
1257 - Unauthorised (generally raised by an action)
1258 here the action is cancelled, the request is rendered and an error
1259 message is displayed indicating that permission was not granted for
1260 the action to take place
1261 - NotFound (raised wherever it needs to be)
1262 this exception percolates up to the CGI interface that called the
1263 client
1266 Determining web context
1267 -----------------------
1269 To determine the "context" of a request, we look at the URL and the
1270 special request variable ``@template``. The URL path after the tracker
1271 identifier is examined. Typical URL paths look like:
1273 1. ``/tracker/issue``
1274 2. ``/tracker/issue1``
1275 3. ``/tracker/@@file/style.css``
1276 4. ``/cgi-bin/roundup.cgi/tracker/file1``
1277 5. ``/cgi-bin/roundup.cgi/tracker/file1/kitten.png``
1279 where the "tracker identifier" is "tracker" in the above cases. That means
1280 we're looking at "issue", "issue1", "@@file/style.css", "file1" and
1281 "file1/kitten.png" in the cases above. The path is generally only one
1282 entry long - longer paths are handled differently.
1284 a. if there is no path, then we are in the "home" context. See `the "home"
1285 context`_ below for more information about how it may be used.
1286 b. if the path starts with "@@file" (as in example 3,
1287 "/tracker/@@file/style.css"), then the additional path entry,
1288 "style.css" specifies the filename of a static file we're to serve up
1289 from the tracker TEMPLATES (or STATIC_FILES, if configured) directory.
1290 This is usually the tracker's "html" directory. Raises a SendStaticFile
1291 exception.
1292 c. if there is something in the path (as in example 1, "issue"), it
1293 identifies the tracker class we're to display.
1294 d. if the path is an item designator (as in examples 2 and 4, "issue1"
1295 and "file1"), then we're to display a specific item.
1296 e. if the path starts with an item designator and is longer than one
1297 entry (as in example 5, "file1/kitten.png"), then we're assumed to be
1298 handling an item of a ``FileClass``, and the extra path information
1299 gives the filename that the client is going to label the download
1300 with (i.e. "file1/kitten.png" is nicer to download than "file1").
1301 This raises a ``SendFile`` exception.
1303 Both b. and e. stop before we bother to determine the template we're
1304 going to use. That's because they don't actually use templates.
1306 The template used is specified by the ``@template`` CGI variable, which
1307 defaults to:
1309 - only classname suplied: "index"
1310 - full item designator supplied: "item"
1313 The "home" Context
1314 ------------------
1316 The "home" context is special because it allows you to add templated
1317 pages to your tracker that don't rely on a class or item (ie. an issues
1318 list or specific issue).
1320 Let's say you wish to add frames to control the layout of your tracker's
1321 interface. You'd probably have:
1323 - A top-level frameset page. This page probably wouldn't be templated, so
1324 it could be served as a static file (see `serving static content`_)
1325 - A sidebar frame that is templated. Let's call this page
1326 "home.navigation.html" in your tracker's "html" directory. To load that
1327 page up, you use the URL:
1329 <tracker url>/home?@template=navigation
1332 Serving static content
1333 ----------------------
1335 See the previous section `determining web context`_ where it describes
1336 ``@@file`` paths.
1339 Performing actions in web requests
1340 ----------------------------------
1342 When a user requests a web page, they may optionally also request for an
1343 action to take place. As described in `how requests are processed`_, the
1344 action is performed before the requested page is generated. Actions are
1345 triggered by using a ``@action`` CGI variable, where the value is one
1346 of:
1348 **login**
1349 Attempt to log a user in.
1351 **logout**
1352 Log the user out - make them "anonymous".
1354 **register**
1355 Attempt to create a new user based on the contents of the form and then
1356 log them in.
1358 **edit**
1359 Perform an edit of an item in the database. There are some `special form
1360 variables`_ you may use.
1362 **new**
1363 Add a new item to the database. You may use the same `special form
1364 variables`_ as in the "edit" action.
1366 **retire**
1367 Retire the item in the database.
1369 **editCSV**
1370 Performs an edit of all of a class' items in one go. See also the
1371 *class*.csv templating method which generates the CSV data to be
1372 edited, and the ``'_generic.index'`` template which uses both of these
1373 features.
1375 **search**
1376 Mangle some of the form variables:
1378 - Set the form ":filter" variable based on the values of the filter
1379 variables - if they're set to anything other than "dontcare" then add
1380 them to :filter.
1382 - Also handle the ":queryname" variable and save off the query to the
1383 user's query list.
1385 Each of the actions is implemented by a corresponding ``*XxxAction*`` (where
1386 "Xxx" is the name of the action) class in the ``roundup.cgi.actions`` module.
1387 These classes are registered with ``roundup.cgi.client.Client``. If you need
1388 to define new actions, you may add them there (see `defining new
1389 web actions`_).
1391 Each action class also has a ``*permission*`` method which determines whether
1392 the action is permissible given the current user. The base permission checks
1393 for each action are:
1395 **login**
1396 Determine whether the user has the "Web Access" Permission.
1397 **logout**
1398 No permission checks are made.
1399 **register**
1400 Determine whether the user has the ("Create", "user") Permission.
1401 **edit**
1402 Determine whether the user has permission to edit this item. If we're
1403 editing the "user" class, users are allowed to edit their own details -
1404 unless they try to edit the "roles" property, which requires the
1405 special Permission "Web Roles".
1406 **new**
1407 Determine whether the user has permission to create this item. No
1408 additional property checks are made. Additionally, new user items may
1409 be created if the user has the ("Create", "user") Permission.
1410 **editCSV**
1411 Determine whether the user has permission to edit this class.
1412 **search**
1413 Determine whether the user has permission to view this class.
1416 Special form variables
1417 ----------------------
1419 Item properties and their values are edited with html FORM
1420 variables and their values. You can:
1422 - Change the value of some property of the current item.
1423 - Create a new item of any class, and edit the new item's
1424 properties,
1425 - Attach newly created items to a multilink property of the
1426 current item.
1427 - Remove items from a multilink property of the current item.
1428 - Specify that some properties are required for the edit
1429 operation to be successful.
1430 - Set up user interface locale.
1432 These operations will only take place if the form action (the
1433 ``@action`` variable) is "edit" or "new".
1435 In the following, <bracketed> values are variable, "@" may be
1436 either ":" or "@", and other text "required" is fixed.
1438 Two special form variables are used to specify user language preferences:
1440 ``@language``
1441 value may be locale name or ``none``. If this variable is set to
1442 locale name, web interface language is changed to given value
1443 (provided that appropriate translation is available), the value
1444 is stored in the browser cookie and will be used for all following
1445 requests. If value is ``none`` the cookie is removed and the
1446 language is changed to the tracker default, set up in the tracker
1447 configuration or OS environment.
1449 ``@charset``
1450 value may be character set name or ``none``. Character set name
1451 is stored in the browser cookie and sets output encoding for all
1452 HTML pages generated by Roundup. If value is ``none`` the cookie
1453 is removed and HTML output is reset to Roundup internal encoding
1454 (UTF-8).
1456 Most properties are specified as form variables:
1458 ``<propname>``
1459 property on the current context item
1461 ``<designator>"@"<propname>``
1462 property on the indicated item (for editing related information)
1464 Designators name a specific item of a class.
1466 ``<classname><N>``
1467 Name an existing item of class <classname>.
1469 ``<classname>"-"<N>``
1470 Name the <N>th new item of class <classname>. If the form
1471 submission is successful, a new item of <classname> is
1472 created. Within the submitted form, a particular
1473 designator of this form always refers to the same new
1474 item.
1476 Once we have determined the "propname", we look at it to see
1477 if it's special:
1479 ``@required``
1480 The associated form value is a comma-separated list of
1481 property names that must be specified when the form is
1482 submitted for the edit operation to succeed.
1484 When the <designator> is missing, the properties are
1485 for the current context item. When <designator> is
1486 present, they are for the item specified by
1487 <designator>.
1489 The "@required" specifier must come before any of the
1490 properties it refers to are assigned in the form.
1492 ``@remove@<propname>=id(s)`` or ``@add@<propname>=id(s)``
1493 The "@add@" and "@remove@" edit actions apply only to
1494 Multilink properties. The form value must be a
1495 comma-separate list of keys for the class specified by
1496 the simple form variable. The listed items are added
1497 to (respectively, removed from) the specified
1498 property.
1500 ``@link@<propname>=<designator>``
1501 If the edit action is "@link@", the simple form
1502 variable must specify a Link or Multilink property.
1503 The form value is a comma-separated list of
1504 designators. The item corresponding to each
1505 designator is linked to the property given by simple
1506 form variable.
1508 None of the above (ie. just a simple form value)
1509 The value of the form variable is converted
1510 appropriately, depending on the type of the property.
1512 For a Link('klass') property, the form value is a
1513 single key for 'klass', where the key field is
1514 specified in schema.py.
1516 For a Multilink('klass') property, the form value is a
1517 comma-separated list of keys for 'klass', where the
1518 key field is specified in schema.py.
1520 Note that for simple-form-variables specifiying Link
1521 and Multilink properties, the linked-to class must
1522 have a key field.
1524 For a String() property specifying a filename, the
1525 file named by the form value is uploaded. This means we
1526 try to set additional properties "filename" and "type" (if
1527 they are valid for the class). Otherwise, the property
1528 is set to the form value.
1530 For Date(), Interval(), Boolean(), and Number()
1531 properties, the form value is converted to the
1532 appropriate
1534 Any of the form variables may be prefixed with a classname or
1535 designator.
1537 Two special form values are supported for backwards compatibility:
1539 @note
1540 This is equivalent to::
1542 @link@messages=msg-1
1543 msg-1@content=value
1545 except that in addition, the "author" and "date" properties of
1546 "msg-1" are set to the userid of the submitter, and the current
1547 time, respectively.
1549 @file
1550 This is equivalent to::
1552 @link@files=file-1
1553 file-1@content=value
1555 The String content value is handled as described above for file
1556 uploads.
1558 If both the "@note" and "@file" form variables are
1559 specified, the action::
1561 @link@msg-1@files=file-1
1563 is also performed.
1565 We also check that FileClass items have a "content" property with
1566 actual content, otherwise we remove them from all_props before
1567 returning.
1570 Default templates
1571 -----------------
1573 The default templates are html4 compliant. If you wish to change them to be
1574 xhtml compliant, you'll need to change the ``html_version`` configuration
1575 variable in ``config.ini`` to ``'xhtml'`` instead of ``'html4'``.
1577 Most customisation of the web view can be done by modifying the
1578 templates in the tracker ``'html'`` directory. There are several types
1579 of files in there. The *minimal* template includes:
1581 **page.html**
1582 This template usually defines the overall look of your tracker. When
1583 you view an issue, it appears inside this template. When you view an
1584 index, it also appears inside this template. This template defines a
1585 macro called "icing" which is used by almost all other templates as a
1586 coating for their content, using its "content" slot. It also defines
1587 the "head_title" and "body_title" slots to allow setting of the page
1588 title.
1589 **home.html**
1590 the default page displayed when no other page is indicated by the user
1591 **home.classlist.html**
1592 a special version of the default page that lists the classes in the
1593 tracker
1594 **classname.item.html**
1595 displays an item of the *classname* class
1596 **classname.index.html**
1597 displays a list of *classname* items
1598 **classname.search.html**
1599 displays a search page for *classname* items
1600 **_generic.index.html**
1601 used to display a list of items where there is no
1602 ``*classname*.index`` available
1603 **_generic.help.html**
1604 used to display a "class help" page where there is no
1605 ``*classname*.help``
1606 **user.register.html**
1607 a special page just for the user class, that renders the registration
1608 page
1609 **style.css.html**
1610 a static file that is served up as-is
1612 The *classic* template has a number of additional templates.
1614 Remember that you can create any template extension you want to,
1615 so if you just want to play around with the templating for new issues,
1616 you can copy the current "issue.item" template to "issue.test", and then
1617 access the test template using the "@template" URL argument::
1619 http://your.tracker.example/tracker/issue?@template=test
1621 and it won't affect your users using the "issue.item" template.
1624 How the templates work
1625 ----------------------
1628 Basic Templating Actions
1629 ~~~~~~~~~~~~~~~~~~~~~~~~
1631 Roundup's templates consist of special attributes on the HTML tags.
1632 These attributes form the `Template Attribute Language`_, or TAL.
1633 The basic TAL commands are:
1635 **tal:define="variable expression; variable expression; ..."**
1636 Define a new variable that is local to this tag and its contents. For
1637 example::
1639 <html tal:define="title request/description">
1640 <head><title tal:content="title"></title></head>
1641 </html>
1643 In this example, the variable "title" is defined as the result of the
1644 expression "request/description". The "tal:content" command inside the
1645 <html> tag may then use the "title" variable.
1647 **tal:condition="expression"**
1648 Only keep this tag and its contents if the expression is true. For
1649 example::
1651 <p tal:condition="python:request.user.hasPermission('View', 'issue')">
1652 Display some issue information.
1653 </p>
1655 In the example, the <p> tag and its contents are only displayed if
1656 the user has the "View" permission for issues. We consider the number
1657 zero, a blank string, an empty list, and the built-in variable
1658 nothing to be false values. Nearly every other value is true,
1659 including non-zero numbers, and strings with anything in them (even
1660 spaces!).
1662 **tal:repeat="variable expression"**
1663 Repeat this tag and its contents for each element of the sequence
1664 that the expression returns, defining a new local variable and a
1665 special "repeat" variable for each element. For example::
1667 <tr tal:repeat="u user/list">
1668 <td tal:content="u/id"></td>
1669 <td tal:content="u/username"></td>
1670 <td tal:content="u/realname"></td>
1671 </tr>
1673 The example would iterate over the sequence of users returned by
1674 "user/list" and define the local variable "u" for each entry. Using
1675 the repeat command creates a new variable called "repeat" which you
1676 may access to gather information about the iteration. See the section
1677 below on `the repeat variable`_.
1679 **tal:replace="expression"**
1680 Replace this tag with the result of the expression. For example::
1682 <span tal:replace="request/user/realname" />
1684 The example would replace the <span> tag and its contents with the
1685 user's realname. If the user's realname was "Bruce", then the
1686 resultant output would be "Bruce".
1688 **tal:content="expression"**
1689 Replace the contents of this tag with the result of the expression.
1690 For example::
1692 <span tal:content="request/user/realname">user's name appears here
1693 </span>
1695 The example would replace the contents of the <span> tag with the
1696 user's realname. If the user's realname was "Bruce" then the
1697 resultant output would be "<span>Bruce</span>".
1699 **tal:attributes="attribute expression; attribute expression; ..."**
1700 Set attributes on this tag to the results of expressions. For
1701 example::
1703 <a tal:attributes="href string:user${request/user/id}">My Details</a>
1705 In the example, the "href" attribute of the <a> tag is set to the
1706 value of the "string:user${request/user/id}" expression, which will
1707 be something like "user123".
1709 **tal:omit-tag="expression"**
1710 Remove this tag (but not its contents) if the expression is true. For
1711 example::
1713 <span tal:omit-tag="python:1">Hello, world!</span>
1715 would result in output of::
1717 Hello, world!
1719 Note that the commands on a given tag are evaulated in the order above,
1720 so *define* comes before *condition*, and so on.
1722 Additionally, you may include tags such as <tal:block>, which are
1723 removed from output. Its content is kept, but the tag itself is not (so
1724 don't go using any "tal:attributes" commands on it). This is useful for
1725 making arbitrary blocks of HTML conditional or repeatable (very handy
1726 for repeating multiple table rows, which would othewise require an
1727 illegal tag placement to effect the repeat).
1729 .. _TAL:
1730 .. _Template Attribute Language:
1731 http://dev.zope.org/Wikis/DevSite/Projects/ZPT/TAL%20Specification%201.4
1734 Templating Expressions
1735 ~~~~~~~~~~~~~~~~~~~~~~
1737 Templating Expressions are covered by `Template Attribute Language
1738 Expression Syntax`_, or TALES. The expressions you may use in the
1739 attribute values may be one of the following forms:
1741 **Path Expressions** - eg. ``item/status/checklist``
1742 These are object attribute / item accesses. Roughly speaking, the
1743 path ``item/status/checklist`` is broken into parts ``item``,
1744 ``status`` and ``checklist``. The ``item`` part is the root of the
1745 expression. We then look for a ``status`` attribute on ``item``, or
1746 failing that, a ``status`` item (as in ``item['status']``). If that
1747 fails, the path expression fails. When we get to the end, the object
1748 we're left with is evaluated to get a string - if it is a method, it
1749 is called; if it is an object, it is stringified. Path expressions
1750 may have an optional ``path:`` prefix, but they are the default
1751 expression type, so it's not necessary.
1753 If an expression evaluates to ``default``, then the expression is
1754 "cancelled" - whatever HTML already exists in the template will
1755 remain (tag content in the case of ``tal:content``, attributes in the
1756 case of ``tal:attributes``).
1758 If an expression evaluates to ``nothing`` then the target of the
1759 expression is removed (tag content in the case of ``tal:content``,
1760 attributes in the case of ``tal:attributes`` and the tag itself in
1761 the case of ``tal:replace``).
1763 If an element in the path may not exist, then you can use the ``|``
1764 operator in the expression to provide an alternative. So, the
1765 expression ``request/form/foo/value | default`` would simply leave
1766 the current HTML in place if the "foo" form variable doesn't exist.
1768 You may use the python function ``path``, as in
1769 ``path("item/status")``, to embed path expressions in Python
1770 expressions.
1772 **String Expressions** - eg. ``string:hello ${user/name}``
1773 These expressions are simple string interpolations - though they can
1774 be just plain strings with no interpolation if you want. The
1775 expression in the ``${ ... }`` is just a path expression as above.
1777 **Python Expressions** - eg. ``python: 1+1``
1778 These expressions give the full power of Python. All the "root level"
1779 variables are available, so ``python:item.status.checklist()`` would
1780 be equivalent to ``item/status/checklist``, assuming that
1781 ``checklist`` is a method.
1783 Modifiers:
1785 **structure** - eg. ``structure python:msg.content.plain(hyperlink=1)``
1786 The result of expressions are normally *escaped* to be safe for HTML
1787 display (all "<", ">" and "&" are turned into special entities). The
1788 ``structure`` expression modifier turns off this escaping - the
1789 result of the expression is now assumed to be HTML, which is passed
1790 to the web browser for rendering.
1792 **not:** - eg. ``not:python:1=1``
1793 This simply inverts the logical true/false value of another
1794 expression.
1796 .. _TALES:
1797 .. _Template Attribute Language Expression Syntax:
1798 http://dev.zope.org/Wikis/DevSite/Projects/ZPT/TALES%20Specification%201.3
1801 Template Macros
1802 ~~~~~~~~~~~~~~~
1804 Macros are used in Roundup to save us from repeating the same common
1805 page stuctures over and over. The most common (and probably only) macro
1806 you'll use is the "icing" macro defined in the "page" template.
1808 Macros are generated and used inside your templates using special
1809 attributes similar to the `basic templating actions`_. In this case,
1810 though, the attributes belong to the `Macro Expansion Template
1811 Attribute Language`_, or METAL. The macro commands are:
1813 **metal:define-macro="macro name"**
1814 Define that the tag and its contents are now a macro that may be
1815 inserted into other templates using the *use-macro* command. For
1816 example::
1818 <html metal:define-macro="page">
1819 ...
1820 </html>
1822 defines a macro called "page" using the ``<html>`` tag and its
1823 contents. Once defined, macros are stored on the template they're
1824 defined on in the ``macros`` attribute. You can access them later on
1825 through the ``templates`` variable, eg. the most common
1826 ``templates/page/macros/icing`` to access the "page" macro of the
1827 "page" template.
1829 **metal:use-macro="path expression"**
1830 Use a macro, which is identified by the path expression (see above).
1831 This will replace the current tag with the identified macro contents.
1832 For example::
1834 <tal:block metal:use-macro="templates/page/macros/icing">
1835 ...
1836 </tal:block>
1838 will replace the tag and its contents with the "page" macro of the
1839 "page" template.
1841 **metal:define-slot="slot name"** and **metal:fill-slot="slot name"**
1842 To define *dynamic* parts of the macro, you define "slots" which may
1843 be filled when the macro is used with a *use-macro* command. For
1844 example, the ``templates/page/macros/icing`` macro defines a slot like
1845 so::
1847 <title metal:define-slot="head_title">title goes here</title>
1849 In your *use-macro* command, you may now use a *fill-slot* command
1850 like this::
1852 <title metal:fill-slot="head_title">My Title</title>
1854 where the tag that fills the slot completely replaces the one defined
1855 as the slot in the macro.
1857 Note that you may not mix `METAL`_ and `TAL`_ commands on the same tag, but
1858 TAL commands may be used freely inside METAL-using tags (so your
1859 *fill-slots* tags may have all manner of TAL inside them).
1861 .. _METAL:
1862 .. _Macro Expansion Template Attribute Language:
1863 http://dev.zope.org/Wikis/DevSite/Projects/ZPT/METAL%20Specification%201.0
1865 Information available to templates
1866 ----------------------------------
1868 This is implemented by ``roundup.cgi.templating.RoundupPageTemplate``
1870 The following variables are available to templates.
1872 **context**
1873 The current context. This is either None, a `hyperdb class wrapper`_
1874 or a `hyperdb item wrapper`_
1875 **request**
1876 Includes information about the current request, including:
1877 - the current index information (``filterspec``, ``filter`` args,
1878 ``properties``, etc) parsed out of the form.
1879 - methods for easy filterspec link generation
1880 - "form"
1881 The current CGI form information as a mapping of form argument name
1882 to value (specifically a cgi.FieldStorage)
1883 - "env" the CGI environment variables
1884 - "base" the base URL for this instance
1885 - "user" a HTMLItem instance for the current user
1886 - "language" as determined by the browser or config
1887 - "classname" the current classname (possibly None)
1888 - "template" the current template (suffix, also possibly None)
1889 **config**
1890 This variable holds all the values defined in the tracker config.ini
1891 file (eg. TRACKER_NAME, etc.)
1892 **db**
1893 The current database, used to access arbitrary database items.
1894 **templates**
1895 Access to all the tracker templates by name. Used mainly in
1896 *use-macro* commands.
1897 **utils**
1898 This variable makes available some utility functions like batching.
1899 **nothing**
1900 This is a special variable - if an expression evaluates to this, then
1901 the tag (in the case of a ``tal:replace``), its contents (in the case
1902 of ``tal:content``) or some attributes (in the case of
1903 ``tal:attributes``) will not appear in the the output. So, for
1904 example::
1906 <span tal:attributes="class nothing">Hello, World!</span>
1908 would result in::
1910 <span>Hello, World!</span>
1912 **default**
1913 Also a special variable - if an expression evaluates to this, then the
1914 existing HTML in the template will not be replaced or removed, it will
1915 remain. So::
1917 <span tal:replace="default">Hello, World!</span>
1919 would result in::
1921 <span>Hello, World!</span>
1923 **true**, **false**
1924 Boolean constants that may be used in `templating expressions`_
1925 instead of ``python:1`` and ``python:0``.
1926 **i18n**
1927 Internationalization service, providing two string translation methods:
1929 **gettext** (*message*)
1930 Return the localized translation of message
1931 **ngettext** (*singular*, *plural*, *number*)
1932 Like ``gettext()``, but consider plural forms. If a translation
1933 is found, apply the plural formula to *number*, and return the
1934 resulting message (some languages have more than two plural forms).
1935 If no translation is found, return singular if *number* is 1;
1936 return plural otherwise.
1938 This function requires python2.3; in earlier python versions
1939 may not work as expected.
1941 The context variable
1942 ~~~~~~~~~~~~~~~~~~~~
1944 The *context* variable is one of three things based on the current
1945 context (see `determining web context`_ for how we figure this out):
1947 1. if we're looking at a "home" page, then it's None
1948 2. if we're looking at a specific hyperdb class, it's a
1949 `hyperdb class wrapper`_.
1950 3. if we're looking at a specific hyperdb item, it's a
1951 `hyperdb item wrapper`_.
1953 If the context is not None, we can access the properties of the class or
1954 item. The only real difference between cases 2 and 3 above are:
1956 1. the properties may have a real value behind them, and this will
1957 appear if the property is displayed through ``context/property`` or
1958 ``context/property/field``.
1959 2. the context's "id" property will be a false value in the second case,
1960 but a real, or true value in the third. Thus we can determine whether
1961 we're looking at a real item from the hyperdb by testing
1962 "context/id".
1964 Hyperdb class wrapper
1965 :::::::::::::::::::::
1967 This is implemented by the ``roundup.cgi.templating.HTMLClass``
1968 class.
1970 This wrapper object provides access to a hyperb class. It is used
1971 primarily in both index view and new item views, but it's also usable
1972 anywhere else that you wish to access information about a class, or the
1973 items of a class, when you don't have a specific item of that class in
1974 mind.
1976 We allow access to properties. There will be no "id" property. The value
1977 accessed through the property will be the current value of the same name
1978 from the CGI form.
1980 There are several methods available on these wrapper objects:
1982 =========== =============================================================
1983 Method Description
1984 =========== =============================================================
1985 properties return a `hyperdb property wrapper`_ for all of this class's
1986 properties.
1987 list lists all of the active (not retired) items in the class.
1988 csv return the items of this class as a chunk of CSV text.
1989 propnames lists the names of the properties of this class.
1990 filter lists of items from this class, filtered and sorted. Two
1991 options are avaible for sorting:
1993 1. by the current *request* filterspec/filter/sort/group args
1994 2. by the "filterspec", "sort" and "group" keyword args.
1995 "filterspec" is ``{propname: value(s)}``. "sort" and
1996 "group" are an optionally empty list ``[(dir, prop)]``
1997 where dir is '+', '-' or None
1998 and prop is a prop name or None.
2000 The propname in filterspec and prop in a sort/group spec
2001 may be transitive, i.e., it may contain properties of
2002 the form link.link.link.name.
2004 eg. All issues with a priority of "1" with messages added in
2005 the last week, sorted by activity date:
2006 ``issue.filter(filterspec={"priority": "1",
2007 'messages.creation' : '.-1w;'}, sort=[('activity', '+')])``
2009 filter_sql **Only in SQL backends**
2011 Lists the items that match the SQL provided. The SQL is a
2012 complete "select" statement.
2014 The SQL select must include the item id as the first column.
2016 This function **does not** filter out retired items, add
2017 on a where clause "__retired__ <> 1" if you don't want
2018 retired nodes.
2020 classhelp display a link to a javascript popup containing this class'
2021 "help" template.
2023 This generates a link to a popup window which displays the
2024 properties indicated by "properties" of the class named by
2025 "classname". The "properties" should be a comma-separated list
2026 (eg. 'id,name,description'). Properties defaults to all the
2027 properties of a class (excluding id, creator, created and
2028 activity).
2030 You may optionally override the "label" displayed, the "width",
2031 the "height", the number of items per page ("pagesize") and
2032 the field on which the list is sorted ("sort").
2034 With the "filter" arg it is possible to specify a filter for
2035 which items are supposed to be displayed. It has to be of
2036 the format "<field>=<values>;<field>=<values>;...".
2038 The popup window will be resizable and scrollable.
2040 If the "property" arg is given, it's passed through to the
2041 javascript help_window function. This allows updating of a
2042 property in the calling HTML page.
2044 If the "form" arg is given, it's passed through to the
2045 javascript help_window function - it's the name of the form
2046 the "property" belongs to.
2048 submit generate a submit button (and action hidden element)
2049 renderWith render this class with the given template.
2050 history returns 'New node - no history' :)
2051 is_edit_ok is the user allowed to Edit the current class?
2052 is_view_ok is the user allowed to View the current class?
2053 =========== =============================================================
2055 Note that if you have a property of the same name as one of the above
2056 methods, you'll need to access it using a python "item access"
2057 expression. For example::
2059 python:context['list']
2061 will access the "list" property, rather than the list method.
2064 Hyperdb item wrapper
2065 ::::::::::::::::::::
2067 This is implemented by the ``roundup.cgi.templating.HTMLItem``
2068 class.
2070 This wrapper object provides access to a hyperb item.
2072 We allow access to properties. There will be no "id" property. The value
2073 accessed through the property will be the current value of the same name
2074 from the CGI form.
2076 There are several methods available on these wrapper objects:
2078 =============== ========================================================
2079 Method Description
2080 =============== ========================================================
2081 submit generate a submit button (and action hidden element)
2082 journal return the journal of the current item (**not
2083 implemented**)
2084 history render the journal of the current item as HTML
2085 renderQueryForm specific to the "query" class - render the search form
2086 for the query
2087 hasPermission specific to the "user" class - determine whether the
2088 user has a Permission. The signature is::
2090 hasPermission(self, permission, [classname=],
2091 [property=], [itemid=])
2093 where the classname defaults to the current context.
2094 hasRole specific to the "user" class - determine whether the
2095 user has a Role. The signature is::
2097 hasRole(self, rolename)
2099 is_edit_ok is the user allowed to Edit the current item?
2100 is_view_ok is the user allowed to View the current item?
2101 is_retired is the item retired?
2102 download_url generate a url-quoted link for download of FileClass
2103 item contents (ie. file<id>/<name>)
2104 copy_url generate a url-quoted link for creating a copy
2105 of this item. By default, the copy will acquire
2106 all properties of the current item except for
2107 ``messages`` and ``files``. This can be overridden
2108 by passing ``exclude`` argument which contains a list
2109 (or any iterable) of property names that shall not be
2110 copied. Database-driven properties like ``id`` or
2111 ``activity`` cannot be copied.
2112 =============== ========================================================
2114 Note that if you have a property of the same name as one of the above
2115 methods, you'll need to access it using a python "item access"
2116 expression. For example::
2118 python:context['journal']
2120 will access the "journal" property, rather than the journal method.
2123 Hyperdb property wrapper
2124 ::::::::::::::::::::::::
2126 This is implemented by subclasses of the
2127 ``roundup.cgi.templating.HTMLProperty`` class (``HTMLStringProperty``,
2128 ``HTMLNumberProperty``, and so on).
2130 This wrapper object provides access to a single property of a class. Its
2131 value may be either:
2133 1. if accessed through a `hyperdb item wrapper`_, then it's a value from
2134 the hyperdb
2135 2. if access through a `hyperdb class wrapper`_, then it's a value from
2136 the CGI form
2139 The property wrapper has some useful attributes:
2141 =============== ========================================================
2142 Attribute Description
2143 =============== ========================================================
2144 _name the name of the property
2145 _value the value of the property if any - this is the actual
2146 value retrieved from the hyperdb for this property
2147 =============== ========================================================
2149 There are several methods available on these wrapper objects:
2151 =========== ================================================================
2152 Method Description
2153 =========== ================================================================
2154 plain render a "plain" representation of the property. This method
2155 may take two arguments:
2157 escape
2158 If true, escape the text so it is HTML safe (default: no). The
2159 reason this defaults to off is that text is usually escaped
2160 at a later stage by the TAL commands, unless the "structure"
2161 option is used in the template. The following ``tal:content``
2162 expressions are all equivalent::
2164 "structure python:msg.content.plain(escape=1)"
2165 "python:msg.content.plain()"
2166 "msg/content/plain"
2167 "msg/content"
2169 Usually you'll only want to use the escape option in a
2170 complex expression.
2172 hyperlink
2173 If true, turn URLs, email addresses and hyperdb item
2174 designators in the text into hyperlinks (default: no). Note
2175 that you'll need to use the "structure" TAL option if you
2176 want to use this ``tal:content`` expression::
2178 "structure python:msg.content.plain(hyperlink=1)"
2180 The text is automatically HTML-escaped before the hyperlinking
2181 transformation done in the plain() method.
2183 hyperlinked The same as msg.content.plain(hyperlink=1), but nicer::
2185 "structure msg/content/hyperlinked"
2187 field render an appropriate form edit field for the property - for
2188 most types this is a text entry box, but for Booleans it's a
2189 tri-state yes/no/neither selection. This method may take some
2190 arguments:
2192 size
2193 Sets the width in characters of the edit field
2195 format (Date properties only)
2196 Sets the format of the date in the field - uses the same
2197 format string argument as supplied to the ``pretty`` method
2198 below.
2200 popcal (Date properties only)
2201 Include the Javascript-based popup calendar for date
2202 selection. Defaults to on.
2204 stext only on String properties - render the value of the property
2205 as StructuredText (requires the StructureText module to be
2206 installed separately)
2207 multiline only on String properties - render a multiline form edit
2208 field for the property
2209 email only on String properties - render the value of the property
2210 as an obscured email address
2211 confirm only on Password properties - render a second form edit field
2212 for the property, used for confirmation that the user typed
2213 the password correctly. Generates a field with name
2214 "name:confirm".
2215 now only on Date properties - return the current date as a new
2216 property
2217 reldate only on Date properties - render the interval between the date
2218 and now
2219 local only on Date properties - return this date as a new property
2220 with some timezone offset, for example::
2222 python:context.creation.local(10)
2224 will render the date with a +10 hour offset.
2225 pretty Date properties - render the date as "dd Mon YYYY" (eg. "19
2226 Mar 2004"). Takes an optional format argument, for example::
2228 python:context.activity.pretty('%Y-%m-%d')
2230 Will format as "2004-03-19" instead.
2232 Interval properties - render the interval in a pretty
2233 format (eg. "yesterday"). The format arguments are those used
2234 in the standard ``strftime`` call (see the `Python Library
2235 Reference: time module`__)
2236 popcal Generate a link to a popup calendar which may be used to
2237 edit the date field, for example::
2239 <span tal:replace="structure context/due/popcal" />
2241 you still need to include the ``field`` for the property, so
2242 typically you'd have::
2244 <span tal:replace="structure context/due/field" />
2245 <span tal:replace="structure context/due/popcal" />
2247 menu only on Link and Multilink properties - render a form select
2248 list for this property. Takes a number of optional arguments
2250 size
2251 is used to limit the length of the list labels
2252 height
2253 is used to set the <select> tag's "size" attribute
2254 showid
2255 includes the item ids in the list labels
2256 additional
2257 lists properties which should be included in the label
2258 sort_on
2259 indicates the property to sort the list on as (direction,
2260 (direction, property) where direction is '+' or '-'. A
2261 single string with the direction prepended may be used.
2262 For example: ('-', 'order'), '+name'.
2263 value
2264 gives a default value to preselect in the menu
2266 The remaining keyword arguments are used as conditions for
2267 filtering the items in the list - they're passed as the
2268 "filterspec" argument to a Class.filter() call. For example::
2270 <span tal:replace="structure context/status/menu" />
2272 <span tal:replace="python:context.status.menu(order='+name",
2273 value='chatting',
2274 filterspec={'status': '1,2,3,4'}" />
2276 sorted only on Multilink properties - produce a list of the linked
2277 items sorted by some property, for example::
2279 python:context.files.sorted('creation')
2281 Will list the files by upload date.
2282 reverse only on Multilink properties - produce a list of the linked
2283 items in reverse order
2284 isset returns True if the property has been set to a value
2285 =========== ================================================================
2287 __ http://docs.python.org/lib/module-time.html
2289 All of the above functions perform checks for permissions required to
2290 display or edit the data they are manipulating. The simplest case is
2291 editing an issue title. Including the expression::
2293 context/title/field
2295 Will present the user with an edit field, if they have edit permission. If
2296 not, then they will be presented with a static display if they have view
2297 permission. If they don't even have view permission, then an error message
2298 is raised, preventing the display of the page, indicating that they don't
2299 have permission to view the information.
2302 The request variable
2303 ~~~~~~~~~~~~~~~~~~~~
2305 This is implemented by the ``roundup.cgi.templating.HTMLRequest``
2306 class.
2308 The request variable is packed with information about the current
2309 request.
2311 .. taken from ``roundup.cgi.templating.HTMLRequest`` docstring
2313 =========== ============================================================
2314 Variable Holds
2315 =========== ============================================================
2316 form the CGI form as a cgi.FieldStorage
2317 env the CGI environment variables
2318 base the base URL for this tracker
2319 user a HTMLUser instance for this user
2320 classname the current classname (possibly None)
2321 template the current template (suffix, also possibly None)
2322 form the current CGI form variables in a FieldStorage
2323 =========== ============================================================
2325 **Index page specific variables (indexing arguments)**
2327 =========== ============================================================
2328 Variable Holds
2329 =========== ============================================================
2330 columns dictionary of the columns to display in an index page
2331 show a convenience access to columns - request/show/colname will
2332 be true if the columns should be displayed, false otherwise
2333 sort index sort columns [(direction, column name)]
2334 group index grouping properties [(direction, column name)]
2335 filter properties to filter the index on
2336 filterspec values to filter the index on (property=value, eg
2337 ``priority=1`` or ``messages.author=42``
2338 search_text text to perform a full-text search on for an index
2339 =========== ============================================================
2341 There are several methods available on the request variable:
2343 =============== ========================================================
2344 Method Description
2345 =============== ========================================================
2346 description render a description of the request - handle for the
2347 page title
2348 indexargs_form render the current index args as form elements
2349 indexargs_url render the current index args as a URL
2350 base_javascript render some javascript that is used by other components
2351 of the templating
2352 batch run the current index args through a filter and return a
2353 list of items (see `hyperdb item wrapper`_, and
2354 `batching`_)
2355 =============== ========================================================
2357 The form variable
2358 :::::::::::::::::
2360 The form variable is a bit special because it's actually a python
2361 FieldStorage object. That means that you have two ways to access its
2362 contents. For example, to look up the CGI form value for the variable
2363 "name", use the path expression::
2365 request/form/name/value
2367 or the python expression::
2369 python:request.form['name'].value
2371 Note the "item" access used in the python case, and also note the
2372 explicit "value" attribute we have to access. That's because the form
2373 variables are stored as MiniFieldStorages. If there's more than one
2374 "name" value in the form, then the above will break since
2375 ``request/form/name`` is actually a *list* of MiniFieldStorages. So it's
2376 best to know beforehand what you're dealing with.
2379 The db variable
2380 ~~~~~~~~~~~~~~~
2382 This is implemented by the ``roundup.cgi.templating.HTMLDatabase``
2383 class.
2385 Allows access to all hyperdb classes as attributes of this variable. If
2386 you want access to the "user" class, for example, you would use::
2388 db/user
2389 python:db.user
2391 Also, the current id of the current user is available as
2392 ``db.getuid()``. This isn't so useful in templates (where you have
2393 ``request/user``), but it can be useful in detectors or interfaces.
2395 The access results in a `hyperdb class wrapper`_.
2398 The templates variable
2399 ~~~~~~~~~~~~~~~~~~~~~~
2401 This is implemented by the ``roundup.cgi.templating.Templates``
2402 class.
2404 This variable doesn't have any useful methods defined. It supports being
2405 used in expressions to access the templates, and consequently the
2406 template macros. You may access the templates using the following path
2407 expression::
2409 templates/name
2411 or the python expression::
2413 templates[name]
2415 where "name" is the name of the template you wish to access. The
2416 template has one useful attribute, namely "macros". To access a specific
2417 macro (called "macro_name"), use the path expression::
2419 templates/name/macros/macro_name
2421 or the python expression::
2423 templates[name].macros[macro_name]
2425 The repeat variable
2426 ~~~~~~~~~~~~~~~~~~~
2428 The repeat variable holds an entry for each active iteration. That is, if
2429 you have a ``tal:repeat="user db/users"`` command, then there will be a
2430 repeat variable entry called "user". This may be accessed as either::
2432 repeat/user
2433 python:repeat['user']
2435 The "user" entry has a number of methods available for information:
2437 =============== =========================================================
2438 Method Description
2439 =============== =========================================================
2440 first True if the current item is the first in the sequence.
2441 last True if the current item is the last in the sequence.
2442 even True if the current item is an even item in the sequence.
2443 odd True if the current item is an odd item in the sequence.
2444 number Current position in the sequence, starting from 1.
2445 letter Current position in the sequence as a letter, a through
2446 z, then aa through zz, and so on.
2447 Letter Same as letter(), except uppercase.
2448 roman Current position in the sequence as lowercase roman
2449 numerals.
2450 Roman Same as roman(), except uppercase.
2451 =============== =========================================================
2454 The utils variable
2455 ~~~~~~~~~~~~~~~~~~
2457 This is implemented by the
2458 ``roundup.cgi.templating.TemplatingUtils`` class, but it may be extended
2459 as described below.
2461 =============== ========================================================
2462 Method Description
2463 =============== ========================================================
2464 Batch return a batch object using the supplied list
2465 url_quote quote some text as safe for a URL (ie. space, %, ...)
2466 html_quote quote some text as safe in HTML (ie. <, >, ...)
2467 html_calendar renders an HTML calendar used by the
2468 ``_generic.calendar.html`` template (itself invoked by
2469 the popupCalendar DateHTMLProperty method
2470 =============== ========================================================
2472 You may add additional utility methods by writing them in your tracker
2473 ``extensions`` directory and registering them with the templating system
2474 using ``instance.registerUtil`` (see `adding a time log to your issues`_ for
2475 an example of this).
2478 Batching
2479 ::::::::
2481 Use Batch to turn a list of items, or item ids of a given class, into a
2482 series of batches. Its usage is::
2484 python:utils.Batch(sequence, size, start, end=0, orphan=0,
2485 overlap=0)
2487 or, to get the current index batch::
2489 request/batch
2491 The parameters are:
2493 ========= ==============================================================
2494 Parameter Usage
2495 ========= ==============================================================
2496 sequence a list of HTMLItems
2497 size how big to make the sequence.
2498 start where to start (0-indexed) in the sequence.
2499 end where to end (0-indexed) in the sequence.
2500 orphan if the next batch would contain less items than this value,
2501 then it is combined with this batch
2502 overlap the number of items shared between adjacent batches
2503 ========= ==============================================================
2505 All of the parameters are assigned as attributes on the batch object. In
2506 addition, it has several more attributes:
2508 =============== ========================================================
2509 Attribute Description
2510 =============== ========================================================
2511 start indicates the start index of the batch. *Unlike
2512 the argument, is a 1-based index (I know, lame)*
2513 first indicates the start index of the batch *as a 0-based
2514 index*
2515 length the actual number of elements in the batch
2516 sequence_length the length of the original, unbatched, sequence.
2517 =============== ========================================================
2519 And several methods:
2521 =============== ========================================================
2522 Method Description
2523 =============== ========================================================
2524 previous returns a new Batch with the previous batch settings
2525 next returns a new Batch with the next batch settings
2526 propchanged detect if the named property changed on the current item
2527 when compared to the last item
2528 =============== ========================================================
2530 An example of batching::
2532 <table class="otherinfo">
2533 <tr><th colspan="4" class="header">Existing Keywords</th></tr>
2534 <tr tal:define="keywords db/keyword/list"
2535 tal:repeat="start python:range(0, len(keywords), 4)">
2536 <td tal:define="batch python:utils.Batch(keywords, 4, start)"
2537 tal:repeat="keyword batch" tal:content="keyword/name">
2538 keyword here</td>
2539 </tr>
2540 </table>
2542 ... which will produce a table with four columns containing the items of
2543 the "keyword" class (well, their "name" anyway).
2546 Displaying Properties
2547 ---------------------
2549 Properties appear in the user interface in three contexts: in indices,
2550 in editors, and as search arguments. For each type of property, there
2551 are several display possibilities. For example, in an index view, a
2552 string property may just be printed as a plain string, but in an editor
2553 view, that property may be displayed in an editable field.
2556 Index Views
2557 -----------
2559 This is one of the class context views. It is also the default view for
2560 classes. The template used is "*classname*.index".
2563 Index View Specifiers
2564 ~~~~~~~~~~~~~~~~~~~~~
2566 An index view specifier (URL fragment) looks like this (whitespace has
2567 been added for clarity)::
2569 /issue?status=unread,in-progress,resolved&
2570 keyword=security,ui&
2571 @group=priority,-status&
2572 @sort=-activity&
2573 @filters=status,keyword&
2574 @columns=title,status,fixer
2576 The index view is determined by two parts of the specifier: the layout
2577 part and the filter part. The layout part consists of the query
2578 parameters that begin with colons, and it determines the way that the
2579 properties of selected items are displayed. The filter part consists of
2580 all the other query parameters, and it determines the criteria by which
2581 items are selected for display. The filter part is interactively
2582 manipulated with the form widgets displayed in the filter section. The
2583 layout part is interactively manipulated by clicking on the column
2584 headings in the table.
2586 The filter part selects the union of the sets of items with values
2587 matching any specified Link properties and the intersection of the sets
2588 of items with values matching any specified Multilink properties.
2590 The example specifies an index of "issue" items. Only items with a
2591 "status" of either "unread" or "in-progress" or "resolved" are
2592 displayed, and only items with "keyword" values including both "security"
2593 and "ui" are displayed. The items are grouped by priority arranged in
2594 ascending order and in descending order by status; and within
2595 groups, sorted by activity, arranged in descending order. The filter
2596 section shows filters for the "status" and "keyword" properties, and the
2597 table includes columns for the "title", "status", and "fixer"
2598 properties.
2600 ============ =============================================================
2601 Argument Description
2602 ============ =============================================================
2603 @sort sort by prop name, optionally preceeded with '-' to give
2604 descending or nothing for ascending sorting. Several
2605 properties can be specified delimited with comma.
2606 Internally a search-page using several sort properties may
2607 use @sort0, @sort1 etc. with option @sortdir0, @sortdir1
2608 etc. for the direction of sorting (a non-empty value of
2609 sortdir0 specifies reverse order).
2610 @group group by prop name, optionally preceeded with '-' or to sort
2611 in descending or nothing for ascending order. Several
2612 properties can be specified delimited with comma.
2613 Internally a search-page using several grouping properties may
2614 use @group0, @group1 etc. with option @groupdir0, @groupdir1
2615 etc. for the direction of grouping (a non-empty value of
2616 groupdir0 specifies reverse order).
2617 @columns selects the columns that should be displayed. Default is
2618 all.
2619 @filter indicates which properties are being used in filtering.
2620 Default is none.
2621 propname selects the values the item properties given by propname must
2622 have (very basic search/filter).
2623 @search_text if supplied, performs a full-text search (message bodies,
2624 issue titles, etc)
2625 ============ =============================================================
2628 Searching Views
2629 ---------------
2631 .. note::
2632 if you add a new column to the ``@columns`` form variable potentials
2633 then you will need to add the column to the appropriate `index views`_
2634 template so that it is actually displayed.
2636 This is one of the class context views. The template used is typically
2637 "*classname*.search". The form on this page should have "search" as its
2638 ``@action`` variable. The "search" action:
2640 - sets up additional filtering, as well as performing indexed text
2641 searching
2642 - sets the ``@filter`` variable correctly
2643 - saves the query off if ``@query_name`` is set.
2645 The search page should lay out any fields that you wish to allow the
2646 user to search on. If your schema contains a large number of properties,
2647 you should be wary of making all of those properties available for
2648 searching, as this can cause confusion. If the additional properties are
2649 Strings, consider having their value indexed, and then they will be
2650 searchable using the full text indexed search. This is both faster, and
2651 more useful for the end user.
2653 If the search view does specify the "search" ``@action``, then it may also
2654 provide an additional argument:
2656 ============ =============================================================
2657 Argument Description
2658 ============ =============================================================
2659 @query_name if supplied, the index parameters (including @search_text)
2660 will be saved off as a the query item and registered against
2661 the user's queries property. Note that the *classic* template
2662 schema has this ability, but the *minimal* template schema
2663 does not.
2664 ============ =============================================================
2667 Item Views
2668 ----------
2670 The basic view of a hyperdb item is provided by the "*classname*.item"
2671 template. It generally has three sections; an "editor", a "spool" and a
2672 "history" section.
2675 Editor Section
2676 ~~~~~~~~~~~~~~
2678 The editor section is used to manipulate the item - it may be a static
2679 display if the user doesn't have permission to edit the item.
2681 Here's an example of a basic editor template (this is the default
2682 "classic" template issue item edit form - from the "issue.item.html"
2683 template)::
2685 <table class="form">
2686 <tr>
2687 <th>Title</th>
2688 <td colspan="3" tal:content="structure python:context.title.field(size=60)">title</td>
2689 </tr>
2691 <tr>
2692 <th>Priority</th>
2693 <td tal:content="structure context/priority/menu">priority</td>
2694 <th>Status</th>
2695 <td tal:content="structure context/status/menu">status</td>
2696 </tr>
2698 <tr>
2699 <th>Superseder</th>
2700 <td>
2701 <span tal:replace="structure python:context.superseder.field(showid=1, size=20)" />
2702 <span tal:replace="structure python:db.issue.classhelp('id,title')" />
2703 <span tal:condition="context/superseder">
2704 <br>View: <span tal:replace="structure python:context.superseder.link(showid=1)" />
2705 </span>
2706 </td>
2707 <th>Nosy List</th>
2708 <td>
2709 <span tal:replace="structure context/nosy/field" />
2710 <span tal:replace="structure python:db.user.classhelp('username,realname,address,phone')" />
2711 </td>
2712 </tr>
2714 <tr>
2715 <th>Assigned To</th>
2716 <td tal:content="structure context/assignedto/menu">
2717 assignedto menu
2718 </td>
2719 <td> </td>
2720 <td> </td>
2721 </tr>
2723 <tr>
2724 <th>Change Note</th>
2725 <td colspan="3">
2726 <textarea name=":note" wrap="hard" rows="5" cols="60"></textarea>
2727 </td>
2728 </tr>
2730 <tr>
2731 <th>File</th>
2732 <td colspan="3"><input type="file" name=":file" size="40"></td>
2733 </tr>
2735 <tr>
2736 <td> </td>
2737 <td colspan="3" tal:content="structure context/submit">
2738 submit button will go here
2739 </td>
2740 </tr>
2741 </table>
2744 When a change is submitted, the system automatically generates a message
2745 describing the changed properties. As shown in the example, the editor
2746 template can use the ":note" and ":file" fields, which are added to the
2747 standard changenote message generated by Roundup.
2750 Form values
2751 :::::::::::
2753 We have a number of ways to pull properties out of the form in order to
2754 meet the various needs of:
2756 1. editing the current item (perhaps an issue item)
2757 2. editing information related to the current item (eg. messages or
2758 attached files)
2759 3. creating new information to be linked to the current item (eg. time
2760 spent on an issue)
2762 In the following, ``<bracketed>`` values are variable, ":" may be one of
2763 ":" or "@", and other text ("required") is fixed.
2765 Properties are specified as form variables:
2767 ``<propname>``
2768 property on the current context item
2770 ``<designator>:<propname>``
2771 property on the indicated item (for editing related information)
2773 ``<classname>-<N>:<propname>``
2774 property on the Nth new item of classname (generally for creating new
2775 items to attach to the current item)
2777 Once we have determined the "propname", we check to see if it is one of
2778 the special form values:
2780 ``@required``
2781 The named property values must be supplied or a ValueError will be
2782 raised.
2784 ``@remove@<propname>=id(s)``
2785 The ids will be removed from the multilink property.
2787 ``:add:<propname>=id(s)``
2788 The ids will be added to the multilink property.
2790 ``:link:<propname>=<designator>``
2791 Used to add a link to new items created during edit. These are
2792 collected and returned in ``all_links``. This will result in an
2793 additional linking operation (either Link set or Multilink append)
2794 after the edit/create is done using ``all_props`` in ``_editnodes``.
2795 The <propname> on the current item will be set/appended the id of the
2796 newly created item of class <designator> (where <designator> must be
2797 <classname>-<N>).
2799 Any of the form variables may be prefixed with a classname or
2800 designator.
2802 Two special form values are supported for backwards compatibility:
2804 ``:note``
2805 create a message (with content, author and date), linked to the
2806 context item. This is ALWAYS designated "msg-1".
2807 ``:file``
2808 create a file, attached to the current item and any message created by
2809 :note. This is ALWAYS designated "file-1".
2812 Spool Section
2813 ~~~~~~~~~~~~~
2815 The spool section lists related information like the messages and files
2816 of an issue.
2818 TODO
2821 History Section
2822 ~~~~~~~~~~~~~~~
2824 The final section displayed is the history of the item - its database
2825 journal. This is generally generated with the template::
2827 <tal:block tal:replace="structure context/history" />
2829 *To be done:*
2831 *The actual history entries of the item may be accessed for manual
2832 templating through the "journal" method of the item*::
2834 <tal:block tal:repeat="entry context/journal">
2835 a journal entry
2836 </tal:block>
2838 *where each journal entry is an HTMLJournalEntry.*
2841 Defining new web actions
2842 ------------------------
2844 You may define new actions to be triggered by the ``@action`` form variable.
2845 These are added to the tracker ``extensions`` directory and registered
2846 using ``instance.registerAction``.
2848 All the existing Actions are defined in ``roundup.cgi.actions``.
2850 Adding action classes takes three steps; first you `define the new
2851 action class`_, then you `register the action class`_ with the cgi
2852 interface so it may be triggered by the ``@action`` form variable.
2853 Finally you `use the new action`_ in your HTML form.
2855 See "`setting up a "wizard" (or "druid") for controlled adding of
2856 issues`_" for an example.
2859 Define the new action class
2860 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2862 Create a new action class in your tracker's ``extensions`` directory, for
2863 example ``myaction.py``::
2865 from roundup.cgi.actions import Action
2867 class MyAction(Action):
2868 def handle(self):
2869 ''' Perform some action. No return value is required.
2870 '''
2872 The *self.client* attribute is an instance of ``roundup.cgi.client.Client``.
2873 See the docstring of that class for details of what it can do.
2875 The method will typically check the ``self.form`` variable's contents.
2876 It may then:
2878 - add information to ``self.client.ok_message`` or ``self.client.error_message``
2879 - change the ``self.client.template`` variable to alter what the user will see
2880 next
2881 - raise Unauthorised, SendStaticFile, SendFile, NotFound or Redirect
2882 exceptions (import them from roundup.cgi.exceptions)
2885 Register the action class
2886 ~~~~~~~~~~~~~~~~~~~~~~~~~~
2888 The class is now written, but isn't available to the user until you register
2889 it with the following code appended to your ``myaction.py`` file::
2891 def init(instance):
2892 instance.registerAction('myaction', myActionClass)
2894 This maps the action name "myaction" to the action class we defined.
2897 Use the new action
2898 ~~~~~~~~~~~~~~~~~~
2900 In your HTML form, add a hidden form element like so::
2902 <input type="hidden" name="@action" value="myaction">
2904 where "myaction" is the name you registered in the previous step.
2906 Actions may return content to the user
2907 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2909 Actions generally perform some database manipulation and then pass control
2910 on to the rendering of a template in the current context (see `Determining
2911 web context`_ for how that works.) Some actions will want to generate the
2912 actual content returned to the user. Action methods may return their own
2913 content string to be displayed to the user, overriding the templating step.
2914 In this situation, we assume that the content is HTML by default. You may
2915 override the content type indicated to the user by calling ``setHeader``::
2917 self.client.setHeader('Content-Type', 'text/csv')
2919 This example indicates that the value sent back to the user is actually
2920 comma-separated value content (eg. something to be loaded into a
2921 spreadsheet or database).
2924 8-bit character set support in Web interface
2925 --------------------------------------------
2927 The web interface uses UTF-8 default. It may be overridden in both forms
2928 and a browser cookie.
2930 - In forms, use the ``@charset`` variable.
2931 - To use the cookie override, have the ``roundup_charset`` cookie set.
2933 In both cases, the value is a valid charset name (eg. ``utf-8`` or
2934 ``kio8-r``).
2936 Inside Roundup, all strings are stored and processed in utf-8.
2937 Unfortunately, some older browsers do not work properly with
2938 utf-8-encoded pages (e.g. Netscape Navigator 4 displays wrong
2939 characters in form fields). This version allows one to change
2940 the character set for http transfers. To do so, you may add
2941 the following code to your ``page.html`` template::
2943 <tal:block define="uri string:${request/base}${request/env/PATH_INFO}">
2944 <a tal:attributes="href python:request.indexargs_url(uri,
2945 {'@charset':'utf-8'})">utf-8</a>
2946 <a tal:attributes="href python:request.indexargs_url(uri,
2947 {'@charset':'koi8-r'})">koi8-r</a>
2948 </tal:block>
2950 (substitute ``koi8-r`` with appropriate charset for your language).
2951 Charset preference is kept in the browser cookie ``roundup_charset``.
2953 ``meta http-equiv`` lines added to the tracker templates in version 0.6.0
2954 should be changed to include actual character set name::
2956 <meta http-equiv="Content-Type"
2957 tal:attributes="content string:text/html;; charset=${request/client/charset}"
2958 />
2960 The charset is also sent in the http header.
2963 Examples
2964 ========
2966 .. contents::
2967 :local:
2968 :depth: 2
2971 Changing what's stored in the database
2972 --------------------------------------
2974 The following examples illustrate ways to change the information stored in
2975 the database.
2978 Adding a new field to the classic schema
2979 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2981 This example shows how to add a simple field (a due date) to the default
2982 classic schema. It does not add any additional behaviour, such as enforcing
2983 the due date, or causing automatic actions to fire if the due date passes.
2985 You add new fields by editing the ``schema.py`` file in you tracker's home.
2986 Schema changes are automatically applied to the database on the next
2987 tracker access (note that roundup-server would need to be restarted as it
2988 caches the schema).
2990 1. Modify the ``schema.py``::
2992 issue = IssueClass(db, "issue",
2993 assignedto=Link("user"), keyword=Multilink("keyword"),
2994 priority=Link("priority"), status=Link("status"),
2995 due_date=Date())
2997 2. Add an edit field to the ``issue.item.html`` template::
2999 <tr>
3000 <th>Due Date</th>
3001 <td tal:content="structure context/due_date/field" />
3002 </tr>
3004 If you want to show only the date part of due_date then do this instead::
3006 <tr>
3007 <th>Due Date</th>
3008 <td tal:content="structure python:context.due_date.field(format='%Y-%m-%d')" />
3009 </tr>
3011 3. Add the property to the ``issue.index.html`` page::
3013 (in the heading row)
3014 <th tal:condition="request/show/due_date">Due Date</th>
3015 (in the data row)
3016 <td tal:condition="request/show/due_date"
3017 tal:content="i/due_date" />
3019 If you want format control of the display of the due date you can
3020 enter the following in the data row to show only the actual due date::
3022 <td tal:condition="request/show/due_date"
3023 tal:content="python:i.due_date.pretty('%Y-%m-%d')"> </td>
3025 4. Add the property to the ``issue.search.html`` page::
3027 <tr tal:define="name string:due_date">
3028 <th i18n:translate="">Due Date:</th>
3029 <td metal:use-macro="search_input"></td>
3030 <td metal:use-macro="column_input"></td>
3031 <td metal:use-macro="sort_input"></td>
3032 <td metal:use-macro="group_input"></td>
3033 </tr>
3035 5. If you wish for the due date to appear in the standard views listed
3036 in the sidebar of the web interface then you'll need to add "due_date"
3037 to the columns and columns_showall lists in your ``page.html``::
3039 columns string:id,activity,due_date,title,creator,status;
3040 columns_showall string:id,activity,due_date,title,creator,assignedto,status;
3042 Adding a new constrained field to the classic schema
3043 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3045 This example shows how to add a new constrained property (i.e. a
3046 selection of distinct values) to your tracker.
3049 Introduction
3050 ::::::::::::
3052 To make the classic schema of Roundup useful as a TODO tracking system
3053 for a group of systems administrators, it needs an extra data field per
3054 issue: a category.
3056 This would let sysadmins quickly list all TODOs in their particular area
3057 of interest without having to do complex queries, and without relying on
3058 the spelling capabilities of other sysadmins (a losing proposition at
3059 best).
3062 Adding a field to the database
3063 ::::::::::::::::::::::::::::::
3065 This is the easiest part of the change. The category would just be a
3066 plain string, nothing fancy. To change what is in the database you need
3067 to add some lines to the ``schema.py`` file of your tracker instance.
3068 Under the comment::
3070 # add any additional database schema configuration here
3072 add::
3074 category = Class(db, "category", name=String())
3075 category.setkey("name")
3077 Here we are setting up a chunk of the database which we are calling
3078 "category". It contains a string, which we are refering to as "name" for
3079 lack of a more imaginative title. (Since "name" is one of the properties
3080 that Roundup looks for on items if you do not set a key for them, it's
3081 probably a good idea to stick with it for new classes if at all
3082 appropriate.) Then we are setting the key of this chunk of the database
3083 to be that "name". This is equivalent to an index for database types.
3084 This also means that there can only be one category with a given name.
3086 Adding the above lines allows us to create categories, but they're not
3087 tied to the issues that we are going to be creating. It's just a list of
3088 categories off on its own, which isn't much use. We need to link it in
3089 with the issues. To do that, find the lines
3090 in ``schema.py`` which set up the "issue" class, and then add a link to
3091 the category::
3093 issue = IssueClass(db, "issue", ... ,
3094 category=Multilink("category"), ... )
3096 The ``Multilink()`` means that each issue can have many categories. If
3097 you were adding something with a one-to-one relationship to issues (such
3098 as the "assignedto" property), use ``Link()`` instead.
3100 That is all you need to do to change the schema. The rest of the effort
3101 is fiddling around so you can actually use the new category.
3104 Populating the new category class
3105 :::::::::::::::::::::::::::::::::
3107 If you haven't initialised the database with the ``roundup-admin``
3108 "initialise" command, then you can add the following to the tracker
3109 ``initial_data.py`` under the comment::
3111 # add any additional database creation steps here - but only if you
3112 # haven't initialised the database with the admin "initialise" command
3114 Add::
3116 category = db.getclass('category')
3117 category.create(name="scipy")
3118 category.create(name="chaco")
3119 category.create(name="weave")
3121 If the database has already been initalised, then you need to use the
3122 ``roundup-admin`` tool::
3124 % roundup-admin -i <tracker home>
3125 Roundup <version> ready for input.
3126 Type "help" for help.
3127 roundup> create category name=scipy
3128 1
3129 roundup> create category name=chaco
3130 2
3131 roundup> create category name=weave
3132 3
3133 roundup> exit...
3134 There are unsaved changes. Commit them (y/N)? y
3137 Setting up security on the new objects
3138 ::::::::::::::::::::::::::::::::::::::
3140 By default only the admin user can look at and change objects. This
3141 doesn't suit us, as we want any user to be able to create new categories
3142 as required, and obviously everyone needs to be able to view the
3143 categories of issues for it to be useful.
3145 We therefore need to change the security of the category objects. This
3146 is also done in ``schema.py``.
3148 There are currently two loops which set up permissions and then assign
3149 them to various roles. Simply add the new "category" to both lists::
3151 # Assign the access and edit permissions for issue, file and message
3152 # to regular users now
3153 for cl in 'issue', 'file', 'msg', 'category':
3154 p = db.security.getPermission('View', cl)
3155 db.security.addPermissionToRole('User', 'View', cl)
3156 db.security.addPermissionToRole('User', 'Edit', cl)
3157 db.security.addPermissionToRole('User', 'Create', cl)
3159 These lines assign the "View" and "Edit" Permissions to the "User" role,
3160 so that normal users can view and edit "category" objects.
3162 This is all the work that needs to be done for the database. It will
3163 store categories, and let users view and edit them. Now on to the
3164 interface stuff.
3167 Changing the web left hand frame
3168 ::::::::::::::::::::::::::::::::
3170 We need to give the users the ability to create new categories, and the
3171 place to put the link to this functionality is in the left hand function
3172 bar, under the "Issues" area. The file that defines how this area looks
3173 is ``html/page.html``, which is what we are going to be editing next.
3175 If you look at this file you can see that it contains a lot of
3176 "classblock" sections which are chunks of HTML that will be included or
3177 excluded in the output depending on whether the condition in the
3178 classblock is met. We are going to add the category code at the end of
3179 the classblock for the *issue* class::
3181 <p class="classblock"
3182 tal:condition="python:request.user.hasPermission('View', 'category')">
3183 <b>Categories</b><br>
3184 <a tal:condition="python:request.user.hasPermission('Edit', 'category')"
3185 href="category?@template=item">New Category<br></a>
3186 </p>
3188 The first two lines is the classblock definition, which sets up a
3189 condition that only users who have "View" permission for the "category"
3190 object will have this section included in their output. Next comes a
3191 plain "Categories" header in bold. Everyone who can view categories will
3192 get that.
3194 Next comes the link to the editing area of categories. This link will
3195 only appear if the condition - that the user has "Edit" permissions for
3196 the "category" objects - is matched. If they do have permission then
3197 they will get a link to another page which will let the user add new
3198 categories.
3200 Note that if you have permission to *view* but not to *edit* categories,
3201 then all you will see is a "Categories" header with nothing underneath
3202 it. This is obviously not very good interface design, but will do for
3203 now. I just claim that it is so I can add more links in this section
3204 later on. However, to fix the problem you could change the condition in
3205 the classblock statement, so that only users with "Edit" permission
3206 would see the "Categories" stuff.
3209 Setting up a page to edit categories
3210 ::::::::::::::::::::::::::::::::::::
3212 We defined code in the previous section which let users with the
3213 appropriate permissions see a link to a page which would let them edit
3214 conditions. Now we have to write that page.
3216 The link was for the *item* template of the *category* object. This
3217 translates into Roundup looking for a file called ``category.item.html``
3218 in the ``html`` tracker directory. This is the file that we are going to
3219 write now.
3221 First, we add an info tag in a comment which doesn't affect the outcome
3222 of the code at all, but is useful for debugging. If you load a page in a
3223 browser and look at the page source, you can see which sections come
3224 from which files by looking for these comments::
3226 <!-- category.item -->
3228 Next we need to add in the METAL macro stuff so we get the normal page
3229 trappings::
3231 <tal:block metal:use-macro="templates/page/macros/icing">
3232 <title metal:fill-slot="head_title">Category editing</title>
3233 <td class="page-header-top" metal:fill-slot="body_title">
3234 <h2>Category editing</h2>
3235 </td>
3236 <td class="content" metal:fill-slot="content">
3238 Next we need to setup up a standard HTML form, which is the whole
3239 purpose of this file. We link to some handy javascript which sends the
3240 form through only once. This is to stop users hitting the send button
3241 multiple times when they are impatient and thus having the form sent
3242 multiple times::
3244 <form method="POST" onSubmit="return submit_once()"
3245 enctype="multipart/form-data">
3247 Next we define some code which sets up the minimum list of fields that
3248 we require the user to enter. There will be only one field - "name" - so
3249 they better put something in it, otherwise the whole form is pointless::
3251 <input type="hidden" name="@required" value="name">
3253 To get everything to line up properly we will put everything in a table,
3254 and put a nice big header on it so the user has an idea what is
3255 happening::
3257 <table class="form">
3258 <tr><th class="header" colspan="2">Category</th></tr>
3260 Next, we need the field into which the user is going to enter the new
3261 category. The ``context.name.field(size=60)`` bit tells Roundup to
3262 generate a normal HTML field of size 60, and the contents of that field
3263 will be the "name" variable of the current context (namely "category").
3264 The upshot of this is that when the user types something in
3265 to the form, a new category will be created with that name::
3267 <tr>
3268 <th>Name</th>
3269 <td tal:content="structure python:context.name.field(size=60)">
3270 name</td>
3271 </tr>
3273 Then a submit button so that the user can submit the new category::
3275 <tr>
3276 <td> </td>
3277 <td colspan="3" tal:content="structure context/submit">
3278 submit button will go here
3279 </td>
3280 </tr>
3282 Finally we finish off the tags we used at the start to do the METAL
3283 stuff::
3285 </td>
3286 </tal:block>
3288 So putting it all together, and closing the table and form we get::
3290 <!-- category.item -->
3291 <tal:block metal:use-macro="templates/page/macros/icing">
3292 <title metal:fill-slot="head_title">Category editing</title>
3293 <td class="page-header-top" metal:fill-slot="body_title">
3294 <h2>Category editing</h2>
3295 </td>
3296 <td class="content" metal:fill-slot="content">
3297 <form method="POST" onSubmit="return submit_once()"
3298 enctype="multipart/form-data">
3300 <table class="form">
3301 <tr><th class="header" colspan="2">Category</th></tr>
3303 <tr>
3304 <th>Name</th>
3305 <td tal:content="structure python:context.name.field(size=60)">
3306 name</td>
3307 </tr>
3309 <tr>
3310 <td>
3311
3312 <input type="hidden" name="@required" value="name">
3313 </td>
3314 <td colspan="3" tal:content="structure context/submit">
3315 submit button will go here
3316 </td>
3317 </tr>
3318 </table>
3319 </form>
3320 </td>
3321 </tal:block>
3323 This is quite a lot to just ask the user one simple question, but there
3324 is a lot of setup for basically one line (the form line) to do its work.
3325 To add another field to "category" would involve one more line (well,
3326 maybe a few extra to get the formatting correct).
3329 Adding the category to the issue
3330 ::::::::::::::::::::::::::::::::
3332 We now have the ability to create issues to our heart's content, but
3333 that is pointless unless we can assign categories to issues. Just like
3334 the ``html/category.item.html`` file was used to define how to add a new
3335 category, the ``html/issue.item.html`` is used to define how a new issue
3336 is created.
3338 Just like ``category.issue.html``, this file defines a form which has a
3339 table to lay things out. It doesn't matter where in the table we add new
3340 stuff, it is entirely up to your sense of aesthetics::
3342 <th>Category</th>
3343 <td>
3344 <span tal:replace="structure context/category/field" />
3345 <span tal:replace="structure python:db.category.classhelp('name',
3346 property='category', width='200')" />
3347 </td>
3349 First, we define a nice header so that the user knows what the next
3350 section is, then the middle line does what we are most interested in.
3351 This ``context/category/field`` gets replaced by a field which contains
3352 the category in the current context (the current context being the new
3353 issue).
3355 The classhelp lines generate a link (labelled "list") to a popup window
3356 which contains the list of currently known categories.
3359 Searching on categories
3360 :::::::::::::::::::::::
3362 Now we can add categories, and create issues with categories. The next
3363 obvious thing that we would like to be able to do, would be to search
3364 for issues based on their category, so that, for example, anyone working
3365 on the web server could look at all issues in the category "Web".
3367 If you look for "Search Issues" in the ``html/page.html`` file, you will
3368 find that it looks something like
3369 ``<a href="issue?@template=search">Search Issues</a>``. This shows us
3370 that when you click on "Search Issues" it will be looking for a
3371 ``issue.search.html`` file to display. So that is the file that we will
3372 change.
3374 If you look at this file it should begin to seem familiar, although it
3375 does use some new macros. You can add the new category search code anywhere you
3376 like within that form::
3378 <tr tal:define="name string:category;
3379 db_klass string:category;
3380 db_content string:name;">
3381 <th>Priority:</th>
3382 <td metal:use-macro="search_select"></td>
3383 <td metal:use-macro="column_input"></td>
3384 <td metal:use-macro="sort_input"></td>
3385 <td metal:use-macro="group_input"></td>
3386 </tr>
3388 The definitions in the ``<tr>`` opening tag are used by the macros:
3390 - ``search_select`` expands to a drop-down box with all categories using
3391 ``db_klass`` and ``db_content``.
3392 - ``column_input`` expands to a checkbox for selecting what columns
3393 should be displayed.
3394 - ``sort_input`` expands to a radio button for selecting what property
3395 should be sorted on.
3396 - ``group_input`` expands to a radio button for selecting what property
3397 should be grouped on.
3399 The category search code above would expand to the following::
3401 <tr>
3402 <th>Category:</th>
3403 <td>
3404 <select name="category">
3405 <option value="">don't care</option>
3406 <option value="">------------</option>
3407 <option value="1">scipy</option>
3408 <option value="2">chaco</option>
3409 <option value="3">weave</option>
3410 </select>
3411 </td>
3412 <td><input type="checkbox" name=":columns" value="category"></td>
3413 <td><input type="radio" name=":sort0" value="category"></td>
3414 <td><input type="radio" name=":group0" value="category"></td>
3415 </tr>
3417 Adding category to the default view
3418 :::::::::::::::::::::::::::::::::::
3420 We can now add categories, add issues with categories, and search for
3421 issues based on categories. This is everything that we need to do;
3422 however, there is some more icing that we would like. I think the
3423 category of an issue is important enough that it should be displayed by
3424 default when listing all the issues.
3426 Unfortunately, this is a bit less obvious than the previous steps. The
3427 code defining how the issues look is in ``html/issue.index.html``. This
3428 is a large table with a form down at the bottom for redisplaying and so
3429 forth.
3431 Firstly we need to add an appropriate header to the start of the table::
3433 <th tal:condition="request/show/category">Category</th>
3435 The *condition* part of this statement is to avoid displaying the
3436 Category column if the user has selected not to see it.
3438 The rest of the table is a loop which will go through every issue that
3439 matches the display criteria. The loop variable is "i" - which means
3440 that every issue gets assigned to "i" in turn.
3442 The new part of code to display the category will look like this::
3444 <td tal:condition="request/show/category"
3445 tal:content="i/category"></td>
3447 The condition is the same as above: only display the condition when the
3448 user hasn't asked for it to be hidden. The next part is to set the
3449 content of the cell to be the category part of "i" - the current issue.
3451 Finally we have to edit ``html/page.html`` again. This time, we need to
3452 tell it that when the user clicks on "Unassigned Issues" or "All Issues",
3453 the category column should be included in the resulting list. If you
3454 scroll down the page file, you can see the links with lots of options.
3455 The option that we are interested in is the ``:columns=`` one which
3456 tells roundup which fields of the issue to display. Simply add
3457 "category" to that list and it all should work.
3459 Adding a time log to your issues
3460 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3462 We want to log the dates and amount of time spent working on issues, and
3463 be able to give a summary of the total time spent on a particular issue.
3465 1. Add a new class to your tracker ``schema.py``::
3467 # storage for time logging
3468 timelog = Class(db, "timelog", period=Interval())
3470 Note that we automatically get the date of the time log entry
3471 creation through the standard property "creation".
3473 You will need to grant "Creation" permission to the users who are
3474 allowed to add timelog entries. You may do this with::
3476 db.security.addPermissionToRole('User', 'Create', 'timelog')
3477 db.security.addPermissionToRole('User', 'View', 'timelog')
3479 If users are also able to *edit* timelog entries, then also include::
3481 db.security.addPermissionToRole('User', 'Edit', 'timelog')
3483 2. Link to the new class from your issue class (again, in
3484 ``schema.py``)::
3486 issue = IssueClass(db, "issue",
3487 assignedto=Link("user"), keyword=Multilink("keyword"),
3488 priority=Link("priority"), status=Link("status"),
3489 times=Multilink("timelog"))
3491 the "times" property is the new link to the "timelog" class.
3493 3. We'll need to let people add in times to the issue, so in the web
3494 interface we'll have a new entry field. This is a special field
3495 because unlike the other fields in the ``issue.item`` template, it
3496 affects a different item (a timelog item) and not the template's
3497 item (an issue). We have a special syntax for form fields that affect
3498 items other than the template default item (see the cgi
3499 documentation on `special form variables`_). In particular, we add a
3500 field to capture a new timelog item's period::
3502 <tr>
3503 <th>Time Log</th>
3504 <td colspan=3><input type="text" name="timelog-1@period" />
3505 (enter as '3y 1m 4d 2:40:02' or parts thereof)
3506 </td>
3507 </tr>
3509 and another hidden field that links that new timelog item (new
3510 because it's marked as having id "-1") to the issue item. It looks
3511 like this::
3513 <input type="hidden" name="@link@times" value="timelog-1" />
3515 On submission, the "-1" timelog item will be created and assigned a
3516 real item id. The "times" property of the issue will have the new id
3517 added to it.
3519 The full entry will now look like this::
3521 <tr>
3522 <th>Time Log</th>
3523 <td colspan=3><input type="text" name="timelog-1@period" />
3524 (enter as '3y 1m 4d 2:40:02' or parts thereof)
3525 <input type="hidden" name="@link@times" value="timelog-1" />
3526 </td>
3527 </tr>
3530 4. We want to display a total of the timelog times that have been
3531 accumulated for an issue. To do this, we'll need to actually write
3532 some Python code, since it's beyond the scope of PageTemplates to
3533 perform such calculations. We do this by adding a module ``timespent.py``
3534 to the ``extensions`` directory in our tracker. The contents of this
3535 file is as follows::
3537 from roundup import date
3539 def totalTimeSpent(times):
3540 ''' Call me with a list of timelog items (which have an
3541 Interval "period" property)
3542 '''
3543 total = date.Interval('0d')
3544 for time in times:
3545 total += time.period._value
3546 return total
3548 def init(instance):
3549 instance.registerUtil('totalTimeSpent', totalTimeSpent)
3551 We will now be able to access the ``totalTimeSpent`` function via the
3552 ``utils`` variable in our templates, as shown in the next step.
3554 5. Display the timelog for an issue::
3556 <table class="otherinfo" tal:condition="context/times">
3557 <tr><th colspan="3" class="header">Time Log
3558 <tal:block
3559 tal:replace="python:utils.totalTimeSpent(context.times)" />
3560 </th></tr>
3561 <tr><th>Date</th><th>Period</th><th>Logged By</th></tr>
3562 <tr tal:repeat="time context/times">
3563 <td tal:content="time/creation"></td>
3564 <td tal:content="time/period"></td>
3565 <td tal:content="time/creator"></td>
3566 </tr>
3567 </table>
3569 I put this just above the Messages log in my issue display. Note our
3570 use of the ``totalTimeSpent`` method which will total up the times
3571 for the issue and return a new Interval. That will be automatically
3572 displayed in the template as text like "+ 1y 2:40" (1 year, 2 hours
3573 and 40 minutes).
3575 6. If you're using a persistent web server - ``roundup-server`` or
3576 ``mod_python`` for example - then you'll need to restart that to pick up
3577 the code changes. When that's done, you'll be able to use the new
3578 time logging interface.
3580 An extension of this modification attaches the timelog entries to any
3581 change message entered at the time of the timelog entry:
3583 A. Add a link to the timelog to the msg class in ``schema.py``:
3585 msg = FileClass(db, "msg",
3586 author=Link("user", do_journal='no'),
3587 recipients=Multilink("user", do_journal='no'),
3588 date=Date(),
3589 summary=String(),
3590 files=Multilink("file"),
3591 messageid=String(),
3592 inreplyto=String(),
3593 times=Multilink("timelog"))
3595 B. Add a new hidden field that links that new timelog item (new
3596 because it's marked as having id "-1") to the new message.
3597 The link is placed in ``issue.item.html`` in the same section that
3598 handles the timelog entry.
3600 It looks like this after this addition::
3602 <tr>
3603 <th>Time Log</th>
3604 <td colspan=3><input type="text" name="timelog-1@period" />
3605 (enter as '3y 1m 4d 2:40:02' or parts thereof)
3606 <input type="hidden" name="@link@times" value="timelog-1" />
3607 <input type="hidden" name="msg-1@link@times" value="timelog-1" />
3608 </td>
3609 </tr>
3611 The "times" property of the message will have the new id added to it.
3613 C. Add the timelog listing from step 5. to the ``msg.item.html`` template
3614 so that the timelog entry appears on the message view page. Note that
3615 the call to totalTimeSpent is not used here since there will only be one
3616 single timelog entry for each message.
3618 I placed it after the Date entry like this::
3620 <tr>
3621 <th i18n:translate="">Date:</th>
3622 <td tal:content="context/date"></td>
3623 </tr>
3624 </table>
3626 <table class="otherinfo" tal:condition="context/times">
3627 <tr><th colspan="3" class="header">Time Log</th></tr>
3628 <tr><th>Date</th><th>Period</th><th>Logged By</th></tr>
3629 <tr tal:repeat="time context/times">
3630 <td tal:content="time/creation"></td>
3631 <td tal:content="time/period"></td>
3632 <td tal:content="time/creator"></td>
3633 </tr>
3634 </table>
3636 <table class="messages">
3639 Tracking different types of issues
3640 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3642 Sometimes you will want to track different types of issues - developer,
3643 customer support, systems, sales leads, etc. A single Roundup tracker is
3644 able to support multiple types of issues. This example demonstrates adding
3645 a system support issue class to a tracker.
3647 1. Figure out what information you're going to want to capture. OK, so
3648 this is obvious, but sometimes it's better to actually sit down for a
3649 while and think about the schema you're going to implement.
3651 2. Add the new issue class to your tracker's ``schema.py``. Just after the
3652 "issue" class definition, add::
3654 # list our systems
3655 system = Class(db, "system", name=String(), order=Number())
3656 system.setkey("name")
3658 # store issues related to those systems
3659 support = IssueClass(db, "support",
3660 assignedto=Link("user"), keyword=Multilink("keyword"),
3661 status=Link("status"), deadline=Date(),
3662 affects=Multilink("system"))
3664 3. Copy the existing ``issue.*`` (item, search and index) templates in the
3665 tracker's ``html`` to ``support.*``. Edit them so they use the properties
3666 defined in the ``support`` class. Be sure to check for hidden form
3667 variables like "required" to make sure they have the correct set of
3668 required properties.
3670 4. Edit the modules in the ``detectors``, adding lines to their ``init``
3671 functions where appropriate. Look for ``audit`` and ``react`` registrations
3672 on the ``issue`` class, and duplicate them for ``support``.
3674 5. Create a new sidebar box for the new support class. Duplicate the
3675 existing issues one, changing the ``issue`` class name to ``support``.
3677 6. Re-start your tracker and start using the new ``support`` class.
3680 Optionally, you might want to restrict the users able to access this new
3681 class to just the users with a new "SysAdmin" Role. To do this, we add
3682 some security declarations::
3684 db.security.addPermissionToRole('SysAdmin', 'View', 'support')
3685 db.security.addPermissionToRole('SysAdmin', 'Create', 'support')
3686 db.security.addPermissionToRole('SysAdmin', 'Edit', 'support')
3688 You would then (as an "admin" user) edit the details of the appropriate
3689 users, and add "SysAdmin" to their Roles list.
3691 Alternatively, you might want to change the Edit/View permissions granted
3692 for the ``issue`` class so that it's only available to users with the "System"
3693 or "Developer" Role, and then the new class you're adding is available to
3694 all with the "User" Role.
3697 Using External User Databases
3698 -----------------------------
3700 Using an external password validation source
3701 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3703 .. note:: You will need to either have an "admin" user in your external
3704 password source *or* have one of your regular users have
3705 the Admin Role assigned. If you need to assign the Role *after*
3706 making the changes below, you may use the ``roundup-admin``
3707 program to edit a user's details.
3709 We have a centrally-managed password changing system for our users. This
3710 results in a UN*X passwd-style file that we use for verification of
3711 users. Entries in the file consist of ``name:password`` where the
3712 password is encrypted using the standard UN*X ``crypt()`` function (see
3713 the ``crypt`` module in your Python distribution). An example entry
3714 would be::
3716 admin:aamrgyQfDFSHw
3718 Each user of Roundup must still have their information stored in the Roundup
3719 database - we just use the passwd file to check their password. To do this, we
3720 need to override the standard ``verifyPassword`` method defined in
3721 ``roundup.cgi.actions.LoginAction`` and register the new class. The
3722 following is added as ``externalpassword.py`` in the tracker ``extensions``
3723 directory::
3725 import os, crypt
3726 from roundup.cgi.actions import LoginAction
3728 class ExternalPasswordLoginAction(LoginAction):
3729 def verifyPassword(self, userid, password):
3730 '''Look through the file, line by line, looking for a
3731 name that matches.
3732 '''
3733 # get the user's username
3734 username = self.db.user.get(userid, 'username')
3736 # the passwords are stored in the "passwd.txt" file in the
3737 # tracker home
3738 file = os.path.join(self.db.config.TRACKER_HOME, 'passwd.txt')
3740 # see if we can find a match
3741 for ent in [line.strip().split(':') for line in
3742 open(file).readlines()]:
3743 if ent[0] == username:
3744 return crypt.crypt(password, ent[1][:2]) == ent[1]
3746 # user doesn't exist in the file
3747 return 0
3749 def init(instance):
3750 instance.registerAction('login', ExternalPasswordLoginAction)
3752 You should also remove the redundant password fields from the ``user.item``
3753 template.
3756 Using a UN*X passwd file as the user database
3757 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3759 On some systems the primary store of users is the UN*X passwd file. It
3760 holds information on users such as their username, real name, password
3761 and primary user group.
3763 Roundup can use this store as its primary source of user information,
3764 but it needs additional information too - email address(es), roundup
3765 Roles, vacation flags, roundup hyperdb item ids, etc. Also, "retired"
3766 users must still exist in the user database, unlike some passwd files in
3767 which the users are removed when they no longer have access to a system.
3769 To make use of the passwd file, we therefore synchronise between the two
3770 user stores. We also use the passwd file to validate the user logins, as
3771 described in the previous example, `using an external password
3772 validation source`_. We keep the user lists in sync using a fairly
3773 simple script that runs once a day, or several times an hour if more
3774 immediate access is needed. In short, it:
3776 1. parses the passwd file, finding usernames, passwords and real names,
3777 2. compares that list to the current roundup user list:
3779 a. entries no longer in the passwd file are *retired*
3780 b. entries with mismatching real names are *updated*
3781 c. entries only exist in the passwd file are *created*
3783 3. send an email to administrators to let them know what's been done.
3785 The retiring and updating are simple operations, requiring only a call
3786 to ``retire()`` or ``set()``. The creation operation requires more
3787 information though - the user's email address and their Roundup Roles.
3788 We're going to assume that the user's email address is the same as their
3789 login name, so we just append the domain name to that. The Roles are
3790 determined using the passwd group identifier - mapping their UN*X group
3791 to an appropriate set of Roles.
3793 The script to perform all this, broken up into its main components, is
3794 as follows. Firstly, we import the necessary modules and open the
3795 tracker we're to work on::
3797 import sys, os, smtplib
3798 from roundup import instance, date
3800 # open the tracker
3801 tracker_home = sys.argv[1]
3802 tracker = instance.open(tracker_home)
3804 Next we read in the *passwd* file from the tracker home::
3806 # read in the users from the "passwd.txt" file
3807 file = os.path.join(tracker_home, 'passwd.txt')
3808 users = [x.strip().split(':') for x in open(file).readlines()]
3810 Handle special users (those to ignore in the file, and those who don't
3811 appear in the file)::
3813 # users to not keep ever, pre-load with the users I know aren't
3814 # "real" users
3815 ignore = ['ekmmon', 'bfast', 'csrmail']
3817 # users to keep - pre-load with the roundup-specific users
3818 keep = ['comment_pool', 'network_pool', 'admin', 'dev-team',
3819 'cs_pool', 'anonymous', 'system_pool', 'automated']
3821 Now we map the UN*X group numbers to the Roles that users should have::
3823 roles = {
3824 '501': 'User,Tech', # tech
3825 '502': 'User', # finance
3826 '503': 'User,CSR', # customer service reps
3827 '504': 'User', # sales
3828 '505': 'User', # marketing
3829 }
3831 Now we do all the work. Note that the body of the script (where we have
3832 the tracker database open) is wrapped in a ``try`` / ``finally`` clause,
3833 so that we always close the database cleanly when we're finished. So, we
3834 now do all the work::
3836 # open the database
3837 db = tracker.open('admin')
3838 try:
3839 # store away messages to send to the tracker admins
3840 msg = []
3842 # loop over the users list read in from the passwd file
3843 for user,passw,uid,gid,real,home,shell in users:
3844 if user in ignore:
3845 # this user shouldn't appear in our tracker
3846 continue
3847 keep.append(user)
3848 try:
3849 # see if the user exists in the tracker
3850 uid = db.user.lookup(user)
3852 # yes, they do - now check the real name for correctness
3853 if real != db.user.get(uid, 'realname'):
3854 db.user.set(uid, realname=real)
3855 msg.append('FIX %s - %s'%(user, real))
3856 except KeyError:
3857 # nope, the user doesn't exist
3858 db.user.create(username=user, realname=real,
3859 address='%s@ekit-inc.com'%user, roles=roles[gid])
3860 msg.append('ADD %s - %s (%s)'%(user, real, roles[gid]))
3862 # now check that all the users in the tracker are also in our
3863 # "keep" list - retire those who aren't
3864 for uid in db.user.list():
3865 user = db.user.get(uid, 'username')
3866 if user not in keep:
3867 db.user.retire(uid)
3868 msg.append('RET %s'%user)
3870 # if we did work, then send email to the tracker admins
3871 if msg:
3872 # create the email
3873 msg = '''Subject: %s user database maintenance
3875 %s
3876 '''%(db.config.TRACKER_NAME, '\n'.join(msg))
3878 # send the email
3879 smtp = smtplib.SMTP(db.config.MAILHOST)
3880 addr = db.config.ADMIN_EMAIL
3881 smtp.sendmail(addr, addr, msg)
3883 # now we're done - commit the changes
3884 db.commit()
3885 finally:
3886 # always close the database cleanly
3887 db.close()
3889 And that's it!
3892 Using an LDAP database for user information
3893 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3895 A script that reads users from an LDAP store using
3896 http://python-ldap.sf.net/ and then compares the list to the users in the
3897 roundup user database would be pretty easy to write. You'd then have it run
3898 once an hour / day (or on demand if you can work that into your LDAP store
3899 workflow). See the example `Using a UN*X passwd file as the user database`_
3900 for more information about doing this.
3902 To authenticate off the LDAP store (rather than using the passwords in the
3903 Roundup user database) you'd use the same python-ldap module inside an
3904 extension to the cgi interface. You'd do this by overriding the method called
3905 ``verifyPassword`` on the ``LoginAction`` class in your tracker's
3906 ``extensions`` directory (see `using an external password validation
3907 source`_). The method is implemented by default as::
3909 def verifyPassword(self, userid, password):
3910 ''' Verify the password that the user has supplied
3911 '''
3912 stored = self.db.user.get(self.userid, 'password')
3913 if password == stored:
3914 return 1
3915 if not password and not stored:
3916 return 1
3917 return 0
3919 So you could reimplement this as something like::
3921 def verifyPassword(self, userid, password):
3922 ''' Verify the password that the user has supplied
3923 '''
3924 # look up some unique LDAP information about the user
3925 username = self.db.user.get(self.userid, 'username')
3926 # now verify the password supplied against the LDAP store
3929 Changes to Tracker Behaviour
3930 ----------------------------
3932 Preventing SPAM
3933 ~~~~~~~~~~~~~~~
3935 The following detector code may be installed in your tracker's
3936 ``detectors`` directory. It will block any messages being created that
3937 have HTML attachments (a very common vector for spam and phishing)
3938 and any messages that have more than 2 HTTP URLs in them. Just copy
3939 the following into ``detectors/anti_spam.py`` in your tracker::
3941 from roundup.exceptions import Reject
3943 def reject_html(db, cl, nodeid, newvalues):
3944 if newvalues['type'] == 'text/html':
3945 raise Reject, 'not allowed'
3947 def reject_manylinks(db, cl, nodeid, newvalues):
3948 content = newvalues['content']
3949 if content.count('http://') > 2:
3950 raise Reject, 'not allowed'
3952 def init(db):
3953 db.file.audit('create', reject_html)
3954 db.msg.audit('create', reject_manylinks)
3956 You may also wish to block image attachments if your tracker does not
3957 need that ability::
3959 if newvalues['type'].startswith('image/'):
3960 raise Reject, 'not allowed'
3963 Stop "nosy" messages going to people on vacation
3964 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3966 When users go on vacation and set up vacation email bouncing, you'll
3967 start to see a lot of messages come back through Roundup "Fred is on
3968 vacation". Not very useful, and relatively easy to stop.
3970 1. add a "vacation" flag to your users::
3972 user = Class(db, "user",
3973 username=String(), password=Password(),
3974 address=String(), realname=String(),
3975 phone=String(), organisation=String(),
3976 alternate_addresses=String(),
3977 roles=String(), queries=Multilink("query"),
3978 vacation=Boolean())
3980 2. So that users may edit the vacation flags, add something like the
3981 following to your ``user.item`` template::
3983 <tr>
3984 <th>On Vacation</th>
3985 <td tal:content="structure context/vacation/field">vacation</td>
3986 </tr>
3988 3. edit your detector ``nosyreactor.py`` so that the ``nosyreaction()``
3989 consists of::
3991 def nosyreaction(db, cl, nodeid, oldvalues):
3992 users = db.user
3993 messages = db.msg
3994 # send a copy of all new messages to the nosy list
3995 for msgid in determineNewMessages(cl, nodeid, oldvalues):
3996 try:
3997 # figure the recipient ids
3998 sendto = []
3999 seen_message = {}
4000 recipients = messages.get(msgid, 'recipients')
4001 for recipid in messages.get(msgid, 'recipients'):
4002 seen_message[recipid] = 1
4004 # figure the author's id, and indicate they've received
4005 # the message
4006 authid = messages.get(msgid, 'author')
4008 # possibly send the message to the author, as long as
4009 # they aren't anonymous
4010 if (db.config.MESSAGES_TO_AUTHOR == 'yes' and
4011 users.get(authid, 'username') != 'anonymous'):
4012 sendto.append(authid)
4013 seen_message[authid] = 1
4015 # now figure the nosy people who weren't recipients
4016 nosy = cl.get(nodeid, 'nosy')
4017 for nosyid in nosy:
4018 # Don't send nosy mail to the anonymous user (that
4019 # user shouldn't appear in the nosy list, but just
4020 # in case they do...)
4021 if users.get(nosyid, 'username') == 'anonymous':
4022 continue
4023 # make sure they haven't seen the message already
4024 if not seen_message.has_key(nosyid):
4025 # send it to them
4026 sendto.append(nosyid)
4027 recipients.append(nosyid)
4029 # generate a change note
4030 if oldvalues:
4031 note = cl.generateChangeNote(nodeid, oldvalues)
4032 else:
4033 note = cl.generateCreateNote(nodeid)
4035 # we have new recipients
4036 if sendto:
4037 # filter out the people on vacation
4038 sendto = [i for i in sendto
4039 if not users.get(i, 'vacation', 0)]
4041 # map userids to addresses
4042 sendto = [users.get(i, 'address') for i in sendto]
4044 # update the message's recipients list
4045 messages.set(msgid, recipients=recipients)
4047 # send the message
4048 cl.send_message(nodeid, msgid, note, sendto)
4049 except roundupdb.MessageSendError, message:
4050 raise roundupdb.DetectorError, message
4052 Note that this is the standard nosy reaction code, with the small
4053 addition of::
4055 # filter out the people on vacation
4056 sendto = [i for i in sendto if not users.get(i, 'vacation', 0)]
4058 which filters out the users that have the vacation flag set to true.
4060 Adding in state transition control
4061 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4063 Sometimes tracker admins want to control the states to which users may
4064 move issues. You can do this by following these steps:
4066 1. make "status" a required variable. This is achieved by adding the
4067 following to the top of the form in the ``issue.item.html``
4068 template::
4070 <input type="hidden" name="@required" value="status">
4072 This will force users to select a status.
4074 2. add a Multilink property to the status class::
4076 stat = Class(db, "status", ... , transitions=Multilink('status'),
4077 ...)
4079 and then edit the statuses already created, either:
4081 a. through the web using the class list -> status class editor, or
4082 b. using the ``roundup-admin`` "set" command.
4084 3. add an auditor module ``checktransition.py`` in your tracker's
4085 ``detectors`` directory, for example::
4087 def checktransition(db, cl, nodeid, newvalues):
4088 ''' Check that the desired transition is valid for the "status"
4089 property.
4090 '''
4091 if not newvalues.has_key('status'):
4092 return
4093 current = cl.get(nodeid, 'status')
4094 new = newvalues['status']
4095 if new == current:
4096 return
4097 ok = db.status.get(current, 'transitions')
4098 if new not in ok:
4099 raise ValueError, 'Status not allowed to move from "%s" to "%s"'%(
4100 db.status.get(current, 'name'), db.status.get(new, 'name'))
4102 def init(db):
4103 db.issue.audit('set', checktransition)
4105 4. in the ``issue.item.html`` template, change the status editing bit
4106 from::
4108 <th>Status</th>
4109 <td tal:content="structure context/status/menu">status</td>
4111 to::
4113 <th>Status</th>
4114 <td>
4115 <select tal:condition="context/id" name="status">
4116 <tal:block tal:define="ok context/status/transitions"
4117 tal:repeat="state db/status/list">
4118 <option tal:condition="python:state.id in ok"
4119 tal:attributes="
4120 value state/id;
4121 selected python:state.id == context.status.id"
4122 tal:content="state/name"></option>
4123 </tal:block>
4124 </select>
4125 <tal:block tal:condition="not:context/id"
4126 tal:replace="structure context/status/menu" />
4127 </td>
4129 which displays only the allowed status to transition to.
4132 Blocking issues that depend on other issues
4133 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4135 We needed the ability to mark certain issues as "blockers" - that is,
4136 they can't be resolved until another issue (the blocker) they rely on is
4137 resolved. To achieve this:
4139 1. Create a new property on the ``issue`` class:
4140 ``blockers=Multilink("issue")``. To do this, edit the definition of
4141 this class in your tracker's ``schema.py`` file. Change this::
4143 issue = IssueClass(db, "issue",
4144 assignedto=Link("user"), keyword=Multilink("keyword"),
4145 priority=Link("priority"), status=Link("status"))
4147 to this, adding the blockers entry::
4149 issue = IssueClass(db, "issue",
4150 blockers=Multilink("issue"),
4151 assignedto=Link("user"), keyword=Multilink("keyword"),
4152 priority=Link("priority"), status=Link("status"))
4154 2. Add the new ``blockers`` property to the ``issue.item.html`` edit
4155 page, using something like::
4157 <th>Waiting On</th>
4158 <td>
4159 <span tal:replace="structure python:context.blockers.field(showid=1,
4160 size=20)" />
4161 <span tal:replace="structure python:db.issue.classhelp('id,title',
4162 property='blockers')" />
4163 <span tal:condition="context/blockers"
4164 tal:repeat="blk context/blockers">
4165 <br>View: <a tal:attributes="href string:issue${blk/id}"
4166 tal:content="blk/id"></a>
4167 </span>
4168 </td>
4170 You'll need to fiddle with your item page layout to find an
4171 appropriate place to put it - I'll leave that fun part up to you.
4172 Just make sure it appears in the first table, possibly somewhere near
4173 the "superseders" field.
4175 3. Create a new detector module (see below) which enforces the rules:
4177 - issues may not be resolved if they have blockers
4178 - when a blocker is resolved, it's removed from issues it blocks
4180 The contents of the detector should be something like this::
4183 def blockresolution(db, cl, nodeid, newvalues):
4184 ''' If the issue has blockers, don't allow it to be resolved.
4185 '''
4186 if nodeid is None:
4187 blockers = []
4188 else:
4189 blockers = cl.get(nodeid, 'blockers')
4190 blockers = newvalues.get('blockers', blockers)
4192 # don't do anything if there's no blockers or the status hasn't
4193 # changed
4194 if not blockers or not newvalues.has_key('status'):
4195 return
4197 # get the resolved state ID
4198 resolved_id = db.status.lookup('resolved')
4200 # format the info
4201 u = db.config.TRACKER_WEB
4202 s = ', '.join(['<a href="%sissue%s">%s</a>'%(
4203 u,id,id) for id in blockers])
4204 if len(blockers) == 1:
4205 s = 'issue %s is'%s
4206 else:
4207 s = 'issues %s are'%s
4209 # ok, see if we're trying to resolve
4210 if newvalues['status'] == resolved_id:
4211 raise ValueError, "This issue can't be resolved until %s resolved."%s
4214 def resolveblockers(db, cl, nodeid, oldvalues):
4215 ''' When we resolve an issue that's a blocker, remove it from the
4216 blockers list of the issue(s) it blocks.
4217 '''
4218 newstatus = cl.get(nodeid,'status')
4220 # no change?
4221 if oldvalues.get('status', None) == newstatus:
4222 return
4224 resolved_id = db.status.lookup('resolved')
4226 # interesting?
4227 if newstatus != resolved_id:
4228 return
4230 # yes - find all the blocked issues, if any, and remove me from
4231 # their blockers list
4232 issues = cl.find(blockers=nodeid)
4233 for issueid in issues:
4234 blockers = cl.get(issueid, 'blockers')
4235 if nodeid in blockers:
4236 blockers.remove(nodeid)
4237 cl.set(issueid, blockers=blockers)
4239 def init(db):
4240 # might, in an obscure situation, happen in a create
4241 db.issue.audit('create', blockresolution)
4242 db.issue.audit('set', blockresolution)
4244 # can only happen on a set
4245 db.issue.react('set', resolveblockers)
4247 Put the above code in a file called "blockers.py" in your tracker's
4248 "detectors" directory.
4250 4. Finally, and this is an optional step, modify the tracker web page
4251 URLs so they filter out issues with any blockers. You do this by
4252 adding an additional filter on "blockers" for the value "-1". For
4253 example, the existing "Show All" link in the "page" template (in the
4254 tracker's "html" directory) looks like this::
4256 <a href="#"
4257 tal:attributes="href python:request.indexargs_url('issue', {
4258 '@sort': '-activity',
4259 '@group': 'priority',
4260 '@filter': 'status',
4261 '@columns': columns_showall,
4262 '@search_text': '',
4263 'status': status_notresolved,
4264 '@dispname': i18n.gettext('Show All'),
4265 })"
4266 i18n:translate="">Show All</a><br>
4268 modify it to add the "blockers" info to the URL (note, both the
4269 "@filter" *and* "blockers" values must be specified)::
4271 <a href="#"
4272 tal:attributes="href python:request.indexargs_url('issue', {
4273 '@sort': '-activity',
4274 '@group': 'priority',
4275 '@filter': 'status,blockers',
4276 '@columns': columns_showall,
4277 '@search_text': '',
4278 'status': status_notresolved,
4279 'blockers': '-1',
4280 '@dispname': i18n.gettext('Show All'),
4281 })"
4282 i18n:translate="">Show All</a><br>
4284 The above examples are line-wrapped on the trailing & and should
4285 be unwrapped.
4287 That's it. You should now be able to set blockers on your issues. Note
4288 that if you want to know whether an issue has any other issues dependent
4289 on it (i.e. it's in their blockers list) you can look at the journal
4290 history at the bottom of the issue page - look for a "link" event to
4291 another issue's "blockers" property.
4293 Add users to the nosy list based on the keyword
4294 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4296 Let's say we need the ability to automatically add users to the nosy
4297 list based
4298 on the occurance of a keyword. Every user should be allowed to edit their
4299 own list of keywords for which they want to be added to the nosy list.
4301 Below, we'll show that this change can be done with minimal
4302 understanding of the Roundup system, using only copy and paste.
4304 This requires three changes to the tracker: a change in the database to
4305 allow per-user recording of the lists of keywords for which he wants to
4306 be put on the nosy list, a change in the user view allowing them to edit
4307 this list of keywords, and addition of an auditor which updates the nosy
4308 list when a keyword is set.
4310 Adding the nosy keyword list
4311 ::::::::::::::::::::::::::::
4313 The change to make in the database, is that for any user there should be a list
4314 of keywords for which he wants to be put on the nosy list. Adding a
4315 ``Multilink`` of ``keyword`` seems to fullfill this. As such, all that has to
4316 be done is to add a new field to the definition of ``user`` within the file
4317 ``schema.py``. We will call this new field ``nosy_keywords``, and the updated
4318 definition of user will be::
4320 user = Class(db, "user",
4321 username=String(), password=Password(),
4322 address=String(), realname=String(),
4323 phone=String(), organisation=String(),
4324 alternate_addresses=String(),
4325 queries=Multilink('query'), roles=String(),
4326 timezone=String(),
4327 nosy_keywords=Multilink('keyword'))
4329 Changing the user view to allow changing the nosy keyword list
4330 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
4332 We want any user to be able to change the list of keywords for which
4333 he will by default be added to the nosy list. We choose to add this
4334 to the user view, as is generated by the file ``html/user.item.html``.
4335 We can easily
4336 see that the keyword field in the issue view has very similar editing
4337 requirements as our nosy keywords, both being lists of keywords. As
4338 such, we look for Keywords in ``issue.item.html``, and extract the
4339 associated parts from there. We add this to ``user.item.html`` at the
4340 bottom of the list of viewed items (i.e. just below the 'Alternate
4341 E-mail addresses' in the classic template)::
4343 <tr>
4344 <th>Nosy Keywords</th>
4345 <td>
4346 <span tal:replace="structure context/nosy_keywords/field" />
4347 <span tal:replace="structure python:db.keyword.classhelp(property='nosy_keywords')" />
4348 </td>
4349 </tr>
4352 Addition of an auditor to update the nosy list
4353 ::::::::::::::::::::::::::::::::::::::::::::::
4355 The more difficult part is the logic to add
4356 the users to the nosy list when required.
4357 We choose to perform this action whenever the keywords on an
4358 item are set (this includes the creation of items).
4359 Here we choose to start out with a copy of the
4360 ``detectors/nosyreaction.py`` detector, which we copy to the file
4361 ``detectors/nosy_keyword_reaction.py``.
4362 This looks like a good start as it also adds users
4363 to the nosy list. A look through the code reveals that the
4364 ``nosyreaction`` function actually sends the e-mail.
4365 We don't need this. Therefore, we can change the ``init`` function to::
4367 def init(db):
4368 db.issue.audit('create', update_kw_nosy)
4369 db.issue.audit('set', update_kw_nosy)
4371 After that, we rename the ``updatenosy`` function to ``update_kw_nosy``.
4372 The first two blocks of code in that function relate to setting
4373 ``current`` to a combination of the old and new nosy lists. This
4374 functionality is left in the new auditor. The following block of
4375 code, which handled adding the assignedto user(s) to the nosy list in
4376 ``updatenosy``, should be replaced by a block of code to add the
4377 interested users to the nosy list. We choose here to loop over all
4378 new keywords, than looping over all users,
4379 and assign the user to the nosy list when the keyword occurs in the user's
4380 ``nosy_keywords``. The next part in ``updatenosy`` -- adding the author
4381 and/or recipients of a message to the nosy list -- is obviously not
4382 relevant here and is thus deleted from the new auditor. The last
4383 part, copying the new nosy list to ``newvalues``, can stay as is.
4384 This results in the following function::
4386 def update_kw_nosy(db, cl, nodeid, newvalues):
4387 '''Update the nosy list for changes to the keywords
4388 '''
4389 # nodeid will be None if this is a new node
4390 current = {}
4391 if nodeid is None:
4392 ok = ('new', 'yes')
4393 else:
4394 ok = ('yes',)
4395 # old node, get the current values from the node if they haven't
4396 # changed
4397 if not newvalues.has_key('nosy'):
4398 nosy = cl.get(nodeid, 'nosy')
4399 for value in nosy:
4400 if not current.has_key(value):
4401 current[value] = 1
4403 # if the nosy list changed in this transaction, init from the new value
4404 if newvalues.has_key('nosy'):
4405 nosy = newvalues.get('nosy', [])
4406 for value in nosy:
4407 if not db.hasnode('user', value):
4408 continue
4409 if not current.has_key(value):
4410 current[value] = 1
4412 # add users with keyword in nosy_keywords to the nosy list
4413 if newvalues.has_key('keyword') and newvalues['keyword'] is not None:
4414 keyword_ids = newvalues['keyword']
4415 for keyword in keyword_ids:
4416 # loop over all users,
4417 # and assign user to nosy when keyword in nosy_keywords
4418 for user_id in db.user.list():
4419 nosy_kw = db.user.get(user_id, "nosy_keywords")
4420 found = 0
4421 for kw in nosy_kw:
4422 if kw == keyword:
4423 found = 1
4424 if found:
4425 current[user_id] = 1
4427 # that's it, save off the new nosy list
4428 newvalues['nosy'] = current.keys()
4430 These two function are the only ones needed in the file.
4432 TODO: update this example to use the ``find()`` Class method.
4434 Caveats
4435 :::::::
4437 A few problems with the design here can be noted:
4439 Multiple additions
4440 When a user, after automatic selection, is manually removed
4441 from the nosy list, he is added to the nosy list again when the
4442 keyword list of the issue is updated. A better design might be
4443 to only check which keywords are new compared to the old list
4444 of keywords, and only add users when they have indicated
4445 interest on a new keyword.
4447 The code could also be changed to only trigger on the ``create()``
4448 event, rather than also on the ``set()`` event, thus only setting
4449 the nosy list when the issue is created.
4451 Scalability
4452 In the auditor, there is a loop over all users. For a site with
4453 only few users this will pose no serious problem; however, with
4454 many users this will be a serious performance bottleneck.
4455 A way out would be to link from the keywords to the users who
4456 selected these keywords as nosy keywords. This will eliminate the
4457 loop over all users.
4459 Changes to Security and Permissions
4460 -----------------------------------
4462 Restricting the list of users that are assignable to a task
4463 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4465 1. In your tracker's ``schema.py``, create a new Role, say "Developer"::
4467 db.security.addRole(name='Developer', description='A developer')
4469 2. Just after that, create a new Permission, say "Fixer", specific to
4470 "issue"::
4472 p = db.security.addPermission(name='Fixer', klass='issue',
4473 description='User is allowed to be assigned to fix issues')
4475 3. Then assign the new Permission to your "Developer" Role::
4477 db.security.addPermissionToRole('Developer', p)
4479 4. In the issue item edit page (``html/issue.item.html`` in your tracker
4480 directory), use the new Permission in restricting the "assignedto"
4481 list::
4483 <select name="assignedto">
4484 <option value="-1">- no selection -</option>
4485 <tal:block tal:repeat="user db/user/list">
4486 <option tal:condition="python:user.hasPermission(
4487 'Fixer', context._classname)"
4488 tal:attributes="
4489 value user/id;
4490 selected python:user.id == context.assignedto"
4491 tal:content="user/realname"></option>
4492 </tal:block>
4493 </select>
4495 For extra security, you may wish to setup an auditor to enforce the
4496 Permission requirement (install this as ``assignedtoFixer.py`` in your
4497 tracker ``detectors`` directory)::
4499 def assignedtoMustBeFixer(db, cl, nodeid, newvalues):
4500 ''' Ensure the assignedto value in newvalues is used with the
4501 Fixer Permission
4502 '''
4503 if not newvalues.has_key('assignedto'):
4504 # don't care
4505 return
4507 # get the userid
4508 userid = newvalues['assignedto']
4509 if not db.security.hasPermission('Fixer', userid, cl.classname):
4510 raise ValueError, 'You do not have permission to edit %s'%cl.classname
4512 def init(db):
4513 db.issue.audit('set', assignedtoMustBeFixer)
4514 db.issue.audit('create', assignedtoMustBeFixer)
4516 So now, if an edit action attempts to set "assignedto" to a user that
4517 doesn't have the "Fixer" Permission, the error will be raised.
4520 Users may only edit their issues
4521 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4523 In this case, users registering themselves are granted Provisional
4524 access, meaning they
4525 have access to edit the issues they submit, but not others. We create a new
4526 Role called "Provisional User" which is granted to newly-registered users,
4527 and has limited access. One of the Permissions they have is the new "Edit
4528 Own" on issues (regular users have "Edit".)
4530 First up, we create the new Role and Permission structure in
4531 ``schema.py``::
4533 #
4534 # New users not approved by the admin
4535 #
4536 db.security.addRole(name='Provisional User',
4537 description='New user registered via web or email')
4539 # These users need to be able to view and create issues but only edit
4540 # and view their own
4541 db.security.addPermissionToRole('Provisional User', 'Create', 'issue')
4542 def own_issue(db, userid, itemid):
4543 '''Determine whether the userid matches the creator of the issue.'''
4544 return userid == db.issue.get(itemid, 'creator')
4545 p = db.security.addPermission(name='Edit', klass='issue',
4546 check=own_issue, description='Can only edit own issues')
4547 db.security.addPermissionToRole('Provisional User', p)
4548 p = db.security.addPermission(name='View', klass='issue',
4549 check=own_issue, description='Can only view own issues')
4550 db.security.addPermissionToRole('Provisional User', p)
4552 # Assign the Permissions for issue-related classes
4553 for cl in 'file', 'msg', 'query', 'keyword':
4554 db.security.addPermissionToRole('Provisional User', 'View', cl)
4555 db.security.addPermissionToRole('Provisional User', 'Edit', cl)
4556 db.security.addPermissionToRole('Provisional User', 'Create', cl)
4557 for cl in 'priority', 'status':
4558 db.security.addPermissionToRole('Provisional User', 'View', cl)
4560 # and give the new users access to the web and email interface
4561 db.security.addPermissionToRole('Provisional User', 'Web Access')
4562 db.security.addPermissionToRole('Provisional User', 'Email Access')
4564 # make sure they can view & edit their own user record
4565 def own_record(db, userid, itemid):
4566 '''Determine whether the userid matches the item being accessed.'''
4567 return userid == itemid
4568 p = db.security.addPermission(name='View', klass='user', check=own_record,
4569 description="User is allowed to view their own user details")
4570 db.security.addPermissionToRole('Provisional User', p)
4571 p = db.security.addPermission(name='Edit', klass='user', check=own_record,
4572 description="User is allowed to edit their own user details")
4573 db.security.addPermissionToRole('Provisional User', p)
4575 Then, in ``config.ini``, we change the Role assigned to newly-registered
4576 users, replacing the existing ``'User'`` values::
4578 [main]
4579 ...
4580 new_web_user_roles = 'Provisional User'
4581 new_email_user_roles = 'Provisional User'
4584 All users may only view and edit issues, files and messages they create
4585 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4587 Replace the standard "classic" tracker View and Edit Permission assignments
4588 for the "issue", "file" and "msg" classes with the following::
4590 def checker(klass):
4591 def check(db, userid, itemid, klass=klass):
4592 return db.getclass(klass).get(itemid, 'creator') == userid
4593 return check
4594 for cl in 'issue', 'file', 'msg':
4595 p = db.security.addPermission(name='View', klass=cl,
4596 check=checker(cl))
4597 db.security.addPermissionToRole('User', p)
4598 p = db.security.addPermission(name='Edit', klass=cl,
4599 check=checker(cl))
4600 db.security.addPermissionToRole('User', p)
4601 db.security.addPermissionToRole('User', 'Create', cl)
4605 Changes to the Web User Interface
4606 ---------------------------------
4608 Adding action links to the index page
4609 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4611 Add a column to the ``item.index.html`` template.
4613 Resolving the issue::
4615 <a tal:attributes="href
4616 string:issue${i/id}?:status=resolved&:action=edit">resolve</a>
4618 "Take" the issue::
4620 <a tal:attributes="href
4621 string:issue${i/id}?:assignedto=${request/user/id}&:action=edit">take</a>
4623 ... and so on.
4625 Colouring the rows in the issue index according to priority
4626 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4628 A simple ``tal:attributes`` statement will do the bulk of the work here. In
4629 the ``issue.index.html`` template, add this to the ``<tr>`` that
4630 displays the rows of data::
4632 <tr tal:attributes="class string:priority-${i/priority/plain}">
4634 and then in your stylesheet (``style.css``) specify the colouring for the
4635 different priorities, as follows::
4637 tr.priority-critical td {
4638 background-color: red;
4639 }
4641 tr.priority-urgent td {
4642 background-color: orange;
4643 }
4645 and so on, with far less offensive colours :)
4647 Editing multiple items in an index view
4648 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4650 To edit the status of all items in the item index view, edit the
4651 ``issue.item.html``:
4653 1. add a form around the listing table (separate from the existing
4654 index-page form), so at the top it reads::
4656 <form method="POST" tal:attributes="action request/classname">
4657 <table class="list">
4659 and at the bottom of that table::
4661 </table>
4662 </form
4664 making sure you match the ``</table>`` from the list table, not the
4665 navigation table or the subsequent form table.
4667 2. in the display for the issue property, change::
4669 <td tal:condition="request/show/status"
4670 tal:content="python:i.status.plain() or default"> </td>
4672 to::
4674 <td tal:condition="request/show/status"
4675 tal:content="structure i/status/field"> </td>
4677 this will result in an edit field for the status property.
4679 3. after the ``tal:block`` which lists the index items (marked by
4680 ``tal:repeat="i batch"``) add a new table row::
4682 <tr>
4683 <td tal:attributes="colspan python:len(request.columns)">
4684 <input type="submit" value=" Save Changes ">
4685 <input type="hidden" name="@action" value="edit">
4686 <tal:block replace="structure request/indexargs_form" />
4687 </td>
4688 </tr>
4690 which gives us a submit button, indicates that we are performing an edit
4691 on any changed statuses. The final ``tal:block`` will make sure that the
4692 current index view parameters (filtering, columns, etc) will be used in
4693 rendering the next page (the results of the editing).
4696 Displaying only message summaries in the issue display
4697 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4699 Alter the ``issue.item`` template section for messages to::
4701 <table class="messages" tal:condition="context/messages">
4702 <tr><th colspan="5" class="header">Messages</th></tr>
4703 <tr tal:repeat="msg context/messages">
4704 <td><a tal:attributes="href string:msg${msg/id}"
4705 tal:content="string:msg${msg/id}"></a></td>
4706 <td tal:content="msg/author">author</td>
4707 <td class="date" tal:content="msg/date/pretty">date</td>
4708 <td tal:content="msg/summary">summary</td>
4709 <td>
4710 <a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">
4711 remove</a>
4712 </td>
4713 </tr>
4714 </table>
4717 Enabling display of either message summaries or the entire messages
4718 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4720 This is pretty simple - all we need to do is copy the code from the
4721 example `displaying only message summaries in the issue display`_ into
4722 our template alongside the summary display, and then introduce a switch
4723 that shows either the one or the other. We'll use a new form variable,
4724 ``@whole_messages`` to achieve this::
4726 <table class="messages" tal:condition="context/messages">
4727 <tal:block tal:condition="not:request/form/@whole_messages/value | python:0">
4728 <tr><th colspan="3" class="header">Messages</th>
4729 <th colspan="2" class="header">
4730 <a href="?@whole_messages=yes">show entire messages</a>
4731 </th>
4732 </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">remove</a>
4741 </td>
4742 </tr>
4743 </tal:block>
4745 <tal:block tal:condition="request/form/@whole_messages/value | python:0">
4746 <tr><th colspan="2" class="header">Messages</th>
4747 <th class="header">
4748 <a href="?@whole_messages=">show only summaries</a>
4749 </th>
4750 </tr>
4751 <tal:block tal:repeat="msg context/messages">
4752 <tr>
4753 <th tal:content="msg/author">author</th>
4754 <th class="date" tal:content="msg/date/pretty">date</th>
4755 <th style="text-align: right">
4756 (<a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">remove</a>)
4757 </th>
4758 </tr>
4759 <tr><td colspan="3" tal:content="msg/content"></td></tr>
4760 </tal:block>
4761 </tal:block>
4762 </table>
4765 Setting up a "wizard" (or "druid") for controlled adding of issues
4766 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4768 1. Set up the page templates you wish to use for data input. My wizard
4769 is going to be a two-step process: first figuring out what category
4770 of issue the user is submitting, and then getting details specific to
4771 that category. The first page includes a table of help, explaining
4772 what the category names mean, and then the core of the form::
4774 <form method="POST" onSubmit="return submit_once()"
4775 enctype="multipart/form-data">
4776 <input type="hidden" name="@template" value="add_page1">
4777 <input type="hidden" name="@action" value="page1_submit">
4779 <strong>Category:</strong>
4780 <tal:block tal:replace="structure context/category/menu" />
4781 <input type="submit" value="Continue">
4782 </form>
4784 The next page has the usual issue entry information, with the
4785 addition of the following form fragments::
4787 <form method="POST" onSubmit="return submit_once()"
4788 enctype="multipart/form-data"
4789 tal:condition="context/is_edit_ok"
4790 tal:define="cat request/form/category/value">
4792 <input type="hidden" name="@template" value="add_page2">
4793 <input type="hidden" name="@required" value="title">
4794 <input type="hidden" name="category" tal:attributes="value cat">
4795 .
4796 .
4797 .
4798 </form>
4800 Note that later in the form, I use the value of "cat" to decide which
4801 form elements should be displayed. For example::
4803 <tal:block tal:condition="python:cat in '6 10 13 14 15 16 17'.split()">
4804 <tr>
4805 <th>Operating System</th>
4806 <td tal:content="structure context/os/field"></td>
4807 </tr>
4808 <tr>
4809 <th>Web Browser</th>
4810 <td tal:content="structure context/browser/field"></td>
4811 </tr>
4812 </tal:block>
4814 ... the above section will only be displayed if the category is one
4815 of 6, 10, 13, 14, 15, 16 or 17.
4817 3. Determine what actions need to be taken between the pages - these are
4818 usually to validate user choices and determine what page is next. Now encode
4819 those actions in a new ``Action`` class (see `defining new web actions`_)::
4821 from roundup.cgi.actions import Action
4823 class Page1SubmitAction(Action):
4824 def handle(self):
4825 ''' Verify that the user has selected a category, and then move
4826 on to page 2.
4827 '''
4828 category = self.form['category'].value
4829 if category == '-1':
4830 self.error_message.append('You must select a category of report')
4831 return
4832 # everything's ok, move on to the next page
4833 self.template = 'add_page2'
4835 def init(instance):
4836 instance.registerAction('page1_submit', Page1SubmitAction)
4838 4. Use the usual "new" action as the ``@action`` on the final page, and
4839 you're done (the standard context/submit method can do this for you).
4842 Debugging Trackers
4843 ==================
4845 There are three switches in tracker configs that turn on debugging in
4846 Roundup:
4848 1. web :: debug
4849 2. mail :: debug
4850 3. logging :: level
4852 See the config.ini file or the `tracker configuration`_ section above for
4853 more information.
4855 Additionally, the ``roundup-server.py`` script has its own debugging mode
4856 in which it reloads edited templates immediately when they are changed,
4857 rather than requiring a web server restart.
4860 -------------------
4862 Back to `Table of Contents`_
4864 .. _`Table of Contents`: index.html
4865 .. _`design documentation`: design.html
4866 .. _`admin guide`: admin_guide.html