1 ===================
2 Customising Roundup
3 ===================
5 :Version: $Revision: 1.134 $
7 .. This document borrows from the ZopeBook section on ZPT. The original is at:
8 http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
10 .. contents::
11 :depth: 1
13 What You Can Do
14 ===============
16 Before you get too far, it's probably worth having a quick read of the Roundup
17 `design documentation`_.
19 Customisation of Roundup can take one of six forms:
21 1. `tracker configuration`_ file changes
22 2. database, or `tracker schema`_ changes
23 3. "definition" class `database content`_ changes
24 4. behavioural changes, through detectors_
25 5. `security / access controls`_
26 6. change the `web interface`_
28 The third case is special because it takes two distinctly different forms
29 depending upon whether the tracker has been initialised or not. The other two
30 may be done at any time, before or after tracker initialisation. Yes, this
31 includes adding or removing properties from classes.
34 Trackers in a Nutshell
35 ======================
37 Trackers have the following structure:
39 =================== ========================================================
40 Tracker File Description
41 =================== ========================================================
42 config.py Holds the basic `tracker configuration`_
43 dbinit.py Holds the `tracker schema`_
44 interfaces.py Defines the Web and E-Mail interfaces for the tracker
45 select_db.py Selects the database back-end for the tracker
46 db/ Holds the tracker's database
47 db/files/ Holds the tracker's upload files and messages
48 detectors/ Auditors and reactors for this tracker
49 html/ Web interface templates, images and style sheets
50 =================== ========================================================
52 Tracker Configuration
53 =====================
55 The ``config.py`` located in your tracker home contains the basic
56 configuration for the web and e-mail components of roundup's interfaces.
57 As the name suggests, this file is a Python module. This means that any
58 valid python expression may be used in the file. Mostly though, you'll
59 be setting the configuration variables to string values. Python string
60 values must be quoted with either single or double quotes::
62 'this is a string'
63 "this is also a string - use it when the value has 'single quotes'"
64 this is not a string - it's not quoted
66 Python strings may use formatting that's almost identical to C string
67 formatting. The ``%`` operator is used to perform the formatting, like
68 so::
70 'roundup-admin@%s'%MAIL_DOMAIN
72 this will create a string ``'roundup-admin@tracker.domain.example'`` if
73 MAIL_DOMAIN is set to ``'tracker.domain.example'``.
75 You'll also note some values are set to::
77 os.path.join(TRACKER_HOME, 'db')
79 or similar. This creates a new string which holds the path to the
80 ``'db'`` directory in the TRACKER_HOME directory. This is just a
81 convenience so if the TRACKER_HOME changes you don't have to edit
82 multiple valoues.
84 The configuration variables available are:
86 **TRACKER_HOME** - ``os.path.split(__file__)[0]``
87 The tracker home directory. The above default code will automatically
88 determine the tracker home for you, so you can just leave it alone.
90 **MAILHOST** - ``'localhost'``
91 The SMTP mail host that roundup will use to send e-mail.
93 **MAILUSER** - ``()``
94 If your SMTP mail host requires a username and password for access, then
95 specify them here. eg. ``MAILUSER = ('username', 'password')``
97 **MAILHOST_TLS** - ``'no'``
98 If your SMTP mail host provides or requires TLS (Transport Layer
99 Security) then set ``MAILHOST_TLS = 'yes'``
101 **MAILHOST_TLS_KEYFILE** - ``''``
102 If you're using TLS, you may also set MAILHOST_TLS_KEYFILE to the name of
103 a PEM formatted file that contains your private key.
105 **MAILHOST_TLS_CERTFILE** - ``''``
106 If you're using TLS and have specified a MAILHOST_TLS_KEYFILE, you may
107 also set MAILHOST_TLS_CERTFILE to the name of a PEM formatted certificate
108 chain file.
110 **MAIL_DOMAIN** - ``'tracker.domain.example'``
111 The domain name used for email addresses.
113 **DATABASE** - ``os.path.join(TRACKER_HOME, 'db')``
114 This is the directory that the database is going to be stored in. By default
115 it is in the tracker home.
117 **TEMPLATES** - ``os.path.join(TRACKER_HOME, 'html')``
118 This is the directory that the HTML templates reside in. By default they are
119 in the tracker home.
121 **TRACKER_NAME** - ``'Roundup issue tracker'``
122 A descriptive name for your roundup tracker. This is sent out in e-mails and
123 appears in the heading of CGI pages.
125 **TRACKER_EMAIL** - ``'issue_tracker@%s'%MAIL_DOMAIN``
126 The email address that e-mail sent to roundup should go to. Think of it as the
127 tracker's personal e-mail address.
129 **TRACKER_WEB** - ``'http://tracker.example/cgi-bin/roundup.cgi/bugs/'``
130 The web address that the tracker is viewable at. This will be included in
131 information sent to users of the tracker. The URL **must** include the
132 cgi-bin part or anything else that is required to get to the home page of
133 the tracker. You **must** include a trailing '/' in the URL.
135 **ADMIN_EMAIL** - ``'roundup-admin@%s'%MAIL_DOMAIN``
136 The email address that roundup will complain to if it runs into trouble.
138 **EMAIL_FROM_TAG** - ``''``
139 Additional text to include in the "name" part of the ``From:`` address used
140 in nosy messages. If the sending user is "Foo Bar", the ``From:`` line is
141 usually::
143 "Foo Bar" <issue_tracker@tracker.example>
145 The EMAIL_FROM_TAG goes inside the "Foo Bar" quotes like so::
147 "Foo Bar EMAIL_FROM_TAG" <issue_tracker@tracker.example>
149 **ERROR_MESSAGES_TO** - ``'user'``, ``'dispatcher'`` or ``'both'``
150 Sends error messages to the dispatcher, user, or both. It will use the
151 ``DISPATCHER_EMAIL`` address if set, otherwise it'll use the
152 ``ADMIN_EMAIL`` address.
154 **DISPATCHER_EMAIL** - ``''``
155 The email address that Roundup will issue all error messages to. This is
156 also useful if you want to switch your 'new message' notification to
157 a central user.
159 **MESSAGES_TO_AUTHOR** - ``'new'``, ``'yes'`` or``'no'``
160 Send nosy messages to the author of the message?
161 If 'new' is used, then the author will only be sent the message when the
162 message creates a new issue. If 'yes' then the author will always be sent
163 a copy of the message they wrote.
165 **ADD_AUTHOR_TO_NOSY** - ``'new'``, ``'yes'`` or ``'no'``
166 Does the author of a message get placed on the nosy list automatically?
167 If ``'new'`` is used, then the author will only be added when a message
168 creates a new issue. If ``'yes'``, then the author will be added on followups
169 too. If ``'no'``, they're never added to the nosy.
171 **ADD_RECIPIENTS_TO_NOSY** - ``'new'``, ``'yes'`` or ``'no'``
172 Do the recipients (To:, Cc:) of a message get placed on the nosy list?
173 If ``'new'`` is used, then the recipients will only be added when a message
174 creates a new issue. If ``'yes'``, then the recipients will be added on
175 followups too. If ``'no'``, they're never added to the nosy.
177 **EMAIL_SIGNATURE_POSITION** - ``'top'``, ``'bottom'`` or ``'none'``
178 Where to place the email signature in messages that Roundup generates.
180 **EMAIL_KEEP_QUOTED_TEXT** - ``'yes'`` or ``'no'``
181 Keep email citations. Citations are the part of e-mail which the sender has
182 quoted in their reply to previous e-mail with ``>`` or ``|`` characters at
183 the start of the line.
185 **EMAIL_LEAVE_BODY_UNCHANGED** - ``'no'``
186 Preserve the email body as is. Enabiling this will cause the entire message
187 body to be stored, including all citations, signatures and Outlook-quoted
188 sections (ie. "Original Message" blocks). It should be either ``'yes'``
189 or ``'no'``.
191 **MAIL_DEFAULT_CLASS** - ``'issue'`` or ``''``
192 Default class to use in the mailgw if one isn't supplied in email
193 subjects. To disable, comment out the variable below or leave it blank.
195 **HTML_VERSION** - ``'html4'`` or ``'xhtml'``
196 HTML version to generate. The templates are html4 by default. If you
197 wish to make them xhtml, then you'll need to change this var to 'xhtml'
198 too so all auto-generated HTML is compliant.
200 **EMAIL_CHARSET** - ``utf-8`` (or ``iso-8859-1`` for Eudora users)
201 Character set to encode email headers with. We use utf-8 by default, as
202 it's the most flexible. Some mail readers (eg. Eudora) can't cope with
203 that, so you might need to specify a more limited character set (eg.
204 'iso-8859-1'.
206 **DEFAULT_TIMEZONE** - ``0``
207 Numeric hour timezone offest to be used when displaying local times.
208 The default timezone is used when users do not choose their own in
209 their settings.
211 The default config.py is given below - as you
212 can see, the MAIL_DOMAIN must be edited before any interaction with the
213 tracker is attempted.::
215 # roundup home is this package's directory
216 TRACKER_HOME=os.path.split(__file__)[0]
218 # The SMTP mail host that roundup will use to send mail
219 MAILHOST = 'localhost'
221 # The domain name used for email addresses.
222 MAIL_DOMAIN = 'your.tracker.email.domain.example'
224 # This is the directory that the database is going to be stored in
225 DATABASE = os.path.join(TRACKER_HOME, 'db')
227 # This is the directory that the HTML templates reside in
228 TEMPLATES = os.path.join(TRACKER_HOME, 'html')
230 # A descriptive name for your roundup tracker
231 TRACKER_NAME = 'Roundup issue tracker'
233 # The email address that mail to roundup should go to
234 TRACKER_EMAIL = 'issue_tracker@%s'%MAIL_DOMAIN
236 # The web address that the tracker is viewable at. This will be
237 # included in information sent to users of the tracker. The URL MUST
238 # include the cgi-bin part or anything else that is required to get
239 # to the home page of the tracker. You MUST include a trailing '/'
240 # in the URL.
241 TRACKER_WEB = 'http://tracker.example/cgi-bin/roundup.cgi/bugs/'
243 # The email address that roundup will complain to if it runs into
244 # trouble
245 ADMIN_EMAIL = 'roundup-admin@%s'%MAIL_DOMAIN
247 # Additional text to include in the "name" part of the From: address
248 # used in nosy messages. If the sending user is "Foo Bar", the From:
249 # line is usually: "Foo Bar" <issue_tracker@tracker.example>
250 # the EMAIL_FROM_TAG goes inside the "Foo Bar" quotes like so:
251 # "Foo Bar EMAIL_FROM_TAG" <issue_tracker@tracker.example>
252 EMAIL_FROM_TAG = ""
254 # Send nosy messages to the author of the message
255 MESSAGES_TO_AUTHOR = 'no' # either 'yes' or 'no'
257 # Does the author of a message get placed on the nosy list
258 # automatically? If 'new' is used, then the author will only be
259 # added when a message creates a new issue. If 'yes', then the
260 # author will be added on followups too. If 'no', they're never
261 # added to the nosy.
262 ADD_AUTHOR_TO_NOSY = 'new' # one of 'yes', 'no', 'new'
264 # Do the recipients (To:, Cc:) of a message get placed on the nosy
265 # list? If 'new' is used, then the recipients will only be added
266 # when a message creates a new issue. If 'yes', then the recipients
267 # will be added on followups too. If 'no', they're never added to
268 # the nosy.
269 ADD_RECIPIENTS_TO_NOSY = 'new' # either 'yes', 'no', 'new'
271 # Where to place the email signature
272 EMAIL_SIGNATURE_POSITION = 'bottom' # one of 'top', 'bottom', 'none'
274 # Keep email citations
275 EMAIL_KEEP_QUOTED_TEXT = 'no' # either 'yes' or 'no'
277 # Preserve the email body as is
278 EMAIL_LEAVE_BODY_UNCHANGED = 'no' # either 'yes' or 'no'
280 # Default class to use in the mailgw if one isn't supplied in email
281 # subjects. To disable, comment out the variable below or leave it
282 # blank. Examples:
283 MAIL_DEFAULT_CLASS = 'issue' # use "issue" class by default
284 #MAIL_DEFAULT_CLASS = '' # disable (or just comment the var out)
286 # HTML version to generate. The templates are html4 by default. If you
287 # wish to make them xhtml, then you'll need to change this var to 'xhtml'
288 # too so all auto-generated HTML is compliant.
289 HTML_VERSION = 'html4' # either 'html4' or 'xhtml'
291 # Character set to encode email headers with. We use utf-8 by default, as
292 # it's the most flexible. Some mail readers (eg. Eudora) can't cope with
293 # that, so you might need to specify a more limited character set (eg.
294 # 'iso-8859-1'.
295 EMAIL_CHARSET = 'utf-8'
296 #EMAIL_CHARSET = 'iso-8859-1' # use this instead for Eudora users
298 # You may specify a different default timezone, for use when users do not
299 # choose their own in their settings.
300 DEFAULT_TIMEZONE = 0 # specify as numeric hour offest
302 #
303 # SECURITY DEFINITIONS
304 #
305 # define the Roles that a user gets when they register with the
306 # tracker these are a comma-separated string of role names (e.g.
307 # 'Admin,User')
308 NEW_WEB_USER_ROLES = 'User'
309 NEW_EMAIL_USER_ROLES = 'User'
311 Tracker Schema
312 ==============
314 Note: if you modify the schema, you'll most likely need to edit the
315 `web interface`_ HTML template files and `detectors`_ to reflect
316 your changes.
318 A tracker schema defines what data is stored in the tracker's database.
319 Schemas are defined using Python code in the ``dbinit.py`` module of your
320 tracker.
322 The ``dbinit.py`` module
323 ------------------------
325 The ``dbinit.py`` module contains two functions:
327 **open**
328 This function defines what your tracker looks like on the inside, the
329 **schema** of the tracker. It defines the **Classes** and **properties**
330 on each class. It also defines the **security** for those Classes. The
331 next few sections describe how schemas work and what you can do with
332 them.
333 **init**
334 This function is responsible for setting up the initial state of your
335 tracker. It's called exactly once - but the ``roundup-admin initialise``
336 command. See the start of the section on `database content`_ for more
337 info about how this works.
340 The "classic" schema
341 --------------------
343 The "classic" schema looks like this (see below for the meaning
344 of ``'setkey'``)::
346 pri = Class(db, "priority", name=String(), order=String())
347 pri.setkey("name")
349 stat = Class(db, "status", name=String(), order=String())
350 stat.setkey("name")
352 keyword = Class(db, "keyword", name=String())
353 keyword.setkey("name")
355 user = Class(db, "user", username=String(), organisation=String(),
356 password=String(), address=String(), realname=String(),
357 phone=String())
358 user.setkey("username")
360 msg = FileClass(db, "msg", author=Link("user"), summary=String(),
361 date=Date(), recipients=Multilink("user"),
362 files=Multilink("file"))
364 file = FileClass(db, "file", name=String(), type=String())
366 issue = IssueClass(db, "issue", topic=Multilink("keyword"),
367 status=Link("status"), assignedto=Link("user"),
368 priority=Link("priority"))
369 issue.setkey('title')
372 What you can't do to the schema
373 -------------------------------
375 You must never:
377 **Remove the users class**
378 This class is the only *required* class in Roundup. Similarly, its
379 username, password and address properties must never be removed.
381 **Change the type of a property**
382 Property types must *never* be changed - the database simply doesn't take
383 this kind of action into account. Note that you can't just remove a
384 property and re-add it as a new type either. If you wanted to make the
385 assignedto property a Multilink, you'd need to create a new property
386 assignedto_list and remove the old assignedto property.
389 What you can do to the schema
390 -----------------------------
392 Your schema may be changed at any time before or after the tracker has been
393 initialised (or used). You may:
395 **Add new properties to classes, or add whole new classes**
396 This is painless and easy to do - there are generally no repurcussions
397 from adding new information to a tracker's schema.
399 **Remove properties**
400 Removing properties is a little more tricky - you need to make sure that
401 the property is no longer used in the `web interface`_ *or* by the
402 detectors_.
406 Classes and Properties - creating a new information store
407 ---------------------------------------------------------
409 In the tracker above, we've defined 7 classes of information:
411 priority
412 Defines the possible levels of urgency for issues.
414 status
415 Defines the possible states of processing the issue may be in.
417 keyword
418 Initially empty, will hold keywords useful for searching issues.
420 user
421 Initially holding the "admin" user, will eventually have an entry
422 for all users using roundup.
424 msg
425 Initially empty, will hold all e-mail messages sent to or
426 generated by roundup.
428 file
429 Initially empty, will hold all files attached to issues.
431 issue
432 Initially empty, this is where the issue information is stored.
434 We define the "priority" and "status" classes to allow two things:
435 reduction in the amount of information stored on the issue and more
436 powerful, accurate searching of issues by priority and status. By only
437 requiring a link on the issue (which is stored as a single number) we
438 reduce the chance that someone mis-types a priority or status - or
439 simply makes a new one up.
442 Class and Items
443 ~~~~~~~~~~~~~~~
445 A Class defines a particular class (or type) of data that will be stored
446 in the database. A class comprises one or more properties, which gives
447 the information about the class items.
449 The actual data entered into the database, using ``class.create()``, are
450 called items. They have a special immutable property called ``'id'``. We
451 sometimes refer to this as the *itemid*.
454 Properties
455 ~~~~~~~~~~
457 A Class is comprised of one or more properties of the following types:
459 * String properties are for storing arbitrary-length strings.
460 * Password properties are for storing encoded arbitrary-length strings.
461 The default encoding is defined on the ``roundup.password.Password``
462 class.
463 * Date properties store date-and-time stamps. Their values are Timestamp
464 objects.
465 * Number properties store numeric values.
466 * Boolean properties store on/off, yes/no, true/false values.
467 * A Link property refers to a single other item selected from a
468 specified class. The class is part of the property; the value is an
469 integer, the id of the chosen item.
470 * A Multilink property refers to possibly many items in a specified
471 class. The value is a list of integers.
474 FileClass
475 ~~~~~~~~~
477 FileClasses save their "content" attribute off in a separate file from
478 the rest of the database. This reduces the number of large entries in
479 the database, which generally makes databases more efficient, and also
480 allows us to use command-line tools to operate on the files. They are
481 stored in the files sub-directory of the ``'db'`` directory in your
482 tracker.
485 IssueClass
486 ~~~~~~~~~~
488 IssueClasses automatically include the "messages", "files", "nosy", and
489 "superseder" properties.
491 The messages and files properties list the links to the messages and
492 files related to the issue. The nosy property is a list of links to
493 users who wish to be informed of changes to the issue - they get "CC'ed"
494 e-mails when messages are sent to or generated by the issue. The nosy
495 reactor (in the ``'detectors'`` directory) handles this action. The
496 superseder link indicates an issue which has superseded this one.
498 They also have the dynamically generated "creation", "activity" and
499 "creator" properties.
501 The value of the "creation" property is the date when an item was
502 created, and the value of the "activity" property is the date when any
503 property on the item was last edited (equivalently, these are the dates
504 on the first and last records in the item's journal). The "creator"
505 property holds a link to the user that created the issue.
508 setkey(property)
509 ~~~~~~~~~~~~~~~~
511 Select a String property of the class to be the key property. The key
512 property must be unique, and allows references to the items in the class
513 by the content of the key property. That is, we can refer to users by
514 their username: for example, let's say that there's an issue in roundup,
515 issue 23. There's also a user, richard, who happens to be user 2. To
516 assign an issue to him, we could do either of::
518 roundup-admin set issue23 assignedto=2
520 or::
522 roundup-admin set issue23 assignedto=richard
524 Note, the same thing can be done in the web and e-mail interfaces.
526 If a class does not have an "order" property, the key is also used to
527 sort instances of the class when it is rendered in the user interface.
528 (If a class has no "order" property, sorting is by the labelproperty of
529 the class. This is computed, in order of precedence, as the key, the
530 "name", the "title", or the first property alphabetically.)
533 create(information)
534 ~~~~~~~~~~~~~~~~~~~
536 Create an item in the database. This is generally used to create items
537 in the "definitional" classes like "priority" and "status".
540 Examples of adding to your schema
541 ---------------------------------
543 TODO
546 Detectors - adding behaviour to your tracker
547 ============================================
548 .. _detectors:
550 Detectors are initialised every time you open your tracker database, so
551 you're free to add and remove them any time, even after the database is
552 initialised via the "roundup-admin initialise" command.
554 The detectors in your tracker fire *before* (**auditors**) and *after*
555 (**reactors**) changes to the contents of your database. They are Python
556 modules that sit in your tracker's ``detectors`` directory. You will
557 have some installed by default - have a look. You can write new
558 detectors or modify the existing ones. The existing detectors installed
559 for you are:
561 **nosyreaction.py**
562 This provides the automatic nosy list maintenance and email sending.
563 The nosy reactor (``nosyreaction``) fires when new messages are added
564 to issues. The nosy auditor (``updatenosy``) fires when issues are
565 changed, and figures out what changes need to be made to the nosy list
566 (such as adding new authors, etc.)
567 **statusauditor.py**
568 This provides the ``chatty`` auditor which changes the issue status
569 from ``unread`` or ``closed`` to ``chatting`` if new messages appear.
570 It also provides the ``presetunread`` auditor which pre-sets the
571 status to ``unread`` on new items if the status isn't explicitly
572 defined.
573 **messagesummary.py**
574 Generates the ``summary`` property for new messages based on the message
575 content.
576 **userauditor.py**
577 Verifies the content of some of the user fields (email addresses and
578 roles lists).
580 If you don't want this default behaviour, you're completely free to change
581 or remove these detectors.
583 See the detectors section in the `design document`__ for details of the
584 interface for detectors.
586 __ design.html
589 Detector API
590 ------------
592 Auditors are called with the arguments::
594 audit(db, cl, itemid, newdata)
596 where ``db`` is the database, ``cl`` is an instance of Class or
597 IssueClass within the database, and ``newdata`` is a dictionary mapping
598 property names to values.
600 For a ``create()`` operation, the ``itemid`` argument is None and
601 newdata contains all of the initial property values with which the item
602 is about to be created.
604 For a ``set()`` operation, newdata contains only the names and values of
605 properties that are about to be changed.
607 For a ``retire()`` or ``restore()`` operation, newdata is None.
609 Reactors are called with the arguments::
611 react(db, cl, itemid, olddata)
613 where ``db`` is the database, ``cl`` is an instance of Class or
614 IssueClass within the database, and ``olddata`` is a dictionary mapping
615 property names to values.
617 For a ``create()`` operation, the ``itemid`` argument is the id of the
618 newly-created item and ``olddata`` is None.
620 For a ``set()`` operation, ``olddata`` contains the names and previous
621 values of properties that were changed.
623 For a ``retire()`` or ``restore()`` operation, ``itemid`` is the id of
624 the retired or restored item and ``olddata`` is None.
627 Additional Detectors Ready For Use
628 ----------------------------------
630 Sample additional detectors that have been found useful will appear in
631 the ``'detectors'`` directory of the Roundup distribution. If you want
632 to use one, copy it to the ``'detectors'`` of your tracker instance:
634 **newissuecopy.py**
635 This detector sends an email to a team address whenever a new issue is
636 created. The address is hard-coded into the detector, so edit it
637 before you use it (look for the text 'team@team.host') or you'll get
638 email errors!
639 **creator_resolution.py**
640 Catch attempts to set the status to "resolved" - if the assignedto
641 user isn't the creator, then set the status to "confirm-done". Note that
642 "classic" Roundup doesn't have that status, so you'll have to add it. If
643 you don't want to though, it'll just use "in-progress" instead.
644 **email_auditor.py**
645 If a file added to an issue is of type message/rfc822, we tack on the
646 extension .eml.
647 The reason for this is that Microsoft Internet Explorer will not open
648 things with a .eml attachment, as they deem it 'unsafe'. Worse yet,
649 they'll just give you an incomprehensible error message. For more
650 information, see the detector code - it has a length explanation.
653 Auditor or Reactor?
654 -------------------
656 Generally speaking, the following rules should be observed:
658 **Auditors**
659 Are used for `vetoing creation of or changes to items`_. They might
660 also make automatic changes to item properties.
661 **Reactors**
662 Detect changes in the database and react accordingly. They should avoid
663 making changes to the database where possible, as this could create
664 detector loops.
667 Vetoing creation of or changes to items
668 ---------------------------------------
670 Auditors may raise the ``Reject`` exception to prevent the creation of
671 or changes to items in the database. The mail gateway, for example, will
672 not attach files or messages to issues when the creation of those files or
673 messages are prevented through the ``Reject`` exception. It'll also not create
674 users if that creation is ``Reject``'ed too.
676 To use, simply add at the top of your auditor::
678 from roundup.exceptions import Reject
680 And then when your rejection criteria have been detected, simply::
682 raise Reject
685 Generating email from Roundup
686 -----------------------------
688 The module ``roundup.mailer`` contains most of the nuts-n-bolts required
689 to generate email messages from Roundup.
691 In addition, the ``IssueClass`` methods ``nosymessage()`` and
692 ``send_message()`` are used to generate nosy messages, and may generate
693 messages which only consist of a change note (ie. the message id parameter
694 is not required).
697 Database Content
698 ================
700 Note: if you modify the content of definitional classes, you'll most
701 likely need to edit the tracker `detectors`_ to reflect your
702 changes.
704 Customisation of the special "definitional" classes (eg. status,
705 priority, resolution, ...) may be done either before or after the
706 tracker is initialised. The actual method of doing so is completely
707 different in each case though, so be careful to use the right one.
709 **Changing content before tracker initialisation**
710 Edit the dbinit module in your tracker to alter the items created in
711 using the ``create()`` methods.
713 **Changing content after tracker initialisation**
714 As the "admin" user, click on the "class list" link in the web
715 interface to bring up a list of all database classes. Click on the
716 name of the class you wish to change the content of.
718 You may also use the ``roundup-admin`` interface's create, set and
719 retire methods to add, alter or remove items from the classes in
720 question.
722 See "`adding a new field to the classic schema`_" for an example that
723 requires database content changes.
726 Security / Access Controls
727 ==========================
729 A set of Permissions is built into the security module by default:
731 - Edit (everything)
732 - View (everything)
734 Every Class you define in your tracker's schema also gets an Edit and View
735 Permission of its own.
737 The default interfaces define:
739 - Web Registration
740 - Web Access
741 - Web Roles
742 - Email Registration
743 - Email Access
745 These are hooked into the default Roles:
747 - Admin (Edit everything, View everything, Web Roles)
748 - User (Web Access, Email Access)
749 - Anonymous (Web Registration, Email Registration)
751 And finally, the "admin" user gets the "Admin" Role, and the "anonymous"
752 user gets "Anonymous" assigned when the database is initialised on
753 installation. The two default schemas then define:
755 - Edit issue, View issue (both)
756 - Edit file, View file (both)
757 - Edit msg, View msg (both)
758 - Edit support, View support (extended only)
760 and assign those Permissions to the "User" Role. Put together, these
761 settings appear in the ``open()`` function of the tracker ``dbinit.py``
762 (the following is taken from the "minimal" template's ``dbinit.py``)::
764 #
765 # SECURITY SETTINGS
766 #
767 # and give the regular users access to the web and email interface
768 p = db.security.getPermission('Web Access')
769 db.security.addPermissionToRole('User', p)
770 p = db.security.getPermission('Email Access')
771 db.security.addPermissionToRole('User', p)
773 # May users view other user information? Comment these lines out
774 # if you don't want them to
775 p = db.security.getPermission('View', 'user')
776 db.security.addPermissionToRole('User', p)
778 # Assign the appropriate permissions to the anonymous user's
779 # Anonymous role. Choices here are:
780 # - Allow anonymous users to register through the web
781 p = db.security.getPermission('Web Registration')
782 db.security.addPermissionToRole('Anonymous', p)
783 # - Allow anonymous (new) users to register through the email
784 # gateway
785 p = db.security.getPermission('Email Registration')
786 db.security.addPermissionToRole('Anonymous', p)
789 New User Roles
790 --------------
792 New users are assigned the Roles defined in the config file as:
794 - NEW_WEB_USER_ROLES
795 - NEW_EMAIL_USER_ROLES
798 Changing Access Controls
799 ------------------------
801 You may alter the configuration variables to change the Role that new
802 web or email users get, for example to not give them access to the web
803 interface if they register through email.
805 You may use the ``roundup-admin`` "``security``" command to display the
806 current Role and Permission configuration in your tracker.
809 Adding a new Permission
810 ~~~~~~~~~~~~~~~~~~~~~~~
812 When adding a new Permission, you will need to:
814 1. add it to your tracker's dbinit so it is created, using
815 ``security.addPermission``, for example::
817 self.security.addPermission(name="View", klass='frozzle',
818 description="User is allowed to access frozzles")
820 will set up a new "View" permission on the Class "frozzle".
821 2. enable it for the Roles that should have it (verify with
822 "``roundup-admin security``")
823 3. add it to the relevant HTML interface templates
824 4. add it to the appropriate xxxPermission methods on in your tracker
825 interfaces module
828 Example Scenarios
829 ~~~~~~~~~~~~~~~~~
831 **automatic registration of users in the e-mail gateway**
832 By giving the "anonymous" user the "Email Registration" Role, any
833 unidentified user will automatically be registered with the tracker
834 (with no password, so they won't be able to log in through the web
835 until an admin sets their password). Note: this is the default
836 behaviour in the tracker templates that ship with Roundup.
838 **anonymous access through the e-mail gateway**
839 Give the "anonymous" user the "Email Access" and ("Edit", "issue")
840 Roles but do not not give them the "Email Registration" Role. This
841 means that when an unknown user sends email into the tracker, they're
842 automatically logged in as "anonymous". Since they don't have the
843 "Email Registration" Role, they won't be automatically registered, but
844 since "anonymous" has permission to use the gateway, they'll still be
845 able to submit issues. Note that the Sender information - their email
846 address - will not be available - they're *anonymous*.
848 **only developers may be assigned issues**
849 Create a new Permission called "Fixer" for the "issue" class. Create a
850 new Role "Developer" which has that Permission, and assign that to the
851 appropriate users. Filter the list of users available in the assignedto
852 list to include only those users. Enforce the Permission with an
853 auditor. See the example
854 `restricting the list of users that are assignable to a task`_.
856 **only managers may sign off issues as complete**
857 Create a new Permission called "Closer" for the "issue" class. Create a
858 new Role "Manager" which has that Permission, and assign that to the
859 appropriate users. In your web interface, only display the "resolved"
860 issue state option when the user has the "Closer" Permissions. Enforce
861 the Permission with an auditor. This is very similar to the previous
862 example, except that the web interface check would look like::
864 <option tal:condition="python:request.user.hasPermission('Closer')"
865 value="resolved">Resolved</option>
867 **don't give web access to users who register through email**
868 Create a new Role called "Email User" which has all the Permissions of
869 the normal "User" Role minus the "Web Access" Permission. This will
870 allow users to send in emails to the tracker, but not access the web
871 interface.
873 **let some users edit the details of all users**
874 Create a new Role called "User Admin" which has the Permission for
875 editing users::
877 db.security.addRole(name='User Admin', description='Managing users')
878 p = db.security.getPermission('Edit', 'user')
879 db.security.addPermissionToRole('User Admin', p)
881 and assign the Role to the users who need the permission.
884 Web Interface
885 =============
887 .. contents::
888 :local:
890 The web interface is provided by the ``roundup.cgi.client`` module and
891 is used by ``roundup.cgi``, ``roundup-server`` and ``ZRoundup``
892 (``ZRoundup`` is broken, until further notice). In all cases, we
893 determine which tracker is being accessed (the first part of the URL
894 path inside the scope of the CGI handler) and pass control on to the
895 tracker ``interfaces.Client`` class - which uses the ``Client`` class
896 from ``roundup.cgi.client`` - which handles the rest of the access
897 through its ``main()`` method. This means that you can do pretty much
898 anything you want as a web interface to your tracker.
900 Repercussions of changing the tracker schema
901 ---------------------------------------------
903 If you choose to change the `tracker schema`_ you will need to ensure
904 the web interface knows about it:
906 1. Index, item and search pages for the relevant classes may need to
907 have properties added or removed,
908 2. The "page" template may require links to be changed, as might the
909 "home" page's content arguments.
911 How requests are processed
912 --------------------------
914 The basic processing of a web request proceeds as follows:
916 1. figure out who we are, defaulting to the "anonymous" user
917 2. figure out what the request is for - we call this the "context"
918 3. handle any requested action (item edit, search, ...)
919 4. render the template requested by the context, resulting in HTML
920 output
922 In some situations, exceptions occur:
924 - HTTP Redirect (generally raised by an action)
925 - SendFile (generally raised by ``determine_context``)
926 here we serve up a FileClass "content" property
927 - SendStaticFile (generally raised by ``determine_context``)
928 here we serve up a file from the tracker "html" directory
929 - Unauthorised (generally raised by an action)
930 here the action is cancelled, the request is rendered and an error
931 message is displayed indicating that permission was not granted for
932 the action to take place
933 - NotFound (raised wherever it needs to be)
934 this exception percolates up to the CGI interface that called the
935 client
937 Determining web context
938 -----------------------
940 To determine the "context" of a request, we look at the URL and the
941 special request variable ``@template``. The URL path after the tracker
942 identifier is examined. Typical URL paths look like:
944 1. ``/tracker/issue``
945 2. ``/tracker/issue1``
946 3. ``/tracker/@file/style.css``
947 4. ``/cgi-bin/roundup.cgi/tracker/file1``
948 5. ``/cgi-bin/roundup.cgi/tracker/file1/kitten.png``
950 where the "tracker identifier" is "tracker" in the above cases. That means
951 we're looking at "issue", "issue1", "@file/style.css", "file1" and
952 "file1/kitten.png" in the cases above. The path is generally only one
953 entry long - longer paths are handled differently.
955 a. if there is no path, then we are in the "home" context.
956 b. if the path starts with "@file" (as in example 3,
957 "/tracker/@file/style.css"), then the additional path entry,
958 "style.css" specifies the filename of a static file we're to serve up
959 from the tracker "html" directory. Raises a SendStaticFile exception.
960 c. if there is something in the path (as in example 1, "issue"), it
961 identifies the tracker class we're to display.
962 d. if the path is an item designator (as in examples 2 and 4, "issue1"
963 and "file1"), then we're to display a specific item.
964 e. if the path starts with an item designator and is longer than one
965 entry (as in example 5, "file1/kitten.png"), then we're assumed to be
966 handling an item of a ``FileClass``, and the extra path information
967 gives the filename that the client is going to label the download
968 with (i.e. "file1/kitten.png" is nicer to download than "file1").
969 This raises a ``SendFile`` exception.
971 Both b. and e. stop before we bother to determine the template we're
972 going to use. That's because they don't actually use templates.
974 The template used is specified by the ``@template`` CGI variable, which
975 defaults to:
977 - only classname suplied: "index"
978 - full item designator supplied: "item"
981 Serving static content
982 ----------------------
984 See the previous section `determining web context`_ where it describes
985 ``@file`` paths.
988 Performing actions in web requests
989 ----------------------------------
991 When a user requests a web page, they may optionally also request for an
992 action to take place. As described in `how requests are processed`_, the
993 action is performed before the requested page is generated. Actions are
994 triggered by using a ``@action`` CGI variable, where the value is one
995 of:
997 **login**
998 Attempt to log a user in.
1000 **logout**
1001 Log the user out - make them "anonymous".
1003 **register**
1004 Attempt to create a new user based on the contents of the form and then
1005 log them in.
1007 **edit**
1008 Perform an edit of an item in the database. There are some `special form
1009 variables`_ you may use.
1011 **new**
1012 Add a new item to the database. You may use the same `special form
1013 variables`_ as in the "edit" action.
1015 **retire**
1016 Retire the item in the database.
1018 **editCSV**
1019 Performs an edit of all of a class' items in one go. See also the
1020 *class*.csv templating method which generates the CSV data to be
1021 edited, and the ``'_generic.index'`` template which uses both of these
1022 features.
1024 **search**
1025 Mangle some of the form variables:
1027 - Set the form ":filter" variable based on the values of the filter
1028 variables - if they're set to anything other than "dontcare" then add
1029 them to :filter.
1031 - Also handle the ":queryname" variable and save off the query to the
1032 user's query list.
1034 Each of the actions is implemented by a corresponding ``*XxxAction*`` (where
1035 "Xxx" is the name of the action) class in the ``roundup.cgi.actions`` module.
1036 These classes are registered with ``roundup.cgi.client.Client`` which also
1037 happens to be available in your tracker instance as ``interfaces.Client``. So
1038 if you need to define new actions, you may add them there (see `defining new
1039 web actions`_).
1041 Each action class also has a ``*permission*`` method which determines whether
1042 the action is permissible given the current user. The base permission checks
1043 are:
1045 **login**
1046 Determine whether the user has permission to log in. Base behaviour is
1047 to check the user has "Web Access".
1048 **logout**
1049 No permission checks are made.
1050 **register**
1051 Determine whether the user has permission to register. Base behaviour
1052 is to check the user has the "Web Registration" Permission.
1053 **edit**
1054 Determine whether the user has permission to edit this item. Base
1055 behaviour is to check whether the user can edit this class. If we're
1056 editing the "user" class, users are allowed to edit their own details -
1057 unless they try to edit the "roles" property, which requires the
1058 special Permission "Web Roles".
1059 **new**
1060 Determine whether the user has permission to create (or edit) this
1061 item. Base behaviour is to check the user can edit this class. No
1062 additional property checks are made. Additionally, new user items may
1063 be created if the user has the "Web Registration" Permission.
1064 **editCSV**
1065 Determine whether the user has permission to edit this class. Base
1066 behaviour is to check whether the user may edit this class.
1067 **search**
1068 Determine whether the user has permission to search this class. Base
1069 behaviour is to check whether the user may view this class.
1072 Special form variables
1073 ----------------------
1075 Item properties and their values are edited with html FORM
1076 variables and their values. You can:
1078 - Change the value of some property of the current item.
1079 - Create a new item of any class, and edit the new item's
1080 properties,
1081 - Attach newly created items to a multilink property of the
1082 current item.
1083 - Remove items from a multilink property of the current item.
1084 - Specify that some properties are required for the edit
1085 operation to be successful.
1087 In the following, <bracketed> values are variable, "@" may be
1088 either ":" or "@", and other text "required" is fixed.
1090 Most properties are specified as form variables:
1092 ``<propname>``
1093 property on the current context item
1095 ``<designator>"@"<propname>``
1096 property on the indicated item (for editing related information)
1098 Designators name a specific item of a class.
1100 ``<classname><N>``
1101 Name an existing item of class <classname>.
1103 ``<classname>"-"<N>``
1104 Name the <N>th new item of class <classname>. If the form
1105 submission is successful, a new item of <classname> is
1106 created. Within the submitted form, a particular
1107 designator of this form always refers to the same new
1108 item.
1110 Once we have determined the "propname", we look at it to see
1111 if it's special:
1113 ``@required``
1114 The associated form value is a comma-separated list of
1115 property names that must be specified when the form is
1116 submitted for the edit operation to succeed.
1118 When the <designator> is missing, the properties are
1119 for the current context item. When <designator> is
1120 present, they are for the item specified by
1121 <designator>.
1123 The "@required" specifier must come before any of the
1124 properties it refers to are assigned in the form.
1126 ``@remove@<propname>=id(s)`` or ``@add@<propname>=id(s)``
1127 The "@add@" and "@remove@" edit actions apply only to
1128 Multilink properties. The form value must be a
1129 comma-separate list of keys for the class specified by
1130 the simple form variable. The listed items are added
1131 to (respectively, removed from) the specified
1132 property.
1134 ``@link@<propname>=<designator>``
1135 If the edit action is "@link@", the simple form
1136 variable must specify a Link or Multilink property.
1137 The form value is a comma-separated list of
1138 designators. The item corresponding to each
1139 designator is linked to the property given by simple
1140 form variable.
1142 None of the above (ie. just a simple form value)
1143 The value of the form variable is converted
1144 appropriately, depending on the type of the property.
1146 For a Link('klass') property, the form value is a
1147 single key for 'klass', where the key field is
1148 specified in dbinit.py.
1150 For a Multilink('klass') property, the form value is a
1151 comma-separated list of keys for 'klass', where the
1152 key field is specified in dbinit.py.
1154 Note that for simple-form-variables specifiying Link
1155 and Multilink properties, the linked-to class must
1156 have a key field.
1158 For a String() property specifying a filename, the
1159 file named by the form value is uploaded. This means we
1160 try to set additional properties "filename" and "type" (if
1161 they are valid for the class). Otherwise, the property
1162 is set to the form value.
1164 For Date(), Interval(), Boolean(), and Number()
1165 properties, the form value is converted to the
1166 appropriate
1168 Any of the form variables may be prefixed with a classname or
1169 designator.
1171 Two special form values are supported for backwards compatibility:
1173 @note
1174 This is equivalent to::
1176 @link@messages=msg-1
1177 msg-1@content=value
1179 except that in addition, the "author" and "date" properties of
1180 "msg-1" are set to the userid of the submitter, and the current
1181 time, respectively.
1183 @file
1184 This is equivalent to::
1186 @link@files=file-1
1187 file-1@content=value
1189 The String content value is handled as described above for file
1190 uploads.
1192 If both the "@note" and "@file" form variables are
1193 specified, the action::
1195 @link@msg-1@files=file-1
1197 is also performed.
1199 We also check that FileClass items have a "content" property with
1200 actual content, otherwise we remove them from all_props before
1201 returning.
1205 Default templates
1206 -----------------
1208 The default templates are html4 compliant. If you wish to change them to be
1209 xhtml compliant, you'll need to change the ``HTML_VERSION`` configuration
1210 variable in ``config.py`` to ``'xhtml'`` instead of ``'html4'``.
1212 Most customisation of the web view can be done by modifying the
1213 templates in the tracker ``'html'`` directory. There are several types
1214 of files in there. The *minimal* template includes:
1216 **page.html**
1217 This template usually defines the overall look of your tracker. When
1218 you view an issue, it appears inside this template. When you view an
1219 index, it also appears inside this template. This template defines a
1220 macro called "icing" which is used by almost all other templates as a
1221 coating for their content, using its "content" slot. It also defines
1222 the "head_title" and "body_title" slots to allow setting of the page
1223 title.
1224 **home.html**
1225 the default page displayed when no other page is indicated by the user
1226 **home.classlist.html**
1227 a special version of the default page that lists the classes in the
1228 tracker
1229 **classname.item.html**
1230 displays an item of the *classname* class
1231 **classname.index.html**
1232 displays a list of *classname* items
1233 **classname.search.html**
1234 displays a search page for *classname* items
1235 **_generic.index.html**
1236 used to display a list of items where there is no
1237 ``*classname*.index`` available
1238 **_generic.help.html**
1239 used to display a "class help" page where there is no
1240 ``*classname*.help``
1241 **user.register.html**
1242 a special page just for the user class, that renders the registration
1243 page
1244 **style.css.html**
1245 a static file that is served up as-is
1247 The *classic* template has a number of additional templates.
1249 Note: Remember that you can create any template extension you want to,
1250 so if you just want to play around with the templating for new issues,
1251 you can copy the current "issue.item" template to "issue.test", and then
1252 access the test template using the "@template" URL argument::
1254 http://your.tracker.example/tracker/issue?@template=test
1256 and it won't affect your users using the "issue.item" template.
1259 How the templates work
1260 ----------------------
1263 Basic Templating Actions
1264 ~~~~~~~~~~~~~~~~~~~~~~~~
1266 Roundup's templates consist of special attributes on the HTML tags.
1267 These attributes form the Template Attribute Language, or TAL. The basic
1268 TAL commands are:
1270 **tal:define="variable expression; variable expression; ..."**
1271 Define a new variable that is local to this tag and its contents. For
1272 example::
1274 <html tal:define="title request/description">
1275 <head><title tal:content="title"></title></head>
1276 </html>
1278 In this example, the variable "title" is defined as the result of the
1279 expression "request/description". The "tal:content" command inside the
1280 <html> tag may then use the "title" variable.
1282 **tal:condition="expression"**
1283 Only keep this tag and its contents if the expression is true. For
1284 example::
1286 <p tal:condition="python:request.user.hasPermission('View', 'issue')">
1287 Display some issue information.
1288 </p>
1290 In the example, the <p> tag and its contents are only displayed if
1291 the user has the "View" permission for issues. We consider the number
1292 zero, a blank string, an empty list, and the built-in variable
1293 nothing to be false values. Nearly every other value is true,
1294 including non-zero numbers, and strings with anything in them (even
1295 spaces!).
1297 **tal:repeat="variable expression"**
1298 Repeat this tag and its contents for each element of the sequence
1299 that the expression returns, defining a new local variable and a
1300 special "repeat" variable for each element. For example::
1302 <tr tal:repeat="u user/list">
1303 <td tal:content="u/id"></td>
1304 <td tal:content="u/username"></td>
1305 <td tal:content="u/realname"></td>
1306 </tr>
1308 The example would iterate over the sequence of users returned by
1309 "user/list" and define the local variable "u" for each entry.
1311 **tal:replace="expression"**
1312 Replace this tag with the result of the expression. For example::
1314 <span tal:replace="request/user/realname" />
1316 The example would replace the <span> tag and its contents with the
1317 user's realname. If the user's realname was "Bruce", then the
1318 resultant output would be "Bruce".
1320 **tal:content="expression"**
1321 Replace the contents of this tag with the result of the expression.
1322 For example::
1324 <span tal:content="request/user/realname">user's name appears here
1325 </span>
1327 The example would replace the contents of the <span> tag with the
1328 user's realname. If the user's realname was "Bruce" then the
1329 resultant output would be "<span>Bruce</span>".
1331 **tal:attributes="attribute expression; attribute expression; ..."**
1332 Set attributes on this tag to the results of expressions. For
1333 example::
1335 <a tal:attributes="href string:user${request/user/id}">My Details</a>
1337 In the example, the "href" attribute of the <a> tag is set to the
1338 value of the "string:user${request/user/id}" expression, which will
1339 be something like "user123".
1341 **tal:omit-tag="expression"**
1342 Remove this tag (but not its contents) if the expression is true. For
1343 example::
1345 <span tal:omit-tag="python:1">Hello, world!</span>
1347 would result in output of::
1349 Hello, world!
1351 Note that the commands on a given tag are evaulated in the order above,
1352 so *define* comes before *condition*, and so on.
1354 Additionally, you may include tags such as <tal:block>, which are
1355 removed from output. Its content is kept, but the tag itself is not (so
1356 don't go using any "tal:attributes" commands on it). This is useful for
1357 making arbitrary blocks of HTML conditional or repeatable (very handy
1358 for repeating multiple table rows, which would othewise require an
1359 illegal tag placement to effect the repeat).
1362 Templating Expressions
1363 ~~~~~~~~~~~~~~~~~~~~~~
1365 The expressions you may use in the attribute values may be one of the
1366 following forms:
1368 **Path Expressions** - eg. ``item/status/checklist``
1369 These are object attribute / item accesses. Roughly speaking, the
1370 path ``item/status/checklist`` is broken into parts ``item``,
1371 ``status`` and ``checklist``. The ``item`` part is the root of the
1372 expression. We then look for a ``status`` attribute on ``item``, or
1373 failing that, a ``status`` item (as in ``item['status']``). If that
1374 fails, the path expression fails. When we get to the end, the object
1375 we're left with is evaluated to get a string - if it is a method, it
1376 is called; if it is an object, it is stringified. Path expressions
1377 may have an optional ``path:`` prefix, but they are the default
1378 expression type, so it's not necessary.
1380 If an expression evaluates to ``default``, then the expression is
1381 "cancelled" - whatever HTML already exists in the template will
1382 remain (tag content in the case of ``tal:content``, attributes in the
1383 case of ``tal:attributes``).
1385 If an expression evaluates to ``nothing`` then the target of the
1386 expression is removed (tag content in the case of ``tal:content``,
1387 attributes in the case of ``tal:attributes`` and the tag itself in
1388 the case of ``tal:replace``).
1390 If an element in the path may not exist, then you can use the ``|``
1391 operator in the expression to provide an alternative. So, the
1392 expression ``request/form/foo/value | default`` would simply leave
1393 the current HTML in place if the "foo" form variable doesn't exist.
1395 You may use the python function ``path``, as in
1396 ``path("item/status")``, to embed path expressions in Python
1397 expressions.
1399 **String Expressions** - eg. ``string:hello ${user/name}``
1400 These expressions are simple string interpolations - though they can
1401 be just plain strings with no interpolation if you want. The
1402 expression in the ``${ ... }`` is just a path expression as above.
1404 **Python Expressions** - eg. ``python: 1+1``
1405 These expressions give the full power of Python. All the "root level"
1406 variables are available, so ``python:item.status.checklist()`` would
1407 be equivalent to ``item/status/checklist``, assuming that
1408 ``checklist`` is a method.
1410 Modifiers:
1412 **structure** - eg. ``structure python:msg.content.plain(hyperlink=1)``
1413 The result of expressions are normally *escaped* to be safe for HTML
1414 display (all "<", ">" and "&" are turned into special entities). The
1415 ``structure`` expression modifier turns off this escaping - the
1416 result of the expression is now assumed to be HTML, which is passed
1417 to the web browser for rendering.
1419 **not:** - eg. ``not:python:1=1``
1420 This simply inverts the logical true/false value of another
1421 expression.
1424 Template Macros
1425 ~~~~~~~~~~~~~~~
1427 Macros are used in Roundup to save us from repeating the same common
1428 page stuctures over and over. The most common (and probably only) macro
1429 you'll use is the "icing" macro defined in the "page" template.
1431 Macros are generated and used inside your templates using special
1432 attributes similar to the `basic templating actions`_. In this case,
1433 though, the attributes belong to the Macro Expansion Template Attribute
1434 Language, or METAL. The macro commands are:
1436 **metal:define-macro="macro name"**
1437 Define that the tag and its contents are now a macro that may be
1438 inserted into other templates using the *use-macro* command. For
1439 example::
1441 <html metal:define-macro="page">
1442 ...
1443 </html>
1445 defines a macro called "page" using the ``<html>`` tag and its
1446 contents. Once defined, macros are stored on the template they're
1447 defined on in the ``macros`` attribute. You can access them later on
1448 through the ``templates`` variable, eg. the most common
1449 ``templates/page/macros/icing`` to access the "page" macro of the
1450 "page" template.
1452 **metal:use-macro="path expression"**
1453 Use a macro, which is identified by the path expression (see above).
1454 This will replace the current tag with the identified macro contents.
1455 For example::
1457 <tal:block metal:use-macro="templates/page/macros/icing">
1458 ...
1459 </tal:block>
1461 will replace the tag and its contents with the "page" macro of the
1462 "page" template.
1464 **metal:define-slot="slot name"** and **metal:fill-slot="slot name"**
1465 To define *dynamic* parts of the macro, you define "slots" which may
1466 be filled when the macro is used with a *use-macro* command. For
1467 example, the ``templates/page/macros/icing`` macro defines a slot like
1468 so::
1470 <title metal:define-slot="head_title">title goes here</title>
1472 In your *use-macro* command, you may now use a *fill-slot* command
1473 like this::
1475 <title metal:fill-slot="head_title">My Title</title>
1477 where the tag that fills the slot completely replaces the one defined
1478 as the slot in the macro.
1480 Note that you may not mix METAL and TAL commands on the same tag, but
1481 TAL commands may be used freely inside METAL-using tags (so your
1482 *fill-slots* tags may have all manner of TAL inside them).
1485 Information available to templates
1486 ----------------------------------
1488 Note: this is implemented by
1489 ``roundup.cgi.templating.RoundupPageTemplate``
1491 The following variables are available to templates.
1493 **context**
1494 The current context. This is either None, a `hyperdb class wrapper`_
1495 or a `hyperdb item wrapper`_
1496 **request**
1497 Includes information about the current request, including:
1498 - the current index information (``filterspec``, ``filter`` args,
1499 ``properties``, etc) parsed out of the form.
1500 - methods for easy filterspec link generation
1501 - *user*, the current user item as an HTMLItem instance
1502 - *form*
1503 The current CGI form information as a mapping of form argument name
1504 to value
1505 **config**
1506 This variable holds all the values defined in the tracker config.py
1507 file (eg. TRACKER_NAME, etc.)
1508 **db**
1509 The current database, used to access arbitrary database items.
1510 **templates**
1511 Access to all the tracker templates by name. Used mainly in
1512 *use-macro* commands.
1513 **utils**
1514 This variable makes available some utility functions like batching.
1515 **nothing**
1516 This is a special variable - if an expression evaluates to this, then
1517 the tag (in the case of a ``tal:replace``), its contents (in the case
1518 of ``tal:content``) or some attributes (in the case of
1519 ``tal:attributes``) will not appear in the the output. So, for
1520 example::
1522 <span tal:attributes="class nothing">Hello, World!</span>
1524 would result in::
1526 <span>Hello, World!</span>
1528 **default**
1529 Also a special variable - if an expression evaluates to this, then the
1530 existing HTML in the template will not be replaced or removed, it will
1531 remain. So::
1533 <span tal:replace="default">Hello, World!</span>
1535 would result in::
1537 <span>Hello, World!</span>
1540 The context variable
1541 ~~~~~~~~~~~~~~~~~~~~
1543 The *context* variable is one of three things based on the current
1544 context (see `determining web context`_ for how we figure this out):
1546 1. if we're looking at a "home" page, then it's None
1547 2. if we're looking at a specific hyperdb class, it's a
1548 `hyperdb class wrapper`_.
1549 3. if we're looking at a specific hyperdb item, it's a
1550 `hyperdb item wrapper`_.
1552 If the context is not None, we can access the properties of the class or
1553 item. The only real difference between cases 2 and 3 above are:
1555 1. the properties may have a real value behind them, and this will
1556 appear if the property is displayed through ``context/property`` or
1557 ``context/property/field``.
1558 2. the context's "id" property will be a false value in the second case,
1559 but a real, or true value in the third. Thus we can determine whether
1560 we're looking at a real item from the hyperdb by testing
1561 "context/id".
1563 Hyperdb class wrapper
1564 :::::::::::::::::::::
1566 Note: this is implemented by the ``roundup.cgi.templating.HTMLClass``
1567 class.
1569 This wrapper object provides access to a hyperb class. It is used
1570 primarily in both index view and new item views, but it's also usable
1571 anywhere else that you wish to access information about a class, or the
1572 items of a class, when you don't have a specific item of that class in
1573 mind.
1575 We allow access to properties. There will be no "id" property. The value
1576 accessed through the property will be the current value of the same name
1577 from the CGI form.
1579 There are several methods available on these wrapper objects:
1581 =========== =============================================================
1582 Method Description
1583 =========== =============================================================
1584 properties return a `hyperdb property wrapper`_ for all of this class's
1585 properties.
1586 list lists all of the active (not retired) items in the class.
1587 csv return the items of this class as a chunk of CSV text.
1588 propnames lists the names of the properties of this class.
1589 filter lists of items from this class, filtered and sorted by the
1590 current *request* filterspec/filter/sort/group args
1591 classhelp display a link to a javascript popup containing this class'
1592 "help" template.
1593 submit generate a submit button (and action hidden element)
1594 renderWith render this class with the given template.
1595 history returns 'New node - no history' :)
1596 is_edit_ok is the user allowed to Edit the current class?
1597 is_view_ok is the user allowed to View the current class?
1598 =========== =============================================================
1600 Note that if you have a property of the same name as one of the above
1601 methods, you'll need to access it using a python "item access"
1602 expression. For example::
1604 python:context['list']
1606 will access the "list" property, rather than the list method.
1609 Hyperdb item wrapper
1610 ::::::::::::::::::::
1612 Note: this is implemented by the ``roundup.cgi.templating.HTMLItem``
1613 class.
1615 This wrapper object provides access to a hyperb item.
1617 We allow access to properties. There will be no "id" property. The value
1618 accessed through the property will be the current value of the same name
1619 from the CGI form.
1621 There are several methods available on these wrapper objects:
1623 =============== ========================================================
1624 Method Description
1625 =============== ========================================================
1626 submit generate a submit button (and action hidden element)
1627 journal return the journal of the current item (**not
1628 implemented**)
1629 history render the journal of the current item as HTML
1630 renderQueryForm specific to the "query" class - render the search form
1631 for the query
1632 hasPermission specific to the "user" class - determine whether the
1633 user has a Permission
1634 is_edit_ok is the user allowed to Edit the current item?
1635 is_view_ok is the user allowed to View the current item?
1636 is_retired is the item retired?
1637 download_url generates a url-quoted link for download of FileClass
1638 item contents (ie. file<id>/<name>)
1639 =============== ========================================================
1641 Note that if you have a property of the same name as one of the above
1642 methods, you'll need to access it using a python "item access"
1643 expression. For example::
1645 python:context['journal']
1647 will access the "journal" property, rather than the journal method.
1650 Hyperdb property wrapper
1651 ::::::::::::::::::::::::
1653 Note: this is implemented by subclasses of the
1654 ``roundup.cgi.templating.HTMLProperty`` class (``HTMLStringProperty``,
1655 ``HTMLNumberProperty``, and so on).
1657 This wrapper object provides access to a single property of a class. Its
1658 value may be either:
1660 1. if accessed through a `hyperdb item wrapper`_, then it's a value from
1661 the hyperdb
1662 2. if access through a `hyperdb class wrapper`_, then it's a value from
1663 the CGI form
1666 The property wrapper has some useful attributes:
1668 =============== ========================================================
1669 Attribute Description
1670 =============== ========================================================
1671 _name the name of the property
1672 _value the value of the property if any - this is the actual
1673 value retrieved from the hyperdb for this property
1674 =============== ========================================================
1676 There are several methods available on these wrapper objects:
1678 =========== ================================================================
1679 Method Description
1680 =========== ================================================================
1681 plain render a "plain" representation of the property. This method
1682 may take two arguments:
1684 escape
1685 If true, escape the text so it is HTML safe (default: no). The
1686 reason this defaults to off is that text is usually escaped
1687 at a later stage by the TAL commands, unless the "structure"
1688 option is used in the template. The following ``tal:content``
1689 expressions are all equivalent::
1691 "structure python:msg.content.plain(escape=1)"
1692 "python:msg.content.plain()"
1693 "msg/content/plain"
1694 "msg/content"
1696 Usually you'll only want to use the escape option in a
1697 complex expression.
1699 hyperlink
1700 If true, turn URLs, email addresses and hyperdb item
1701 designators in the text into hyperlinks (default: no). Note
1702 that you'll need to use the "structure" TAL option if you
1703 want to use this ``tal:content`` expression::
1705 "structure python:msg.content.plain(hyperlink=1)"
1707 Note also that the text is automatically HTML-escaped before
1708 the hyperlinking transformation.
1709 hyperlinked The same as msg.content.plain(hyperlink=1), but nicer::
1711 "structure msg/content/hyperlinked"
1713 field render an appropriate form edit field for the property - for
1714 most types this is a text entry box, but for Booleans it's a
1715 tri-state yes/no/neither selection.
1716 stext only on String properties - render the value of the property
1717 as StructuredText (requires the StructureText module to be
1718 installed separately)
1719 multiline only on String properties - render a multiline form edit
1720 field for the property
1721 email only on String properties - render the value of the property
1722 as an obscured email address
1723 confirm only on Password properties - render a second form edit field
1724 for the property, used for confirmation that the user typed
1725 the password correctly. Generates a field with name
1726 "name:confirm".
1727 now only on Date properties - return the current date as a new
1728 property
1729 reldate only on Date properties - render the interval between the date
1730 and now
1731 local only on Date properties - return this date as a new property
1732 with some timezone offset, for example::
1734 python:context.creation.local(10)
1736 will render the date with a +10 hour offset.
1737 pretty Date properties - render the date as "dd Mon YYYY" (eg. "19
1738 Mar 2004"). Takes an optional format argument, for example::
1740 python:context.activity.pretty('%Y-%m-%d')
1742 Will format as "2004-03-19" instead.
1744 Interval properties - render the interval in a pretty
1745 format (eg. "yesterday")
1746 menu only on Link and Multilink properties - render a form select
1747 list for this property
1748 reverse only on Multilink properties - produce a list of the linked
1749 items in reverse order
1750 isset returns True if the property has been set to a value
1751 =========== ================================================================
1753 All of the above functions perform checks for permissions required to
1754 display or edit the data they are manipulating. The simplest case is
1755 editing an issue title. Including the expression::
1757 context/title/field
1759 Will present the user with an edit field, if they have edit permission. If
1760 not, then they will be presented with a static display if they have view
1761 permission. If they don't even have view permission, then an error message
1762 is raised, preventing the display of the page, indicating that they don't
1763 have permission to view the information.
1766 The request variable
1767 ~~~~~~~~~~~~~~~~~~~~
1769 Note: this is implemented by the ``roundup.cgi.templating.HTMLRequest``
1770 class.
1772 The request variable is packed with information about the current
1773 request.
1775 .. taken from ``roundup.cgi.templating.HTMLRequest`` docstring
1777 =========== ============================================================
1778 Variable Holds
1779 =========== ============================================================
1780 form the CGI form as a cgi.FieldStorage
1781 env the CGI environment variables
1782 base the base URL for this tracker
1783 user a HTMLUser instance for this user
1784 classname the current classname (possibly None)
1785 template the current template (suffix, also possibly None)
1786 form the current CGI form variables in a FieldStorage
1787 =========== ============================================================
1789 **Index page specific variables (indexing arguments)**
1791 =========== ============================================================
1792 Variable Holds
1793 =========== ============================================================
1794 columns dictionary of the columns to display in an index page
1795 show a convenience access to columns - request/show/colname will
1796 be true if the columns should be displayed, false otherwise
1797 sort index sort column (direction, column name)
1798 group index grouping property (direction, column name)
1799 filter properties to filter the index on
1800 filterspec values to filter the index on
1801 search_text text to perform a full-text search on for an index
1802 =========== ============================================================
1804 There are several methods available on the request variable:
1806 =============== ========================================================
1807 Method Description
1808 =============== ========================================================
1809 description render a description of the request - handle for the
1810 page title
1811 indexargs_form render the current index args as form elements
1812 indexargs_url render the current index args as a URL
1813 base_javascript render some javascript that is used by other components
1814 of the templating
1815 batch run the current index args through a filter and return a
1816 list of items (see `hyperdb item wrapper`_, and
1817 `batching`_)
1818 =============== ========================================================
1820 The form variable
1821 :::::::::::::::::
1823 The form variable is a bit special because it's actually a python
1824 FieldStorage object. That means that you have two ways to access its
1825 contents. For example, to look up the CGI form value for the variable
1826 "name", use the path expression::
1828 request/form/name/value
1830 or the python expression::
1832 python:request.form['name'].value
1834 Note the "item" access used in the python case, and also note the
1835 explicit "value" attribute we have to access. That's because the form
1836 variables are stored as MiniFieldStorages. If there's more than one
1837 "name" value in the form, then the above will break since
1838 ``request/form/name`` is actually a *list* of MiniFieldStorages. So it's
1839 best to know beforehand what you're dealing with.
1842 The db variable
1843 ~~~~~~~~~~~~~~~
1845 Note: this is implemented by the ``roundup.cgi.templating.HTMLDatabase``
1846 class.
1848 Allows access to all hyperdb classes as attributes of this variable. If
1849 you want access to the "user" class, for example, you would use::
1851 db/user
1852 python:db.user
1854 Also, the current id of the current user is available as
1855 ``db.getuid()``. This isn't so useful in templates (where you have
1856 ``request/user``), but it can be useful in detectors or interfaces.
1858 The access results in a `hyperdb class wrapper`_.
1861 The templates variable
1862 ~~~~~~~~~~~~~~~~~~~~~~
1864 Note: this is implemented by the ``roundup.cgi.templating.Templates``
1865 class.
1867 This variable doesn't have any useful methods defined. It supports being
1868 used in expressions to access the templates, and consequently the
1869 template macros. You may access the templates using the following path
1870 expression::
1872 templates/name
1874 or the python expression::
1876 templates[name]
1878 where "name" is the name of the template you wish to access. The
1879 template has one useful attribute, namely "macros". To access a specific
1880 macro (called "macro_name"), use the path expression::
1882 templates/name/macros/macro_name
1884 or the python expression::
1886 templates[name].macros[macro_name]
1889 The utils variable
1890 ~~~~~~~~~~~~~~~~~~
1892 Note: this is implemented by the
1893 ``roundup.cgi.templating.TemplatingUtils`` class, but it may be extended
1894 as described below.
1896 =============== ========================================================
1897 Method Description
1898 =============== ========================================================
1899 Batch return a batch object using the supplied list
1900 url_quote quote some text as safe for a URL (ie. space, %, ...)
1901 html_quote quote some text as safe in HTML (ie. <, >, ...)
1902 =============== ========================================================
1904 You may add additional utility methods by writing them in your tracker
1905 ``interfaces.py`` module's ``TemplatingUtils`` class. See `adding a time
1906 log to your issues`_ for an example. The TemplatingUtils class itself
1907 will have a single attribute, ``client``, which may be used to access
1908 the ``client.db`` when you need to perform arbitrary database queries.
1910 Batching
1911 ::::::::
1913 Use Batch to turn a list of items, or item ids of a given class, into a
1914 series of batches. Its usage is::
1916 python:utils.Batch(sequence, size, start, end=0, orphan=0,
1917 overlap=0)
1919 or, to get the current index batch::
1921 request/batch
1923 The parameters are:
1925 ========= ==============================================================
1926 Parameter Usage
1927 ========= ==============================================================
1928 sequence a list of HTMLItems
1929 size how big to make the sequence.
1930 start where to start (0-indexed) in the sequence.
1931 end where to end (0-indexed) in the sequence.
1932 orphan if the next batch would contain less items than this value,
1933 then it is combined with this batch
1934 overlap the number of items shared between adjacent batches
1935 ========= ==============================================================
1937 All of the parameters are assigned as attributes on the batch object. In
1938 addition, it has several more attributes:
1940 =============== ========================================================
1941 Attribute Description
1942 =============== ========================================================
1943 start indicates the start index of the batch. *Note: unlike
1944 the argument, is a 1-based index (I know, lame)*
1945 first indicates the start index of the batch *as a 0-based
1946 index*
1947 length the actual number of elements in the batch
1948 sequence_length the length of the original, unbatched, sequence.
1949 =============== ========================================================
1951 And several methods:
1953 =============== ========================================================
1954 Method Description
1955 =============== ========================================================
1956 previous returns a new Batch with the previous batch settings
1957 next returns a new Batch with the next batch settings
1958 propchanged detect if the named property changed on the current item
1959 when compared to the last item
1960 =============== ========================================================
1962 An example of batching::
1964 <table class="otherinfo">
1965 <tr><th colspan="4" class="header">Existing Keywords</th></tr>
1966 <tr tal:define="keywords db/keyword/list"
1967 tal:repeat="start python:range(0, len(keywords), 4)">
1968 <td tal:define="batch python:utils.Batch(keywords, 4, start)"
1969 tal:repeat="keyword batch" tal:content="keyword/name">
1970 keyword here</td>
1971 </tr>
1972 </table>
1974 ... which will produce a table with four columns containing the items of
1975 the "keyword" class (well, their "name" anyway).
1977 Displaying Properties
1978 ---------------------
1980 Properties appear in the user interface in three contexts: in indices,
1981 in editors, and as search arguments. For each type of property, there
1982 are several display possibilities. For example, in an index view, a
1983 string property may just be printed as a plain string, but in an editor
1984 view, that property may be displayed in an editable field.
1987 Index Views
1988 -----------
1990 This is one of the class context views. It is also the default view for
1991 classes. The template used is "*classname*.index".
1994 Index View Specifiers
1995 ~~~~~~~~~~~~~~~~~~~~~
1997 An index view specifier (URL fragment) looks like this (whitespace has
1998 been added for clarity)::
2000 /issue?status=unread,in-progress,resolved&
2001 topic=security,ui&
2002 :group=+priority&
2003 :sort==activity&
2004 :filters=status,topic&
2005 :columns=title,status,fixer
2007 The index view is determined by two parts of the specifier: the layout
2008 part and the filter part. The layout part consists of the query
2009 parameters that begin with colons, and it determines the way that the
2010 properties of selected items are displayed. The filter part consists of
2011 all the other query parameters, and it determines the criteria by which
2012 items are selected for display. The filter part is interactively
2013 manipulated with the form widgets displayed in the filter section. The
2014 layout part is interactively manipulated by clicking on the column
2015 headings in the table.
2017 The filter part selects the union of the sets of items with values
2018 matching any specified Link properties and the intersection of the sets
2019 of items with values matching any specified Multilink properties.
2021 The example specifies an index of "issue" items. Only items with a
2022 "status" of either "unread" or "in-progress" or "resolved" are
2023 displayed, and only items with "topic" values including both "security"
2024 and "ui" are displayed. The items are grouped by priority, arranged in
2025 ascending order; and within groups, sorted by activity, arranged in
2026 descending order. The filter section shows filters for the "status" and
2027 "topic" properties, and the table includes columns for the "title",
2028 "status", and "fixer" properties.
2030 Searching Views
2031 ---------------
2033 Note: if you add a new column to the ``:columns`` form variable
2034 potentials then you will need to add the column to the appropriate
2035 `index views`_ template so that it is actually displayed.
2037 This is one of the class context views. The template used is typically
2038 "*classname*.search". The form on this page should have "search" as its
2039 ``@action`` variable. The "search" action:
2041 - sets up additional filtering, as well as performing indexed text
2042 searching
2043 - sets the ``:filter`` variable correctly
2044 - saves the query off if ``:query_name`` is set.
2046 The search page should lay out any fields that you wish to allow the
2047 user to search on. If your schema contains a large number of properties,
2048 you should be wary of making all of those properties available for
2049 searching, as this can cause confusion. If the additional properties are
2050 Strings, consider having their value indexed, and then they will be
2051 searchable using the full text indexed search. This is both faster, and
2052 more useful for the end user.
2054 The two special form values on search pages which are handled by the
2055 "search" action are:
2057 :search_text
2058 Text with which to perform a search of the text index. Results from
2059 that search will be used to limit the results of other filters (using
2060 an intersection operation)
2061 :query_name
2062 If supplied, the search parameters (including :search_text) will be
2063 saved off as a the query item and registered against the user's
2064 queries property. Note that the *classic* template schema has this
2065 ability, but the *minimal* template schema does not.
2068 Item Views
2069 ----------
2071 The basic view of a hyperdb item is provided by the "*classname*.item"
2072 template. It generally has three sections; an "editor", a "spool" and a
2073 "history" section.
2076 Editor Section
2077 ~~~~~~~~~~~~~~
2079 The editor section is used to manipulate the item - it may be a static
2080 display if the user doesn't have permission to edit the item.
2082 Here's an example of a basic editor template (this is the default
2083 "classic" template issue item edit form - from the "issue.item.html"
2084 template)::
2086 <table class="form">
2087 <tr>
2088 <th>Title</th>
2089 <td colspan="3" tal:content="structure python:context.title.field(size=60)">title</td>
2090 </tr>
2092 <tr>
2093 <th>Priority</th>
2094 <td tal:content="structure context/priority/menu">priority</td>
2095 <th>Status</th>
2096 <td tal:content="structure context/status/menu">status</td>
2097 </tr>
2099 <tr>
2100 <th>Superseder</th>
2101 <td>
2102 <span tal:replace="structure python:context.superseder.field(showid=1, size=20)" />
2103 <span tal:replace="structure python:db.issue.classhelp('id,title')" />
2104 <span tal:condition="context/superseder">
2105 <br>View: <span tal:replace="structure python:context.superseder.link(showid=1)" />
2106 </span>
2107 </td>
2108 <th>Nosy List</th>
2109 <td>
2110 <span tal:replace="structure context/nosy/field" />
2111 <span tal:replace="structure python:db.user.classhelp('username,realname,address,phone')" />
2112 </td>
2113 </tr>
2115 <tr>
2116 <th>Assigned To</th>
2117 <td tal:content="structure context/assignedto/menu">
2118 assignedto menu
2119 </td>
2120 <td> </td>
2121 <td> </td>
2122 </tr>
2124 <tr>
2125 <th>Change Note</th>
2126 <td colspan="3">
2127 <textarea name=":note" wrap="hard" rows="5" cols="60"></textarea>
2128 </td>
2129 </tr>
2131 <tr>
2132 <th>File</th>
2133 <td colspan="3"><input type="file" name=":file" size="40"></td>
2134 </tr>
2136 <tr>
2137 <td> </td>
2138 <td colspan="3" tal:content="structure context/submit">
2139 submit button will go here
2140 </td>
2141 </tr>
2142 </table>
2145 When a change is submitted, the system automatically generates a message
2146 describing the changed properties. As shown in the example, the editor
2147 template can use the ":note" and ":file" fields, which are added to the
2148 standard changenote message generated by Roundup.
2151 Form values
2152 :::::::::::
2154 We have a number of ways to pull properties out of the form in order to
2155 meet the various needs of:
2157 1. editing the current item (perhaps an issue item)
2158 2. editing information related to the current item (eg. messages or
2159 attached files)
2160 3. creating new information to be linked to the current item (eg. time
2161 spent on an issue)
2163 In the following, ``<bracketed>`` values are variable, ":" may be one of
2164 ":" or "@", and other text ("required") is fixed.
2166 Properties are specified as form variables:
2168 ``<propname>``
2169 property on the current context item
2171 ``<designator>:<propname>``
2172 property on the indicated item (for editing related information)
2174 ``<classname>-<N>:<propname>``
2175 property on the Nth new item of classname (generally for creating new
2176 items to attach to the current item)
2178 Once we have determined the "propname", we check to see if it is one of
2179 the special form values:
2181 ``@required``
2182 The named property values must be supplied or a ValueError will be
2183 raised.
2185 ``@remove@<propname>=id(s)``
2186 The ids will be removed from the multilink property.
2188 ``:add:<propname>=id(s)``
2189 The ids will be added to the multilink property.
2191 ``:link:<propname>=<designator>``
2192 Used to add a link to new items created during edit. These are
2193 collected and returned in ``all_links``. This will result in an
2194 additional linking operation (either Link set or Multilink append)
2195 after the edit/create is done using ``all_props`` in ``_editnodes``.
2196 The <propname> on the current item will be set/appended the id of the
2197 newly created item of class <designator> (where <designator> must be
2198 <classname>-<N>).
2200 Any of the form variables may be prefixed with a classname or
2201 designator.
2203 Two special form values are supported for backwards compatibility:
2205 ``:note``
2206 create a message (with content, author and date), linked to the
2207 context item. This is ALWAYS designated "msg-1".
2208 ``:file``
2209 create a file, attached to the current item and any message created by
2210 :note. This is ALWAYS designated "file-1".
2213 Spool Section
2214 ~~~~~~~~~~~~~
2216 The spool section lists related information like the messages and files
2217 of an issue.
2219 TODO
2222 History Section
2223 ~~~~~~~~~~~~~~~
2225 The final section displayed is the history of the item - its database
2226 journal. This is generally generated with the template::
2228 <tal:block tal:replace="structure context/history" />
2230 *To be done:*
2232 *The actual history entries of the item may be accessed for manual
2233 templating through the "journal" method of the item*::
2235 <tal:block tal:repeat="entry context/journal">
2236 a journal entry
2237 </tal:block>
2239 *where each journal entry is an HTMLJournalEntry.*
2241 Defining new web actions
2242 ------------------------
2244 You may define new actions to be triggered by the ``@action`` form variable.
2245 These are added to the tracker ``interfaces.py`` as ``Action`` classes that get
2246 called by the the ``Client`` class.
2248 Adding action classes takes three steps; first you `define the new
2249 action class`_, then you `register the action class`_ with the cgi
2250 interface so it may be triggered by the ``@action`` form variable.
2251 Finally you `use the new action`_ in your HTML form.
2253 See "`setting up a "wizard" (or "druid") for controlled adding of
2254 issues`_" for an example.
2257 Define the new action class
2258 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2260 The action classes have the following interface::
2262 class MyAction(Action):
2263 def handle(self):
2264 ''' Perform some action. No return value is required.
2265 '''
2267 The *self.client* attribute is an instance of your tracker ``instance.Client``
2268 class - thus it's mostly implemented by ``roundup.cgi.client.Client``. See the
2269 docstring of that class for details of what it can do.
2271 The method will typically check the ``self.form`` variable's contents.
2272 It may then:
2274 - add information to ``self.client.ok_message`` or ``self.client.error_message``
2275 - change the ``self.client.template`` variable to alter what the user will see
2276 next
2277 - raise Unauthorised, SendStaticFile, SendFile, NotFound or Redirect
2278 exceptions (import them from roundup.cgi.exceptions)
2281 Register the action class
2282 ~~~~~~~~~~~~~~~~~~~~~~~~~~
2284 The class is now written, but isn't available to the user until you add it to
2285 the ``instance.Client`` class ``actions`` variable, like so::
2287 actions = client.Client.actions + (
2288 ('myaction', myActionClass),
2289 )
2291 This maps the action name "myaction" to the action class we defined.
2293 Use the new action
2294 ~~~~~~~~~~~~~~~~~~
2296 In your HTML form, add a hidden form element like so::
2298 <input type="hidden" name="@action" value="myaction">
2300 where "myaction" is the name you registered in the previous step.
2302 Actions may return content to the user
2303 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2305 Actions generally perform some database manipulation and then pass control
2306 on to the rendering of a template in the current context (see `Determining
2307 web context`_ for how that works.) Some actions will want to generate the
2308 actual content returned to the user. Action methods may return their own
2309 content string to be displayed to the user, overriding the templating step.
2310 In this situation, we assume that the content is HTML by default. You may
2311 override the content type indicated to the user by calling ``setHeader``::
2313 self.client.setHeader('Content-Type', 'text/csv')
2315 This example indicates that the value sent back to the user is actually
2316 comma-separated value content (eg. something to be loaded into a
2317 spreadsheet or database).
2320 Examples
2321 ========
2323 .. contents::
2324 :local:
2325 :depth: 2
2328 Changing what's stored in the database
2329 --------------------------------------
2331 The following examples illustrate ways to change the information stored in
2332 the database.
2335 Adding a new field to the classic schema
2336 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2338 This example shows how to add a new constrained property (i.e. a
2339 selection of distinct values) to your tracker.
2342 Introduction
2343 ::::::::::::
2345 To make the classic schema of roundup useful as a TODO tracking system
2346 for a group of systems administrators, it needed an extra data field per
2347 issue: a category.
2349 This would let sysadmins quickly list all TODOs in their particular area
2350 of interest without having to do complex queries, and without relying on
2351 the spelling capabilities of other sysadmins (a losing proposition at
2352 best).
2355 Adding a field to the database
2356 ::::::::::::::::::::::::::::::
2358 This is the easiest part of the change. The category would just be a
2359 plain string, nothing fancy. To change what is in the database you need
2360 to add some lines to the ``open()`` function in ``dbinit.py``. Under the
2361 comment::
2363 # add any additional database schema configuration here
2365 add::
2367 category = Class(db, "category", name=String())
2368 category.setkey("name")
2370 Here we are setting up a chunk of the database which we are calling
2371 "category". It contains a string, which we are refering to as "name" for
2372 lack of a more imaginative title. (Since "name" is one of the properties
2373 that Roundup looks for on items if you do not set a key for them, it's
2374 probably a good idea to stick with it for new classes if at all
2375 appropriate.) Then we are setting the key of this chunk of the database
2376 to be that "name". This is equivalent to an index for database types.
2377 This also means that there can only be one category with a given name.
2379 Adding the above lines allows us to create categories, but they're not
2380 tied to the issues that we are going to be creating. It's just a list of
2381 categories off on its own, which isn't much use. We need to link it in
2382 with the issues. To do that, find the lines in the ``open()`` function
2383 in ``dbinit.py`` which set up the "issue" class, and then add a link to
2384 the category::
2386 issue = IssueClass(db, "issue", ... ,
2387 category=Multilink("category"), ... )
2389 The ``Multilink()`` means that each issue can have many categories. If
2390 you were adding something with a one-to-one relationship to issues (such
2391 as the "assignedto" property), use ``Link()`` instead.
2393 That is all you need to do to change the schema. The rest of the effort
2394 is fiddling around so you can actually use the new category.
2397 Populating the new category class
2398 :::::::::::::::::::::::::::::::::
2400 If you haven't initialised the database with the roundup-admin
2401 "initialise" command, then you can add the following to the tracker
2402 ``dbinit.py`` in the ``init()`` function under the comment::
2404 # add any additional database create steps here - but only if you
2405 # haven't initialised the database with the admin "initialise" command
2407 Add::
2409 category = db.getclass('category')
2410 category.create(name="scipy", order="1")
2411 category.create(name="chaco", order="2")
2412 category.create(name="weave", order="3")
2414 If the database has already been initalised, then you need to use the
2415 ``roundup-admin`` tool::
2417 % roundup-admin -i <tracker home>
2418 Roundup <version> ready for input.
2419 Type "help" for help.
2420 roundup> create category name=scipy order=1
2421 1
2422 roundup> create category name=chaco order=1
2423 2
2424 roundup> create category name=weave order=1
2425 3
2426 roundup> exit...
2427 There are unsaved changes. Commit them (y/N)? y
2429 TODO: explain why order=1 in each case.
2432 Setting up security on the new objects
2433 ::::::::::::::::::::::::::::::::::::::
2435 By default only the admin user can look at and change objects. This
2436 doesn't suit us, as we want any user to be able to create new categories
2437 as required, and obviously everyone needs to be able to view the
2438 categories of issues for it to be useful.
2440 We therefore need to change the security of the category objects. This
2441 is also done in the ``open()`` function of ``dbinit.py``.
2443 There are currently two loops which set up permissions and then assign
2444 them to various roles. Simply add the new "category" to both lists::
2446 # new permissions for this schema
2447 for cl in 'issue', 'file', 'msg', 'user', 'category':
2448 db.security.addPermission(name="Edit", klass=cl,
2449 description="User is allowed to edit "+cl)
2450 db.security.addPermission(name="View", klass=cl,
2451 description="User is allowed to access "+cl)
2453 # Assign the access and edit permissions for issue, file and message
2454 # to regular users now
2455 for cl in 'issue', 'file', 'msg', 'category':
2456 p = db.security.getPermission('View', cl)
2457 db.security.addPermissionToRole('User', p)
2458 p = db.security.getPermission('Edit', cl)
2459 db.security.addPermissionToRole('User', p)
2461 So you are in effect doing the following (with 'cl' substituted by its
2462 value)::
2464 db.security.addPermission(name="Edit", klass='category',
2465 description="User is allowed to edit "+'category')
2466 db.security.addPermission(name="View", klass='category',
2467 description="User is allowed to access "+'category')
2469 which is creating two permission types; that of editing and viewing
2470 "category" objects respectively. Then the following lines assign those
2471 new permissions to the "User" role, so that normal users can view and
2472 edit "category" objects::
2474 p = db.security.getPermission('View', 'category')
2475 db.security.addPermissionToRole('User', p)
2477 p = db.security.getPermission('Edit', 'category')
2478 db.security.addPermissionToRole('User', p)
2480 This is all the work that needs to be done for the database. It will
2481 store categories, and let users view and edit them. Now on to the
2482 interface stuff.
2485 Changing the web left hand frame
2486 ::::::::::::::::::::::::::::::::
2488 We need to give the users the ability to create new categories, and the
2489 place to put the link to this functionality is in the left hand function
2490 bar, under the "Issues" area. The file that defines how this area looks
2491 is ``html/page``, which is what we are going to be editing next.
2493 If you look at this file you can see that it contains a lot of
2494 "classblock" sections which are chunks of HTML that will be included or
2495 excluded in the output depending on whether the condition in the
2496 classblock is met. Under the end of the classblock for issue is where we
2497 are going to add the category code::
2499 <p class="classblock"
2500 tal:condition="python:request.user.hasPermission('View', 'category')">
2501 <b>Categories</b><br>
2502 <a tal:condition="python:request.user.hasPermission('Edit', 'category')"
2503 href="category?@template=item">New Category<br></a>
2504 </p>
2506 The first two lines is the classblock definition, which sets up a
2507 condition that only users who have "View" permission for the "category"
2508 object will have this section included in their output. Next comes a
2509 plain "Categories" header in bold. Everyone who can view categories will
2510 get that.
2512 Next comes the link to the editing area of categories. This link will
2513 only appear if the condition - that the user has "Edit" permissions for
2514 the "category" objects - is matched. If they do have permission then
2515 they will get a link to another page which will let the user add new
2516 categories.
2518 Note that if you have permission to *view* but not to *edit* categories,
2519 then all you will see is a "Categories" header with nothing underneath
2520 it. This is obviously not very good interface design, but will do for
2521 now. I just claim that it is so I can add more links in this section
2522 later on. However to fix the problem you could change the condition in
2523 the classblock statement, so that only users with "Edit" permission
2524 would see the "Categories" stuff.
2527 Setting up a page to edit categories
2528 ::::::::::::::::::::::::::::::::::::
2530 We defined code in the previous section which let users with the
2531 appropriate permissions see a link to a page which would let them edit
2532 conditions. Now we have to write that page.
2534 The link was for the *item* template of the *category* object. This
2535 translates into Roundup looking for a file called ``category.item.html``
2536 in the ``html`` tracker directory. This is the file that we are going to
2537 write now.
2539 First we add an info tag in a comment which doesn't affect the outcome
2540 of the code at all, but is useful for debugging. If you load a page in a
2541 browser and look at the page source, you can see which sections come
2542 from which files by looking for these comments::
2544 <!-- category.item -->
2546 Next we need to add in the METAL macro stuff so we get the normal page
2547 trappings::
2549 <tal:block metal:use-macro="templates/page/macros/icing">
2550 <title metal:fill-slot="head_title">Category editing</title>
2551 <td class="page-header-top" metal:fill-slot="body_title">
2552 <h2>Category editing</h2>
2553 </td>
2554 <td class="content" metal:fill-slot="content">
2556 Next we need to setup up a standard HTML form, which is the whole
2557 purpose of this file. We link to some handy javascript which sends the
2558 form through only once. This is to stop users hitting the send button
2559 multiple times when they are impatient and thus having the form sent
2560 multiple times::
2562 <form method="POST" onSubmit="return submit_once()"
2563 enctype="multipart/form-data">
2565 Next we define some code which sets up the minimum list of fields that
2566 we require the user to enter. There will be only one field - "name" - so
2567 they better put something in it, otherwise the whole form is pointless::
2569 <input type="hidden" name="@required" value="name">
2571 To get everything to line up properly we will put everything in a table,
2572 and put a nice big header on it so the user has an idea what is
2573 happening::
2575 <table class="form">
2576 <tr><th class="header" colspan="2">Category</th></tr>
2578 Next, we need the field into which the user is going to enter the new
2579 category. The "context.name.field(size=60)" bit tells Roundup to
2580 generate a normal HTML field of size 60, and the contents of that field
2581 will be the "name" variable of the current context (which is
2582 "category"). The upshot of this is that when the user types something in
2583 to the form, a new category will be created with that name::
2585 <tr>
2586 <th>Name</th>
2587 <td tal:content="structure python:context.name.field(size=60)">
2588 name</td>
2589 </tr>
2591 Then a submit button so that the user can submit the new category::
2593 <tr>
2594 <td> </td>
2595 <td colspan="3" tal:content="structure context/submit">
2596 submit button will go here
2597 </td>
2598 </tr>
2600 Finally we finish off the tags we used at the start to do the METAL
2601 stuff::
2603 </td>
2604 </tal:block>
2606 So putting it all together, and closing the table and form we get::
2608 <!-- category.item -->
2609 <tal:block metal:use-macro="templates/page/macros/icing">
2610 <title metal:fill-slot="head_title">Category editing</title>
2611 <td class="page-header-top" metal:fill-slot="body_title">
2612 <h2>Category editing</h2>
2613 </td>
2614 <td class="content" metal:fill-slot="content">
2615 <form method="POST" onSubmit="return submit_once()"
2616 enctype="multipart/form-data">
2618 <table class="form">
2619 <tr><th class="header" colspan="2">Category</th></tr>
2621 <tr>
2622 <th>Name</th>
2623 <td tal:content="structure python:context.name.field(size=60)">
2624 name</td>
2625 </tr>
2627 <tr>
2628 <td>
2629
2630 <input type="hidden" name="@required" value="name">
2631 </td>
2632 <td colspan="3" tal:content="structure context/submit">
2633 submit button will go here
2634 </td>
2635 </tr>
2636 </table>
2637 </form>
2638 </td>
2639 </tal:block>
2641 This is quite a lot to just ask the user one simple question, but there
2642 is a lot of setup for basically one line (the form line) to do its work.
2643 To add another field to "category" would involve one more line (well,
2644 maybe a few extra to get the formatting correct).
2647 Adding the category to the issue
2648 ::::::::::::::::::::::::::::::::
2650 We now have the ability to create issues to our heart's content, but
2651 that is pointless unless we can assign categories to issues. Just like
2652 the ``html/category.item.html`` file was used to define how to add a new
2653 category, the ``html/issue.item.html`` is used to define how a new issue
2654 is created.
2656 Just like ``category.issue.html`` this file defines a form which has a
2657 table to lay things out. It doesn't matter where in the table we add new
2658 stuff, it is entirely up to your sense of aesthetics::
2660 <th>Category</th>
2661 <td><span tal:replace="structure context/category/field" />
2662 <span tal:replace="structure db/category/classhelp" />
2663 </td>
2665 First, we define a nice header so that the user knows what the next
2666 section is, then the middle line does what we are most interested in.
2667 This ``context/category/field`` gets replaced by a field which contains
2668 the category in the current context (the current context being the new
2669 issue).
2671 The classhelp lines generate a link (labelled "list") to a popup window
2672 which contains the list of currently known categories.
2675 Searching on categories
2676 :::::::::::::::::::::::
2678 We can add categories, and create issues with categories. The next
2679 obvious thing that we would like to be able to do, would be to search
2680 for issues based on their category, so that, for example, anyone working
2681 on the web server could look at all issues in the category "Web".
2683 If you look for "Search Issues" in the 'html/page.html' file, you will
2684 find that it looks something like
2685 ``<a href="issue?@template=search">Search Issues</a>``. This shows us
2686 that when you click on "Search Issues" it will be looking for a
2687 ``issue.search.html`` file to display. So that is the file that we will
2688 change.
2690 If you look at this file it should be starting to seem familiar, although it
2691 does use some new macros. You can add the new category search code anywhere you
2692 like within that form::
2694 <tr tal:define="name string:category;
2695 db_klass string:category;
2696 db_content string:name;">
2697 <th>Priority:</th>
2698 <td metal:use-macro="search_select"></td>
2699 <td metal:use-macro="column_input"></td>
2700 <td metal:use-macro="sort_input"></td>
2701 <td metal:use-macro="group_input"></td>
2702 </tr>
2704 The definitions in the <tr> opening tag are used by the macros:
2706 - search_select expands to a drop-down box with all categories using db_klass
2707 and db_content.
2708 - column_input expands to a checkbox for selecting what columns should be
2709 displayed.
2710 - sort_input expands to a radio button for selecting what property should be
2711 sorted on.
2712 - group_input expands to a radio button for selecting what property should be
2713 group on.
2715 The category search code above would expand to the following::
2717 <tr>
2718 <th>Category:</th>
2719 <td>
2720 <select name="category">
2721 <option value="">don't care</option>
2722 <option value="">------------</option>
2723 <option value="1">scipy</option>
2724 <option value="2">chaco</option>
2725 <option value="3">weave</option>
2726 </select>
2727 </td>
2728 <td><input type="checkbox" name=":columns" value="category"></td>
2729 <td><input type="radio" name=":sort" value="category"></td>
2730 <td><input type="radio" name=":group" value="category"></td>
2731 </tr>
2733 Adding category to the default view
2734 :::::::::::::::::::::::::::::::::::
2736 We can now add categories, add issues with categories, and search for
2737 issues based on categories. This is everything that we need to do;
2738 however, there is some more icing that we would like. I think the
2739 category of an issue is important enough that it should be displayed by
2740 default when listing all the issues.
2742 Unfortunately, this is a bit less obvious than the previous steps. The
2743 code defining how the issues look is in ``html/issue.index.html``. This
2744 is a large table with a form down at the bottom for redisplaying and so
2745 forth.
2747 Firstly we need to add an appropriate header to the start of the table::
2749 <th tal:condition="request/show/category">Category</th>
2751 The *condition* part of this statement is to avoid displaying the
2752 Category column if the user has selected not to see it.
2754 The rest of the table is a loop which will go through every issue that
2755 matches the display criteria. The loop variable is "i" - which means
2756 that every issue gets assigned to "i" in turn.
2758 The new part of code to display the category will look like this::
2760 <td tal:condition="request/show/category"
2761 tal:content="i/category"></td>
2763 The condition is the same as above: only display the condition when the
2764 user hasn't asked for it to be hidden. The next part is to set the
2765 content of the cell to be the category part of "i" - the current issue.
2767 Finally we have to edit ``html/page.html`` again. This time, we need to
2768 tell it that when the user clicks on "Unasigned Issues" or "All Issues",
2769 the category column should be included in the resulting list. If you
2770 scroll down the page file, you can see the links with lots of options.
2771 The option that we are interested in is the ``:columns=`` one which
2772 tells roundup which fields of the issue to display. Simply add
2773 "category" to that list and it all should work.
2775 Adding a time log to your issues
2776 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2778 We want to log the dates and amount of time spent working on issues, and
2779 be able to give a summary of the total time spent on a particular issue.
2781 1. Add a new class to your tracker ``dbinit.py``::
2783 # storage for time logging
2784 timelog = Class(db, "timelog", period=Interval())
2786 Note that we automatically get the date of the time log entry
2787 creation through the standard property "creation".
2789 2. Link to the new class from your issue class (again, in
2790 ``dbinit.py``)::
2792 issue = IssueClass(db, "issue",
2793 assignedto=Link("user"), topic=Multilink("keyword"),
2794 priority=Link("priority"), status=Link("status"),
2795 times=Multilink("timelog"))
2797 the "times" property is the new link to the "timelog" class.
2799 3. We'll need to let people add in times to the issue, so in the web
2800 interface we'll have a new entry field. This is a special field
2801 because unlike the other fields in the issue.item template, it
2802 affects a different item (a timelog item) and not the template's
2803 item, an issue. We have a special syntax for form fields that affect
2804 items other than the template default item (see the cgi
2805 documentation on `special form variables`_). In particular, we add a
2806 field to capture a new timelog item's perdiod::
2808 <tr>
2809 <th>Time Log</th>
2810 <td colspan=3><input type="text" name="timelog-1@period" />
2811 <br />(enter as '3y 1m 4d 2:40:02' or parts thereof)
2812 </td>
2813 </tr>
2815 and another hidden field that links that new timelog item (new
2816 because it's marked as having id "-1") to the issue item. It looks
2817 like this::
2819 <input type="hidden" name="@link@times" value="timelog-1" />
2821 On submission, the "-1" timelog item will be created and assigned a
2822 real item id. The "times" property of the issue will have the new id
2823 added to it.
2825 4. We want to display a total of the time log times that have been
2826 accumulated for an issue. To do this, we'll need to actually write
2827 some Python code, since it's beyond the scope of PageTemplates to
2828 perform such calculations. We do this by adding a method to the
2829 TemplatingUtils class in our tracker ``interfaces.py`` module::
2831 class TemplatingUtils:
2832 ''' Methods implemented on this class will be available to HTML
2833 templates through the 'utils' variable.
2834 '''
2835 def totalTimeSpent(self, times):
2836 ''' Call me with a list of timelog items (which have an
2837 Interval "period" property)
2838 '''
2839 total = Interval('0d')
2840 for time in times:
2841 total += time.period._value
2842 return total
2844 Replace the ``pass`` line if one appears in your TemplatingUtils
2845 class. As indicated in the docstrings, we will be able to access the
2846 ``totalTimeSpent`` method via the ``utils`` variable in our templates.
2848 5. Display the time log for an issue::
2850 <table class="otherinfo" tal:condition="context/times">
2851 <tr><th colspan="3" class="header">Time Log
2852 <tal:block
2853 tal:replace="python:utils.totalTimeSpent(context.times)" />
2854 </th></tr>
2855 <tr><th>Date</th><th>Period</th><th>Logged By</th></tr>
2856 <tr tal:repeat="time context/times">
2857 <td tal:content="time/creation"></td>
2858 <td tal:content="time/period"></td>
2859 <td tal:content="time/creator"></td>
2860 </tr>
2861 </table>
2863 I put this just above the Messages log in my issue display. Note our
2864 use of the ``totalTimeSpent`` method which will total up the times
2865 for the issue and return a new Interval. That will be automatically
2866 displayed in the template as text like "+ 1y 2:40" (1 year, 2 hours
2867 and 40 minutes).
2869 8. If you're using a persistent web server - roundup-server or
2870 mod_python for example - then you'll need to restart that to pick up
2871 the code changes. When that's done, you'll be able to use the new
2872 time logging interface.
2875 Tracking different types of issues
2876 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2878 Sometimes you will want to track different types of issues - developer,
2879 customer support, systems, sales leads, etc. A single Roundup tracker is
2880 able to support multiple types of issues. This example demonstrates adding
2881 a customer support issue class to a tracker.
2883 1. Figure out what information you're going to want to capture. OK, so
2884 this is obvious, but sometimes it's better to actually sit down for a
2885 while and think about the schema you're going to implement.
2887 2. Add the new issue class to your tracker's ``dbinit.py`` - in this
2888 example, we're adding a "system support" class. Just after the "issue"
2889 class definition in the "open" function, add::
2891 support = IssueClass(db, "support",
2892 assignedto=Link("user"), topic=Multilink("keyword"),
2893 status=Link("status"), deadline=Date(),
2894 affects=Multilink("system"))
2896 3. Copy the existing "issue.*" (item, search and index) templates in the
2897 tracker's "html" to "support.*". Edit them so they use the properties
2898 defined in the "support" class. Be sure to check for hidden form
2899 variables like "required" to make sure they have the correct set of
2900 required properties.
2902 4. Edit the modules in the "detectors", adding lines to their "init"
2903 functions where appropriate. Look for "audit" and "react" registrations
2904 on the "issue" class, and duplicate them for "support".
2906 5. Create a new sidebar box for the new support class. Duplicate the
2907 existing issues one, changing the "issue" class name to "support".
2909 6. Re-start your tracker and start using the new "support" class.
2912 Optionally, you might want to restrict the users able to access this new
2913 class to just the users with a new "SysAdmin" Role. To do this, we add
2914 some security declarations::
2916 p = db.security.getPermission('View', 'support')
2917 db.security.addPermissionToRole('SysAdmin', p)
2918 p = db.security.getPermission('Edit', 'support')
2919 db.security.addPermissionToRole('SysAdmin', p)
2921 You would then (as an "admin" user) edit the details of the appropriate
2922 users, and add "SysAdmin" to their Roles list.
2924 Alternatively, you might want to change the Edit/View permissions granted
2925 for the "issue" class so that it's only available to users with the "System"
2926 or "Developer" Role, and then the new class you're adding is available to
2927 all with the "User" Role.
2930 Using External User Databases
2931 -----------------------------
2933 Using an external password validation source
2934 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2936 We have a centrally-managed password changing system for our users. This
2937 results in a UN*X passwd-style file that we use for verification of
2938 users. Entries in the file consist of ``name:password`` where the
2939 password is encrypted using the standard UN*X ``crypt()`` function (see
2940 the ``crypt`` module in your Python distribution). An example entry
2941 would be::
2943 admin:aamrgyQfDFSHw
2945 Each user of Roundup must still have their information stored in the Roundup
2946 database - we just use the passwd file to check their password. To do this, we
2947 need to override the standard ``verifyPassword`` method defined in
2948 ``roundup.cgi.actions.LoginAction`` and register the new class with our
2949 ``Client`` class in the tracker home ``interfaces.py`` module::
2951 from roundup.cgi.actions import LoginAction
2953 class ExternalPasswordLoginAction(LoginAction):
2954 def verifyPassword(self, userid, password):
2955 # get the user's username
2956 username = self.db.user.get(userid, 'username')
2958 # the passwords are stored in the "passwd.txt" file in the
2959 # tracker home
2960 file = os.path.join(self.db.config.TRACKER_HOME, 'passwd.txt')
2962 # see if we can find a match
2963 for ent in [line.strip().split(':') for line in
2964 open(file).readlines()]:
2965 if ent[0] == username:
2966 return crypt.crypt(password, ent[1][:2]) == ent[1]
2968 # user doesn't exist in the file
2969 return 0
2971 class Client(client.Client):
2972 actions = client.Client.actions + (
2973 ('login', ExternalPasswordLoginAction)
2974 )
2976 What this does is look through the file, line by line, looking for a
2977 name that matches.
2979 We also remove the redundant password fields from the ``user.item``
2980 template.
2983 Using a UN*X passwd file as the user database
2984 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2986 On some systems the primary store of users is the UN*X passwd file. It
2987 holds information on users such as their username, real name, password
2988 and primary user group.
2990 Roundup can use this store as its primary source of user information,
2991 but it needs additional information too - email address(es), roundup
2992 Roles, vacation flags, roundup hyperdb item ids, etc. Also, "retired"
2993 users must still exist in the user database, unlike some passwd files in
2994 which the users are removed when they no longer have access to a system.
2996 To make use of the passwd file, we therefore synchronise between the two
2997 user stores. We also use the passwd file to validate the user logins, as
2998 described in the previous example, `using an external password
2999 validation source`_. We keep the users lists in sync using a fairly
3000 simple script that runs once a day, or several times an hour if more
3001 immediate access is needed. In short, it:
3003 1. parses the passwd file, finding usernames, passwords and real names,
3004 2. compares that list to the current roundup user list:
3006 a. entries no longer in the passwd file are *retired*
3007 b. entries with mismatching real names are *updated*
3008 c. entries only exist in the passwd file are *created*
3010 3. send an email to administrators to let them know what's been done.
3012 The retiring and updating are simple operations, requiring only a call
3013 to ``retire()`` or ``set()``. The creation operation requires more
3014 information though - the user's email address and their roundup Roles.
3015 We're going to assume that the user's email address is the same as their
3016 login name, so we just append the domain name to that. The Roles are
3017 determined using the passwd group identifier - mapping their UN*X group
3018 to an appropriate set of Roles.
3020 The script to perform all this, broken up into its main components, is
3021 as follows. Firstly, we import the necessary modules and open the
3022 tracker we're to work on::
3024 import sys, os, smtplib
3025 from roundup import instance, date
3027 # open the tracker
3028 tracker_home = sys.argv[1]
3029 tracker = instance.open(tracker_home)
3031 Next we read in the *passwd* file from the tracker home::
3033 # read in the users
3034 file = os.path.join(tracker_home, 'users.passwd')
3035 users = [x.strip().split(':') for x in open(file).readlines()]
3037 Handle special users (those to ignore in the file, and those who don't
3038 appear in the file)::
3040 # users to not keep ever, pre-load with the users I know aren't
3041 # "real" users
3042 ignore = ['ekmmon', 'bfast', 'csrmail']
3044 # users to keep - pre-load with the roundup-specific users
3045 keep = ['comment_pool', 'network_pool', 'admin', 'dev-team',
3046 'cs_pool', 'anonymous', 'system_pool', 'automated']
3048 Now we map the UN*X group numbers to the Roles that users should have::
3050 roles = {
3051 '501': 'User,Tech', # tech
3052 '502': 'User', # finance
3053 '503': 'User,CSR', # customer service reps
3054 '504': 'User', # sales
3055 '505': 'User', # marketing
3056 }
3058 Now we do all the work. Note that the body of the script (where we have
3059 the tracker database open) is wrapped in a ``try`` / ``finally`` clause,
3060 so that we always close the database cleanly when we're finished. So, we
3061 now do all the work::
3063 # open the database
3064 db = tracker.open('admin')
3065 try:
3066 # store away messages to send to the tracker admins
3067 msg = []
3069 # loop over the users list read in from the passwd file
3070 for user,passw,uid,gid,real,home,shell in users:
3071 if user in ignore:
3072 # this user shouldn't appear in our tracker
3073 continue
3074 keep.append(user)
3075 try:
3076 # see if the user exists in the tracker
3077 uid = db.user.lookup(user)
3079 # yes, they do - now check the real name for correctness
3080 if real != db.user.get(uid, 'realname'):
3081 db.user.set(uid, realname=real)
3082 msg.append('FIX %s - %s'%(user, real))
3083 except KeyError:
3084 # nope, the user doesn't exist
3085 db.user.create(username=user, realname=real,
3086 address='%s@ekit-inc.com'%user, roles=roles[gid])
3087 msg.append('ADD %s - %s (%s)'%(user, real, roles[gid]))
3089 # now check that all the users in the tracker are also in our
3090 # "keep" list - retire those who aren't
3091 for uid in db.user.list():
3092 user = db.user.get(uid, 'username')
3093 if user not in keep:
3094 db.user.retire(uid)
3095 msg.append('RET %s'%user)
3097 # if we did work, then send email to the tracker admins
3098 if msg:
3099 # create the email
3100 msg = '''Subject: %s user database maintenance
3102 %s
3103 '''%(db.config.TRACKER_NAME, '\n'.join(msg))
3105 # send the email
3106 smtp = smtplib.SMTP(db.config.MAILHOST)
3107 addr = db.config.ADMIN_EMAIL
3108 smtp.sendmail(addr, addr, msg)
3110 # now we're done - commit the changes
3111 db.commit()
3112 finally:
3113 # always close the database cleanly
3114 db.close()
3116 And that's it!
3119 Using an LDAP database for user information
3120 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3122 A script that reads users from an LDAP store using
3123 http://python-ldap.sf.net/ and then compares the list to the users in the
3124 roundup user database would be pretty easy to write. You'd then have it run
3125 once an hour / day (or on demand if you can work that into your LDAP store
3126 workflow). See the example `Using a UN*X passwd file as the user database`_
3127 for more information about doing this.
3129 To authenticate off the LDAP store (rather than using the passwords in the
3130 roundup user database) you'd use the same python-ldap module inside an
3131 extension to the cgi interface. You'd do this by overriding the method called
3132 "verifyPassword" on the LoginAction class in your tracker's interfaces.py
3133 module (see `using an external password validation source`_). The method is
3134 implemented by default as::
3136 def verifyPassword(self, userid, password):
3137 ''' Verify the password that the user has supplied
3138 '''
3139 stored = self.db.user.get(self.userid, 'password')
3140 if password == stored:
3141 return 1
3142 if not password and not stored:
3143 return 1
3144 return 0
3146 So you could reimplement this as something like::
3148 def verifyPassword(self, userid, password):
3149 ''' Verify the password that the user has supplied
3150 '''
3151 # look up some unique LDAP information about the user
3152 username = self.db.user.get(self.userid, 'username')
3153 # now verify the password supplied against the LDAP store
3156 Changes to Tracker Behaviour
3157 ----------------------------
3159 Stop "nosy" messages going to people on vacation
3160 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3162 When users go on vacation and set up vacation email bouncing, you'll
3163 start to see a lot of messages come back through Roundup "Fred is on
3164 vacation". Not very useful, and relatively easy to stop.
3166 1. add a "vacation" flag to your users::
3168 user = Class(db, "user",
3169 username=String(), password=Password(),
3170 address=String(), realname=String(),
3171 phone=String(), organisation=String(),
3172 alternate_addresses=String(),
3173 roles=String(), queries=Multilink("query"),
3174 vacation=Boolean())
3176 2. So that users may edit the vacation flags, add something like the
3177 following to your ``user.item`` template::
3179 <tr>
3180 <th>On Vacation</th>
3181 <td tal:content="structure context/vacation/field">vacation</td>
3182 </tr>
3184 3. edit your detector ``nosyreactor.py`` so that the ``nosyreaction()``
3185 consists of::
3187 def nosyreaction(db, cl, nodeid, oldvalues):
3188 users = db.user
3189 messages = db.msg
3190 # send a copy of all new messages to the nosy list
3191 for msgid in determineNewMessages(cl, nodeid, oldvalues):
3192 try:
3193 # figure the recipient ids
3194 sendto = []
3195 seen_message = {}
3196 recipients = messages.get(msgid, 'recipients')
3197 for recipid in messages.get(msgid, 'recipients'):
3198 seen_message[recipid] = 1
3200 # figure the author's id, and indicate they've received
3201 # the message
3202 authid = messages.get(msgid, 'author')
3204 # possibly send the message to the author, as long as
3205 # they aren't anonymous
3206 if (db.config.MESSAGES_TO_AUTHOR == 'yes' and
3207 users.get(authid, 'username') != 'anonymous'):
3208 sendto.append(authid)
3209 seen_message[authid] = 1
3211 # now figure the nosy people who weren't recipients
3212 nosy = cl.get(nodeid, 'nosy')
3213 for nosyid in nosy:
3214 # Don't send nosy mail to the anonymous user (that
3215 # user shouldn't appear in the nosy list, but just
3216 # in case they do...)
3217 if users.get(nosyid, 'username') == 'anonymous':
3218 continue
3219 # make sure they haven't seen the message already
3220 if not seen_message.has_key(nosyid):
3221 # send it to them
3222 sendto.append(nosyid)
3223 recipients.append(nosyid)
3225 # generate a change note
3226 if oldvalues:
3227 note = cl.generateChangeNote(nodeid, oldvalues)
3228 else:
3229 note = cl.generateCreateNote(nodeid)
3231 # we have new recipients
3232 if sendto:
3233 # filter out the people on vacation
3234 sendto = [i for i in sendto
3235 if not users.get(i, 'vacation', 0)]
3237 # map userids to addresses
3238 sendto = [users.get(i, 'address') for i in sendto]
3240 # update the message's recipients list
3241 messages.set(msgid, recipients=recipients)
3243 # send the message
3244 cl.send_message(nodeid, msgid, note, sendto)
3245 except roundupdb.MessageSendError, message:
3246 raise roundupdb.DetectorError, message
3248 Note that this is the standard nosy reaction code, with the small
3249 addition of::
3251 # filter out the people on vacation
3252 sendto = [i for i in sendto if not users.get(i, 'vacation', 0)]
3254 which filters out the users that have the vacation flag set to true.
3256 Adding in state transition control
3257 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3259 Sometimes tracker admins want to control the states that users may move
3260 issues to. You can do this by following these steps:
3262 1. make "status" a required variable. This is achieved by adding the
3263 following to the top of the form in the ``issue.item.html``
3264 template::
3266 <input type="hidden" name="@required" value="status">
3268 this will force users to select a status.
3270 2. add a Multilink property to the status class::
3272 stat = Class(db, "status", ... , transitions=Multilink('status'),
3273 ...)
3275 and then edit the statuses already created, either:
3277 a. through the web using the class list -> status class editor, or
3278 b. using the roundup-admin "set" command.
3280 3. add an auditor module ``checktransition.py`` in your tracker's
3281 ``detectors`` directory, for example::
3283 def checktransition(db, cl, nodeid, newvalues):
3284 ''' Check that the desired transition is valid for the "status"
3285 property.
3286 '''
3287 if not newvalues.has_key('status'):
3288 return
3289 current = cl.get(nodeid, 'status')
3290 new = newvalues['status']
3291 if new == current:
3292 return
3293 ok = db.status.get(current, 'transitions')
3294 if new not in ok:
3295 raise ValueError, 'Status not allowed to move from "%s" to "%s"'%(
3296 db.status.get(current, 'name'), db.status.get(new, 'name'))
3298 def init(db):
3299 db.issue.audit('set', checktransition)
3301 4. in the ``issue.item.html`` template, change the status editing bit
3302 from::
3304 <th>Status</th>
3305 <td tal:content="structure context/status/menu">status</td>
3307 to::
3309 <th>Status</th>
3310 <td>
3311 <select tal:condition="context/id" name="status">
3312 <tal:block tal:define="ok context/status/transitions"
3313 tal:repeat="state db/status/list">
3314 <option tal:condition="python:state.id in ok"
3315 tal:attributes="
3316 value state/id;
3317 selected python:state.id == context.status.id"
3318 tal:content="state/name"></option>
3319 </tal:block>
3320 </select>
3321 <tal:block tal:condition="not:context/id"
3322 tal:replace="structure context/status/menu" />
3323 </td>
3325 which displays only the allowed status to transition to.
3328 Blocking issues that depend on other issues
3329 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3331 We needed the ability to mark certain issues as "blockers" - that is,
3332 they can't be resolved until another issue (the blocker) they rely on is
3333 resolved. To achieve this:
3335 1. Create a new property on the issue Class,
3336 ``blockers=Multilink("issue")``. Edit your tracker's dbinit.py file.
3337 Where the "issue" class is defined, something like::
3339 issue = IssueClass(db, "issue",
3340 assignedto=Link("user"), topic=Multilink("keyword"),
3341 priority=Link("priority"), status=Link("status"))
3343 add the blockers entry like so::
3345 issue = IssueClass(db, "issue",
3346 blockers=Multilink("issue"),
3347 assignedto=Link("user"), topic=Multilink("keyword"),
3348 priority=Link("priority"), status=Link("status"))
3350 2. Add the new "blockers" property to the issue.item edit page, using
3351 something like::
3353 <th>Waiting On</th>
3354 <td>
3355 <span tal:replace="structure python:context.blockers.field(showid=1,
3356 size=20)" />
3357 <span tal:replace="structure python:db.issue.classhelp('id,title')" />
3358 <span tal:condition="context/blockers"
3359 tal:repeat="blk context/blockers">
3360 <br>View: <a tal:attributes="href string:issue${blk/id}"
3361 tal:content="blk/id"></a>
3362 </span>
3364 You'll need to fiddle with your item page layout to find an
3365 appropriate place to put it - I'll leave that fun part up to you.
3366 Just make sure it appears in the first table, possibly somewhere near
3367 the "superseders" field.
3369 3. Create a new detector module (attached) which enforces the rules:
3371 - issues may not be resolved if they have blockers
3372 - when a blocker is resolved, it's removed from issues it blocks
3374 The contents of the detector should be something like this::
3376 def blockresolution(db, cl, nodeid, newvalues):
3377 ''' If the issue has blockers, don't allow it to be resolved.
3378 '''
3379 if nodeid is None:
3380 blockers = []
3381 else:
3382 blockers = cl.get(nodeid, 'blockers')
3383 blockers = newvalues.get('blockers', blockers)
3385 # don't do anything if there's no blockers or the status hasn't
3386 # changed
3387 if not blockers or not newvalues.has_key('status'):
3388 return
3390 # get the resolved state ID
3391 resolved_id = db.status.lookup('resolved')
3393 # format the info
3394 u = db.config.TRACKER_WEB
3395 s = ', '.join(['<a href="%sissue%s">%s</a>'%(
3396 u,id,id) for id in blockers])
3397 if len(blockers) == 1:
3398 s = 'issue %s is'%s
3399 else:
3400 s = 'issues %s are'%s
3402 # ok, see if we're trying to resolve
3403 if newvalues['status'] == resolved_id:
3404 raise ValueError, "This issue can't be resolved until %s resolved."%s
3406 def resolveblockers(db, cl, nodeid, newvalues):
3407 ''' When we resolve an issue that's a blocker, remove it from the
3408 blockers list of the issue(s) it blocks.
3409 '''
3410 if not newvalues.has_key('status'):
3411 return
3413 # get the resolved state ID
3414 resolved_id = db.status.lookup('resolved')
3416 # interesting?
3417 if newvalues['status'] != resolved_id:
3418 return
3420 # yes - find all the blocked issues, if any, and remove me from
3421 # their blockers list
3422 issues = cl.find(blockers=nodeid)
3423 for issueid in issues:
3424 blockers = cl.get(issueid, 'blockers')
3425 if nodeid in blockers:
3426 blockers.remove(nodeid)
3427 cl.set(issueid, blockers=blockers)
3430 def init(db):
3431 # might, in an obscure situation, happen in a create
3432 db.issue.audit('create', blockresolution)
3433 db.issue.audit('set', blockresolution)
3435 # can only happen on a set
3436 db.issue.react('set', resolveblockers)
3438 Put the above code in a file called "blockers.py" in your tracker's
3439 "detectors" directory.
3441 4. Finally, and this is an optional step, modify the tracker web page
3442 URLs so they filter out issues with any blockers. You do this by
3443 adding an additional filter on "blockers" for the value "-1". For
3444 example, the existing "Show All" link in the "page" template (in the
3445 tracker's "html" directory) looks like this::
3447 <a href="issue?:sort=-activity&:group=priority&:filter=status&:columns=id,activity,title,creator,assignedto,status&status=-1,1,2,3,4,5,6,7">Show All</a><br>
3449 modify it to add the "blockers" info to the URL (note, both the
3450 ":filter" *and* "blockers" values must be specified)::
3452 <a href="issue?:sort=-activity&:group=priority&:filter=status,blockers&blockers=-1&:columns=id,activity,title,creator,assignedto,status&status=-1,1,2,3,4,5,6,7">Show All</a><br>
3454 That's it. You should now be able to set blockers on your issues. Note
3455 that if you want to know whether an issue has any other issues dependent
3456 on it (i.e. it's in their blockers list) you can look at the journal
3457 history at the bottom of the issue page - look for a "link" event to
3458 another issue's "blockers" property.
3460 Add users to the nosy list based on the topic
3461 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3463 We need the ability to automatically add users to the nosy list based
3464 on the occurence of a topic. Every user should be allowed to edit his
3465 own list of topics for which he wants to be added to the nosy list.
3467 Below will be showed that such a change can be performed with only
3468 minimal understanding of the roundup system, but with clever use
3469 of Copy and Paste.
3471 This requires three changes to the tracker: a change in the database to
3472 allow per-user recording of the lists of topics for which he wants to
3473 be put on the nosy list, a change in the user view allowing to edit
3474 this list of topics, and addition of an auditor which updates the nosy
3475 list when a topic is set.
3477 Adding the nosy topic list
3478 ::::::::::::::::::::::::::
3480 The change in the database to make is that for any user there should be
3481 a list of topics for which he wants to be put on the nosy list. Adding
3482 a ``Multilink`` of ``keyword`` seem to fullfill this (note that within
3483 the code topics are called ``keywords``.) As such, all what has to be
3484 done is to add a new field to the definition of ``user`` within the
3485 file ``dbinit.py``. We will call this new field ``nosy_keywords``, and
3486 the updated definition of user will be::
3488 user = Class(db, "user",
3489 username=String(), password=Password(),
3490 address=String(), realname=String(),
3491 phone=String(), organisation=String(),
3492 alternate_addresses=String(),
3493 queries=Multilink('query'), roles=String(),
3494 timezone=String(),
3495 nosy_keywords=Multilink('keyword'))
3497 Changing the user view to allow changing the nosy topic list
3498 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
3500 We want any user to be able to change the list of topics for which
3501 he will by default be added to the nosy list. We choose to add this
3502 to the user view, as is generated by the file ``html/user.item.html``.
3503 We easily can
3504 see that the topic field in the issue view has very similar editting
3505 requirements as our nosy topics, both being a list of topics. As
3506 such, we search for Topics in ``issue.item.html``, and extract the
3507 associated parts from there. We add this to ``user.item.html`` at the
3508 bottom of the list of viewed items (i.e. just below the 'Alternate
3509 E-mail addresses' in the classic template)::
3511 <tr>
3512 <th>Nosy Topics</th>
3513 <td>
3514 <span tal:replace="structure context/nosy_keywords/field" />
3515 <span tal:replace="structure python:db.keyword.classhelp(property='nosy_keywords')" />
3516 </td>
3517 </tr>
3520 Addition of an auditor to update the nosy list
3521 ::::::::::::::::::::::::::::::::::::::::::::::
3523 The more difficult part is the addition of the logic to actually
3524 at the users to the nosy list when it is required.
3525 The choice is made to perform this action when the topics on an
3526 item are set, including when an item is created.
3527 Here we choose to start out with a copy of the
3528 ``detectors/nosyreaction.py`` detector, which we copy to the file
3529 ``detectors/nosy_keyword_reaction.py``.
3530 This looks like a good start as it also adds users
3531 to the nosy list. A look through the code reveals that the
3532 ``nosyreaction`` function actually is sending the e-mail, which
3533 we do not need. As such, we can change the init function to::
3535 def init(db):
3536 db.issue.audit('create', update_kw_nosy)
3537 db.issue.audit('set', update_kw_nosy)
3539 After that we rename the ``updatenosy`` function to ``update_kw_nosy``.
3540 The first two blocks of code in that function relate to settings
3541 ``current`` to a combination of the old and new nosy lists. This
3542 functionality is left in the new auditor. The following block of
3543 code, which in ``updatenosy`` handled adding the assignedto user(s)
3544 to the nosy list, should be replaced by a block of code to add the
3545 interested users to the nosy list. We choose here to loop over all
3546 new topics, than loop over all users,
3547 and assign the user to the nosy list when the topic in the user's
3548 nosy_keywords. The next part in ``updatenosy``, adding the author
3549 and/or recipients of a message to the nosy list, obviously is not
3550 relevant here and thus is deleted from the new auditor. The last
3551 part, copying the new nosy list to newvalues, does not have to be changed.
3552 This brings the following function::
3554 def update_kw_nosy(db, cl, nodeid, newvalues):
3555 '''Update the nosy list for changes to the topics
3556 '''
3557 # nodeid will be None if this is a new node
3558 current = {}
3559 if nodeid is None:
3560 ok = ('new', 'yes')
3561 else:
3562 ok = ('yes',)
3563 # old node, get the current values from the node if they haven't
3564 # changed
3565 if not newvalues.has_key('nosy'):
3566 nosy = cl.get(nodeid, 'nosy')
3567 for value in nosy:
3568 if not current.has_key(value):
3569 current[value] = 1
3571 # if the nosy list changed in this transaction, init from the new value
3572 if newvalues.has_key('nosy'):
3573 nosy = newvalues.get('nosy', [])
3574 for value in nosy:
3575 if not db.hasnode('user', value):
3576 continue
3577 if not current.has_key(value):
3578 current[value] = 1
3580 # add users with topic in nosy_keywords to the nosy list
3581 if newvalues.has_key('topic') and newvalues['topic'] is not None:
3582 topic_ids = newvalues['topic']
3583 for topic in topic_ids:
3584 # loop over all users,
3585 # and assign user to nosy when topic in nosy_keywords
3586 for user_id in db.user.list():
3587 nosy_kw = db.user.get(user_id, "nosy_keywords")
3588 found = 0
3589 for kw in nosy_kw:
3590 if kw == topic:
3591 found = 1
3592 if found:
3593 current[user_id] = 1
3595 # that's it, save off the new nosy list
3596 newvalues['nosy'] = current.keys()
3598 and these two function are the only ones needed in the file.
3600 TODO: update this example to use the find() Class method.
3602 Caveats
3603 :::::::
3605 A few problems with the design here can be noted:
3607 Multiple additions
3608 When a user, after automatic selection, is manually removed
3609 from the nosy list, he again is added to the nosy list when the
3610 topic list of the issue is updated. A better design might be
3611 to only check which topics are new compared to the old list
3612 of topics, and only add users when they have indicated
3613 interest on a new topic.
3615 The code could also be changed to only trigger on the create() event,
3616 rather than also on the set() event, thus only setting the nosy list
3617 when the issue is created.
3619 Scalability
3620 In the auditor there is a loop over all users. For a site with
3621 only few users this will pose no serious problem, however, with
3622 many users this will be a serious performance bottleneck.
3623 A way out will be to link from the topics to the users which
3624 selected these topics a nosy topics. This will eliminate the
3625 loop over all users.
3627 Changes to Security and Permissions
3628 -----------------------------------
3630 Restricting the list of users that are assignable to a task
3631 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3633 1. In your tracker's "dbinit.py", create a new Role, say "Developer"::
3635 db.security.addRole(name='Developer', description='A developer')
3637 2. Just after that, create a new Permission, say "Fixer", specific to
3638 "issue"::
3640 p = db.security.addPermission(name='Fixer', klass='issue',
3641 description='User is allowed to be assigned to fix issues')
3643 3. Then assign the new Permission to your "Developer" Role::
3645 db.security.addPermissionToRole('Developer', p)
3647 4. In the issue item edit page ("html/issue.item.html" in your tracker
3648 directory), use the new Permission in restricting the "assignedto"
3649 list::
3651 <select name="assignedto">
3652 <option value="-1">- no selection -</option>
3653 <tal:block tal:repeat="user db/user/list">
3654 <option tal:condition="python:user.hasPermission(
3655 'Fixer', context._classname)"
3656 tal:attributes="
3657 value user/id;
3658 selected python:user.id == context.assignedto"
3659 tal:content="user/realname"></option>
3660 </tal:block>
3661 </select>
3663 For extra security, you may wish to setup an auditor to enforce the
3664 Permission requirement (install this as "assignedtoFixer.py" in your
3665 tracker "detectors" directory)::
3667 def assignedtoMustBeFixer(db, cl, nodeid, newvalues):
3668 ''' Ensure the assignedto value in newvalues is a used with the
3669 Fixer Permission
3670 '''
3671 if not newvalues.has_key('assignedto'):
3672 # don't care
3673 return
3675 # get the userid
3676 userid = newvalues['assignedto']
3677 if not db.security.hasPermission('Fixer', userid, cl.classname):
3678 raise ValueError, 'You do not have permission to edit %s'%cl.classname
3680 def init(db):
3681 db.issue.audit('set', assignedtoMustBeFixer)
3682 db.issue.audit('create', assignedtoMustBeFixer)
3684 So now, if an edit action attempts to set "assignedto" to a user that
3685 doesn't have the "Fixer" Permission, the error will be raised.
3687 Users may only edit their issues
3688 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3690 Users registering themselves are granted Provisional access - meaning they
3691 have access to edit the issues they submit, but not others. We create a new
3692 Role called "Provisional User" which is granted to newly-registered users,
3693 and has limited access. One of the Permissions they have is the new "Edit
3694 Own" on issues (regular users have "Edit".) We back up the permissions with
3695 an auditor.
3697 First up, we create the new Role and Permission structure in
3698 ``dbinit.py``::
3700 # New users not approved by the admin
3701 db.security.addRole(name='Provisional User',
3702 description='New user registered via web or email')
3703 p = db.security.addPermission(name='Edit Own', klass='issue',
3704 description='Can only edit own issues')
3705 db.security.addPermissionToRole('Provisional User', p)
3707 # Assign the access and edit Permissions for issue to new users now
3708 p = db.security.getPermission('View', 'issue')
3709 db.security.addPermissionToRole('Provisional User', p)
3710 p = db.security.getPermission('Edit', 'issue')
3711 db.security.addPermissionToRole('Provisional User', p)
3713 # and give the new users access to the web and email interface
3714 p = db.security.getPermission('Web Access')
3715 db.security.addPermissionToRole('Provisional User', p)
3716 p = db.security.getPermission('Email Access')
3717 db.security.addPermissionToRole('Provisional User', p)
3720 Then in the ``config.py`` we change the Role assigned to newly-registered
3721 users, replacing the existing ``'User'`` values::
3723 NEW_WEB_USER_ROLES = 'Provisional User'
3724 NEW_EMAIL_USER_ROLES = 'Provisional User'
3726 Finally we add a new *auditor* to the ``detectors`` directory called
3727 ``provisional_user_auditor.py``::
3729 def audit_provisionaluser(db, cl, nodeid, newvalues):
3730 ''' New users are only allowed to modify their own issues.
3731 '''
3732 if (db.getuid() != cl.get(nodeid, 'creator')
3733 and db.security.hasPermission('Edit Own', db.getuid(), cl.classname)):
3734 raise ValueError, ('You are only allowed to edit your own %s'
3735 % cl.classname)
3737 def init(db):
3738 # fire before changes are made
3739 db.issue.audit('set', audit_provisionaluser)
3740 db.issue.audit('retire', audit_provisionaluser)
3741 db.issue.audit('restore', audit_provisionaluser)
3743 Note that some older trackers might also want to change the ``page.html``
3744 template as follows::
3746 <p class="classblock"
3747 - tal:condition="python:request.user.username != 'anonymous'">
3748 + tal:condition="python:request.user.hasPermission('View', 'user')">
3749 <b>Administration</b><br>
3750 <tal:block tal:condition="python:request.user.hasPermission('Edit', None)">
3751 <a href="home?:template=classlist">Class List</a><br>
3753 (note that the "-" indicates a removed line, and the "+" indicates an added
3754 line).
3757 Changes to the Web User Interface
3758 ---------------------------------
3760 Adding action links to the index page
3761 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3763 Add a column to the item.index.html template.
3765 Resolving the issue::
3767 <a tal:attributes="href
3768 string:issue${i/id}?:status=resolved&:action=edit">resolve</a>
3770 "Take" the issue::
3772 <a tal:attributes="href
3773 string:issue${i/id}?:assignedto=${request/user/id}&:action=edit">take</a>
3775 ... and so on
3777 Colouring the rows in the issue index according to priority
3778 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3780 A simple ``tal:attributes`` statement will do the bulk of the work here. In
3781 the ``issue.index.html`` template, add to the ``<tr>`` that displays the
3782 actual rows of data::
3784 <tr tal:attributes="class string:priority-${i/priority/plain}">
3786 and then in your stylesheet (``style.css``) specify the colouring for the
3787 different priorities, like::
3789 tr.priority-critical td {
3790 background-color: red;
3791 }
3793 tr.priority-urgent td {
3794 background-color: orange;
3795 }
3797 and so on, with far less offensive colours :)
3799 Editing multiple items in an index view
3800 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3802 To edit the status of all items in the item index view, edit the
3803 ``issue.item.html``:
3805 1. add a form around the listing table, so at the top it reads::
3807 <form method="POST" tal:attributes="action request/classname">
3808 <table class="list">
3810 and at the bottom of that table::
3812 </table>
3813 </form
3815 making sure you match the ``</table>`` from the list table, not the
3816 navigation table or the subsequent form table.
3818 2. in the display for the issue property, change::
3820 <td tal:condition="request/show/status"
3821 tal:content="python:i.status.plain() or default"> </td>
3823 to::
3825 <td tal:condition="request/show/status"
3826 tal:content="structure i/status/field"> </td>
3828 this will result in an edit field for the status property.
3830 3. after the ``tal:block`` which lists the actual index items (marked by
3831 ``tal:repeat="i batch"``) add a new table row::
3833 <tr>
3834 <td tal:attributes="colspan python:len(request.columns)">
3835 <input type="submit" value=" Save Changes ">
3836 <input type="hidden" name="@action" value="edit">
3837 <tal:block replace="structure request/indexargs_form" />
3838 </td>
3839 </tr>
3841 which gives us a submit button, indicates that we are performing an edit
3842 on any changed statuses and the final block will make sure that the
3843 current index view parameters (filtering, columns, etc) will be used in
3844 rendering the next page (the results of the editing).
3847 Displaying only message summaries in the issue display
3848 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3850 Alter the issue.item template section for messages to::
3852 <table class="messages" tal:condition="context/messages">
3853 <tr><th colspan="5" class="header">Messages</th></tr>
3854 <tr tal:repeat="msg context/messages">
3855 <td><a tal:attributes="href string:msg${msg/id}"
3856 tal:content="string:msg${msg/id}"></a></td>
3857 <td tal:content="msg/author">author</td>
3858 <td class="date" tal:content="msg/date/pretty">date</td>
3859 <td tal:content="msg/summary">summary</td>
3860 <td>
3861 <a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">
3862 remove</a>
3863 </td>
3864 </tr>
3865 </table>
3868 Enabling display of either message summaries or the entire messages
3869 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3871 This is pretty simple - all we need to do is copy the code from the
3872 example `displaying only message summaries in the issue display`_ into
3873 our template alongside the summary display, and then introduce a switch
3874 that shows either one or the other. We'll use a new form variable,
3875 ``@whole_messages`` to achieve this::
3877 <table class="messages" tal:condition="context/messages">
3878 <tal:block tal:condition="not:request/form/@whole_messages/value | python:0">
3879 <tr><th colspan="3" class="header">Messages</th>
3880 <th colspan="2" class="header">
3881 <a href="?@whole_messages=yes">show entire messages</a>
3882 </th>
3883 </tr>
3884 <tr tal:repeat="msg context/messages">
3885 <td><a tal:attributes="href string:msg${msg/id}"
3886 tal:content="string:msg${msg/id}"></a></td>
3887 <td tal:content="msg/author">author</td>
3888 <td class="date" tal:content="msg/date/pretty">date</td>
3889 <td tal:content="msg/summary">summary</td>
3890 <td>
3891 <a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">remove</a>
3892 </td>
3893 </tr>
3894 </tal:block>
3896 <tal:block tal:condition="request/form/@whole_messages/value | python:0">
3897 <tr><th colspan="2" class="header">Messages</th>
3898 <th class="header">
3899 <a href="?@whole_messages=">show only summaries</a>
3900 </th>
3901 </tr>
3902 <tal:block tal:repeat="msg context/messages">
3903 <tr>
3904 <th tal:content="msg/author">author</th>
3905 <th class="date" tal:content="msg/date/pretty">date</th>
3906 <th style="text-align: right">
3907 (<a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">remove</a>)
3908 </th>
3909 </tr>
3910 <tr><td colspan="3" tal:content="msg/content"></td></tr>
3911 </tal:block>
3912 </tal:block>
3913 </table>
3915 Setting up a "wizard" (or "druid") for controlled adding of issues
3916 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3918 1. Set up the page templates you wish to use for data input. My wizard
3919 is going to be a two-step process: first figuring out what category
3920 of issue the user is submitting, and then getting details specific to
3921 that category. The first page includes a table of help, explaining
3922 what the category names mean, and then the core of the form::
3924 <form method="POST" onSubmit="return submit_once()"
3925 enctype="multipart/form-data">
3926 <input type="hidden" name="@template" value="add_page1">
3927 <input type="hidden" name="@action" value="page1_submit">
3929 <strong>Category:</strong>
3930 <tal:block tal:replace="structure context/category/menu" />
3931 <input type="submit" value="Continue">
3932 </form>
3934 The next page has the usual issue entry information, with the
3935 addition of the following form fragments::
3937 <form method="POST" onSubmit="return submit_once()"
3938 enctype="multipart/form-data"
3939 tal:condition="context/is_edit_ok"
3940 tal:define="cat request/form/category/value">
3942 <input type="hidden" name="@template" value="add_page2">
3943 <input type="hidden" name="@required" value="title">
3944 <input type="hidden" name="category" tal:attributes="value cat">
3945 .
3946 .
3947 .
3948 </form>
3950 Note that later in the form, I test the value of "cat" include form
3951 elements that are appropriate. For example::
3953 <tal:block tal:condition="python:cat in '6 10 13 14 15 16 17'.split()">
3954 <tr>
3955 <th>Operating System</th>
3956 <td tal:content="structure context/os/field"></td>
3957 </tr>
3958 <tr>
3959 <th>Web Browser</th>
3960 <td tal:content="structure context/browser/field"></td>
3961 </tr>
3962 </tal:block>
3964 ... the above section will only be displayed if the category is one
3965 of 6, 10, 13, 14, 15, 16 or 17.
3967 3. Determine what actions need to be taken between the pages - these are
3968 usually to validate user choices and determine what page is next. Now encode
3969 those actions in a new ``Action`` class and insert hooks to those actions in
3970 the "actions" attribute on on the ``interfaces.Client`` class, like so (see
3971 `defining new web actions`_)::
3973 class Page1SubmitAction(Action):
3974 def handle(self):
3975 ''' Verify that the user has selected a category, and then move
3976 on to page 2.
3977 '''
3978 category = self.form['category'].value
3979 if category == '-1':
3980 self.error_message.append('You must select a category of report')
3981 return
3982 # everything's ok, move on to the next page
3983 self.template = 'add_page2'
3985 actions = client.Client.actions + (
3986 ('page1_submit', Page1SubmitAction),
3987 )
3989 4. Use the usual "new" action as the ``@action`` on the final page, and
3990 you're done (the standard context/submit method can do this for you).
3994 -------------------
3996 Back to `Table of Contents`_
3998 .. _`Table of Contents`: index.html
3999 .. _`design documentation`: design.html