1 ===================
2 Customising Roundup
3 ===================
5 :Version: $Revision: 1.125 $
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 The default config.py is given below - as you
207 can see, the MAIL_DOMAIN must be edited before any interaction with the
208 tracker is attempted.::
210 # roundup home is this package's directory
211 TRACKER_HOME=os.path.split(__file__)[0]
213 # The SMTP mail host that roundup will use to send mail
214 MAILHOST = 'localhost'
216 # The domain name used for email addresses.
217 MAIL_DOMAIN = 'your.tracker.email.domain.example'
219 # This is the directory that the database is going to be stored in
220 DATABASE = os.path.join(TRACKER_HOME, 'db')
222 # This is the directory that the HTML templates reside in
223 TEMPLATES = os.path.join(TRACKER_HOME, 'html')
225 # A descriptive name for your roundup tracker
226 TRACKER_NAME = 'Roundup issue tracker'
228 # The email address that mail to roundup should go to
229 TRACKER_EMAIL = 'issue_tracker@%s'%MAIL_DOMAIN
231 # The web address that the tracker is viewable at. This will be
232 # included in information sent to users of the tracker. The URL MUST
233 # include the cgi-bin part or anything else that is required to get
234 # to the home page of the tracker. You MUST include a trailing '/'
235 # in the URL.
236 TRACKER_WEB = 'http://tracker.example/cgi-bin/roundup.cgi/bugs/'
238 # The email address that roundup will complain to if it runs into
239 # trouble
240 ADMIN_EMAIL = 'roundup-admin@%s'%MAIL_DOMAIN
242 # Additional text to include in the "name" part of the From: address
243 # used in nosy messages. If the sending user is "Foo Bar", the From:
244 # line is usually: "Foo Bar" <issue_tracker@tracker.example>
245 # the EMAIL_FROM_TAG goes inside the "Foo Bar" quotes like so:
246 # "Foo Bar EMAIL_FROM_TAG" <issue_tracker@tracker.example>
247 EMAIL_FROM_TAG = ""
249 # Send nosy messages to the author of the message
250 MESSAGES_TO_AUTHOR = 'no' # either 'yes' or 'no'
252 # Does the author of a message get placed on the nosy list
253 # automatically? If 'new' is used, then the author will only be
254 # added when a message creates a new issue. If 'yes', then the
255 # author will be added on followups too. If 'no', they're never
256 # added to the nosy.
257 ADD_AUTHOR_TO_NOSY = 'new' # one of 'yes', 'no', 'new'
259 # Do the recipients (To:, Cc:) of a message get placed on the nosy
260 # list? If 'new' is used, then the recipients will only be added
261 # when a message creates a new issue. If 'yes', then the recipients
262 # will be added on followups too. If 'no', they're never added to
263 # the nosy.
264 ADD_RECIPIENTS_TO_NOSY = 'new' # either 'yes', 'no', 'new'
266 # Where to place the email signature
267 EMAIL_SIGNATURE_POSITION = 'bottom' # one of 'top', 'bottom', 'none'
269 # Keep email citations
270 EMAIL_KEEP_QUOTED_TEXT = 'no' # either 'yes' or 'no'
272 # Preserve the email body as is
273 EMAIL_LEAVE_BODY_UNCHANGED = 'no' # either 'yes' or 'no'
275 # Default class to use in the mailgw if one isn't supplied in email
276 # subjects. To disable, comment out the variable below or leave it
277 # blank. Examples:
278 MAIL_DEFAULT_CLASS = 'issue' # use "issue" class by default
279 #MAIL_DEFAULT_CLASS = '' # disable (or just comment the var out)
281 # HTML version to generate. The templates are html4 by default. If you
282 # wish to make them xhtml, then you'll need to change this var to 'xhtml'
283 # too so all auto-generated HTML is compliant.
284 HTML_VERSION = 'html4' # either 'html4' or 'xhtml'
286 # Character set to encode email headers with. We use utf-8 by default, as
287 # it's the most flexible. Some mail readers (eg. Eudora) can't cope with
288 # that, so you might need to specify a more limited character set (eg.
289 # 'iso-8859-1'.
290 EMAIL_CHARSET = 'utf-8'
291 #EMAIL_CHARSET = 'iso-8859-1' # use this instead for Eudora users
293 #
294 # SECURITY DEFINITIONS
295 #
296 # define the Roles that a user gets when they register with the
297 # tracker these are a comma-separated string of role names (e.g.
298 # 'Admin,User')
299 NEW_WEB_USER_ROLES = 'User'
300 NEW_EMAIL_USER_ROLES = 'User'
302 Tracker Schema
303 ==============
305 Note: if you modify the schema, you'll most likely need to edit the
306 `web interface`_ HTML template files and `detectors`_ to reflect
307 your changes.
309 A tracker schema defines what data is stored in the tracker's database.
310 Schemas are defined using Python code in the ``dbinit.py`` module of your
311 tracker. The "classic" schema looks like this (see below for the meaning
312 of ``'setkey'``)::
314 pri = Class(db, "priority", name=String(), order=String())
315 pri.setkey("name")
317 stat = Class(db, "status", name=String(), order=String())
318 stat.setkey("name")
320 keyword = Class(db, "keyword", name=String())
321 keyword.setkey("name")
323 user = Class(db, "user", username=String(), organisation=String(),
324 password=String(), address=String(), realname=String(),
325 phone=String())
326 user.setkey("username")
328 msg = FileClass(db, "msg", author=Link("user"), summary=String(),
329 date=Date(), recipients=Multilink("user"),
330 files=Multilink("file"))
332 file = FileClass(db, "file", name=String(), type=String())
334 issue = IssueClass(db, "issue", topic=Multilink("keyword"),
335 status=Link("status"), assignedto=Link("user"),
336 priority=Link("priority"))
337 issue.setkey('title')
340 What you can't do to the schema
341 -------------------------------
343 You must never:
345 **Remove the users class**
346 This class is the only *required* class in Roundup. Similarly, its
347 username, password and address properties must never be removed.
349 **Change the type of a property**
350 Property types must *never* be changed - the database simply doesn't take
351 this kind of action into account. Note that you can't just remove a
352 property and re-add it as a new type either. If you wanted to make the
353 assignedto property a Multilink, you'd need to create a new property
354 assignedto_list and remove the old assignedto property.
357 What you can do to the schema
358 -----------------------------
360 Your schema may be changed at any time before or after the tracker has been
361 initialised (or used). You may:
363 **Add new properties to classes, or add whole new classes**
364 This is painless and easy to do - there are generally no repurcussions
365 from adding new information to a tracker's schema.
367 **Remove properties**
368 Removing properties is a little more tricky - you need to make sure that
369 the property is no longer used in the `web interface`_ *or* by the
370 detectors_.
374 Classes and Properties - creating a new information store
375 ---------------------------------------------------------
377 In the tracker above, we've defined 7 classes of information:
379 priority
380 Defines the possible levels of urgency for issues.
382 status
383 Defines the possible states of processing the issue may be in.
385 keyword
386 Initially empty, will hold keywords useful for searching issues.
388 user
389 Initially holding the "admin" user, will eventually have an entry
390 for all users using roundup.
392 msg
393 Initially empty, will hold all e-mail messages sent to or
394 generated by roundup.
396 file
397 Initially empty, will hold all files attached to issues.
399 issue
400 Initially empty, this is where the issue information is stored.
402 We define the "priority" and "status" classes to allow two things:
403 reduction in the amount of information stored on the issue and more
404 powerful, accurate searching of issues by priority and status. By only
405 requiring a link on the issue (which is stored as a single number) we
406 reduce the chance that someone mis-types a priority or status - or
407 simply makes a new one up.
410 Class and Items
411 ~~~~~~~~~~~~~~~
413 A Class defines a particular class (or type) of data that will be stored
414 in the database. A class comprises one or more properties, which gives
415 the information about the class items.
417 The actual data entered into the database, using ``class.create()``, are
418 called items. They have a special immutable property called ``'id'``. We
419 sometimes refer to this as the *itemid*.
422 Properties
423 ~~~~~~~~~~
425 A Class is comprised of one or more properties of the following types:
427 * String properties are for storing arbitrary-length strings.
428 * Password properties are for storing encoded arbitrary-length strings.
429 The default encoding is defined on the ``roundup.password.Password``
430 class.
431 * Date properties store date-and-time stamps. Their values are Timestamp
432 objects.
433 * Number properties store numeric values.
434 * Boolean properties store on/off, yes/no, true/false values.
435 * A Link property refers to a single other item selected from a
436 specified class. The class is part of the property; the value is an
437 integer, the id of the chosen item.
438 * A Multilink property refers to possibly many items in a specified
439 class. The value is a list of integers.
442 FileClass
443 ~~~~~~~~~
445 FileClasses save their "content" attribute off in a separate file from
446 the rest of the database. This reduces the number of large entries in
447 the database, which generally makes databases more efficient, and also
448 allows us to use command-line tools to operate on the files. They are
449 stored in the files sub-directory of the ``'db'`` directory in your
450 tracker.
453 IssueClass
454 ~~~~~~~~~~
456 IssueClasses automatically include the "messages", "files", "nosy", and
457 "superseder" properties.
459 The messages and files properties list the links to the messages and
460 files related to the issue. The nosy property is a list of links to
461 users who wish to be informed of changes to the issue - they get "CC'ed"
462 e-mails when messages are sent to or generated by the issue. The nosy
463 reactor (in the ``'detectors'`` directory) handles this action. The
464 superseder link indicates an issue which has superseded this one.
466 They also have the dynamically generated "creation", "activity" and
467 "creator" properties.
469 The value of the "creation" property is the date when an item was
470 created, and the value of the "activity" property is the date when any
471 property on the item was last edited (equivalently, these are the dates
472 on the first and last records in the item's journal). The "creator"
473 property holds a link to the user that created the issue.
476 setkey(property)
477 ~~~~~~~~~~~~~~~~
479 Select a String property of the class to be the key property. The key
480 property must be unique, and allows references to the items in the class
481 by the content of the key property. That is, we can refer to users by
482 their username: for example, let's say that there's an issue in roundup,
483 issue 23. There's also a user, richard, who happens to be user 2. To
484 assign an issue to him, we could do either of::
486 roundup-admin set issue23 assignedto=2
488 or::
490 roundup-admin set issue23 assignedto=richard
492 Note, the same thing can be done in the web and e-mail interfaces.
494 If a class does not have an "order" property, the key is also used to
495 sort instances of the class when it is rendered in the user interface.
496 (If a class has no "order" property, sorting is by the labelproperty of
497 the class. This is computed, in order of precedence, as the key, the
498 "name", the "title", or the first property alphabetically.)
501 create(information)
502 ~~~~~~~~~~~~~~~~~~~
504 Create an item in the database. This is generally used to create items
505 in the "definitional" classes like "priority" and "status".
508 Examples of adding to your schema
509 ---------------------------------
511 TODO
514 Detectors - adding behaviour to your tracker
515 ============================================
516 .. _detectors:
518 Detectors are initialised every time you open your tracker database, so
519 you're free to add and remove them any time, even after the database is
520 initialised via the "roundup-admin initialise" command.
522 The detectors in your tracker fire *before* (**auditors**) and *after*
523 (**reactors**) changes to the contents of your database. They are Python
524 modules that sit in your tracker's ``detectors`` directory. You will
525 have some installed by default - have a look. You can write new
526 detectors or modify the existing ones. The existing detectors installed
527 for you are:
529 **nosyreaction.py**
530 This provides the automatic nosy list maintenance and email sending.
531 The nosy reactor (``nosyreaction``) fires when new messages are added
532 to issues. The nosy auditor (``updatenosy``) fires when issues are
533 changed, and figures out what changes need to be made to the nosy list
534 (such as adding new authors, etc.)
535 **statusauditor.py**
536 This provides the ``chatty`` auditor which changes the issue status
537 from ``unread`` or ``closed`` to ``chatting`` if new messages appear.
538 It also provides the ``presetunread`` auditor which pre-sets the
539 status to ``unread`` on new items if the status isn't explicitly
540 defined.
541 **messagesummary.py**
542 Generates the ``summary`` property for new messages based on the message
543 content.
544 **userauditor.py**
545 Verifies the content of some of the user fields (email addresses and
546 roles lists).
548 If you don't want this default behaviour, you're completely free to change
549 or remove these detectors.
551 See the detectors section in the `design document`__ for details of the
552 interface for detectors.
554 __ design.html
556 Sample additional detectors that have been found useful will appear in
557 the ``'detectors'`` directory of the Roundup distribution. If you want
558 to use one, copy it to the ``'detectors'`` of your tracker instance:
560 **newissuecopy.py**
561 This detector sends an email to a team address whenever a new issue is
562 created. The address is hard-coded into the detector, so edit it
563 before you use it (look for the text 'team@team.host') or you'll get
564 email errors!
566 The detector code::
568 from roundup import roundupdb
570 def newissuecopy(db, cl, nodeid, oldvalues):
571 ''' Copy a message about new issues to a team address.
572 '''
573 # so use all the messages in the create
574 change_note = cl.generateCreateNote(nodeid)
576 # send a copy to the nosy list
577 for msgid in cl.get(nodeid, 'messages'):
578 try:
579 # note: last arg must be a list
580 cl.send_message(nodeid, msgid, change_note,
581 ['team@team.host'])
582 except roundupdb.MessageSendError, message:
583 raise roundupdb.DetectorError, message
585 def init(db):
586 db.issue.react('create', newissuecopy)
589 Auditor or Reactor?
590 -------------------
592 Generally speaking, the following rules should be observed:
594 **Auditors**
595 Are used for `vetoing creation of or changes to items`_. They might
596 also make automatic changes to item properties.
597 **Reactors**
598 Detect changes in the database and react accordingly. They should avoid
599 making changes to the database where possible, as this could create
600 detector loops.
603 Vetoing creation of or changes to items
604 ---------------------------------------
606 Auditors may raise the ``Reject`` exception to prevent the creation of
607 or changes to items in the database. The mail gateway, for example, will
608 not attach files or messages to issues when the creation of those files or
609 messages are prevented through the ``Reject`` exception. It'll also not create
610 users if that creation is ``Reject``'ed too.
612 To use, simply add at the top of your auditor::
614 from roundup.exceptions import Reject
616 And then when your rejection criteria have been detected, simply::
618 raise Reject
621 Generating email from Roundup
622 -----------------------------
624 The module ``roundup.mailer`` contains most of the nuts-n-bolts required
625 to generate email messages from Roundup.
627 In addition, the ``IssueClass`` methods ``nosymessage()`` and
628 ``send_message()`` are used to generate nosy messages, and may generate
629 messages which only consist of a change note (ie. the message id parameter
630 is not required).
633 Database Content
634 ================
636 Note: if you modify the content of definitional classes, you'll most
637 likely need to edit the tracker `detectors`_ to reflect your
638 changes.
640 Customisation of the special "definitional" classes (eg. status,
641 priority, resolution, ...) may be done either before or after the
642 tracker is initialised. The actual method of doing so is completely
643 different in each case though, so be careful to use the right one.
645 **Changing content before tracker initialisation**
646 Edit the dbinit module in your tracker to alter the items created in
647 using the ``create()`` methods.
649 **Changing content after tracker initialisation**
650 As the "admin" user, click on the "class list" link in the web
651 interface to bring up a list of all database classes. Click on the
652 name of the class you wish to change the content of.
654 You may also use the ``roundup-admin`` interface's create, set and
655 retire methods to add, alter or remove items from the classes in
656 question.
658 See "`adding a new field to the classic schema`_" for an example that
659 requires database content changes.
662 Security / Access Controls
663 ==========================
665 A set of Permissions is built into the security module by default:
667 - Edit (everything)
668 - View (everything)
670 Every Class you define in your tracker's schema also gets an Edit and View
671 Permission of its own.
673 The default interfaces define:
675 - Web Registration
676 - Web Access
677 - Web Roles
678 - Email Registration
679 - Email Access
681 These are hooked into the default Roles:
683 - Admin (Edit everything, View everything, Web Roles)
684 - User (Web Access, Email Access)
685 - Anonymous (Web Registration, Email Registration)
687 And finally, the "admin" user gets the "Admin" Role, and the "anonymous"
688 user gets "Anonymous" assigned when the database is initialised on
689 installation. The two default schemas then define:
691 - Edit issue, View issue (both)
692 - Edit file, View file (both)
693 - Edit msg, View msg (both)
694 - Edit support, View support (extended only)
696 and assign those Permissions to the "User" Role. Put together, these
697 settings appear in the ``open()`` function of the tracker ``dbinit.py``
698 (the following is taken from the "minimal" template's ``dbinit.py``)::
700 #
701 # SECURITY SETTINGS
702 #
703 # and give the regular users access to the web and email interface
704 p = db.security.getPermission('Web Access')
705 db.security.addPermissionToRole('User', p)
706 p = db.security.getPermission('Email Access')
707 db.security.addPermissionToRole('User', p)
709 # May users view other user information? Comment these lines out
710 # if you don't want them to
711 p = db.security.getPermission('View', 'user')
712 db.security.addPermissionToRole('User', p)
714 # Assign the appropriate permissions to the anonymous user's
715 # Anonymous role. Choices here are:
716 # - Allow anonymous users to register through the web
717 p = db.security.getPermission('Web Registration')
718 db.security.addPermissionToRole('Anonymous', p)
719 # - Allow anonymous (new) users to register through the email
720 # gateway
721 p = db.security.getPermission('Email Registration')
722 db.security.addPermissionToRole('Anonymous', p)
725 New User Roles
726 --------------
728 New users are assigned the Roles defined in the config file as:
730 - NEW_WEB_USER_ROLES
731 - NEW_EMAIL_USER_ROLES
734 Changing Access Controls
735 ------------------------
737 You may alter the configuration variables to change the Role that new
738 web or email users get, for example to not give them access to the web
739 interface if they register through email.
741 You may use the ``roundup-admin`` "``security``" command to display the
742 current Role and Permission configuration in your tracker.
745 Adding a new Permission
746 ~~~~~~~~~~~~~~~~~~~~~~~
748 When adding a new Permission, you will need to:
750 1. add it to your tracker's dbinit so it is created, using
751 ``security.addPermission``, for example::
753 self.security.addPermission(name="View", klass='frozzle',
754 description="User is allowed to access frozzles")
756 will set up a new "View" permission on the Class "frozzle".
757 2. enable it for the Roles that should have it (verify with
758 "``roundup-admin security``")
759 3. add it to the relevant HTML interface templates
760 4. add it to the appropriate xxxPermission methods on in your tracker
761 interfaces module
764 Example Scenarios
765 ~~~~~~~~~~~~~~~~~
767 **automatic registration of users in the e-mail gateway**
768 By giving the "anonymous" user the "Email Registration" Role, any
769 unidentified user will automatically be registered with the tracker
770 (with no password, so they won't be able to log in through the web
771 until an admin sets their password). Note: this is the default
772 behaviour in the tracker templates that ship with Roundup.
774 **anonymous access through the e-mail gateway**
775 Give the "anonymous" user the "Email Access" and ("Edit", "issue")
776 Roles but do not not give them the "Email Registration" Role. This
777 means that when an unknown user sends email into the tracker, they're
778 automatically logged in as "anonymous". Since they don't have the
779 "Email Registration" Role, they won't be automatically registered, but
780 since "anonymous" has permission to use the gateway, they'll still be
781 able to submit issues. Note that the Sender information - their email
782 address - will not be available - they're *anonymous*.
784 **only developers may be assigned issues**
785 Create a new Permission called "Fixer" for the "issue" class. Create a
786 new Role "Developer" which has that Permission, and assign that to the
787 appropriate users. Filter the list of users available in the assignedto
788 list to include only those users. Enforce the Permission with an
789 auditor. See the example
790 `restricting the list of users that are assignable to a task`_.
792 **only managers may sign off issues as complete**
793 Create a new Permission called "Closer" for the "issue" class. Create a
794 new Role "Manager" which has that Permission, and assign that to the
795 appropriate users. In your web interface, only display the "resolved"
796 issue state option when the user has the "Closer" Permissions. Enforce
797 the Permission with an auditor. This is very similar to the previous
798 example, except that the web interface check would look like::
800 <option tal:condition="python:request.user.hasPermission('Closer')"
801 value="resolved">Resolved</option>
803 **don't give web access to users who register through email**
804 Create a new Role called "Email User" which has all the Permissions of
805 the normal "User" Role minus the "Web Access" Permission. This will
806 allow users to send in emails to the tracker, but not access the web
807 interface.
809 **let some users edit the details of all users**
810 Create a new Role called "User Admin" which has the Permission for
811 editing users::
813 db.security.addRole(name='User Admin', description='Managing users')
814 p = db.security.getPermission('Edit', 'user')
815 db.security.addPermissionToRole('User Admin', p)
817 and assign the Role to the users who need the permission.
820 Web Interface
821 =============
823 .. contents::
824 :local:
825 :depth: 1
827 The web interface is provided by the ``roundup.cgi.client`` module and
828 is used by ``roundup.cgi``, ``roundup-server`` and ``ZRoundup``
829 (``ZRoundup`` is broken, until further notice). In all cases, we
830 determine which tracker is being accessed (the first part of the URL
831 path inside the scope of the CGI handler) and pass control on to the
832 tracker ``interfaces.Client`` class - which uses the ``Client`` class
833 from ``roundup.cgi.client`` - which handles the rest of the access
834 through its ``main()`` method. This means that you can do pretty much
835 anything you want as a web interface to your tracker.
837 Repercussions of changing the tracker schema
838 ---------------------------------------------
840 If you choose to change the `tracker schema`_ you will need to ensure
841 the web interface knows about it:
843 1. Index, item and search pages for the relevant classes may need to
844 have properties added or removed,
845 2. The "page" template may require links to be changed, as might the
846 "home" page's content arguments.
848 How requests are processed
849 --------------------------
851 The basic processing of a web request proceeds as follows:
853 1. figure out who we are, defaulting to the "anonymous" user
854 2. figure out what the request is for - we call this the "context"
855 3. handle any requested action (item edit, search, ...)
856 4. render the template requested by the context, resulting in HTML
857 output
859 In some situations, exceptions occur:
861 - HTTP Redirect (generally raised by an action)
862 - SendFile (generally raised by ``determine_context``)
863 here we serve up a FileClass "content" property
864 - SendStaticFile (generally raised by ``determine_context``)
865 here we serve up a file from the tracker "html" directory
866 - Unauthorised (generally raised by an action)
867 here the action is cancelled, the request is rendered and an error
868 message is displayed indicating that permission was not granted for
869 the action to take place
870 - NotFound (raised wherever it needs to be)
871 this exception percolates up to the CGI interface that called the
872 client
874 Determining web context
875 -----------------------
877 To determine the "context" of a request, we look at the URL and the
878 special request variable ``@template``. The URL path after the tracker
879 identifier is examined. Typical URL paths look like:
881 1. ``/tracker/issue``
882 2. ``/tracker/issue1``
883 3. ``/tracker/@file/style.css``
884 4. ``/cgi-bin/roundup.cgi/tracker/file1``
885 5. ``/cgi-bin/roundup.cgi/tracker/file1/kitten.png``
887 where the "tracker identifier" is "tracker" in the above cases. That means
888 we're looking at "issue", "issue1", "@file/style.css", "file1" and
889 "file1/kitten.png" in the cases above. The path is generally only one
890 entry long - longer paths are handled differently.
892 a. if there is no path, then we are in the "home" context.
893 b. if the path starts with "@file" (as in example 3,
894 "/tracker/@file/style.css"), then the additional path entry,
895 "style.css" specifies the filename of a static file we're to serve up
896 from the tracker "html" directory. Raises a SendStaticFile exception.
897 c. if there is something in the path (as in example 1, "issue"), it
898 identifies the tracker class we're to display.
899 d. if the path is an item designator (as in examples 2 and 4, "issue1"
900 and "file1"), then we're to display a specific item.
901 e. if the path starts with an item designator and is longer than one
902 entry (as in example 5, "file1/kitten.png"), then we're assumed to be
903 handling an item of a ``FileClass``, and the extra path information
904 gives the filename that the client is going to label the download
905 with (i.e. "file1/kitten.png" is nicer to download than "file1").
906 This raises a ``SendFile`` exception.
908 Both b. and e. stop before we bother to determine the template we're
909 going to use. That's because they don't actually use templates.
911 The template used is specified by the ``@template`` CGI variable, which
912 defaults to:
914 - only classname suplied: "index"
915 - full item designator supplied: "item"
918 Serving static content
919 ----------------------
921 See the previous section `determining web context`_ where it describes
922 ``@file`` paths.
925 Performing actions in web requests
926 ----------------------------------
928 When a user requests a web page, they may optionally also request for an
929 action to take place. As described in `how requests are processed`_, the
930 action is performed before the requested page is generated. Actions are
931 triggered by using a ``@action`` CGI variable, where the value is one
932 of:
934 **login**
935 Attempt to log a user in.
937 **logout**
938 Log the user out - make them "anonymous".
940 **register**
941 Attempt to create a new user based on the contents of the form and then
942 log them in.
944 **edit**
945 Perform an edit of an item in the database. There are some `special form
946 variables`_ you may use.
948 **new**
949 Add a new item to the database. You may use the same `special form
950 variables`_ as in the "edit" action.
952 **retire**
953 Retire the item in the database.
955 **editCSV**
956 Performs an edit of all of a class' items in one go. See also the
957 *class*.csv templating method which generates the CSV data to be
958 edited, and the ``'_generic.index'`` template which uses both of these
959 features.
961 **search**
962 Mangle some of the form variables:
964 - Set the form ":filter" variable based on the values of the filter
965 variables - if they're set to anything other than "dontcare" then add
966 them to :filter.
968 - Also handle the ":queryname" variable and save off the query to the
969 user's query list.
971 Each of the actions is implemented by a corresponding ``*XxxAction*`` (where
972 "Xxx" is the name of the action) class in the ``roundup.cgi.actions`` module.
973 These classes are registered with ``roundup.cgi.client.Client`` which also
974 happens to be available in your tracker instance as ``interfaces.Client``. So
975 if you need to define new actions, you may add them there (see `defining new
976 web actions`_).
978 Each action class also has a ``*permission*`` method which determines whether
979 the action is permissible given the current user. The base permission checks
980 are:
982 **login**
983 Determine whether the user has permission to log in. Base behaviour is
984 to check the user has "Web Access".
985 **logout**
986 No permission checks are made.
987 **register**
988 Determine whether the user has permission to register. Base behaviour
989 is to check the user has the "Web Registration" Permission.
990 **edit**
991 Determine whether the user has permission to edit this item. Base
992 behaviour is to check whether the user can edit this class. If we're
993 editing the "user" class, users are allowed to edit their own details -
994 unless they try to edit the "roles" property, which requires the
995 special Permission "Web Roles".
996 **new**
997 Determine whether the user has permission to create (or edit) this
998 item. Base behaviour is to check the user can edit this class. No
999 additional property checks are made. Additionally, new user items may
1000 be created if the user has the "Web Registration" Permission.
1001 **editCSV**
1002 Determine whether the user has permission to edit this class. Base
1003 behaviour is to check whether the user may edit this class.
1004 **search**
1005 Determine whether the user has permission to search this class. Base
1006 behaviour is to check whether the user may view this class.
1009 Special form variables
1010 ----------------------
1012 Item properties and their values are edited with html FORM
1013 variables and their values. You can:
1015 - Change the value of some property of the current item.
1016 - Create a new item of any class, and edit the new item's
1017 properties,
1018 - Attach newly created items to a multilink property of the
1019 current item.
1020 - Remove items from a multilink property of the current item.
1021 - Specify that some properties are required for the edit
1022 operation to be successful.
1024 In the following, <bracketed> values are variable, "@" may be
1025 either ":" or "@", and other text "required" is fixed.
1027 Most properties are specified as form variables:
1029 ``<propname>``
1030 property on the current context item
1032 ``<designator>"@"<propname>``
1033 property on the indicated item (for editing related information)
1035 Designators name a specific item of a class.
1037 ``<classname><N>``
1038 Name an existing item of class <classname>.
1040 ``<classname>"-"<N>``
1041 Name the <N>th new item of class <classname>. If the form
1042 submission is successful, a new item of <classname> is
1043 created. Within the submitted form, a particular
1044 designator of this form always refers to the same new
1045 item.
1047 Once we have determined the "propname", we look at it to see
1048 if it's special:
1050 ``@required``
1051 The associated form value is a comma-separated list of
1052 property names that must be specified when the form is
1053 submitted for the edit operation to succeed.
1055 When the <designator> is missing, the properties are
1056 for the current context item. When <designator> is
1057 present, they are for the item specified by
1058 <designator>.
1060 The "@required" specifier must come before any of the
1061 properties it refers to are assigned in the form.
1063 ``@remove@<propname>=id(s)`` or ``@add@<propname>=id(s)``
1064 The "@add@" and "@remove@" edit actions apply only to
1065 Multilink properties. The form value must be a
1066 comma-separate list of keys for the class specified by
1067 the simple form variable. The listed items are added
1068 to (respectively, removed from) the specified
1069 property.
1071 ``@link@<propname>=<designator>``
1072 If the edit action is "@link@", the simple form
1073 variable must specify a Link or Multilink property.
1074 The form value is a comma-separated list of
1075 designators. The item corresponding to each
1076 designator is linked to the property given by simple
1077 form variable.
1079 None of the above (ie. just a simple form value)
1080 The value of the form variable is converted
1081 appropriately, depending on the type of the property.
1083 For a Link('klass') property, the form value is a
1084 single key for 'klass', where the key field is
1085 specified in dbinit.py.
1087 For a Multilink('klass') property, the form value is a
1088 comma-separated list of keys for 'klass', where the
1089 key field is specified in dbinit.py.
1091 Note that for simple-form-variables specifiying Link
1092 and Multilink properties, the linked-to class must
1093 have a key field.
1095 For a String() property specifying a filename, the
1096 file named by the form value is uploaded. This means we
1097 try to set additional properties "filename" and "type" (if
1098 they are valid for the class). Otherwise, the property
1099 is set to the form value.
1101 For Date(), Interval(), Boolean(), and Number()
1102 properties, the form value is converted to the
1103 appropriate
1105 Any of the form variables may be prefixed with a classname or
1106 designator.
1108 Two special form values are supported for backwards compatibility:
1110 @note
1111 This is equivalent to::
1113 @link@messages=msg-1
1114 msg-1@content=value
1116 except that in addition, the "author" and "date" properties of
1117 "msg-1" are set to the userid of the submitter, and the current
1118 time, respectively.
1120 @file
1121 This is equivalent to::
1123 @link@files=file-1
1124 file-1@content=value
1126 The String content value is handled as described above for file
1127 uploads.
1129 If both the "@note" and "@file" form variables are
1130 specified, the action::
1132 @link@msg-1@files=file-1
1134 is also performed.
1136 We also check that FileClass items have a "content" property with
1137 actual content, otherwise we remove them from all_props before
1138 returning.
1142 Default templates
1143 -----------------
1145 The default templates are html4 compliant. If you wish to change them to be
1146 xhtml compliant, you'll need to change the ``HTML_VERSION`` configuration
1147 variable in ``config.py`` to ``'xhtml'`` instead of ``'html4'``.
1149 Most customisation of the web view can be done by modifying the
1150 templates in the tracker ``'html'`` directory. There are several types
1151 of files in there. The *minimal* template includes:
1153 **page.html**
1154 This template usually defines the overall look of your tracker. When
1155 you view an issue, it appears inside this template. When you view an
1156 index, it also appears inside this template. This template defines a
1157 macro called "icing" which is used by almost all other templates as a
1158 coating for their content, using its "content" slot. It also defines
1159 the "head_title" and "body_title" slots to allow setting of the page
1160 title.
1161 **home.html**
1162 the default page displayed when no other page is indicated by the user
1163 **home.classlist.html**
1164 a special version of the default page that lists the classes in the
1165 tracker
1166 **classname.item.html**
1167 displays an item of the *classname* class
1168 **classname.index.html**
1169 displays a list of *classname* items
1170 **classname.search.html**
1171 displays a search page for *classname* items
1172 **_generic.index.html**
1173 used to display a list of items where there is no
1174 ``*classname*.index`` available
1175 **_generic.help.html**
1176 used to display a "class help" page where there is no
1177 ``*classname*.help``
1178 **user.register.html**
1179 a special page just for the user class, that renders the registration
1180 page
1181 **style.css.html**
1182 a static file that is served up as-is
1184 The *classic* template has a number of additional templates.
1186 Note: Remember that you can create any template extension you want to,
1187 so if you just want to play around with the templating for new issues,
1188 you can copy the current "issue.item" template to "issue.test", and then
1189 access the test template using the "@template" URL argument::
1191 http://your.tracker.example/tracker/issue?@template=test
1193 and it won't affect your users using the "issue.item" template.
1196 How the templates work
1197 ----------------------
1200 Basic Templating Actions
1201 ~~~~~~~~~~~~~~~~~~~~~~~~
1203 Roundup's templates consist of special attributes on the HTML tags.
1204 These attributes form the Template Attribute Language, or TAL. The basic
1205 TAL commands are:
1207 **tal:define="variable expression; variable expression; ..."**
1208 Define a new variable that is local to this tag and its contents. For
1209 example::
1211 <html tal:define="title request/description">
1212 <head><title tal:content="title"></title></head>
1213 </html>
1215 In this example, the variable "title" is defined as the result of the
1216 expression "request/description". The "tal:content" command inside the
1217 <html> tag may then use the "title" variable.
1219 **tal:condition="expression"**
1220 Only keep this tag and its contents if the expression is true. For
1221 example::
1223 <p tal:condition="python:request.user.hasPermission('View', 'issue')">
1224 Display some issue information.
1225 </p>
1227 In the example, the <p> tag and its contents are only displayed if
1228 the user has the "View" permission for issues. We consider the number
1229 zero, a blank string, an empty list, and the built-in variable
1230 nothing to be false values. Nearly every other value is true,
1231 including non-zero numbers, and strings with anything in them (even
1232 spaces!).
1234 **tal:repeat="variable expression"**
1235 Repeat this tag and its contents for each element of the sequence
1236 that the expression returns, defining a new local variable and a
1237 special "repeat" variable for each element. For example::
1239 <tr tal:repeat="u user/list">
1240 <td tal:content="u/id"></td>
1241 <td tal:content="u/username"></td>
1242 <td tal:content="u/realname"></td>
1243 </tr>
1245 The example would iterate over the sequence of users returned by
1246 "user/list" and define the local variable "u" for each entry.
1248 **tal:replace="expression"**
1249 Replace this tag with the result of the expression. For example::
1251 <span tal:replace="request/user/realname" />
1253 The example would replace the <span> tag and its contents with the
1254 user's realname. If the user's realname was "Bruce", then the
1255 resultant output would be "Bruce".
1257 **tal:content="expression"**
1258 Replace the contents of this tag with the result of the expression.
1259 For example::
1261 <span tal:content="request/user/realname">user's name appears here
1262 </span>
1264 The example would replace the contents of the <span> tag with the
1265 user's realname. If the user's realname was "Bruce" then the
1266 resultant output would be "<span>Bruce</span>".
1268 **tal:attributes="attribute expression; attribute expression; ..."**
1269 Set attributes on this tag to the results of expressions. For
1270 example::
1272 <a tal:attributes="href string:user${request/user/id}">My Details</a>
1274 In the example, the "href" attribute of the <a> tag is set to the
1275 value of the "string:user${request/user/id}" expression, which will
1276 be something like "user123".
1278 **tal:omit-tag="expression"**
1279 Remove this tag (but not its contents) if the expression is true. For
1280 example::
1282 <span tal:omit-tag="python:1">Hello, world!</span>
1284 would result in output of::
1286 Hello, world!
1288 Note that the commands on a given tag are evaulated in the order above,
1289 so *define* comes before *condition*, and so on.
1291 Additionally, you may include tags such as <tal:block>, which are
1292 removed from output. Its content is kept, but the tag itself is not (so
1293 don't go using any "tal:attributes" commands on it). This is useful for
1294 making arbitrary blocks of HTML conditional or repeatable (very handy
1295 for repeating multiple table rows, which would othewise require an
1296 illegal tag placement to effect the repeat).
1299 Templating Expressions
1300 ~~~~~~~~~~~~~~~~~~~~~~
1302 The expressions you may use in the attribute values may be one of the
1303 following forms:
1305 **Path Expressions** - eg. ``item/status/checklist``
1306 These are object attribute / item accesses. Roughly speaking, the
1307 path ``item/status/checklist`` is broken into parts ``item``,
1308 ``status`` and ``checklist``. The ``item`` part is the root of the
1309 expression. We then look for a ``status`` attribute on ``item``, or
1310 failing that, a ``status`` item (as in ``item['status']``). If that
1311 fails, the path expression fails. When we get to the end, the object
1312 we're left with is evaluated to get a string - if it is a method, it
1313 is called; if it is an object, it is stringified. Path expressions
1314 may have an optional ``path:`` prefix, but they are the default
1315 expression type, so it's not necessary.
1317 If an expression evaluates to ``default``, then the expression is
1318 "cancelled" - whatever HTML already exists in the template will
1319 remain (tag content in the case of ``tal:content``, attributes in the
1320 case of ``tal:attributes``).
1322 If an expression evaluates to ``nothing`` then the target of the
1323 expression is removed (tag content in the case of ``tal:content``,
1324 attributes in the case of ``tal:attributes`` and the tag itself in
1325 the case of ``tal:replace``).
1327 If an element in the path may not exist, then you can use the ``|``
1328 operator in the expression to provide an alternative. So, the
1329 expression ``request/form/foo/value | default`` would simply leave
1330 the current HTML in place if the "foo" form variable doesn't exist.
1332 You may use the python function ``path``, as in
1333 ``path("item/status")``, to embed path expressions in Python
1334 expressions.
1336 **String Expressions** - eg. ``string:hello ${user/name}``
1337 These expressions are simple string interpolations - though they can
1338 be just plain strings with no interpolation if you want. The
1339 expression in the ``${ ... }`` is just a path expression as above.
1341 **Python Expressions** - eg. ``python: 1+1``
1342 These expressions give the full power of Python. All the "root level"
1343 variables are available, so ``python:item.status.checklist()`` would
1344 be equivalent to ``item/status/checklist``, assuming that
1345 ``checklist`` is a method.
1347 Modifiers:
1349 **structure** - eg. ``structure python:msg.content.plain(hyperlink=1)``
1350 The result of expressions are normally *escaped* to be safe for HTML
1351 display (all "<", ">" and "&" are turned into special entities). The
1352 ``structure`` expression modifier turns off this escaping - the
1353 result of the expression is now assumed to be HTML, which is passed
1354 to the web browser for rendering.
1356 **not:** - eg. ``not:python:1=1``
1357 This simply inverts the logical true/false value of another
1358 expression.
1361 Template Macros
1362 ~~~~~~~~~~~~~~~
1364 Macros are used in Roundup to save us from repeating the same common
1365 page stuctures over and over. The most common (and probably only) macro
1366 you'll use is the "icing" macro defined in the "page" template.
1368 Macros are generated and used inside your templates using special
1369 attributes similar to the `basic templating actions`_. In this case,
1370 though, the attributes belong to the Macro Expansion Template Attribute
1371 Language, or METAL. The macro commands are:
1373 **metal:define-macro="macro name"**
1374 Define that the tag and its contents are now a macro that may be
1375 inserted into other templates using the *use-macro* command. For
1376 example::
1378 <html metal:define-macro="page">
1379 ...
1380 </html>
1382 defines a macro called "page" using the ``<html>`` tag and its
1383 contents. Once defined, macros are stored on the template they're
1384 defined on in the ``macros`` attribute. You can access them later on
1385 through the ``templates`` variable, eg. the most common
1386 ``templates/page/macros/icing`` to access the "page" macro of the
1387 "page" template.
1389 **metal:use-macro="path expression"**
1390 Use a macro, which is identified by the path expression (see above).
1391 This will replace the current tag with the identified macro contents.
1392 For example::
1394 <tal:block metal:use-macro="templates/page/macros/icing">
1395 ...
1396 </tal:block>
1398 will replace the tag and its contents with the "page" macro of the
1399 "page" template.
1401 **metal:define-slot="slot name"** and **metal:fill-slot="slot name"**
1402 To define *dynamic* parts of the macro, you define "slots" which may
1403 be filled when the macro is used with a *use-macro* command. For
1404 example, the ``templates/page/macros/icing`` macro defines a slot like
1405 so::
1407 <title metal:define-slot="head_title">title goes here</title>
1409 In your *use-macro* command, you may now use a *fill-slot* command
1410 like this::
1412 <title metal:fill-slot="head_title">My Title</title>
1414 where the tag that fills the slot completely replaces the one defined
1415 as the slot in the macro.
1417 Note that you may not mix METAL and TAL commands on the same tag, but
1418 TAL commands may be used freely inside METAL-using tags (so your
1419 *fill-slots* tags may have all manner of TAL inside them).
1422 Information available to templates
1423 ----------------------------------
1425 Note: this is implemented by
1426 ``roundup.cgi.templating.RoundupPageTemplate``
1428 The following variables are available to templates.
1430 **context**
1431 The current context. This is either None, a `hyperdb class wrapper`_
1432 or a `hyperdb item wrapper`_
1433 **request**
1434 Includes information about the current request, including:
1435 - the current index information (``filterspec``, ``filter`` args,
1436 ``properties``, etc) parsed out of the form.
1437 - methods for easy filterspec link generation
1438 - *user*, the current user item as an HTMLItem instance
1439 - *form*
1440 The current CGI form information as a mapping of form argument name
1441 to value
1442 **config**
1443 This variable holds all the values defined in the tracker config.py
1444 file (eg. TRACKER_NAME, etc.)
1445 **db**
1446 The current database, used to access arbitrary database items.
1447 **templates**
1448 Access to all the tracker templates by name. Used mainly in
1449 *use-macro* commands.
1450 **utils**
1451 This variable makes available some utility functions like batching.
1452 **nothing**
1453 This is a special variable - if an expression evaluates to this, then
1454 the tag (in the case of a ``tal:replace``), its contents (in the case
1455 of ``tal:content``) or some attributes (in the case of
1456 ``tal:attributes``) will not appear in the the output. So, for
1457 example::
1459 <span tal:attributes="class nothing">Hello, World!</span>
1461 would result in::
1463 <span>Hello, World!</span>
1465 **default**
1466 Also a special variable - if an expression evaluates to this, then the
1467 existing HTML in the template will not be replaced or removed, it will
1468 remain. So::
1470 <span tal:replace="default">Hello, World!</span>
1472 would result in::
1474 <span>Hello, World!</span>
1477 The context variable
1478 ~~~~~~~~~~~~~~~~~~~~
1480 The *context* variable is one of three things based on the current
1481 context (see `determining web context`_ for how we figure this out):
1483 1. if we're looking at a "home" page, then it's None
1484 2. if we're looking at a specific hyperdb class, it's a
1485 `hyperdb class wrapper`_.
1486 3. if we're looking at a specific hyperdb item, it's a
1487 `hyperdb item wrapper`_.
1489 If the context is not None, we can access the properties of the class or
1490 item. The only real difference between cases 2 and 3 above are:
1492 1. the properties may have a real value behind them, and this will
1493 appear if the property is displayed through ``context/property`` or
1494 ``context/property/field``.
1495 2. the context's "id" property will be a false value in the second case,
1496 but a real, or true value in the third. Thus we can determine whether
1497 we're looking at a real item from the hyperdb by testing
1498 "context/id".
1500 Hyperdb class wrapper
1501 :::::::::::::::::::::
1503 Note: this is implemented by the ``roundup.cgi.templating.HTMLClass``
1504 class.
1506 This wrapper object provides access to a hyperb class. It is used
1507 primarily in both index view and new item views, but it's also usable
1508 anywhere else that you wish to access information about a class, or the
1509 items of a class, when you don't have a specific item of that class in
1510 mind.
1512 We allow access to properties. There will be no "id" property. The value
1513 accessed through the property will be the current value of the same name
1514 from the CGI form.
1516 There are several methods available on these wrapper objects:
1518 =========== =============================================================
1519 Method Description
1520 =========== =============================================================
1521 properties return a `hyperdb property wrapper`_ for all of this class's
1522 properties.
1523 list lists all of the active (not retired) items in the class.
1524 csv return the items of this class as a chunk of CSV text.
1525 propnames lists the names of the properties of this class.
1526 filter lists of items from this class, filtered and sorted by the
1527 current *request* filterspec/filter/sort/group args
1528 classhelp display a link to a javascript popup containing this class'
1529 "help" template.
1530 submit generate a submit button (and action hidden element)
1531 renderWith render this class with the given template.
1532 history returns 'New node - no history' :)
1533 is_edit_ok is the user allowed to Edit the current class?
1534 is_view_ok is the user allowed to View the current class?
1535 =========== =============================================================
1537 Note that if you have a property of the same name as one of the above
1538 methods, you'll need to access it using a python "item access"
1539 expression. For example::
1541 python:context['list']
1543 will access the "list" property, rather than the list method.
1546 Hyperdb item wrapper
1547 ::::::::::::::::::::
1549 Note: this is implemented by the ``roundup.cgi.templating.HTMLItem``
1550 class.
1552 This wrapper object provides access to a hyperb item.
1554 We allow access to properties. There will be no "id" property. The value
1555 accessed through the property will be the current value of the same name
1556 from the CGI form.
1558 There are several methods available on these wrapper objects:
1560 =============== ========================================================
1561 Method Description
1562 =============== ========================================================
1563 submit generate a submit button (and action hidden element)
1564 journal return the journal of the current item (**not
1565 implemented**)
1566 history render the journal of the current item as HTML
1567 renderQueryForm specific to the "query" class - render the search form
1568 for the query
1569 hasPermission specific to the "user" class - determine whether the
1570 user has a Permission
1571 is_edit_ok is the user allowed to Edit the current item?
1572 is_view_ok is the user allowed to View the current item?
1573 =============== ========================================================
1575 Note that if you have a property of the same name as one of the above
1576 methods, you'll need to access it using a python "item access"
1577 expression. For example::
1579 python:context['journal']
1581 will access the "journal" property, rather than the journal method.
1584 Hyperdb property wrapper
1585 ::::::::::::::::::::::::
1587 Note: this is implemented by subclasses of the
1588 ``roundup.cgi.templating.HTMLProperty`` class (``HTMLStringProperty``,
1589 ``HTMLNumberProperty``, and so on).
1591 This wrapper object provides access to a single property of a class. Its
1592 value may be either:
1594 1. if accessed through a `hyperdb item wrapper`_, then it's a value from
1595 the hyperdb
1596 2. if access through a `hyperdb class wrapper`_, then it's a value from
1597 the CGI form
1600 The property wrapper has some useful attributes:
1602 =============== ========================================================
1603 Attribute Description
1604 =============== ========================================================
1605 _name the name of the property
1606 _value the value of the property if any - this is the actual
1607 value retrieved from the hyperdb for this property
1608 =============== ========================================================
1610 There are several methods available on these wrapper objects:
1612 =========== ================================================================
1613 Method Description
1614 =========== ================================================================
1615 plain render a "plain" representation of the property. This method
1616 may take two arguments:
1618 escape
1619 If true, escape the text so it is HTML safe (default: no). The
1620 reason this defaults to off is that text is usually escaped
1621 at a later stage by the TAL commands, unless the "structure"
1622 option is used in the template. The following ``tal:content``
1623 expressions are all equivalent::
1625 "structure python:msg.content.plain(escape=1)"
1626 "python:msg.content.plain()"
1627 "msg/content/plain"
1628 "msg/content"
1630 Usually you'll only want to use the escape option in a
1631 complex expression.
1633 hyperlink
1634 If true, turn URLs, email addresses and hyperdb item
1635 designators in the text into hyperlinks (default: no). Note
1636 that you'll need to use the "structure" TAL option if you
1637 want to use this ``tal:content`` expression::
1639 "structure python:msg.content.plain(hyperlink=1)"
1641 Note also that the text is automatically HTML-escaped before
1642 the hyperlinking transformation.
1643 hyperlinked The same as msg.content.plain(hyperlink=1), but nicer::
1645 "structure msg/content/hyperlinked"
1647 field render an appropriate form edit field for the property - for
1648 most types this is a text entry box, but for Booleans it's a
1649 tri-state yes/no/neither selection.
1650 stext only on String properties - render the value of the property
1651 as StructuredText (requires the StructureText module to be
1652 installed separately)
1653 multiline only on String properties - render a multiline form edit
1654 field for the property
1655 email only on String properties - render the value of the property
1656 as an obscured email address
1657 confirm only on Password properties - render a second form edit field
1658 for the property, used for confirmation that the user typed
1659 the password correctly. Generates a field with name
1660 "name:confirm".
1661 now only on Date properties - return the current date as a new
1662 property
1663 reldate only on Date properties - render the interval between the date
1664 and now
1665 local only on Date properties - return this date as a new property
1666 with some timezone offset, for example::
1668 python:context.creation.local(10)
1670 will render the date with a +10 hour offset.
1671 pretty Date properties - render the date as "dd Mon YYYY" (eg. "19
1672 Mar 2004"). Takes an optional format argument, for example::
1674 python:context.activity.pretty('%Y-%m-%d')
1676 Will format as "2004-03-19" instead.
1678 Interval properties - render the interval in a pretty
1679 format (eg. "yesterday")
1680 menu only on Link and Multilink properties - render a form select
1681 list for this property
1682 reverse only on Multilink properties - produce a list of the linked
1683 items in reverse order
1684 =========== ================================================================
1686 All of the above functions perform checks for permissions required to
1687 display or edit the data they are manipulating. The simplest case is
1688 editing an issue title. Including the expression::
1690 context/title/field
1692 Will present the user with an edit field, if they have edit permission. If
1693 not, then they will be presented with a static display if they have view
1694 permission. If they don't even have view permission, then an error message
1695 is raised, preventing the display of the page, indicating that they don't
1696 have permission to view the information.
1699 The request variable
1700 ~~~~~~~~~~~~~~~~~~~~
1702 Note: this is implemented by the ``roundup.cgi.templating.HTMLRequest``
1703 class.
1705 The request variable is packed with information about the current
1706 request.
1708 .. taken from ``roundup.cgi.templating.HTMLRequest`` docstring
1710 =========== ============================================================
1711 Variable Holds
1712 =========== ============================================================
1713 form the CGI form as a cgi.FieldStorage
1714 env the CGI environment variables
1715 base the base URL for this tracker
1716 user a HTMLUser instance for this user
1717 classname the current classname (possibly None)
1718 template the current template (suffix, also possibly None)
1719 form the current CGI form variables in a FieldStorage
1720 =========== ============================================================
1722 **Index page specific variables (indexing arguments)**
1724 =========== ============================================================
1725 Variable Holds
1726 =========== ============================================================
1727 columns dictionary of the columns to display in an index page
1728 show a convenience access to columns - request/show/colname will
1729 be true if the columns should be displayed, false otherwise
1730 sort index sort column (direction, column name)
1731 group index grouping property (direction, column name)
1732 filter properties to filter the index on
1733 filterspec values to filter the index on
1734 search_text text to perform a full-text search on for an index
1735 =========== ============================================================
1737 There are several methods available on the request variable:
1739 =============== ========================================================
1740 Method Description
1741 =============== ========================================================
1742 description render a description of the request - handle for the
1743 page title
1744 indexargs_form render the current index args as form elements
1745 indexargs_url render the current index args as a URL
1746 base_javascript render some javascript that is used by other components
1747 of the templating
1748 batch run the current index args through a filter and return a
1749 list of items (see `hyperdb item wrapper`_, and
1750 `batching`_)
1751 =============== ========================================================
1753 The form variable
1754 :::::::::::::::::
1756 The form variable is a bit special because it's actually a python
1757 FieldStorage object. That means that you have two ways to access its
1758 contents. For example, to look up the CGI form value for the variable
1759 "name", use the path expression::
1761 request/form/name/value
1763 or the python expression::
1765 python:request.form['name'].value
1767 Note the "item" access used in the python case, and also note the
1768 explicit "value" attribute we have to access. That's because the form
1769 variables are stored as MiniFieldStorages. If there's more than one
1770 "name" value in the form, then the above will break since
1771 ``request/form/name`` is actually a *list* of MiniFieldStorages. So it's
1772 best to know beforehand what you're dealing with.
1775 The db variable
1776 ~~~~~~~~~~~~~~~
1778 Note: this is implemented by the ``roundup.cgi.templating.HTMLDatabase``
1779 class.
1781 Allows access to all hyperdb classes as attributes of this variable. If
1782 you want access to the "user" class, for example, you would use::
1784 db/user
1785 python:db.user
1787 Also, the current id of the current user is available as
1788 ``db.getuid()``. This isn't so useful in templates (where you have
1789 ``request/user``), but it can be useful in detectors or interfaces.
1791 The access results in a `hyperdb class wrapper`_.
1794 The templates variable
1795 ~~~~~~~~~~~~~~~~~~~~~~
1797 Note: this is implemented by the ``roundup.cgi.templating.Templates``
1798 class.
1800 This variable doesn't have any useful methods defined. It supports being
1801 used in expressions to access the templates, and consequently the
1802 template macros. You may access the templates using the following path
1803 expression::
1805 templates/name
1807 or the python expression::
1809 templates[name]
1811 where "name" is the name of the template you wish to access. The
1812 template has one useful attribute, namely "macros". To access a specific
1813 macro (called "macro_name"), use the path expression::
1815 templates/name/macros/macro_name
1817 or the python expression::
1819 templates[name].macros[macro_name]
1822 The utils variable
1823 ~~~~~~~~~~~~~~~~~~
1825 Note: this is implemented by the
1826 ``roundup.cgi.templating.TemplatingUtils`` class, but it may be extended
1827 as described below.
1829 =============== ========================================================
1830 Method Description
1831 =============== ========================================================
1832 Batch return a batch object using the supplied list
1833 =============== ========================================================
1835 You may add additional utility methods by writing them in your tracker
1836 ``interfaces.py`` module's ``TemplatingUtils`` class. See `adding a time
1837 log to your issues`_ for an example. The TemplatingUtils class itself
1838 will have a single attribute, ``client``, which may be used to access
1839 the ``client.db`` when you need to perform arbitrary database queries.
1841 Batching
1842 ::::::::
1844 Use Batch to turn a list of items, or item ids of a given class, into a
1845 series of batches. Its usage is::
1847 python:utils.Batch(sequence, size, start, end=0, orphan=0,
1848 overlap=0)
1850 or, to get the current index batch::
1852 request/batch
1854 The parameters are:
1856 ========= ==============================================================
1857 Parameter Usage
1858 ========= ==============================================================
1859 sequence a list of HTMLItems
1860 size how big to make the sequence.
1861 start where to start (0-indexed) in the sequence.
1862 end where to end (0-indexed) in the sequence.
1863 orphan if the next batch would contain less items than this value,
1864 then it is combined with this batch
1865 overlap the number of items shared between adjacent batches
1866 ========= ==============================================================
1868 All of the parameters are assigned as attributes on the batch object. In
1869 addition, it has several more attributes:
1871 =============== ========================================================
1872 Attribute Description
1873 =============== ========================================================
1874 start indicates the start index of the batch. *Note: unlike
1875 the argument, is a 1-based index (I know, lame)*
1876 first indicates the start index of the batch *as a 0-based
1877 index*
1878 length the actual number of elements in the batch
1879 sequence_length the length of the original, unbatched, sequence.
1880 =============== ========================================================
1882 And several methods:
1884 =============== ========================================================
1885 Method Description
1886 =============== ========================================================
1887 previous returns a new Batch with the previous batch settings
1888 next returns a new Batch with the next batch settings
1889 propchanged detect if the named property changed on the current item
1890 when compared to the last item
1891 =============== ========================================================
1893 An example of batching::
1895 <table class="otherinfo">
1896 <tr><th colspan="4" class="header">Existing Keywords</th></tr>
1897 <tr tal:define="keywords db/keyword/list"
1898 tal:repeat="start python:range(0, len(keywords), 4)">
1899 <td tal:define="batch python:utils.Batch(keywords, 4, start)"
1900 tal:repeat="keyword batch" tal:content="keyword/name">
1901 keyword here</td>
1902 </tr>
1903 </table>
1905 ... which will produce a table with four columns containing the items of
1906 the "keyword" class (well, their "name" anyway).
1908 Displaying Properties
1909 ---------------------
1911 Properties appear in the user interface in three contexts: in indices,
1912 in editors, and as search arguments. For each type of property, there
1913 are several display possibilities. For example, in an index view, a
1914 string property may just be printed as a plain string, but in an editor
1915 view, that property may be displayed in an editable field.
1918 Index Views
1919 -----------
1921 This is one of the class context views. It is also the default view for
1922 classes. The template used is "*classname*.index".
1925 Index View Specifiers
1926 ~~~~~~~~~~~~~~~~~~~~~
1928 An index view specifier (URL fragment) looks like this (whitespace has
1929 been added for clarity)::
1931 /issue?status=unread,in-progress,resolved&
1932 topic=security,ui&
1933 :group=+priority&
1934 :sort==activity&
1935 :filters=status,topic&
1936 :columns=title,status,fixer
1938 The index view is determined by two parts of the specifier: the layout
1939 part and the filter part. The layout part consists of the query
1940 parameters that begin with colons, and it determines the way that the
1941 properties of selected items are displayed. The filter part consists of
1942 all the other query parameters, and it determines the criteria by which
1943 items are selected for display. The filter part is interactively
1944 manipulated with the form widgets displayed in the filter section. The
1945 layout part is interactively manipulated by clicking on the column
1946 headings in the table.
1948 The filter part selects the union of the sets of items with values
1949 matching any specified Link properties and the intersection of the sets
1950 of items with values matching any specified Multilink properties.
1952 The example specifies an index of "issue" items. Only items with a
1953 "status" of either "unread" or "in-progress" or "resolved" are
1954 displayed, and only items with "topic" values including both "security"
1955 and "ui" are displayed. The items are grouped by priority, arranged in
1956 ascending order; and within groups, sorted by activity, arranged in
1957 descending order. The filter section shows filters for the "status" and
1958 "topic" properties, and the table includes columns for the "title",
1959 "status", and "fixer" properties.
1961 Searching Views
1962 ---------------
1964 Note: if you add a new column to the ``:columns`` form variable
1965 potentials then you will need to add the column to the appropriate
1966 `index views`_ template so that it is actually displayed.
1968 This is one of the class context views. The template used is typically
1969 "*classname*.search". The form on this page should have "search" as its
1970 ``@action`` variable. The "search" action:
1972 - sets up additional filtering, as well as performing indexed text
1973 searching
1974 - sets the ``:filter`` variable correctly
1975 - saves the query off if ``:query_name`` is set.
1977 The search page should lay out any fields that you wish to allow the
1978 user to search on. If your schema contains a large number of properties,
1979 you should be wary of making all of those properties available for
1980 searching, as this can cause confusion. If the additional properties are
1981 Strings, consider having their value indexed, and then they will be
1982 searchable using the full text indexed search. This is both faster, and
1983 more useful for the end user.
1985 The two special form values on search pages which are handled by the
1986 "search" action are:
1988 :search_text
1989 Text with which to perform a search of the text index. Results from
1990 that search will be used to limit the results of other filters (using
1991 an intersection operation)
1992 :query_name
1993 If supplied, the search parameters (including :search_text) will be
1994 saved off as a the query item and registered against the user's
1995 queries property. Note that the *classic* template schema has this
1996 ability, but the *minimal* template schema does not.
1999 Item Views
2000 ----------
2002 The basic view of a hyperdb item is provided by the "*classname*.item"
2003 template. It generally has three sections; an "editor", a "spool" and a
2004 "history" section.
2007 Editor Section
2008 ~~~~~~~~~~~~~~
2010 The editor section is used to manipulate the item - it may be a static
2011 display if the user doesn't have permission to edit the item.
2013 Here's an example of a basic editor template (this is the default
2014 "classic" template issue item edit form - from the "issue.item.html"
2015 template)::
2017 <table class="form">
2018 <tr>
2019 <th>Title</th>
2020 <td colspan="3" tal:content="structure python:context.title.field(size=60)">title</td>
2021 </tr>
2023 <tr>
2024 <th>Priority</th>
2025 <td tal:content="structure context/priority/menu">priority</td>
2026 <th>Status</th>
2027 <td tal:content="structure context/status/menu">status</td>
2028 </tr>
2030 <tr>
2031 <th>Superseder</th>
2032 <td>
2033 <span tal:replace="structure python:context.superseder.field(showid=1, size=20)" />
2034 <span tal:replace="structure python:db.issue.classhelp('id,title')" />
2035 <span tal:condition="context/superseder">
2036 <br>View: <span tal:replace="structure python:context.superseder.link(showid=1)" />
2037 </span>
2038 </td>
2039 <th>Nosy List</th>
2040 <td>
2041 <span tal:replace="structure context/nosy/field" />
2042 <span tal:replace="structure python:db.user.classhelp('username,realname,address,phone')" />
2043 </td>
2044 </tr>
2046 <tr>
2047 <th>Assigned To</th>
2048 <td tal:content="structure context/assignedto/menu">
2049 assignedto menu
2050 </td>
2051 <td> </td>
2052 <td> </td>
2053 </tr>
2055 <tr>
2056 <th>Change Note</th>
2057 <td colspan="3">
2058 <textarea name=":note" wrap="hard" rows="5" cols="60"></textarea>
2059 </td>
2060 </tr>
2062 <tr>
2063 <th>File</th>
2064 <td colspan="3"><input type="file" name=":file" size="40"></td>
2065 </tr>
2067 <tr>
2068 <td> </td>
2069 <td colspan="3" tal:content="structure context/submit">
2070 submit button will go here
2071 </td>
2072 </tr>
2073 </table>
2076 When a change is submitted, the system automatically generates a message
2077 describing the changed properties. As shown in the example, the editor
2078 template can use the ":note" and ":file" fields, which are added to the
2079 standard changenote message generated by Roundup.
2082 Form values
2083 :::::::::::
2085 We have a number of ways to pull properties out of the form in order to
2086 meet the various needs of:
2088 1. editing the current item (perhaps an issue item)
2089 2. editing information related to the current item (eg. messages or
2090 attached files)
2091 3. creating new information to be linked to the current item (eg. time
2092 spent on an issue)
2094 In the following, ``<bracketed>`` values are variable, ":" may be one of
2095 ":" or "@", and other text ("required") is fixed.
2097 Properties are specified as form variables:
2099 ``<propname>``
2100 property on the current context item
2102 ``<designator>:<propname>``
2103 property on the indicated item (for editing related information)
2105 ``<classname>-<N>:<propname>``
2106 property on the Nth new item of classname (generally for creating new
2107 items to attach to the current item)
2109 Once we have determined the "propname", we check to see if it is one of
2110 the special form values:
2112 ``@required``
2113 The named property values must be supplied or a ValueError will be
2114 raised.
2116 ``@remove@<propname>=id(s)``
2117 The ids will be removed from the multilink property.
2119 ``:add:<propname>=id(s)``
2120 The ids will be added to the multilink property.
2122 ``:link:<propname>=<designator>``
2123 Used to add a link to new items created during edit. These are
2124 collected and returned in ``all_links``. This will result in an
2125 additional linking operation (either Link set or Multilink append)
2126 after the edit/create is done using ``all_props`` in ``_editnodes``.
2127 The <propname> on the current item will be set/appended the id of the
2128 newly created item of class <designator> (where <designator> must be
2129 <classname>-<N>).
2131 Any of the form variables may be prefixed with a classname or
2132 designator.
2134 Two special form values are supported for backwards compatibility:
2136 ``:note``
2137 create a message (with content, author and date), linked to the
2138 context item. This is ALWAYS designated "msg-1".
2139 ``:file``
2140 create a file, attached to the current item and any message created by
2141 :note. This is ALWAYS designated "file-1".
2144 Spool Section
2145 ~~~~~~~~~~~~~
2147 The spool section lists related information like the messages and files
2148 of an issue.
2150 TODO
2153 History Section
2154 ~~~~~~~~~~~~~~~
2156 The final section displayed is the history of the item - its database
2157 journal. This is generally generated with the template::
2159 <tal:block tal:replace="structure context/history" />
2161 *To be done:*
2163 *The actual history entries of the item may be accessed for manual
2164 templating through the "journal" method of the item*::
2166 <tal:block tal:repeat="entry context/journal">
2167 a journal entry
2168 </tal:block>
2170 *where each journal entry is an HTMLJournalEntry.*
2172 Defining new web actions
2173 ------------------------
2175 You may define new actions to be triggered by the ``@action`` form variable.
2176 These are added to the tracker ``interfaces.py`` as ``Action`` classes that get
2177 called by the the ``Client`` class.
2179 Adding action classes takes three steps; first you `define the new
2180 action class`_, then you `register the action class`_ with the cgi
2181 interface so it may be triggered by the ``@action`` form variable.
2182 Finally you `use the new action`_ in your HTML form.
2184 See "`setting up a "wizard" (or "druid") for controlled adding of
2185 issues`_" for an example.
2188 Define the new action class
2189 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2191 The action classes have the following interface::
2193 class MyAction(Action):
2194 def handle(self):
2195 ''' Perform some action. No return value is required.
2196 '''
2198 The *self.client* attribute is an instance of your tracker ``instance.Client``
2199 class - thus it's mostly implemented by ``roundup.cgi.client.Client``. See the
2200 docstring of that class for details of what it can do.
2202 The method will typically check the ``self.form`` variable's contents.
2203 It may then:
2205 - add information to ``self.client.ok_message`` or ``self.client.error_message``
2206 - change the ``self.client.template`` variable to alter what the user will see
2207 next
2208 - raise Unauthorised, SendStaticFile, SendFile, NotFound or Redirect
2209 exceptions (import them from roundup.cgi.exceptions)
2212 Register the action class
2213 ~~~~~~~~~~~~~~~~~~~~~~~~~~
2215 The class is now written, but isn't available to the user until you add it to
2216 the ``instance.Client`` class ``actions`` variable, like so::
2218 actions = client.Client.actions + (
2219 ('myaction', myActionClass),
2220 )
2222 This maps the action name "myaction" to the action class we defined.
2224 Use the new action
2225 ~~~~~~~~~~~~~~~~~~
2227 In your HTML form, add a hidden form element like so::
2229 <input type="hidden" name="@action" value="myaction">
2231 where "myaction" is the name you registered in the previous step.
2233 Actions may return content to the user
2234 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2236 Actions generally perform some database manipulation and then pass control
2237 on to the rendering of a template in the current context (see `Determining
2238 web context`_ for how that works.) Some actions will want to generate the
2239 actual content returned to the user. Action methods may return their own
2240 content string to be displayed to the user, overriding the templating step.
2241 In this situation, we assume that the content is HTML by default. You may
2242 override the content type indicated to the user by calling ``setHeader``::
2244 self.client.setHeader('Content-Type', 'text/csv')
2246 This example indicates that the value sent back to the user is actually
2247 comma-separated value content (eg. something to be loaded into a
2248 spreadsheet or database).
2251 Examples
2252 ========
2254 .. contents::
2255 :local:
2256 :depth: 1
2259 Adding a new field to the classic schema
2260 ----------------------------------------
2262 This example shows how to add a new constrained property (i.e. a
2263 selection of distinct values) to your tracker.
2266 Introduction
2267 ~~~~~~~~~~~~
2269 To make the classic schema of roundup useful as a TODO tracking system
2270 for a group of systems administrators, it needed an extra data field per
2271 issue: a category.
2273 This would let sysadmins quickly list all TODOs in their particular area
2274 of interest without having to do complex queries, and without relying on
2275 the spelling capabilities of other sysadmins (a losing proposition at
2276 best).
2279 Adding a field to the database
2280 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2282 This is the easiest part of the change. The category would just be a
2283 plain string, nothing fancy. To change what is in the database you need
2284 to add some lines to the ``open()`` function in ``dbinit.py``. Under the
2285 comment::
2287 # add any additional database schema configuration here
2289 add::
2291 category = Class(db, "category", name=String())
2292 category.setkey("name")
2294 Here we are setting up a chunk of the database which we are calling
2295 "category". It contains a string, which we are refering to as "name" for
2296 lack of a more imaginative title. (Since "name" is one of the properties
2297 that Roundup looks for on items if you do not set a key for them, it's
2298 probably a good idea to stick with it for new classes if at all
2299 appropriate.) Then we are setting the key of this chunk of the database
2300 to be that "name". This is equivalent to an index for database types.
2301 This also means that there can only be one category with a given name.
2303 Adding the above lines allows us to create categories, but they're not
2304 tied to the issues that we are going to be creating. It's just a list of
2305 categories off on its own, which isn't much use. We need to link it in
2306 with the issues. To do that, find the lines in the ``open()`` function
2307 in ``dbinit.py`` which set up the "issue" class, and then add a link to
2308 the category::
2310 issue = IssueClass(db, "issue", ... ,
2311 category=Multilink("category"), ... )
2313 The ``Multilink()`` means that each issue can have many categories. If
2314 you were adding something with a one-to-one relationship to issues (such
2315 as the "assignedto" property), use ``Link()`` instead.
2317 That is all you need to do to change the schema. The rest of the effort
2318 is fiddling around so you can actually use the new category.
2321 Populating the new category class
2322 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2324 If you haven't initialised the database with the roundup-admin
2325 "initialise" command, then you can add the following to the tracker
2326 ``dbinit.py`` in the ``init()`` function under the comment::
2328 # add any additional database create steps here - but only if you
2329 # haven't initialised the database with the admin "initialise" command
2331 Add::
2333 category = db.getclass('category')
2334 category.create(name="scipy", order="1")
2335 category.create(name="chaco", order="2")
2336 category.create(name="weave", order="3")
2338 If the database has already been initalised, then you need to use the
2339 ``roundup-admin`` tool::
2341 % roundup-admin -i <tracker home>
2342 Roundup <version> ready for input.
2343 Type "help" for help.
2344 roundup> create category name=scipy order=1
2345 1
2346 roundup> create category name=chaco order=1
2347 2
2348 roundup> create category name=weave order=1
2349 3
2350 roundup> exit...
2351 There are unsaved changes. Commit them (y/N)? y
2353 TODO: explain why order=1 in each case. Also, does key get set to "name"
2354 automatically when added via roundup-admin?
2357 Setting up security on the new objects
2358 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2360 By default only the admin user can look at and change objects. This
2361 doesn't suit us, as we want any user to be able to create new categories
2362 as required, and obviously everyone needs to be able to view the
2363 categories of issues for it to be useful.
2365 We therefore need to change the security of the category objects. This
2366 is also done in the ``open()`` function of ``dbinit.py``.
2368 There are currently two loops which set up permissions and then assign
2369 them to various roles. Simply add the new "category" to both lists::
2371 # new permissions for this schema
2372 for cl in 'issue', 'file', 'msg', 'user', 'category':
2373 db.security.addPermission(name="Edit", klass=cl,
2374 description="User is allowed to edit "+cl)
2375 db.security.addPermission(name="View", klass=cl,
2376 description="User is allowed to access "+cl)
2378 # Assign the access and edit permissions for issue, file and message
2379 # to regular users now
2380 for cl in 'issue', 'file', 'msg', 'category':
2381 p = db.security.getPermission('View', cl)
2382 db.security.addPermissionToRole('User', p)
2383 p = db.security.getPermission('Edit', cl)
2384 db.security.addPermissionToRole('User', p)
2386 So you are in effect doing the following (with 'cl' substituted by its
2387 value)::
2389 db.security.addPermission(name="Edit", klass='category',
2390 description="User is allowed to edit "+'category')
2391 db.security.addPermission(name="View", klass='category',
2392 description="User is allowed to access "+'category')
2394 which is creating two permission types; that of editing and viewing
2395 "category" objects respectively. Then the following lines assign those
2396 new permissions to the "User" role, so that normal users can view and
2397 edit "category" objects::
2399 p = db.security.getPermission('View', 'category')
2400 db.security.addPermissionToRole('User', p)
2402 p = db.security.getPermission('Edit', 'category')
2403 db.security.addPermissionToRole('User', p)
2405 This is all the work that needs to be done for the database. It will
2406 store categories, and let users view and edit them. Now on to the
2407 interface stuff.
2410 Changing the web left hand frame
2411 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2413 We need to give the users the ability to create new categories, and the
2414 place to put the link to this functionality is in the left hand function
2415 bar, under the "Issues" area. The file that defines how this area looks
2416 is ``html/page``, which is what we are going to be editing next.
2418 If you look at this file you can see that it contains a lot of
2419 "classblock" sections which are chunks of HTML that will be included or
2420 excluded in the output depending on whether the condition in the
2421 classblock is met. Under the end of the classblock for issue is where we
2422 are going to add the category code::
2424 <p class="classblock"
2425 tal:condition="python:request.user.hasPermission('View', 'category')">
2426 <b>Categories</b><br>
2427 <a tal:condition="python:request.user.hasPermission('Edit', 'category')"
2428 href="category?@template=item">New Category<br></a>
2429 </p>
2431 The first two lines is the classblock definition, which sets up a
2432 condition that only users who have "View" permission for the "category"
2433 object will have this section included in their output. Next comes a
2434 plain "Categories" header in bold. Everyone who can view categories will
2435 get that.
2437 Next comes the link to the editing area of categories. This link will
2438 only appear if the condition - that the user has "Edit" permissions for
2439 the "category" objects - is matched. If they do have permission then
2440 they will get a link to another page which will let the user add new
2441 categories.
2443 Note that if you have permission to *view* but not to *edit* categories,
2444 then all you will see is a "Categories" header with nothing underneath
2445 it. This is obviously not very good interface design, but will do for
2446 now. I just claim that it is so I can add more links in this section
2447 later on. However to fix the problem you could change the condition in
2448 the classblock statement, so that only users with "Edit" permission
2449 would see the "Categories" stuff.
2452 Setting up a page to edit categories
2453 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2455 We defined code in the previous section which let users with the
2456 appropriate permissions see a link to a page which would let them edit
2457 conditions. Now we have to write that page.
2459 The link was for the *item* template of the *category* object. This
2460 translates into Roundup looking for a file called ``category.item.html``
2461 in the ``html`` tracker directory. This is the file that we are going to
2462 write now.
2464 First we add an info tag in a comment which doesn't affect the outcome
2465 of the code at all, but is useful for debugging. If you load a page in a
2466 browser and look at the page source, you can see which sections come
2467 from which files by looking for these comments::
2469 <!-- category.item -->
2471 Next we need to add in the METAL macro stuff so we get the normal page
2472 trappings::
2474 <tal:block metal:use-macro="templates/page/macros/icing">
2475 <title metal:fill-slot="head_title">Category editing</title>
2476 <td class="page-header-top" metal:fill-slot="body_title">
2477 <h2>Category editing</h2>
2478 </td>
2479 <td class="content" metal:fill-slot="content">
2481 Next we need to setup up a standard HTML form, which is the whole
2482 purpose of this file. We link to some handy javascript which sends the
2483 form through only once. This is to stop users hitting the send button
2484 multiple times when they are impatient and thus having the form sent
2485 multiple times::
2487 <form method="POST" onSubmit="return submit_once()"
2488 enctype="multipart/form-data">
2490 Next we define some code which sets up the minimum list of fields that
2491 we require the user to enter. There will be only one field - "name" - so
2492 they better put something in it, otherwise the whole form is pointless::
2494 <input type="hidden" name="@required" value="name">
2496 To get everything to line up properly we will put everything in a table,
2497 and put a nice big header on it so the user has an idea what is
2498 happening::
2500 <table class="form">
2501 <tr><th class="header" colspan="2">Category</th></tr>
2503 Next, we need the field into which the user is going to enter the new
2504 category. The "context.name.field(size=60)" bit tells Roundup to
2505 generate a normal HTML field of size 60, and the contents of that field
2506 will be the "name" variable of the current context (which is
2507 "category"). The upshot of this is that when the user types something in
2508 to the form, a new category will be created with that name::
2510 <tr>
2511 <th>Name</th>
2512 <td tal:content="structure python:context.name.field(size=60)">
2513 name</td>
2514 </tr>
2516 Then a submit button so that the user can submit the new category::
2518 <tr>
2519 <td> </td>
2520 <td colspan="3" tal:content="structure context/submit">
2521 submit button will go here
2522 </td>
2523 </tr>
2525 Finally we finish off the tags we used at the start to do the METAL
2526 stuff::
2528 </td>
2529 </tal:block>
2531 So putting it all together, and closing the table and form we get::
2533 <!-- category.item -->
2534 <tal:block metal:use-macro="templates/page/macros/icing">
2535 <title metal:fill-slot="head_title">Category editing</title>
2536 <td class="page-header-top" metal:fill-slot="body_title">
2537 <h2>Category editing</h2>
2538 </td>
2539 <td class="content" metal:fill-slot="content">
2540 <form method="POST" onSubmit="return submit_once()"
2541 enctype="multipart/form-data">
2543 <table class="form">
2544 <tr><th class="header" colspan="2">Category</th></tr>
2546 <tr>
2547 <th>Name</th>
2548 <td tal:content="structure python:context.name.field(size=60)">
2549 name</td>
2550 </tr>
2552 <tr>
2553 <td>
2554
2555 <input type="hidden" name="@required" value="name">
2556 </td>
2557 <td colspan="3" tal:content="structure context/submit">
2558 submit button will go here
2559 </td>
2560 </tr>
2561 </table>
2562 </form>
2563 </td>
2564 </tal:block>
2566 This is quite a lot to just ask the user one simple question, but there
2567 is a lot of setup for basically one line (the form line) to do its work.
2568 To add another field to "category" would involve one more line (well,
2569 maybe a few extra to get the formatting correct).
2572 Adding the category to the issue
2573 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2575 We now have the ability to create issues to our heart's content, but
2576 that is pointless unless we can assign categories to issues. Just like
2577 the ``html/category.item.html`` file was used to define how to add a new
2578 category, the ``html/issue.item.html`` is used to define how a new issue
2579 is created.
2581 Just like ``category.issue.html`` this file defines a form which has a
2582 table to lay things out. It doesn't matter where in the table we add new
2583 stuff, it is entirely up to your sense of aesthetics::
2585 <th>Category</th>
2586 <td><span tal:replace="structure context/category/field" />
2587 <span tal:replace="structure db/category/classhelp" />
2588 </td>
2590 First, we define a nice header so that the user knows what the next
2591 section is, then the middle line does what we are most interested in.
2592 This ``context/category/field`` gets replaced by a field which contains
2593 the category in the current context (the current context being the new
2594 issue).
2596 The classhelp lines generate a link (labelled "list") to a popup window
2597 which contains the list of currently known categories.
2600 Searching on categories
2601 ~~~~~~~~~~~~~~~~~~~~~~~
2603 We can add categories, and create issues with categories. The next
2604 obvious thing that we would like to be able to do, would be to search
2605 for issues based on their category, so that, for example, anyone working
2606 on the web server could look at all issues in the category "Web".
2608 If you look for "Search Issues" in the 'html/page.html' file, you will
2609 find that it looks something like
2610 ``<a href="issue?@template=search">Search Issues</a>``. This shows us
2611 that when you click on "Search Issues" it will be looking for a
2612 ``issue.search.html`` file to display. So that is the file that we will
2613 change.
2615 If you look at this file it should be starting to seem familiar, although it
2616 does use some new macros. You can add the new category search code anywhere you
2617 like within that form::
2619 <tr tal:define="name string:category;
2620 db_klass string:category;
2621 db_content string:name;">
2622 <th>Priority:</th>
2623 <td metal:use-macro="search_select"></td>
2624 <td metal:use-macro="column_input"></td>
2625 <td metal:use-macro="sort_input"></td>
2626 <td metal:use-macro="group_input"></td>
2627 </tr>
2629 The definitions in the <tr> opening tag are used by the macros:
2631 - search_select expands to a drop-down box with all categories using db_klass
2632 and db_content.
2633 - column_input expands to a checkbox for selecting what columns should be
2634 displayed.
2635 - sort_input expands to a radio button for selecting what property should be
2636 sorted on.
2637 - group_input expands to a radio button for selecting what property should be
2638 group on.
2640 The category search code above would expand to the following::
2642 <tr>
2643 <th>Category:</th>
2644 <td>
2645 <select name="category">
2646 <option value="">don't care</option>
2647 <option value="">------------</option>
2648 <option value="1">scipy</option>
2649 <option value="2">chaco</option>
2650 <option value="3">weave</option>
2651 </select>
2652 </td>
2653 <td><input type="checkbox" name=":columns" value="category"></td>
2654 <td><input type="radio" name=":sort" value="category"></td>
2655 <td><input type="radio" name=":group" value="category"></td>
2656 </tr>
2658 Adding category to the default view
2659 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2661 We can now add categories, add issues with categories, and search for
2662 issues based on categories. This is everything that we need to do;
2663 however, there is some more icing that we would like. I think the
2664 category of an issue is important enough that it should be displayed by
2665 default when listing all the issues.
2667 Unfortunately, this is a bit less obvious than the previous steps. The
2668 code defining how the issues look is in ``html/issue.index.html``. This
2669 is a large table with a form down at the bottom for redisplaying and so
2670 forth.
2672 Firstly we need to add an appropriate header to the start of the table::
2674 <th tal:condition="request/show/category">Category</th>
2676 The *condition* part of this statement is to avoid displaying the
2677 Category column if the user has selected not to see it.
2679 The rest of the table is a loop which will go through every issue that
2680 matches the display criteria. The loop variable is "i" - which means
2681 that every issue gets assigned to "i" in turn.
2683 The new part of code to display the category will look like this::
2685 <td tal:condition="request/show/category"
2686 tal:content="i/category"></td>
2688 The condition is the same as above: only display the condition when the
2689 user hasn't asked for it to be hidden. The next part is to set the
2690 content of the cell to be the category part of "i" - the current issue.
2692 Finally we have to edit ``html/page.html`` again. This time, we need to
2693 tell it that when the user clicks on "Unasigned Issues" or "All Issues",
2694 the category column should be included in the resulting list. If you
2695 scroll down the page file, you can see the links with lots of options.
2696 The option that we are interested in is the ``:columns=`` one which
2697 tells roundup which fields of the issue to display. Simply add
2698 "category" to that list and it all should work.
2701 Adding in state transition control
2702 ----------------------------------
2704 Sometimes tracker admins want to control the states that users may move
2705 issues to. You can do this by following these steps:
2707 1. make "status" a required variable. This is achieved by adding the
2708 following to the top of the form in the ``issue.item.html``
2709 template::
2711 <input type="hidden" name="@required" value="status">
2713 this will force users to select a status.
2715 2. add a Multilink property to the status class::
2717 stat = Class(db, "status", ... , transitions=Multilink('status'),
2718 ...)
2720 and then edit the statuses already created, either:
2722 a. through the web using the class list -> status class editor, or
2723 b. using the roundup-admin "set" command.
2725 3. add an auditor module ``checktransition.py`` in your tracker's
2726 ``detectors`` directory, for example::
2728 def checktransition(db, cl, nodeid, newvalues):
2729 ''' Check that the desired transition is valid for the "status"
2730 property.
2731 '''
2732 if not newvalues.has_key('status'):
2733 return
2734 current = cl.get(nodeid, 'status')
2735 new = newvalues['status']
2736 if new == current:
2737 return
2738 ok = db.status.get(current, 'transitions')
2739 if new not in ok:
2740 raise ValueError, 'Status not allowed to move from "%s" to "%s"'%(
2741 db.status.get(current, 'name'), db.status.get(new, 'name'))
2743 def init(db):
2744 db.issue.audit('set', checktransition)
2746 4. in the ``issue.item.html`` template, change the status editing bit
2747 from::
2749 <th>Status</th>
2750 <td tal:content="structure context/status/menu">status</td>
2752 to::
2754 <th>Status</th>
2755 <td>
2756 <select tal:condition="context/id" name="status">
2757 <tal:block tal:define="ok context/status/transitions"
2758 tal:repeat="state db/status/list">
2759 <option tal:condition="python:state.id in ok"
2760 tal:attributes="
2761 value state/id;
2762 selected python:state.id == context.status.id"
2763 tal:content="state/name"></option>
2764 </tal:block>
2765 </select>
2766 <tal:block tal:condition="not:context/id"
2767 tal:replace="structure context/status/menu" />
2768 </td>
2770 which displays only the allowed status to transition to.
2773 Displaying only message summaries in the issue display
2774 ------------------------------------------------------
2776 Alter the issue.item template section for messages to::
2778 <table class="messages" tal:condition="context/messages">
2779 <tr><th colspan="5" class="header">Messages</th></tr>
2780 <tr tal:repeat="msg context/messages">
2781 <td><a tal:attributes="href string:msg${msg/id}"
2782 tal:content="string:msg${msg/id}"></a></td>
2783 <td tal:content="msg/author">author</td>
2784 <td class="date" tal:content="msg/date/pretty">date</td>
2785 <td tal:content="msg/summary">summary</td>
2786 <td>
2787 <a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">
2788 remove</a>
2789 </td>
2790 </tr>
2791 </table>
2793 Restricting the list of users that are assignable to a task
2794 -----------------------------------------------------------
2796 1. In your tracker's "dbinit.py", create a new Role, say "Developer"::
2798 db.security.addRole(name='Developer', description='A developer')
2800 2. Just after that, create a new Permission, say "Fixer", specific to
2801 "issue"::
2803 p = db.security.addPermission(name='Fixer', klass='issue',
2804 description='User is allowed to be assigned to fix issues')
2806 3. Then assign the new Permission to your "Developer" Role::
2808 db.security.addPermissionToRole('Developer', p)
2810 4. In the issue item edit page ("html/issue.item.html" in your tracker
2811 directory), use the new Permission in restricting the "assignedto"
2812 list::
2814 <select name="assignedto">
2815 <option value="-1">- no selection -</option>
2816 <tal:block tal:repeat="user db/user/list">
2817 <option tal:condition="python:user.hasPermission(
2818 'Fixer', context._classname)"
2819 tal:attributes="
2820 value user/id;
2821 selected python:user.id == context.assignedto"
2822 tal:content="user/realname"></option>
2823 </tal:block>
2824 </select>
2826 For extra security, you may wish to setup an auditor to enforce the
2827 Permission requirement (install this as "assignedtoFixer.py" in your
2828 tracker "detectors" directory)::
2830 def assignedtoMustBeFixer(db, cl, nodeid, newvalues):
2831 ''' Ensure the assignedto value in newvalues is a used with the
2832 Fixer Permission
2833 '''
2834 if not newvalues.has_key('assignedto'):
2835 # don't care
2836 return
2838 # get the userid
2839 userid = newvalues['assignedto']
2840 if not db.security.hasPermission('Fixer', userid, cl.classname):
2841 raise ValueError, 'You do not have permission to edit %s'%cl.classname
2843 def init(db):
2844 db.issue.audit('set', assignedtoMustBeFixer)
2845 db.issue.audit('create', assignedtoMustBeFixer)
2847 So now, if an edit action attempts to set "assignedto" to a user that
2848 doesn't have the "Fixer" Permission, the error will be raised.
2851 Setting up a "wizard" (or "druid") for controlled adding of issues
2852 ------------------------------------------------------------------
2854 1. Set up the page templates you wish to use for data input. My wizard
2855 is going to be a two-step process: first figuring out what category
2856 of issue the user is submitting, and then getting details specific to
2857 that category. The first page includes a table of help, explaining
2858 what the category names mean, and then the core of the form::
2860 <form method="POST" onSubmit="return submit_once()"
2861 enctype="multipart/form-data">
2862 <input type="hidden" name="@template" value="add_page1">
2863 <input type="hidden" name="@action" value="page1_submit">
2865 <strong>Category:</strong>
2866 <tal:block tal:replace="structure context/category/menu" />
2867 <input type="submit" value="Continue">
2868 </form>
2870 The next page has the usual issue entry information, with the
2871 addition of the following form fragments::
2873 <form method="POST" onSubmit="return submit_once()"
2874 enctype="multipart/form-data"
2875 tal:condition="context/is_edit_ok"
2876 tal:define="cat request/form/category/value">
2878 <input type="hidden" name="@template" value="add_page2">
2879 <input type="hidden" name="@required" value="title">
2880 <input type="hidden" name="category" tal:attributes="value cat">
2881 .
2882 .
2883 .
2884 </form>
2886 Note that later in the form, I test the value of "cat" include form
2887 elements that are appropriate. For example::
2889 <tal:block tal:condition="python:cat in '6 10 13 14 15 16 17'.split()">
2890 <tr>
2891 <th>Operating System</th>
2892 <td tal:content="structure context/os/field"></td>
2893 </tr>
2894 <tr>
2895 <th>Web Browser</th>
2896 <td tal:content="structure context/browser/field"></td>
2897 </tr>
2898 </tal:block>
2900 ... the above section will only be displayed if the category is one
2901 of 6, 10, 13, 14, 15, 16 or 17.
2903 3. Determine what actions need to be taken between the pages - these are
2904 usually to validate user choices and determine what page is next. Now encode
2905 those actions in a new ``Action`` class and insert hooks to those actions in
2906 the "actions" attribute on on the ``interfaces.Client`` class, like so (see
2907 `defining new web actions`_)::
2909 class Page1SubmitAction(Action):
2910 def handle(self):
2911 ''' Verify that the user has selected a category, and then move
2912 on to page 2.
2913 '''
2914 category = self.form['category'].value
2915 if category == '-1':
2916 self.error_message.append('You must select a category of report')
2917 return
2918 # everything's ok, move on to the next page
2919 self.template = 'add_page2'
2921 actions = client.Client.actions + (
2922 ('page1_submit', Page1SubmitAction),
2923 )
2925 4. Use the usual "new" action as the ``@action`` on the final page, and
2926 you're done (the standard context/submit method can do this for you).
2929 Using an external password validation source
2930 --------------------------------------------
2932 We have a centrally-managed password changing system for our users. This
2933 results in a UN*X passwd-style file that we use for verification of
2934 users. Entries in the file consist of ``name:password`` where the
2935 password is encrypted using the standard UN*X ``crypt()`` function (see
2936 the ``crypt`` module in your Python distribution). An example entry
2937 would be::
2939 admin:aamrgyQfDFSHw
2941 Each user of Roundup must still have their information stored in the Roundup
2942 database - we just use the passwd file to check their password. To do this, we
2943 need to override the standard ``verifyPassword`` method defined in
2944 ``roundup.cgi.actions.LoginAction`` and register the new class with our
2945 ``Client`` class in the tracker home ``interfaces.py`` module::
2947 from roundup.cgi.actions import LoginAction
2949 class ExternalPasswordLoginAction(LoginAction):
2950 def verifyPassword(self, userid, password):
2951 # get the user's username
2952 username = self.db.user.get(userid, 'username')
2954 # the passwords are stored in the "passwd.txt" file in the
2955 # tracker home
2956 file = os.path.join(self.db.config.TRACKER_HOME, 'passwd.txt')
2958 # see if we can find a match
2959 for ent in [line.strip().split(':') for line in
2960 open(file).readlines()]:
2961 if ent[0] == username:
2962 return crypt.crypt(password, ent[1][:2]) == ent[1]
2964 # user doesn't exist in the file
2965 return 0
2967 class Client(client.Client):
2968 actions = client.Client.actions + (
2969 ('login', ExternalPasswordLoginAction)
2970 )
2972 What this does is look through the file, line by line, looking for a
2973 name that matches.
2975 We also remove the redundant password fields from the ``user.item``
2976 template.
2979 Adding a "vacation" flag to users for stopping nosy messages
2980 ------------------------------------------------------------
2982 When users go on vacation and set up vacation email bouncing, you'll
2983 start to see a lot of messages come back through Roundup "Fred is on
2984 vacation". Not very useful, and relatively easy to stop.
2986 1. add a "vacation" flag to your users::
2988 user = Class(db, "user",
2989 username=String(), password=Password(),
2990 address=String(), realname=String(),
2991 phone=String(), organisation=String(),
2992 alternate_addresses=String(),
2993 roles=String(), queries=Multilink("query"),
2994 vacation=Boolean())
2996 2. So that users may edit the vacation flags, add something like the
2997 following to your ``user.item`` template::
2999 <tr>
3000 <th>On Vacation</th>
3001 <td tal:content="structure context/vacation/field">vacation</td>
3002 </tr>
3004 3. edit your detector ``nosyreactor.py`` so that the ``nosyreaction()``
3005 consists of::
3007 def nosyreaction(db, cl, nodeid, oldvalues):
3008 users = db.user
3009 messages = db.msg
3010 # send a copy of all new messages to the nosy list
3011 for msgid in determineNewMessages(cl, nodeid, oldvalues):
3012 try:
3013 # figure the recipient ids
3014 sendto = []
3015 seen_message = {}
3016 recipients = messages.get(msgid, 'recipients')
3017 for recipid in messages.get(msgid, 'recipients'):
3018 seen_message[recipid] = 1
3020 # figure the author's id, and indicate they've received
3021 # the message
3022 authid = messages.get(msgid, 'author')
3024 # possibly send the message to the author, as long as
3025 # they aren't anonymous
3026 if (db.config.MESSAGES_TO_AUTHOR == 'yes' and
3027 users.get(authid, 'username') != 'anonymous'):
3028 sendto.append(authid)
3029 seen_message[authid] = 1
3031 # now figure the nosy people who weren't recipients
3032 nosy = cl.get(nodeid, 'nosy')
3033 for nosyid in nosy:
3034 # Don't send nosy mail to the anonymous user (that
3035 # user shouldn't appear in the nosy list, but just
3036 # in case they do...)
3037 if users.get(nosyid, 'username') == 'anonymous':
3038 continue
3039 # make sure they haven't seen the message already
3040 if not seen_message.has_key(nosyid):
3041 # send it to them
3042 sendto.append(nosyid)
3043 recipients.append(nosyid)
3045 # generate a change note
3046 if oldvalues:
3047 note = cl.generateChangeNote(nodeid, oldvalues)
3048 else:
3049 note = cl.generateCreateNote(nodeid)
3051 # we have new recipients
3052 if sendto:
3053 # filter out the people on vacation
3054 sendto = [i for i in sendto
3055 if not users.get(i, 'vacation', 0)]
3057 # map userids to addresses
3058 sendto = [users.get(i, 'address') for i in sendto]
3060 # update the message's recipients list
3061 messages.set(msgid, recipients=recipients)
3063 # send the message
3064 cl.send_message(nodeid, msgid, note, sendto)
3065 except roundupdb.MessageSendError, message:
3066 raise roundupdb.DetectorError, message
3068 Note that this is the standard nosy reaction code, with the small
3069 addition of::
3071 # filter out the people on vacation
3072 sendto = [i for i in sendto if not users.get(i, 'vacation', 0)]
3074 which filters out the users that have the vacation flag set to true.
3077 Adding a time log to your issues
3078 --------------------------------
3080 We want to log the dates and amount of time spent working on issues, and
3081 be able to give a summary of the total time spent on a particular issue.
3083 1. Add a new class to your tracker ``dbinit.py``::
3085 # storage for time logging
3086 timelog = Class(db, "timelog", period=Interval())
3088 Note that we automatically get the date of the time log entry
3089 creation through the standard property "creation".
3091 2. Link to the new class from your issue class (again, in
3092 ``dbinit.py``)::
3094 issue = IssueClass(db, "issue",
3095 assignedto=Link("user"), topic=Multilink("keyword"),
3096 priority=Link("priority"), status=Link("status"),
3097 times=Multilink("timelog"))
3099 the "times" property is the new link to the "timelog" class.
3101 3. We'll need to let people add in times to the issue, so in the web
3102 interface we'll have a new entry field. This is a special field
3103 because unlike the other fields in the issue.item template, it
3104 affects a different item (a timelog item) and not the template's
3105 item, an issue. We have a special syntax for form fields that affect
3106 items other than the template default item (see the cgi
3107 documentation on `special form variables`_). In particular, we add a
3108 field to capture a new timelog item's perdiod::
3110 <tr>
3111 <th>Time Log</th>
3112 <td colspan=3><input type="text" name="timelog-1@period" />
3113 <br />(enter as '3y 1m 4d 2:40:02' or parts thereof)
3114 </td>
3115 </tr>
3117 and another hidden field that links that new timelog item (new
3118 because it's marked as having id "-1") to the issue item. It looks
3119 like this::
3121 <input type="hidden" name="@link@times" value="timelog-1" />
3123 On submission, the "-1" timelog item will be created and assigned a
3124 real item id. The "times" property of the issue will have the new id
3125 added to it.
3127 4. We want to display a total of the time log times that have been
3128 accumulated for an issue. To do this, we'll need to actually write
3129 some Python code, since it's beyond the scope of PageTemplates to
3130 perform such calculations. We do this by adding a method to the
3131 TemplatingUtils class in our tracker ``interfaces.py`` module::
3133 class TemplatingUtils:
3134 ''' Methods implemented on this class will be available to HTML
3135 templates through the 'utils' variable.
3136 '''
3137 def totalTimeSpent(self, times):
3138 ''' Call me with a list of timelog items (which have an
3139 Interval "period" property)
3140 '''
3141 total = Interval('0d')
3142 for time in times:
3143 total += time.period._value
3144 return total
3146 Replace the ``pass`` line if one appears in your TemplatingUtils
3147 class. As indicated in the docstrings, we will be able to access the
3148 ``totalTimeSpent`` method via the ``utils`` variable in our templates.
3150 5. Display the time log for an issue::
3152 <table class="otherinfo" tal:condition="context/times">
3153 <tr><th colspan="3" class="header">Time Log
3154 <tal:block
3155 tal:replace="python:utils.totalTimeSpent(context.times)" />
3156 </th></tr>
3157 <tr><th>Date</th><th>Period</th><th>Logged By</th></tr>
3158 <tr tal:repeat="time context/times">
3159 <td tal:content="time/creation"></td>
3160 <td tal:content="time/period"></td>
3161 <td tal:content="time/creator"></td>
3162 </tr>
3163 </table>
3165 I put this just above the Messages log in my issue display. Note our
3166 use of the ``totalTimeSpent`` method which will total up the times
3167 for the issue and return a new Interval. That will be automatically
3168 displayed in the template as text like "+ 1y 2:40" (1 year, 2 hours
3169 and 40 minutes).
3171 8. If you're using a persistent web server - roundup-server or
3172 mod_python for example - then you'll need to restart that to pick up
3173 the code changes. When that's done, you'll be able to use the new
3174 time logging interface.
3176 Using a UN*X passwd file as the user database
3177 ---------------------------------------------
3179 On some systems the primary store of users is the UN*X passwd file. It
3180 holds information on users such as their username, real name, password
3181 and primary user group.
3183 Roundup can use this store as its primary source of user information,
3184 but it needs additional information too - email address(es), roundup
3185 Roles, vacation flags, roundup hyperdb item ids, etc. Also, "retired"
3186 users must still exist in the user database, unlike some passwd files in
3187 which the users are removed when they no longer have access to a system.
3189 To make use of the passwd file, we therefore synchronise between the two
3190 user stores. We also use the passwd file to validate the user logins, as
3191 described in the previous example, `using an external password
3192 validation source`_. We keep the users lists in sync using a fairly
3193 simple script that runs once a day, or several times an hour if more
3194 immediate access is needed. In short, it:
3196 1. parses the passwd file, finding usernames, passwords and real names,
3197 2. compares that list to the current roundup user list:
3199 a. entries no longer in the passwd file are *retired*
3200 b. entries with mismatching real names are *updated*
3201 c. entries only exist in the passwd file are *created*
3203 3. send an email to administrators to let them know what's been done.
3205 The retiring and updating are simple operations, requiring only a call
3206 to ``retire()`` or ``set()``. The creation operation requires more
3207 information though - the user's email address and their roundup Roles.
3208 We're going to assume that the user's email address is the same as their
3209 login name, so we just append the domain name to that. The Roles are
3210 determined using the passwd group identifier - mapping their UN*X group
3211 to an appropriate set of Roles.
3213 The script to perform all this, broken up into its main components, is
3214 as follows. Firstly, we import the necessary modules and open the
3215 tracker we're to work on::
3217 import sys, os, smtplib
3218 from roundup import instance, date
3220 # open the tracker
3221 tracker_home = sys.argv[1]
3222 tracker = instance.open(tracker_home)
3224 Next we read in the *passwd* file from the tracker home::
3226 # read in the users
3227 file = os.path.join(tracker_home, 'users.passwd')
3228 users = [x.strip().split(':') for x in open(file).readlines()]
3230 Handle special users (those to ignore in the file, and those who don't
3231 appear in the file)::
3233 # users to not keep ever, pre-load with the users I know aren't
3234 # "real" users
3235 ignore = ['ekmmon', 'bfast', 'csrmail']
3237 # users to keep - pre-load with the roundup-specific users
3238 keep = ['comment_pool', 'network_pool', 'admin', 'dev-team',
3239 'cs_pool', 'anonymous', 'system_pool', 'automated']
3241 Now we map the UN*X group numbers to the Roles that users should have::
3243 roles = {
3244 '501': 'User,Tech', # tech
3245 '502': 'User', # finance
3246 '503': 'User,CSR', # customer service reps
3247 '504': 'User', # sales
3248 '505': 'User', # marketing
3249 }
3251 Now we do all the work. Note that the body of the script (where we have
3252 the tracker database open) is wrapped in a ``try`` / ``finally`` clause,
3253 so that we always close the database cleanly when we're finished. So, we
3254 now do all the work::
3256 # open the database
3257 db = tracker.open('admin')
3258 try:
3259 # store away messages to send to the tracker admins
3260 msg = []
3262 # loop over the users list read in from the passwd file
3263 for user,passw,uid,gid,real,home,shell in users:
3264 if user in ignore:
3265 # this user shouldn't appear in our tracker
3266 continue
3267 keep.append(user)
3268 try:
3269 # see if the user exists in the tracker
3270 uid = db.user.lookup(user)
3272 # yes, they do - now check the real name for correctness
3273 if real != db.user.get(uid, 'realname'):
3274 db.user.set(uid, realname=real)
3275 msg.append('FIX %s - %s'%(user, real))
3276 except KeyError:
3277 # nope, the user doesn't exist
3278 db.user.create(username=user, realname=real,
3279 address='%s@ekit-inc.com'%user, roles=roles[gid])
3280 msg.append('ADD %s - %s (%s)'%(user, real, roles[gid]))
3282 # now check that all the users in the tracker are also in our
3283 # "keep" list - retire those who aren't
3284 for uid in db.user.list():
3285 user = db.user.get(uid, 'username')
3286 if user not in keep:
3287 db.user.retire(uid)
3288 msg.append('RET %s'%user)
3290 # if we did work, then send email to the tracker admins
3291 if msg:
3292 # create the email
3293 msg = '''Subject: %s user database maintenance
3295 %s
3296 '''%(db.config.TRACKER_NAME, '\n'.join(msg))
3298 # send the email
3299 smtp = smtplib.SMTP(db.config.MAILHOST)
3300 addr = db.config.ADMIN_EMAIL
3301 smtp.sendmail(addr, addr, msg)
3303 # now we're done - commit the changes
3304 db.commit()
3305 finally:
3306 # always close the database cleanly
3307 db.close()
3309 And that's it!
3312 Using an LDAP database for user information
3313 -------------------------------------------
3315 A script that reads users from an LDAP store using
3316 http://python-ldap.sf.net/ and then compares the list to the users in the
3317 roundup user database would be pretty easy to write. You'd then have it run
3318 once an hour / day (or on demand if you can work that into your LDAP store
3319 workflow). See the example `Using a UN*X passwd file as the user database`_
3320 for more information about doing this.
3322 To authenticate off the LDAP store (rather than using the passwords in the
3323 roundup user database) you'd use the same python-ldap module inside an
3324 extension to the cgi interface. You'd do this by overriding the method called
3325 "verifyPassword" on the LoginAction class in your tracker's interfaces.py
3326 module (see `using an external password validation source`_). The method is
3327 implemented by default as::
3329 def verifyPassword(self, userid, password):
3330 ''' Verify the password that the user has supplied
3331 '''
3332 stored = self.db.user.get(self.userid, 'password')
3333 if password == stored:
3334 return 1
3335 if not password and not stored:
3336 return 1
3337 return 0
3339 So you could reimplement this as something like::
3341 def verifyPassword(self, userid, password):
3342 ''' Verify the password that the user has supplied
3343 '''
3344 # look up some unique LDAP information about the user
3345 username = self.db.user.get(self.userid, 'username')
3346 # now verify the password supplied against the LDAP store
3349 Enabling display of either message summaries or the entire messages
3350 -------------------------------------------------------------------
3352 This is pretty simple - all we need to do is copy the code from the
3353 example `displaying only message summaries in the issue display`_ into
3354 our template alongside the summary display, and then introduce a switch
3355 that shows either one or the other. We'll use a new form variable,
3356 ``@whole_messages`` to achieve this::
3358 <table class="messages" tal:condition="context/messages">
3359 <tal:block tal:condition="not:request/form/@whole_messages/value | python:0">
3360 <tr><th colspan="3" class="header">Messages</th>
3361 <th colspan="2" class="header">
3362 <a href="?@whole_messages=yes">show entire messages</a>
3363 </th>
3364 </tr>
3365 <tr tal:repeat="msg context/messages">
3366 <td><a tal:attributes="href string:msg${msg/id}"
3367 tal:content="string:msg${msg/id}"></a></td>
3368 <td tal:content="msg/author">author</td>
3369 <td class="date" tal:content="msg/date/pretty">date</td>
3370 <td tal:content="msg/summary">summary</td>
3371 <td>
3372 <a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">remove</a>
3373 </td>
3374 </tr>
3375 </tal:block>
3377 <tal:block tal:condition="request/form/@whole_messages/value | python:0">
3378 <tr><th colspan="2" class="header">Messages</th>
3379 <th class="header">
3380 <a href="?@whole_messages=">show only summaries</a>
3381 </th>
3382 </tr>
3383 <tal:block tal:repeat="msg context/messages">
3384 <tr>
3385 <th tal:content="msg/author">author</th>
3386 <th class="date" tal:content="msg/date/pretty">date</th>
3387 <th style="text-align: right">
3388 (<a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">remove</a>)
3389 </th>
3390 </tr>
3391 <tr><td colspan="3" tal:content="msg/content"></td></tr>
3392 </tal:block>
3393 </tal:block>
3394 </table>
3397 Blocking issues that depend on other issues
3398 -------------------------------------------
3400 We needed the ability to mark certain issues as "blockers" - that is,
3401 they can't be resolved until another issue (the blocker) they rely on is
3402 resolved. To achieve this:
3404 1. Create a new property on the issue Class,
3405 ``blockers=Multilink("issue")``. Edit your tracker's dbinit.py file.
3406 Where the "issue" class is defined, something like::
3408 issue = IssueClass(db, "issue",
3409 assignedto=Link("user"), topic=Multilink("keyword"),
3410 priority=Link("priority"), status=Link("status"))
3412 add the blockers entry like so::
3414 issue = IssueClass(db, "issue",
3415 blockers=Multilink("issue"),
3416 assignedto=Link("user"), topic=Multilink("keyword"),
3417 priority=Link("priority"), status=Link("status"))
3419 2. Add the new "blockers" property to the issue.item edit page, using
3420 something like::
3422 <th>Waiting On</th>
3423 <td>
3424 <span tal:replace="structure python:context.blockers.field(showid=1,
3425 size=20)" />
3426 <span tal:replace="structure python:db.issue.classhelp('id,title')" />
3427 <span tal:condition="context/blockers"
3428 tal:repeat="blk context/blockers">
3429 <br>View: <a tal:attributes="href string:issue${blk/id}"
3430 tal:content="blk/id"></a>
3431 </span>
3433 You'll need to fiddle with your item page layout to find an
3434 appropriate place to put it - I'll leave that fun part up to you.
3435 Just make sure it appears in the first table, possibly somewhere near
3436 the "superseders" field.
3438 3. Create a new detector module (attached) which enforces the rules:
3440 - issues may not be resolved if they have blockers
3441 - when a blocker is resolved, it's removed from issues it blocks
3443 The contents of the detector should be something like this::
3445 def blockresolution(db, cl, nodeid, newvalues):
3446 ''' If the issue has blockers, don't allow it to be resolved.
3447 '''
3448 if nodeid is None:
3449 blockers = []
3450 else:
3451 blockers = cl.get(nodeid, 'blockers')
3452 blockers = newvalues.get('blockers', blockers)
3454 # don't do anything if there's no blockers or the status hasn't
3455 # changed
3456 if not blockers or not newvalues.has_key('status'):
3457 return
3459 # get the resolved state ID
3460 resolved_id = db.status.lookup('resolved')
3462 # format the info
3463 u = db.config.TRACKER_WEB
3464 s = ', '.join(['<a href="%sissue%s">%s</a>'%(
3465 u,id,id) for id in blockers])
3466 if len(blockers) == 1:
3467 s = 'issue %s is'%s
3468 else:
3469 s = 'issues %s are'%s
3471 # ok, see if we're trying to resolve
3472 if newvalues['status'] == resolved_id:
3473 raise ValueError, "This issue can't be resolved until %s resolved."%s
3475 def resolveblockers(db, cl, nodeid, newvalues):
3476 ''' When we resolve an issue that's a blocker, remove it from the
3477 blockers list of the issue(s) it blocks.
3478 '''
3479 if not newvalues.has_key('status'):
3480 return
3482 # get the resolved state ID
3483 resolved_id = db.status.lookup('resolved')
3485 # interesting?
3486 if newvalues['status'] != resolved_id:
3487 return
3489 # yes - find all the blocked issues, if any, and remove me from
3490 # their blockers list
3491 issues = cl.find(blockers=nodeid)
3492 for issueid in issues:
3493 blockers = cl.get(issueid, 'blockers')
3494 if nodeid in blockers:
3495 blockers.remove(nodeid)
3496 cl.set(issueid, blockers=blockers)
3499 def init(db):
3500 # might, in an obscure situation, happen in a create
3501 db.issue.audit('create', blockresolution)
3502 db.issue.audit('set', blockresolution)
3504 # can only happen on a set
3505 db.issue.react('set', resolveblockers)
3507 Put the above code in a file called "blockers.py" in your tracker's
3508 "detectors" directory.
3510 4. Finally, and this is an optional step, modify the tracker web page
3511 URLs so they filter out issues with any blockers. You do this by
3512 adding an additional filter on "blockers" for the value "-1". For
3513 example, the existing "Show All" link in the "page" template (in the
3514 tracker's "html" directory) looks like this::
3516 <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>
3518 modify it to add the "blockers" info to the URL (note, both the
3519 ":filter" *and* "blockers" values must be specified)::
3521 <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>
3523 That's it. You should now be able to set blockers on your issues. Note
3524 that if you want to know whether an issue has any other issues dependent
3525 on it (i.e. it's in their blockers list) you can look at the journal
3526 history at the bottom of the issue page - look for a "link" event to
3527 another issue's "blockers" property.
3529 Add users to the nosy list based on the topic
3530 ---------------------------------------------
3532 We need the ability to automatically add users to the nosy list based
3533 on the occurence of a topic. Every user should be allowed to edit his
3534 own list of topics for which he wants to be added to the nosy list.
3536 Below will be showed that such a change can be performed with only
3537 minimal understanding of the roundup system, but with clever use
3538 of Copy and Paste.
3540 This requires three changes to the tracker: a change in the database to
3541 allow per-user recording of the lists of topics for which he wants to
3542 be put on the nosy list, a change in the user view allowing to edit
3543 this list of topics, and addition of an auditor which updates the nosy
3544 list when a topic is set.
3546 Adding the nosy topic list
3547 ~~~~~~~~~~~~~~~~~~~~~~~~~~
3549 The change in the database to make is that for any user there should be
3550 a list of topics for which he wants to be put on the nosy list. Adding
3551 a ``Multilink`` of ``keyword`` seem to fullfill this (note that within
3552 the code topics are called ``keywords``.) As such, all what has to be
3553 done is to add a new field to the definition of ``user`` within the
3554 file ``dbinit.py``. We will call this new field ``nosy_keywords``, and
3555 the updated definition of user will be::
3557 user = Class(db, "user",
3558 username=String(), password=Password(),
3559 address=String(), realname=String(),
3560 phone=String(), organisation=String(),
3561 alternate_addresses=String(),
3562 queries=Multilink('query'), roles=String(),
3563 timezone=String(),
3564 nosy_keywords=Multilink('keyword'))
3566 Changing the user view to allow changing the nosy topic list
3567 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3569 We want any user to be able to change the list of topics for which
3570 he will by default be added to the nosy list. We choose to add this
3571 to the user view, as is generated by the file ``html/user.item.html``.
3572 We easily can
3573 see that the topic field in the issue view has very similar editting
3574 requirements as our nosy topics, both being a list of topics. As
3575 such, we search for Topics in ``issue.item.html``, and extract the
3576 associated parts from there. We add this to ``user.item.html`` at the
3577 bottom of the list of viewed items (i.e. just below the 'Alternate
3578 E-mail addresses' in the classic template)::
3580 <tr>
3581 <th>Nosy Topics</th>
3582 <td>
3583 <span tal:replace="structure context/nosy_keywords/field" />
3584 <span tal:replace="structure python:db.keyword.classhelp(property='nosy_keywords')" />
3585 </td>
3586 </tr>
3589 Addition of an auditor to update the nosy list
3590 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3592 The more difficult part is the addition of the logic to actually
3593 at the users to the nosy list when it is required.
3594 The choice is made to perform this action when the topics on an
3595 item are set, including when an item is created.
3596 Here we choose to start out with a copy of the
3597 ``detectors/nosyreaction.py`` detector, which we copy to the file
3598 ``detectors/nosy_keyword_reaction.py``.
3599 This looks like a good start as it also adds users
3600 to the nosy list. A look through the code reveals that the
3601 ``nosyreaction`` function actually is sending the e-mail, which
3602 we do not need. As such, we can change the init function to::
3604 def init(db):
3605 db.issue.audit('create', update_kw_nosy)
3606 db.issue.audit('set', update_kw_nosy)
3608 After that we rename the ``updatenosy`` function to ``update_kw_nosy``.
3609 The first two blocks of code in that function relate to settings
3610 ``current`` to a combination of the old and new nosy lists. This
3611 functionality is left in the new auditor. The following block of
3612 code, which in ``updatenosy`` handled adding the assignedto user(s)
3613 to the nosy list, should be replaced by a block of code to add the
3614 interested users to the nosy list. We choose here to loop over all
3615 new topics, than loop over all users,
3616 and assign the user to the nosy list when the topic in the user's
3617 nosy_keywords. The next part in ``updatenosy``, adding the author
3618 and/or recipients of a message to the nosy list, obviously is not
3619 relevant here and thus is deleted from the new auditor. The last
3620 part, copying the new nosy list to newvalues, does not have to be changed.
3621 This brings the following function::
3623 def update_kw_nosy(db, cl, nodeid, newvalues):
3624 '''Update the nosy list for changes to the topics
3625 '''
3626 # nodeid will be None if this is a new node
3627 current = {}
3628 if nodeid is None:
3629 ok = ('new', 'yes')
3630 else:
3631 ok = ('yes',)
3632 # old node, get the current values from the node if they haven't
3633 # changed
3634 if not newvalues.has_key('nosy'):
3635 nosy = cl.get(nodeid, 'nosy')
3636 for value in nosy:
3637 if not current.has_key(value):
3638 current[value] = 1
3640 # if the nosy list changed in this transaction, init from the new value
3641 if newvalues.has_key('nosy'):
3642 nosy = newvalues.get('nosy', [])
3643 for value in nosy:
3644 if not db.hasnode('user', value):
3645 continue
3646 if not current.has_key(value):
3647 current[value] = 1
3649 # add users with topic in nosy_keywords to the nosy list
3650 if newvalues.has_key('topic') and newvalues['topic'] is not None:
3651 topic_ids = newvalues['topic']
3652 for topic in topic_ids:
3653 # loop over all users,
3654 # and assign user to nosy when topic in nosy_keywords
3655 for user_id in db.user.list():
3656 nosy_kw = db.user.get(user_id, "nosy_keywords")
3657 found = 0
3658 for kw in nosy_kw:
3659 if kw == topic:
3660 found = 1
3661 if found:
3662 current[user_id] = 1
3664 # that's it, save off the new nosy list
3665 newvalues['nosy'] = current.keys()
3667 and these two function are the only ones needed in the file.
3669 TODO: update this example to use the find() Class method.
3671 Caveats
3672 ~~~~~~~
3674 A few problems with the design here can be noted:
3676 Multiple additions
3677 When a user, after automatic selection, is manually removed
3678 from the nosy list, he again is added to the nosy list when the
3679 topic list of the issue is updated. A better design might be
3680 to only check which topics are new compared to the old list
3681 of topics, and only add users when they have indicated
3682 interest on a new topic.
3684 The code could also be changed to only trigger on the create() event,
3685 rather than also on the set() event, thus only setting the nosy list
3686 when the issue is created.
3688 Scalability
3689 In the auditor there is a loop over all users. For a site with
3690 only few users this will pose no serious problem, however, with
3691 many users this will be a serious performance bottleneck.
3692 A way out will be to link from the topics to the users which
3693 selected these topics a nosy topics. This will eliminate the
3694 loop over all users.
3697 Adding action links to the index page
3698 -------------------------------------
3700 Add a column to the item.index.html template.
3702 Resolving the issue::
3704 <a tal:attributes="href
3705 string:issue${i/id}?:status=resolved&:action=edit">resolve</a>
3707 "Take" the issue::
3709 <a tal:attributes="href
3710 string:issue${i/id}?:assignedto=${request/user/id}&:action=edit">take</a>
3712 ... and so on
3714 Users may only edit their issues
3715 --------------------------------
3717 Users registering themselves are granted Provisional access - meaning they
3718 have access to edit the issues they submit, but not others. We create a new
3719 Role called "Provisional User" which is granted to newly-registered users,
3720 and has limited access. One of the Permissions they have is the new "Edit
3721 Own" on issues (regular users have "Edit".) We back up the permissions with
3722 an auditor.
3724 First up, we create the new Role and Permission structure in
3725 ``dbinit.py``::
3727 # New users not approved by the admin
3728 db.security.addRole(name='Provisional User',
3729 description='New user registered via web or email')
3730 p = db.security.addPermission(name='Edit Own', klass='issue',
3731 description='Can only edit own issues')
3732 db.security.addPermissionToRole('Provisional User', p)
3734 # Assign the access and edit Permissions for issue to new users now
3735 p = db.security.getPermission('View', 'issue')
3736 db.security.addPermissionToRole('Provisional User', p)
3737 p = db.security.getPermission('Edit', 'issue')
3738 db.security.addPermissionToRole('Provisional User', p)
3740 # and give the new users access to the web and email interface
3741 p = db.security.getPermission('Web Access')
3742 db.security.addPermissionToRole('Provisional User', p)
3743 p = db.security.getPermission('Email Access')
3744 db.security.addPermissionToRole('Provisional User', p)
3747 Then in the ``config.py`` we change the Role assigned to newly-registered
3748 users, replacing the existing ``'User'`` values::
3750 NEW_WEB_USER_ROLES = 'Provisional User'
3751 NEW_EMAIL_USER_ROLES = 'Provisional User'
3753 Finally we add a new *auditor* to the ``detectors`` directory called
3754 ``provisional_user_auditor.py``::
3756 def audit_provisionaluser(db, cl, nodeid, newvalues):
3757 ''' New users are only allowed to modify their own issues.
3758 '''
3759 if (db.getuid() != cl.get(nodeid, 'creator')
3760 and db.security.hasPermission('Edit Own', db.getuid(), cl.classname)):
3761 raise ValueError, ('You are only allowed to edit your own %s'
3762 % cl.classname)
3764 def init(db):
3765 # fire before changes are made
3766 db.issue.audit('set', audit_provisionaluser)
3767 db.issue.audit('retire', audit_provisionaluser)
3768 db.issue.audit('restore', audit_provisionaluser)
3770 Note that some older trackers might also want to change the ``page.html``
3771 template as follows::
3773 <p class="classblock"
3774 - tal:condition="python:request.user.username != 'anonymous'">
3775 + tal:condition="python:request.user.hasPermission('View', 'user')">
3776 <b>Administration</b><br>
3777 <tal:block tal:condition="python:request.user.hasPermission('Edit', None)">
3778 <a href="home?:template=classlist">Class List</a><br>
3780 (note that the "-" indicates a removed line, and the "+" indicates an added
3781 line).
3784 Colouring the rows in the issue index according to priority
3785 -----------------------------------------------------------
3787 A simple ``tal:attributes`` statement will do the bulk of the work here. In
3788 the ``issue.index.html`` template, add to the ``<tr>`` that displays the
3789 actual rows of data::
3791 <tr tal:attributes="class string:priority-${i/priority/plain}">
3793 and then in your stylesheet (``style.css``) specify the colouring for the
3794 different priorities, like::
3796 tr.priority-critical td {
3797 background-color: red;
3798 }
3800 tr.priority-urgent td {
3801 background-color: orange;
3802 }
3804 and so on, with far less offensive colours :)
3806 Editing multiple items in an index view
3807 ---------------------------------------
3809 To edit the status of all items in the item index view, edit the
3810 ``issue.item.html``:
3812 1. add a form around the listing table, so at the top it reads::
3814 <form method="POST" tal:attributes="action request/classname">
3815 <table class="list">
3817 and at the bottom of that table::
3819 </table>
3820 </form
3822 making sure you match the ``</table>`` from the list table, not the
3823 navigation table or the subsequent form table.
3825 2. in the display for the issue property, change::
3827 <td tal:condition="request/show/status"
3828 tal:content="python:i.status.plain() or default"> </td>
3830 to::
3832 <td tal:condition="request/show/status"
3833 tal:content="structure i/status/field"> </td>
3835 this will result in an edit field for the status property.
3837 3. after the ``tal:block`` which lists the actual index items (marked by
3838 ``tal:repeat="i batch"``) add a new table row::
3840 <tr>
3841 <td tal:attributes="colspan python:len(request.columns)">
3842 <input type="submit" value=" Save Changes ">
3843 <input type="hidden" name="@action" value="edit">
3844 <tal:block replace="structure request/indexargs_form" />
3845 </td>
3846 </tr>
3848 which gives us a submit button, indicates that we are performing an edit
3849 on any changed statuses and the final block will make sure that the
3850 current index view parameters (filtering, columns, etc) will be used in
3851 rendering the next page (the results of the editing).
3853 -------------------
3855 Back to `Table of Contents`_
3857 .. _`Table of Contents`: index.html
3858 .. _`design documentation`: design.html