1 ===================
2 Customising Roundup
3 ===================
5 :Version: $Revision: 1.121 $
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 **DISPATCHER_EMAIL** - ``ADMIN_EMAIL``
139 The email address that roundup will issue all error messages to. This is
140 also useful, if you want to switch your 'new message' notification to
141 a central user.
143 **EMAIL_FROM_TAG** - ``''``
144 Additional text to include in the "name" part of the ``From:`` address used
145 in nosy messages. If the sending user is "Foo Bar", the ``From:`` line is
146 usually::
148 "Foo Bar" <issue_tracker@tracker.example>
150 The EMAIL_FROM_TAG goes inside the "Foo Bar" quotes like so::
152 "Foo Bar EMAIL_FROM_TAG" <issue_tracker@tracker.example>
154 **ERROR_MESSAGES_TO** - ``'user'``, ``'dispatcher'`` or ``'both'``
155 Sends error messages to the dispatcher, user, or both.
157 **MESSAGES_TO_AUTHOR** - ``'new'``, ``'yes'`` or``'no'``
158 Send nosy messages to the author of the message?
159 If 'new' is used, then the author will only be sent the message when the
160 message creates a new issue. If 'yes' then the author will always be sent
161 a copy of the message they wrote.
163 **ADD_AUTHOR_TO_NOSY** - ``'new'``, ``'yes'`` or ``'no'``
164 Does the author of a message get placed on the nosy list automatically?
165 If ``'new'`` is used, then the author will only be added when a message
166 creates a new issue. If ``'yes'``, then the author will be added on followups
167 too. If ``'no'``, they're never added to the nosy.
169 **ADD_RECIPIENTS_TO_NOSY** - ``'new'``, ``'yes'`` or ``'no'``
170 Do the recipients (To:, Cc:) of a message get placed on the nosy list?
171 If ``'new'`` is used, then the recipients will only be added when a message
172 creates a new issue. If ``'yes'``, then the recipients will be added on
173 followups too. If ``'no'``, they're never added to the nosy.
175 **EMAIL_SIGNATURE_POSITION** - ``'top'``, ``'bottom'`` or ``'none'``
176 Where to place the email signature in messages that Roundup generates.
178 **EMAIL_KEEP_QUOTED_TEXT** - ``'yes'`` or ``'no'``
179 Keep email citations. Citations are the part of e-mail which the sender has
180 quoted in their reply to previous e-mail with ``>`` or ``|`` characters at
181 the start of the line.
183 **EMAIL_LEAVE_BODY_UNCHANGED** - ``'no'``
184 Preserve the email body as is. Enabiling this will cause the entire message
185 body to be stored, including all citations, signatures and Outlook-quoted
186 sections (ie. "Original Message" blocks). It should be either ``'yes'``
187 or ``'no'``.
189 **MAIL_DEFAULT_CLASS** - ``'issue'`` or ``''``
190 Default class to use in the mailgw if one isn't supplied in email
191 subjects. To disable, comment out the variable below or leave it blank.
193 **HTML_VERSION** - ``'html4'`` or ``'xhtml'``
194 HTML version to generate. The templates are html4 by default. If you
195 wish to make them xhtml, then you'll need to change this var to 'xhtml'
196 too so all auto-generated HTML is compliant.
198 **EMAIL_CHARSET** - ``utf-8`` (or ``iso-8859-1`` for Eudora users)
199 Character set to encode email headers with. We use utf-8 by default, as
200 it's the most flexible. Some mail readers (eg. Eudora) can't cope with
201 that, so you might need to specify a more limited character set (eg.
202 'iso-8859-1'.
204 The default config.py is given below - as you
205 can see, the MAIL_DOMAIN must be edited before any interaction with the
206 tracker is attempted.::
208 # roundup home is this package's directory
209 TRACKER_HOME=os.path.split(__file__)[0]
211 # The SMTP mail host that roundup will use to send mail
212 MAILHOST = 'localhost'
214 # The domain name used for email addresses.
215 MAIL_DOMAIN = 'your.tracker.email.domain.example'
217 # This is the directory that the database is going to be stored in
218 DATABASE = os.path.join(TRACKER_HOME, 'db')
220 # This is the directory that the HTML templates reside in
221 TEMPLATES = os.path.join(TRACKER_HOME, 'html')
223 # A descriptive name for your roundup tracker
224 TRACKER_NAME = 'Roundup issue tracker'
226 # The email address that mail to roundup should go to
227 TRACKER_EMAIL = 'issue_tracker@%s'%MAIL_DOMAIN
229 # The web address that the tracker is viewable at. This will be
230 # included in information sent to users of the tracker. The URL MUST
231 # include the cgi-bin part or anything else that is required to get
232 # to the home page of the tracker. You MUST include a trailing '/'
233 # in the URL.
234 TRACKER_WEB = 'http://tracker.example/cgi-bin/roundup.cgi/bugs/'
236 # The email address that roundup will complain to if it runs into
237 # trouble
238 ADMIN_EMAIL = 'roundup-admin@%s'%MAIL_DOMAIN
240 # Additional text to include in the "name" part of the From: address
241 # used in nosy messages. If the sending user is "Foo Bar", the From:
242 # line is usually: "Foo Bar" <issue_tracker@tracker.example>
243 # the EMAIL_FROM_TAG goes inside the "Foo Bar" quotes like so:
244 # "Foo Bar EMAIL_FROM_TAG" <issue_tracker@tracker.example>
245 EMAIL_FROM_TAG = ""
247 # Send nosy messages to the author of the message
248 MESSAGES_TO_AUTHOR = 'no' # either 'yes' or 'no'
250 # Does the author of a message get placed on the nosy list
251 # automatically? If 'new' is used, then the author will only be
252 # added when a message creates a new issue. If 'yes', then the
253 # author will be added on followups too. If 'no', they're never
254 # added to the nosy.
255 ADD_AUTHOR_TO_NOSY = 'new' # one of 'yes', 'no', 'new'
257 # Do the recipients (To:, Cc:) of a message get placed on the nosy
258 # list? If 'new' is used, then the recipients will only be added
259 # when a message creates a new issue. If 'yes', then the recipients
260 # will be added on followups too. If 'no', they're never added to
261 # the nosy.
262 ADD_RECIPIENTS_TO_NOSY = 'new' # either 'yes', 'no', 'new'
264 # Where to place the email signature
265 EMAIL_SIGNATURE_POSITION = 'bottom' # one of 'top', 'bottom', 'none'
267 # Keep email citations
268 EMAIL_KEEP_QUOTED_TEXT = 'no' # either 'yes' or 'no'
270 # Preserve the email body as is
271 EMAIL_LEAVE_BODY_UNCHANGED = 'no' # either 'yes' or 'no'
273 # Default class to use in the mailgw if one isn't supplied in email
274 # subjects. To disable, comment out the variable below or leave it
275 # blank. Examples:
276 MAIL_DEFAULT_CLASS = 'issue' # use "issue" class by default
277 #MAIL_DEFAULT_CLASS = '' # disable (or just comment the var out)
279 # HTML version to generate. The templates are html4 by default. If you
280 # wish to make them xhtml, then you'll need to change this var to 'xhtml'
281 # too so all auto-generated HTML is compliant.
282 HTML_VERSION = 'html4' # either 'html4' or 'xhtml'
284 # Character set to encode email headers with. We use utf-8 by default, as
285 # it's the most flexible. Some mail readers (eg. Eudora) can't cope with
286 # that, so you might need to specify a more limited character set (eg.
287 # 'iso-8859-1'.
288 EMAIL_CHARSET = 'utf-8'
289 #EMAIL_CHARSET = 'iso-8859-1' # use this instead for Eudora users
291 #
292 # SECURITY DEFINITIONS
293 #
294 # define the Roles that a user gets when they register with the
295 # tracker these are a comma-separated string of role names (e.g.
296 # 'Admin,User')
297 NEW_WEB_USER_ROLES = 'User'
298 NEW_EMAIL_USER_ROLES = 'User'
300 Tracker Schema
301 ==============
303 Note: if you modify the schema, you'll most likely need to edit the
304 `web interface`_ HTML template files and `detectors`_ to reflect
305 your changes.
307 A tracker schema defines what data is stored in the tracker's database.
308 Schemas are defined using Python code in the ``dbinit.py`` module of your
309 tracker. The "classic" schema looks like this (see below for the meaning
310 of ``'setkey'``)::
312 pri = Class(db, "priority", name=String(), order=String())
313 pri.setkey("name")
315 stat = Class(db, "status", name=String(), order=String())
316 stat.setkey("name")
318 keyword = Class(db, "keyword", name=String())
319 keyword.setkey("name")
321 user = Class(db, "user", username=String(), organisation=String(),
322 password=String(), address=String(), realname=String(),
323 phone=String())
324 user.setkey("username")
326 msg = FileClass(db, "msg", author=Link("user"), summary=String(),
327 date=Date(), recipients=Multilink("user"),
328 files=Multilink("file"))
330 file = FileClass(db, "file", name=String(), type=String())
332 issue = IssueClass(db, "issue", topic=Multilink("keyword"),
333 status=Link("status"), assignedto=Link("user"),
334 priority=Link("priority"))
335 issue.setkey('title')
338 What you can't do to the schema
339 -------------------------------
341 You must never:
343 **Remove the users class**
344 This class is the only *required* class in Roundup. Similarly, its
345 username, password and address properties must never be removed.
347 **Change the type of a property**
348 Property types must *never* be changed - the database simply doesn't take
349 this kind of action into account. Note that you can't just remove a
350 property and re-add it as a new type either. If you wanted to make the
351 assignedto property a Multilink, you'd need to create a new property
352 assignedto_list and remove the old assignedto property.
355 What you can do to the schema
356 -----------------------------
358 Your schema may be changed at any time before or after the tracker has been
359 initialised (or used). You may:
361 **Add new properties to classes, or add whole new classes**
362 This is painless and easy to do - there are generally no repurcussions
363 from adding new information to a tracker's schema.
365 **Remove properties**
366 Removing properties is a little more tricky - you need to make sure that
367 the property is no longer used in the `web interface`_ *or* by the
368 detectors_.
372 Classes and Properties - creating a new information store
373 ---------------------------------------------------------
375 In the tracker above, we've defined 7 classes of information:
377 priority
378 Defines the possible levels of urgency for issues.
380 status
381 Defines the possible states of processing the issue may be in.
383 keyword
384 Initially empty, will hold keywords useful for searching issues.
386 user
387 Initially holding the "admin" user, will eventually have an entry
388 for all users using roundup.
390 msg
391 Initially empty, will hold all e-mail messages sent to or
392 generated by roundup.
394 file
395 Initially empty, will hold all files attached to issues.
397 issue
398 Initially empty, this is where the issue information is stored.
400 We define the "priority" and "status" classes to allow two things:
401 reduction in the amount of information stored on the issue and more
402 powerful, accurate searching of issues by priority and status. By only
403 requiring a link on the issue (which is stored as a single number) we
404 reduce the chance that someone mis-types a priority or status - or
405 simply makes a new one up.
408 Class and Items
409 ~~~~~~~~~~~~~~~
411 A Class defines a particular class (or type) of data that will be stored
412 in the database. A class comprises one or more properties, which gives
413 the information about the class items.
415 The actual data entered into the database, using ``class.create()``, are
416 called items. They have a special immutable property called ``'id'``. We
417 sometimes refer to this as the *itemid*.
420 Properties
421 ~~~~~~~~~~
423 A Class is comprised of one or more properties of the following types:
425 * String properties are for storing arbitrary-length strings.
426 * Password properties are for storing encoded arbitrary-length strings.
427 The default encoding is defined on the ``roundup.password.Password``
428 class.
429 * Date properties store date-and-time stamps. Their values are Timestamp
430 objects.
431 * Number properties store numeric values.
432 * Boolean properties store on/off, yes/no, true/false values.
433 * A Link property refers to a single other item selected from a
434 specified class. The class is part of the property; the value is an
435 integer, the id of the chosen item.
436 * A Multilink property refers to possibly many items in a specified
437 class. The value is a list of integers.
440 FileClass
441 ~~~~~~~~~
443 FileClasses save their "content" attribute off in a separate file from
444 the rest of the database. This reduces the number of large entries in
445 the database, which generally makes databases more efficient, and also
446 allows us to use command-line tools to operate on the files. They are
447 stored in the files sub-directory of the ``'db'`` directory in your
448 tracker.
451 IssueClass
452 ~~~~~~~~~~
454 IssueClasses automatically include the "messages", "files", "nosy", and
455 "superseder" properties.
457 The messages and files properties list the links to the messages and
458 files related to the issue. The nosy property is a list of links to
459 users who wish to be informed of changes to the issue - they get "CC'ed"
460 e-mails when messages are sent to or generated by the issue. The nosy
461 reactor (in the ``'detectors'`` directory) handles this action. The
462 superseder link indicates an issue which has superseded this one.
464 They also have the dynamically generated "creation", "activity" and
465 "creator" properties.
467 The value of the "creation" property is the date when an item was
468 created, and the value of the "activity" property is the date when any
469 property on the item was last edited (equivalently, these are the dates
470 on the first and last records in the item's journal). The "creator"
471 property holds a link to the user that created the issue.
474 setkey(property)
475 ~~~~~~~~~~~~~~~~
477 Select a String property of the class to be the key property. The key
478 property must be unique, and allows references to the items in the class
479 by the content of the key property. That is, we can refer to users by
480 their username: for example, let's say that there's an issue in roundup,
481 issue 23. There's also a user, richard, who happens to be user 2. To
482 assign an issue to him, we could do either of::
484 roundup-admin set issue23 assignedto=2
486 or::
488 roundup-admin set issue23 assignedto=richard
490 Note, the same thing can be done in the web and e-mail interfaces.
492 If a class does not have an "order" property, the key is also used to
493 sort instances of the class when it is rendered in the user interface.
494 (If a class has no "order" property, sorting is by the labelproperty of
495 the class. This is computed, in order of precedence, as the key, the
496 "name", the "title", or the first property alphabetically.)
499 create(information)
500 ~~~~~~~~~~~~~~~~~~~
502 Create an item in the database. This is generally used to create items
503 in the "definitional" classes like "priority" and "status".
506 Examples of adding to your schema
507 ---------------------------------
509 TODO
512 Detectors - adding behaviour to your tracker
513 ============================================
514 .. _detectors:
516 Detectors are initialised every time you open your tracker database, so
517 you're free to add and remove them any time, even after the database is
518 initialised via the "roundup-admin initialise" command.
520 The detectors in your tracker fire *before* (**auditors**) and *after*
521 (**reactors**) changes to the contents of your database. They are Python
522 modules that sit in your tracker's ``detectors`` directory. You will
523 have some installed by default - have a look. You can write new
524 detectors or modify the existing ones. The existing detectors installed
525 for you are:
527 **nosyreaction.py**
528 This provides the automatic nosy list maintenance and email sending.
529 The nosy reactor (``nosyreaction``) fires when new messages are added
530 to issues. The nosy auditor (``updatenosy``) fires when issues are
531 changed, and figures out what changes need to be made to the nosy list
532 (such as adding new authors, etc.)
533 **statusauditor.py**
534 This provides the ``chatty`` auditor which changes the issue status
535 from ``unread`` or ``closed`` to ``chatting`` if new messages appear.
536 It also provides the ``presetunread`` auditor which pre-sets the
537 status to ``unread`` on new items if the status isn't explicitly
538 defined.
539 **messagesummary.py**
540 Generates the ``summary`` property for new messages based on the message
541 content.
542 **userauditor.py**
543 Verifies the content of some of the user fields (email addresses and
544 roles lists).
546 If you don't want this default behaviour, you're completely free to change
547 or remove these detectors.
549 See the detectors section in the `design document`__ for details of the
550 interface for detectors.
552 __ design.html
554 Sample additional detectors that have been found useful will appear in
555 the ``'detectors'`` directory of the Roundup distribution. If you want
556 to use one, copy it to the ``'detectors'`` of your tracker instance:
558 **newissuecopy.py**
559 This detector sends an email to a team address whenever a new issue is
560 created. The address is hard-coded into the detector, so edit it
561 before you use it (look for the text 'team@team.host') or you'll get
562 email errors!
564 The detector code::
566 from roundup import roundupdb
568 def newissuecopy(db, cl, nodeid, oldvalues):
569 ''' Copy a message about new issues to a team address.
570 '''
571 # so use all the messages in the create
572 change_note = cl.generateCreateNote(nodeid)
574 # send a copy to the nosy list
575 for msgid in cl.get(nodeid, 'messages'):
576 try:
577 # note: last arg must be a list
578 cl.send_message(nodeid, msgid, change_note,
579 ['team@team.host'])
580 except roundupdb.MessageSendError, message:
581 raise roundupdb.DetectorError, message
583 def init(db):
584 db.issue.react('create', newissuecopy)
587 Database Content
588 ================
590 Note: if you modify the content of definitional classes, you'll most
591 likely need to edit the tracker `detectors`_ to reflect your
592 changes.
594 Customisation of the special "definitional" classes (eg. status,
595 priority, resolution, ...) may be done either before or after the
596 tracker is initialised. The actual method of doing so is completely
597 different in each case though, so be careful to use the right one.
599 **Changing content before tracker initialisation**
600 Edit the dbinit module in your tracker to alter the items created in
601 using the ``create()`` methods.
603 **Changing content after tracker initialisation**
604 As the "admin" user, click on the "class list" link in the web
605 interface to bring up a list of all database classes. Click on the
606 name of the class you wish to change the content of.
608 You may also use the ``roundup-admin`` interface's create, set and
609 retire methods to add, alter or remove items from the classes in
610 question.
612 See "`adding a new field to the classic schema`_" for an example that
613 requires database content changes.
616 Security / Access Controls
617 ==========================
619 A set of Permissions is built into the security module by default:
621 - Edit (everything)
622 - View (everything)
624 Every Class you define in your tracker's schema also gets an Edit and View
625 Permission of its own.
627 The default interfaces define:
629 - Web Registration
630 - Web Access
631 - Web Roles
632 - Email Registration
633 - Email Access
635 These are hooked into the default Roles:
637 - Admin (Edit everything, View everything, Web Roles)
638 - User (Web Access, Email Access)
639 - Anonymous (Web Registration, Email Registration)
641 And finally, the "admin" user gets the "Admin" Role, and the "anonymous"
642 user gets "Anonymous" assigned when the database is initialised on
643 installation. The two default schemas then define:
645 - Edit issue, View issue (both)
646 - Edit file, View file (both)
647 - Edit msg, View msg (both)
648 - Edit support, View support (extended only)
650 and assign those Permissions to the "User" Role. Put together, these
651 settings appear in the ``open()`` function of the tracker ``dbinit.py``
652 (the following is taken from the "minimal" template's ``dbinit.py``)::
654 #
655 # SECURITY SETTINGS
656 #
657 # and give the regular users access to the web and email interface
658 p = db.security.getPermission('Web Access')
659 db.security.addPermissionToRole('User', p)
660 p = db.security.getPermission('Email Access')
661 db.security.addPermissionToRole('User', p)
663 # May users view other user information? Comment these lines out
664 # if you don't want them to
665 p = db.security.getPermission('View', 'user')
666 db.security.addPermissionToRole('User', p)
668 # Assign the appropriate permissions to the anonymous user's
669 # Anonymous role. Choices here are:
670 # - Allow anonymous users to register through the web
671 p = db.security.getPermission('Web Registration')
672 db.security.addPermissionToRole('Anonymous', p)
673 # - Allow anonymous (new) users to register through the email
674 # gateway
675 p = db.security.getPermission('Email Registration')
676 db.security.addPermissionToRole('Anonymous', p)
679 New User Roles
680 --------------
682 New users are assigned the Roles defined in the config file as:
684 - NEW_WEB_USER_ROLES
685 - NEW_EMAIL_USER_ROLES
688 Changing Access Controls
689 ------------------------
691 You may alter the configuration variables to change the Role that new
692 web or email users get, for example to not give them access to the web
693 interface if they register through email.
695 You may use the ``roundup-admin`` "``security``" command to display the
696 current Role and Permission configuration in your tracker.
699 Adding a new Permission
700 ~~~~~~~~~~~~~~~~~~~~~~~
702 When adding a new Permission, you will need to:
704 1. add it to your tracker's dbinit so it is created, using
705 ``security.addPermission``, for example::
707 self.security.addPermission(name="View", klass='frozzle',
708 description="User is allowed to access frozzles")
710 will set up a new "View" permission on the Class "frozzle".
711 2. enable it for the Roles that should have it (verify with
712 "``roundup-admin security``")
713 3. add it to the relevant HTML interface templates
714 4. add it to the appropriate xxxPermission methods on in your tracker
715 interfaces module
718 Example Scenarios
719 ~~~~~~~~~~~~~~~~~
721 **automatic registration of users in the e-mail gateway**
722 By giving the "anonymous" user the "Email Registration" Role, any
723 unidentified user will automatically be registered with the tracker
724 (with no password, so they won't be able to log in through the web
725 until an admin sets their password). Note: this is the default
726 behaviour in the tracker templates that ship with Roundup.
728 **anonymous access through the e-mail gateway**
729 Give the "anonymous" user the "Email Access" and ("Edit", "issue")
730 Roles but do not not give them the "Email Registration" Role. This
731 means that when an unknown user sends email into the tracker, they're
732 automatically logged in as "anonymous". Since they don't have the
733 "Email Registration" Role, they won't be automatically registered, but
734 since "anonymous" has permission to use the gateway, they'll still be
735 able to submit issues. Note that the Sender information - their email
736 address - will not be available - they're *anonymous*.
738 **only developers may be assigned issues**
739 Create a new Permission called "Fixer" for the "issue" class. Create a
740 new Role "Developer" which has that Permission, and assign that to the
741 appropriate users. Filter the list of users available in the assignedto
742 list to include only those users. Enforce the Permission with an
743 auditor. See the example
744 `restricting the list of users that are assignable to a task`_.
746 **only managers may sign off issues as complete**
747 Create a new Permission called "Closer" for the "issue" class. Create a
748 new Role "Manager" which has that Permission, and assign that to the
749 appropriate users. In your web interface, only display the "resolved"
750 issue state option when the user has the "Closer" Permissions. Enforce
751 the Permission with an auditor. This is very similar to the previous
752 example, except that the web interface check would look like::
754 <option tal:condition="python:request.user.hasPermission('Closer')"
755 value="resolved">Resolved</option>
757 **don't give web access to users who register through email**
758 Create a new Role called "Email User" which has all the Permissions of
759 the normal "User" Role minus the "Web Access" Permission. This will
760 allow users to send in emails to the tracker, but not access the web
761 interface.
763 **let some users edit the details of all users**
764 Create a new Role called "User Admin" which has the Permission for
765 editing users::
767 db.security.addRole(name='User Admin', description='Managing users')
768 p = db.security.getPermission('Edit', 'user')
769 db.security.addPermissionToRole('User Admin', p)
771 and assign the Role to the users who need the permission.
774 Web Interface
775 =============
777 .. contents::
778 :local:
779 :depth: 1
781 The web interface is provided by the ``roundup.cgi.client`` module and
782 is used by ``roundup.cgi``, ``roundup-server`` and ``ZRoundup``
783 (``ZRoundup`` is broken, until further notice). In all cases, we
784 determine which tracker is being accessed (the first part of the URL
785 path inside the scope of the CGI handler) and pass control on to the
786 tracker ``interfaces.Client`` class - which uses the ``Client`` class
787 from ``roundup.cgi.client`` - which handles the rest of the access
788 through its ``main()`` method. This means that you can do pretty much
789 anything you want as a web interface to your tracker.
791 Repercussions of changing the tracker schema
792 ---------------------------------------------
794 If you choose to change the `tracker schema`_ you will need to ensure
795 the web interface knows about it:
797 1. Index, item and search pages for the relevant classes may need to
798 have properties added or removed,
799 2. The "page" template may require links to be changed, as might the
800 "home" page's content arguments.
802 How requests are processed
803 --------------------------
805 The basic processing of a web request proceeds as follows:
807 1. figure out who we are, defaulting to the "anonymous" user
808 2. figure out what the request is for - we call this the "context"
809 3. handle any requested action (item edit, search, ...)
810 4. render the template requested by the context, resulting in HTML
811 output
813 In some situations, exceptions occur:
815 - HTTP Redirect (generally raised by an action)
816 - SendFile (generally raised by ``determine_context``)
817 here we serve up a FileClass "content" property
818 - SendStaticFile (generally raised by ``determine_context``)
819 here we serve up a file from the tracker "html" directory
820 - Unauthorised (generally raised by an action)
821 here the action is cancelled, the request is rendered and an error
822 message is displayed indicating that permission was not granted for
823 the action to take place
824 - NotFound (raised wherever it needs to be)
825 this exception percolates up to the CGI interface that called the
826 client
828 Determining web context
829 -----------------------
831 To determine the "context" of a request, we look at the URL and the
832 special request variable ``@template``. The URL path after the tracker
833 identifier is examined. Typical URL paths look like:
835 1. ``/tracker/issue``
836 2. ``/tracker/issue1``
837 3. ``/tracker/_file/style.css``
838 4. ``/cgi-bin/roundup.cgi/tracker/file1``
839 5. ``/cgi-bin/roundup.cgi/tracker/file1/kitten.png``
841 where the "tracker identifier" is "tracker" in the above cases. That means
842 we're looking at "issue", "issue1", "_file/style.css", "file1" and
843 "file1/kitten.png" in the cases above. The path is generally only one
844 entry long - longer paths are handled differently.
846 a. if there is no path, then we are in the "home" context.
847 b. if the path starts with "_file" (as in example 3,
848 "/tracker/_file/style.css"), then the additional path entry,
849 "style.css" specifies the filename of a static file we're to serve up
850 from the tracker "html" directory. Raises a SendStaticFile exception.
851 c. if there is something in the path (as in example 1, "issue"), it
852 identifies the tracker class we're to display.
853 d. if the path is an item designator (as in examples 2 and 4, "issue1"
854 and "file1"), then we're to display a specific item.
855 e. if the path starts with an item designator and is longer than one
856 entry (as in example 5, "file1/kitten.png"), then we're assumed to be
857 handling an item of a ``FileClass``, and the extra path information
858 gives the filename that the client is going to label the download
859 with (i.e. "file1/kitten.png" is nicer to download than "file1").
860 This raises a ``SendFile`` exception.
862 Both b. and e. stop before we bother to determine the template we're
863 going to use. That's because they don't actually use templates.
865 The template used is specified by the ``@template`` CGI variable, which
866 defaults to:
868 - only classname suplied: "index"
869 - full item designator supplied: "item"
872 Performing actions in web requests
873 ----------------------------------
875 When a user requests a web page, they may optionally also request for an
876 action to take place. As described in `how requests are processed`_, the
877 action is performed before the requested page is generated. Actions are
878 triggered by using a ``@action`` CGI variable, where the value is one
879 of:
881 **login**
882 Attempt to log a user in.
884 **logout**
885 Log the user out - make them "anonymous".
887 **register**
888 Attempt to create a new user based on the contents of the form and then
889 log them in.
891 **edit**
892 Perform an edit of an item in the database. There are some `special form
893 variables`_ you may use.
895 **new**
896 Add a new item to the database. You may use the same `special form
897 variables`_ as in the "edit" action.
899 **retire**
900 Retire the item in the database.
902 **editCSV**
903 Performs an edit of all of a class' items in one go. See also the
904 *class*.csv templating method which generates the CSV data to be
905 edited, and the ``'_generic.index'`` template which uses both of these
906 features.
908 **search**
909 Mangle some of the form variables:
911 - Set the form ":filter" variable based on the values of the filter
912 variables - if they're set to anything other than "dontcare" then add
913 them to :filter.
915 - Also handle the ":queryname" variable and save off the query to the
916 user's query list.
918 Each of the actions is implemented by a corresponding ``*XxxAction*`` (where
919 "Xxx" is the name of the action) class in the ``roundup.cgi.actions`` module.
920 These classes are registered with ``roundup.cgi.client.Client`` which also
921 happens to be available in your tracker instance as ``interfaces.Client``. So
922 if you need to define new actions, you may add them there (see `defining new
923 web actions`_).
925 Each action class also has a ``*permission*`` method which determines whether
926 the action is permissible given the current user. The base permission checks
927 are:
929 **login**
930 Determine whether the user has permission to log in. Base behaviour is
931 to check the user has "Web Access".
932 **logout**
933 No permission checks are made.
934 **register**
935 Determine whether the user has permission to register. Base behaviour
936 is to check the user has the "Web Registration" Permission.
937 **edit**
938 Determine whether the user has permission to edit this item. Base
939 behaviour is to check whether the user can edit this class. If we're
940 editing the "user" class, users are allowed to edit their own details -
941 unless they try to edit the "roles" property, which requires the
942 special Permission "Web Roles".
943 **new**
944 Determine whether the user has permission to create (or edit) this
945 item. Base behaviour is to check the user can edit this class. No
946 additional property checks are made. Additionally, new user items may
947 be created if the user has the "Web Registration" Permission.
948 **editCSV**
949 Determine whether the user has permission to edit this class. Base
950 behaviour is to check whether the user may edit this class.
951 **search**
952 Determine whether the user has permission to search this class. Base
953 behaviour is to check whether the user may view this class.
956 Special form variables
957 ----------------------
959 Item properties and their values are edited with html FORM
960 variables and their values. You can:
962 - Change the value of some property of the current item.
963 - Create a new item of any class, and edit the new item's
964 properties,
965 - Attach newly created items to a multilink property of the
966 current item.
967 - Remove items from a multilink property of the current item.
968 - Specify that some properties are required for the edit
969 operation to be successful.
971 In the following, <bracketed> values are variable, "@" may be
972 either ":" or "@", and other text "required" is fixed.
974 Most properties are specified as form variables:
976 ``<propname>``
977 property on the current context item
979 ``<designator>"@"<propname>``
980 property on the indicated item (for editing related information)
982 Designators name a specific item of a class.
984 ``<classname><N>``
985 Name an existing item of class <classname>.
987 ``<classname>"-"<N>``
988 Name the <N>th new item of class <classname>. If the form
989 submission is successful, a new item of <classname> is
990 created. Within the submitted form, a particular
991 designator of this form always refers to the same new
992 item.
994 Once we have determined the "propname", we look at it to see
995 if it's special:
997 ``@required``
998 The associated form value is a comma-separated list of
999 property names that must be specified when the form is
1000 submitted for the edit operation to succeed.
1002 When the <designator> is missing, the properties are
1003 for the current context item. When <designator> is
1004 present, they are for the item specified by
1005 <designator>.
1007 The "@required" specifier must come before any of the
1008 properties it refers to are assigned in the form.
1010 ``@remove@<propname>=id(s)`` or ``@add@<propname>=id(s)``
1011 The "@add@" and "@remove@" edit actions apply only to
1012 Multilink properties. The form value must be a
1013 comma-separate list of keys for the class specified by
1014 the simple form variable. The listed items are added
1015 to (respectively, removed from) the specified
1016 property.
1018 ``@link@<propname>=<designator>``
1019 If the edit action is "@link@", the simple form
1020 variable must specify a Link or Multilink property.
1021 The form value is a comma-separated list of
1022 designators. The item corresponding to each
1023 designator is linked to the property given by simple
1024 form variable.
1026 None of the above (ie. just a simple form value)
1027 The value of the form variable is converted
1028 appropriately, depending on the type of the property.
1030 For a Link('klass') property, the form value is a
1031 single key for 'klass', where the key field is
1032 specified in dbinit.py.
1034 For a Multilink('klass') property, the form value is a
1035 comma-separated list of keys for 'klass', where the
1036 key field is specified in dbinit.py.
1038 Note that for simple-form-variables specifiying Link
1039 and Multilink properties, the linked-to class must
1040 have a key field.
1042 For a String() property specifying a filename, the
1043 file named by the form value is uploaded. This means we
1044 try to set additional properties "filename" and "type" (if
1045 they are valid for the class). Otherwise, the property
1046 is set to the form value.
1048 For Date(), Interval(), Boolean(), and Number()
1049 properties, the form value is converted to the
1050 appropriate
1052 Any of the form variables may be prefixed with a classname or
1053 designator.
1055 Two special form values are supported for backwards compatibility:
1057 @note
1058 This is equivalent to::
1060 @link@messages=msg-1
1061 msg-1@content=value
1063 except that in addition, the "author" and "date" properties of
1064 "msg-1" are set to the userid of the submitter, and the current
1065 time, respectively.
1067 @file
1068 This is equivalent to::
1070 @link@files=file-1
1071 file-1@content=value
1073 The String content value is handled as described above for file
1074 uploads.
1076 If both the "@note" and "@file" form variables are
1077 specified, the action::
1079 @link@msg-1@files=file-1
1081 is also performed.
1083 We also check that FileClass items have a "content" property with
1084 actual content, otherwise we remove them from all_props before
1085 returning.
1089 Default templates
1090 -----------------
1092 The default templates are html4 compliant. If you wish to change them to be
1093 xhtml compliant, you'll need to change the ``HTML_VERSION`` configuration
1094 variable in ``config.py`` to ``'xhtml'`` instead of ``'html4'``.
1096 Most customisation of the web view can be done by modifying the
1097 templates in the tracker ``'html'`` directory. There are several types
1098 of files in there. The *minimal* template includes:
1100 **page.html**
1101 This template usually defines the overall look of your tracker. When
1102 you view an issue, it appears inside this template. When you view an
1103 index, it also appears inside this template. This template defines a
1104 macro called "icing" which is used by almost all other templates as a
1105 coating for their content, using its "content" slot. It also defines
1106 the "head_title" and "body_title" slots to allow setting of the page
1107 title.
1108 **home.html**
1109 the default page displayed when no other page is indicated by the user
1110 **home.classlist.html**
1111 a special version of the default page that lists the classes in the
1112 tracker
1113 **classname.item.html**
1114 displays an item of the *classname* class
1115 **classname.index.html**
1116 displays a list of *classname* items
1117 **classname.search.html**
1118 displays a search page for *classname* items
1119 **_generic.index.html**
1120 used to display a list of items where there is no
1121 ``*classname*.index`` available
1122 **_generic.help.html**
1123 used to display a "class help" page where there is no
1124 ``*classname*.help``
1125 **user.register.html**
1126 a special page just for the user class, that renders the registration
1127 page
1128 **style.css.html**
1129 a static file that is served up as-is
1131 The *classic* template has a number of additional templates.
1133 Note: Remember that you can create any template extension you want to,
1134 so if you just want to play around with the templating for new issues,
1135 you can copy the current "issue.item" template to "issue.test", and then
1136 access the test template using the "@template" URL argument::
1138 http://your.tracker.example/tracker/issue?@template=test
1140 and it won't affect your users using the "issue.item" template.
1143 How the templates work
1144 ----------------------
1147 Basic Templating Actions
1148 ~~~~~~~~~~~~~~~~~~~~~~~~
1150 Roundup's templates consist of special attributes on the HTML tags.
1151 These attributes form the Template Attribute Language, or TAL. The basic
1152 TAL commands are:
1154 **tal:define="variable expression; variable expression; ..."**
1155 Define a new variable that is local to this tag and its contents. For
1156 example::
1158 <html tal:define="title request/description">
1159 <head><title tal:content="title"></title></head>
1160 </html>
1162 In this example, the variable "title" is defined as the result of the
1163 expression "request/description". The "tal:content" command inside the
1164 <html> tag may then use the "title" variable.
1166 **tal:condition="expression"**
1167 Only keep this tag and its contents if the expression is true. For
1168 example::
1170 <p tal:condition="python:request.user.hasPermission('View', 'issue')">
1171 Display some issue information.
1172 </p>
1174 In the example, the <p> tag and its contents are only displayed if
1175 the user has the "View" permission for issues. We consider the number
1176 zero, a blank string, an empty list, and the built-in variable
1177 nothing to be false values. Nearly every other value is true,
1178 including non-zero numbers, and strings with anything in them (even
1179 spaces!).
1181 **tal:repeat="variable expression"**
1182 Repeat this tag and its contents for each element of the sequence
1183 that the expression returns, defining a new local variable and a
1184 special "repeat" variable for each element. For example::
1186 <tr tal:repeat="u user/list">
1187 <td tal:content="u/id"></td>
1188 <td tal:content="u/username"></td>
1189 <td tal:content="u/realname"></td>
1190 </tr>
1192 The example would iterate over the sequence of users returned by
1193 "user/list" and define the local variable "u" for each entry.
1195 **tal:replace="expression"**
1196 Replace this tag with the result of the expression. For example::
1198 <span tal:replace="request/user/realname" />
1200 The example would replace the <span> tag and its contents with the
1201 user's realname. If the user's realname was "Bruce", then the
1202 resultant output would be "Bruce".
1204 **tal:content="expression"**
1205 Replace the contents of this tag with the result of the expression.
1206 For example::
1208 <span tal:content="request/user/realname">user's name appears here
1209 </span>
1211 The example would replace the contents of the <span> tag with the
1212 user's realname. If the user's realname was "Bruce" then the
1213 resultant output would be "<span>Bruce</span>".
1215 **tal:attributes="attribute expression; attribute expression; ..."**
1216 Set attributes on this tag to the results of expressions. For
1217 example::
1219 <a tal:attributes="href string:user${request/user/id}">My Details</a>
1221 In the example, the "href" attribute of the <a> tag is set to the
1222 value of the "string:user${request/user/id}" expression, which will
1223 be something like "user123".
1225 **tal:omit-tag="expression"**
1226 Remove this tag (but not its contents) if the expression is true. For
1227 example::
1229 <span tal:omit-tag="python:1">Hello, world!</span>
1231 would result in output of::
1233 Hello, world!
1235 Note that the commands on a given tag are evaulated in the order above,
1236 so *define* comes before *condition*, and so on.
1238 Additionally, you may include tags such as <tal:block>, which are
1239 removed from output. Its content is kept, but the tag itself is not (so
1240 don't go using any "tal:attributes" commands on it). This is useful for
1241 making arbitrary blocks of HTML conditional or repeatable (very handy
1242 for repeating multiple table rows, which would othewise require an
1243 illegal tag placement to effect the repeat).
1246 Templating Expressions
1247 ~~~~~~~~~~~~~~~~~~~~~~
1249 The expressions you may use in the attribute values may be one of the
1250 following forms:
1252 **Path Expressions** - eg. ``item/status/checklist``
1253 These are object attribute / item accesses. Roughly speaking, the
1254 path ``item/status/checklist`` is broken into parts ``item``,
1255 ``status`` and ``checklist``. The ``item`` part is the root of the
1256 expression. We then look for a ``status`` attribute on ``item``, or
1257 failing that, a ``status`` item (as in ``item['status']``). If that
1258 fails, the path expression fails. When we get to the end, the object
1259 we're left with is evaluated to get a string - if it is a method, it
1260 is called; if it is an object, it is stringified. Path expressions
1261 may have an optional ``path:`` prefix, but they are the default
1262 expression type, so it's not necessary.
1264 If an expression evaluates to ``default``, then the expression is
1265 "cancelled" - whatever HTML already exists in the template will
1266 remain (tag content in the case of ``tal:content``, attributes in the
1267 case of ``tal:attributes``).
1269 If an expression evaluates to ``nothing`` then the target of the
1270 expression is removed (tag content in the case of ``tal:content``,
1271 attributes in the case of ``tal:attributes`` and the tag itself in
1272 the case of ``tal:replace``).
1274 If an element in the path may not exist, then you can use the ``|``
1275 operator in the expression to provide an alternative. So, the
1276 expression ``request/form/foo/value | default`` would simply leave
1277 the current HTML in place if the "foo" form variable doesn't exist.
1279 You may use the python function ``path``, as in
1280 ``path("item/status")``, to embed path expressions in Python
1281 expressions.
1283 **String Expressions** - eg. ``string:hello ${user/name}``
1284 These expressions are simple string interpolations - though they can
1285 be just plain strings with no interpolation if you want. The
1286 expression in the ``${ ... }`` is just a path expression as above.
1288 **Python Expressions** - eg. ``python: 1+1``
1289 These expressions give the full power of Python. All the "root level"
1290 variables are available, so ``python:item.status.checklist()`` would
1291 be equivalent to ``item/status/checklist``, assuming that
1292 ``checklist`` is a method.
1294 Modifiers:
1296 **structure** - eg. ``structure python:msg.content.plain(hyperlink=1)``
1297 The result of expressions are normally *escaped* to be safe for HTML
1298 display (all "<", ">" and "&" are turned into special entities). The
1299 ``structure`` expression modifier turns off this escaping - the
1300 result of the expression is now assumed to be HTML, which is passed
1301 to the web browser for rendering.
1303 **not:** - eg. ``not:python:1=1``
1304 This simply inverts the logical true/false value of another
1305 expression.
1308 Template Macros
1309 ~~~~~~~~~~~~~~~
1311 Macros are used in Roundup to save us from repeating the same common
1312 page stuctures over and over. The most common (and probably only) macro
1313 you'll use is the "icing" macro defined in the "page" template.
1315 Macros are generated and used inside your templates using special
1316 attributes similar to the `basic templating actions`_. In this case,
1317 though, the attributes belong to the Macro Expansion Template Attribute
1318 Language, or METAL. The macro commands are:
1320 **metal:define-macro="macro name"**
1321 Define that the tag and its contents are now a macro that may be
1322 inserted into other templates using the *use-macro* command. For
1323 example::
1325 <html metal:define-macro="page">
1326 ...
1327 </html>
1329 defines a macro called "page" using the ``<html>`` tag and its
1330 contents. Once defined, macros are stored on the template they're
1331 defined on in the ``macros`` attribute. You can access them later on
1332 through the ``templates`` variable, eg. the most common
1333 ``templates/page/macros/icing`` to access the "page" macro of the
1334 "page" template.
1336 **metal:use-macro="path expression"**
1337 Use a macro, which is identified by the path expression (see above).
1338 This will replace the current tag with the identified macro contents.
1339 For example::
1341 <tal:block metal:use-macro="templates/page/macros/icing">
1342 ...
1343 </tal:block>
1345 will replace the tag and its contents with the "page" macro of the
1346 "page" template.
1348 **metal:define-slot="slot name"** and **metal:fill-slot="slot name"**
1349 To define *dynamic* parts of the macro, you define "slots" which may
1350 be filled when the macro is used with a *use-macro* command. For
1351 example, the ``templates/page/macros/icing`` macro defines a slot like
1352 so::
1354 <title metal:define-slot="head_title">title goes here</title>
1356 In your *use-macro* command, you may now use a *fill-slot* command
1357 like this::
1359 <title metal:fill-slot="head_title">My Title</title>
1361 where the tag that fills the slot completely replaces the one defined
1362 as the slot in the macro.
1364 Note that you may not mix METAL and TAL commands on the same tag, but
1365 TAL commands may be used freely inside METAL-using tags (so your
1366 *fill-slots* tags may have all manner of TAL inside them).
1369 Information available to templates
1370 ----------------------------------
1372 Note: this is implemented by
1373 ``roundup.cgi.templating.RoundupPageTemplate``
1375 The following variables are available to templates.
1377 **context**
1378 The current context. This is either None, a `hyperdb class wrapper`_
1379 or a `hyperdb item wrapper`_
1380 **request**
1381 Includes information about the current request, including:
1382 - the current index information (``filterspec``, ``filter`` args,
1383 ``properties``, etc) parsed out of the form.
1384 - methods for easy filterspec link generation
1385 - *user*, the current user item as an HTMLItem instance
1386 - *form*
1387 The current CGI form information as a mapping of form argument name
1388 to value
1389 **config**
1390 This variable holds all the values defined in the tracker config.py
1391 file (eg. TRACKER_NAME, etc.)
1392 **db**
1393 The current database, used to access arbitrary database items.
1394 **templates**
1395 Access to all the tracker templates by name. Used mainly in
1396 *use-macro* commands.
1397 **utils**
1398 This variable makes available some utility functions like batching.
1399 **nothing**
1400 This is a special variable - if an expression evaluates to this, then
1401 the tag (in the case of a ``tal:replace``), its contents (in the case
1402 of ``tal:content``) or some attributes (in the case of
1403 ``tal:attributes``) will not appear in the the output. So, for
1404 example::
1406 <span tal:attributes="class nothing">Hello, World!</span>
1408 would result in::
1410 <span>Hello, World!</span>
1412 **default**
1413 Also a special variable - if an expression evaluates to this, then the
1414 existing HTML in the template will not be replaced or removed, it will
1415 remain. So::
1417 <span tal:replace="default">Hello, World!</span>
1419 would result in::
1421 <span>Hello, World!</span>
1424 The context variable
1425 ~~~~~~~~~~~~~~~~~~~~
1427 The *context* variable is one of three things based on the current
1428 context (see `determining web context`_ for how we figure this out):
1430 1. if we're looking at a "home" page, then it's None
1431 2. if we're looking at a specific hyperdb class, it's a
1432 `hyperdb class wrapper`_.
1433 3. if we're looking at a specific hyperdb item, it's a
1434 `hyperdb item wrapper`_.
1436 If the context is not None, we can access the properties of the class or
1437 item. The only real difference between cases 2 and 3 above are:
1439 1. the properties may have a real value behind them, and this will
1440 appear if the property is displayed through ``context/property`` or
1441 ``context/property/field``.
1442 2. the context's "id" property will be a false value in the second case,
1443 but a real, or true value in the third. Thus we can determine whether
1444 we're looking at a real item from the hyperdb by testing
1445 "context/id".
1447 Hyperdb class wrapper
1448 :::::::::::::::::::::
1450 Note: this is implemented by the ``roundup.cgi.templating.HTMLClass``
1451 class.
1453 This wrapper object provides access to a hyperb class. It is used
1454 primarily in both index view and new item views, but it's also usable
1455 anywhere else that you wish to access information about a class, or the
1456 items of a class, when you don't have a specific item of that class in
1457 mind.
1459 We allow access to properties. There will be no "id" property. The value
1460 accessed through the property will be the current value of the same name
1461 from the CGI form.
1463 There are several methods available on these wrapper objects:
1465 =========== =============================================================
1466 Method Description
1467 =========== =============================================================
1468 properties return a `hyperdb property wrapper`_ for all of this class's
1469 properties.
1470 list lists all of the active (not retired) items in the class.
1471 csv return the items of this class as a chunk of CSV text.
1472 propnames lists the names of the properties of this class.
1473 filter lists of items from this class, filtered and sorted by the
1474 current *request* filterspec/filter/sort/group args
1475 classhelp display a link to a javascript popup containing this class'
1476 "help" template.
1477 submit generate a submit button (and action hidden element)
1478 renderWith render this class with the given template.
1479 history returns 'New node - no history' :)
1480 is_edit_ok is the user allowed to Edit the current class?
1481 is_view_ok is the user allowed to View the current class?
1482 =========== =============================================================
1484 Note that if you have a property of the same name as one of the above
1485 methods, you'll need to access it using a python "item access"
1486 expression. For example::
1488 python:context['list']
1490 will access the "list" property, rather than the list method.
1493 Hyperdb item wrapper
1494 ::::::::::::::::::::
1496 Note: this is implemented by the ``roundup.cgi.templating.HTMLItem``
1497 class.
1499 This wrapper object provides access to a hyperb item.
1501 We allow access to properties. There will be no "id" property. The value
1502 accessed through the property will be the current value of the same name
1503 from the CGI form.
1505 There are several methods available on these wrapper objects:
1507 =============== ========================================================
1508 Method Description
1509 =============== ========================================================
1510 submit generate a submit button (and action hidden element)
1511 journal return the journal of the current item (**not
1512 implemented**)
1513 history render the journal of the current item as HTML
1514 renderQueryForm specific to the "query" class - render the search form
1515 for the query
1516 hasPermission specific to the "user" class - determine whether the
1517 user has a Permission
1518 is_edit_ok is the user allowed to Edit the current item?
1519 is_view_ok is the user allowed to View the current item?
1520 =============== ========================================================
1522 Note that if you have a property of the same name as one of the above
1523 methods, you'll need to access it using a python "item access"
1524 expression. For example::
1526 python:context['journal']
1528 will access the "journal" property, rather than the journal method.
1531 Hyperdb property wrapper
1532 ::::::::::::::::::::::::
1534 Note: this is implemented by subclasses of the
1535 ``roundup.cgi.templating.HTMLProperty`` class (``HTMLStringProperty``,
1536 ``HTMLNumberProperty``, and so on).
1538 This wrapper object provides access to a single property of a class. Its
1539 value may be either:
1541 1. if accessed through a `hyperdb item wrapper`_, then it's a value from
1542 the hyperdb
1543 2. if access through a `hyperdb class wrapper`_, then it's a value from
1544 the CGI form
1547 The property wrapper has some useful attributes:
1549 =============== ========================================================
1550 Attribute Description
1551 =============== ========================================================
1552 _name the name of the property
1553 _value the value of the property if any - this is the actual
1554 value retrieved from the hyperdb for this property
1555 =============== ========================================================
1557 There are several methods available on these wrapper objects:
1559 =========== ================================================================
1560 Method Description
1561 =========== ================================================================
1562 plain render a "plain" representation of the property. This method
1563 may take two arguments:
1565 escape
1566 If true, escape the text so it is HTML safe (default: no). The
1567 reason this defaults to off is that text is usually escaped
1568 at a later stage by the TAL commands, unless the "structure"
1569 option is used in the template. The following ``tal:content``
1570 expressions are all equivalent::
1572 "structure python:msg.content.plain(escape=1)"
1573 "python:msg.content.plain()"
1574 "msg/content/plain"
1575 "msg/content"
1577 Usually you'll only want to use the escape option in a
1578 complex expression.
1580 hyperlink
1581 If true, turn URLs, email addresses and hyperdb item
1582 designators in the text into hyperlinks (default: no). Note
1583 that you'll need to use the "structure" TAL option if you
1584 want to use this ``tal:content`` expression::
1586 "structure python:msg.content.plain(hyperlink=1)"
1588 Note also that the text is automatically HTML-escaped before
1589 the hyperlinking transformation.
1590 hyperlinked The same as msg.content.plain(hyperlink=1), but nicer::
1592 "structure msg/content/hyperlinked"
1594 field render an appropriate form edit field for the property - for
1595 most types this is a text entry box, but for Booleans it's a
1596 tri-state yes/no/neither selection.
1597 stext only on String properties - render the value of the property
1598 as StructuredText (requires the StructureText module to be
1599 installed separately)
1600 multiline only on String properties - render a multiline form edit
1601 field for the property
1602 email only on String properties - render the value of the property
1603 as an obscured email address
1604 confirm only on Password properties - render a second form edit field
1605 for the property, used for confirmation that the user typed
1606 the password correctly. Generates a field with name
1607 "name:confirm".
1608 now only on Date properties - return the current date as a new
1609 property
1610 reldate only on Date properties - render the interval between the date
1611 and now
1612 local only on Date properties - return this date as a new property
1613 with some timezone offset, for example::
1615 python:context.creation.local(10)
1617 will render the date with a +10 hour offset.
1618 pretty Date properties - render the date as "dd Mon YYYY" (eg. "19
1619 Mar 2004"). Takes an optional format argument, for example::
1621 python:context.activity.pretty('%Y-%m-%d')
1623 Will format as "2004-03-19" instead.
1625 Interval properties - render the interval in a pretty
1626 format (eg. "yesterday")
1627 menu only on Link and Multilink properties - render a form select
1628 list for this property
1629 reverse only on Multilink properties - produce a list of the linked
1630 items in reverse order
1631 =========== ================================================================
1634 The request variable
1635 ~~~~~~~~~~~~~~~~~~~~
1637 Note: this is implemented by the ``roundup.cgi.templating.HTMLRequest``
1638 class.
1640 The request variable is packed with information about the current
1641 request.
1643 .. taken from ``roundup.cgi.templating.HTMLRequest`` docstring
1645 =========== ============================================================
1646 Variable Holds
1647 =========== ============================================================
1648 form the CGI form as a cgi.FieldStorage
1649 env the CGI environment variables
1650 base the base URL for this tracker
1651 user a HTMLUser instance for this user
1652 classname the current classname (possibly None)
1653 template the current template (suffix, also possibly None)
1654 form the current CGI form variables in a FieldStorage
1655 =========== ============================================================
1657 **Index page specific variables (indexing arguments)**
1659 =========== ============================================================
1660 Variable Holds
1661 =========== ============================================================
1662 columns dictionary of the columns to display in an index page
1663 show a convenience access to columns - request/show/colname will
1664 be true if the columns should be displayed, false otherwise
1665 sort index sort column (direction, column name)
1666 group index grouping property (direction, column name)
1667 filter properties to filter the index on
1668 filterspec values to filter the index on
1669 search_text text to perform a full-text search on for an index
1670 =========== ============================================================
1672 There are several methods available on the request variable:
1674 =============== ========================================================
1675 Method Description
1676 =============== ========================================================
1677 description render a description of the request - handle for the
1678 page title
1679 indexargs_form render the current index args as form elements
1680 indexargs_url render the current index args as a URL
1681 base_javascript render some javascript that is used by other components
1682 of the templating
1683 batch run the current index args through a filter and return a
1684 list of items (see `hyperdb item wrapper`_, and
1685 `batching`_)
1686 =============== ========================================================
1688 The form variable
1689 :::::::::::::::::
1691 The form variable is a bit special because it's actually a python
1692 FieldStorage object. That means that you have two ways to access its
1693 contents. For example, to look up the CGI form value for the variable
1694 "name", use the path expression::
1696 request/form/name/value
1698 or the python expression::
1700 python:request.form['name'].value
1702 Note the "item" access used in the python case, and also note the
1703 explicit "value" attribute we have to access. That's because the form
1704 variables are stored as MiniFieldStorages. If there's more than one
1705 "name" value in the form, then the above will break since
1706 ``request/form/name`` is actually a *list* of MiniFieldStorages. So it's
1707 best to know beforehand what you're dealing with.
1710 The db variable
1711 ~~~~~~~~~~~~~~~
1713 Note: this is implemented by the ``roundup.cgi.templating.HTMLDatabase``
1714 class.
1716 Allows access to all hyperdb classes as attributes of this variable. If
1717 you want access to the "user" class, for example, you would use::
1719 db/user
1720 python:db.user
1722 Also, the current id of the current user is available as
1723 ``db.getuid()``. This isn't so useful in templates (where you have
1724 ``request/user``), but it can be useful in detectors or interfaces.
1726 The access results in a `hyperdb class wrapper`_.
1729 The templates variable
1730 ~~~~~~~~~~~~~~~~~~~~~~
1732 Note: this is implemented by the ``roundup.cgi.templating.Templates``
1733 class.
1735 This variable doesn't have any useful methods defined. It supports being
1736 used in expressions to access the templates, and consequently the
1737 template macros. You may access the templates using the following path
1738 expression::
1740 templates/name
1742 or the python expression::
1744 templates[name]
1746 where "name" is the name of the template you wish to access. The
1747 template has one useful attribute, namely "macros". To access a specific
1748 macro (called "macro_name"), use the path expression::
1750 templates/name/macros/macro_name
1752 or the python expression::
1754 templates[name].macros[macro_name]
1757 The utils variable
1758 ~~~~~~~~~~~~~~~~~~
1760 Note: this is implemented by the
1761 ``roundup.cgi.templating.TemplatingUtils`` class, but it may be extended
1762 as described below.
1764 =============== ========================================================
1765 Method Description
1766 =============== ========================================================
1767 Batch return a batch object using the supplied list
1768 =============== ========================================================
1770 You may add additional utility methods by writing them in your tracker
1771 ``interfaces.py`` module's ``TemplatingUtils`` class. See `adding a time
1772 log to your issues`_ for an example. The TemplatingUtils class itself
1773 will have a single attribute, ``client``, which may be used to access
1774 the ``client.db`` when you need to perform arbitrary database queries.
1776 Batching
1777 ::::::::
1779 Use Batch to turn a list of items, or item ids of a given class, into a
1780 series of batches. Its usage is::
1782 python:utils.Batch(sequence, size, start, end=0, orphan=0,
1783 overlap=0)
1785 or, to get the current index batch::
1787 request/batch
1789 The parameters are:
1791 ========= ==============================================================
1792 Parameter Usage
1793 ========= ==============================================================
1794 sequence a list of HTMLItems
1795 size how big to make the sequence.
1796 start where to start (0-indexed) in the sequence.
1797 end where to end (0-indexed) in the sequence.
1798 orphan if the next batch would contain less items than this value,
1799 then it is combined with this batch
1800 overlap the number of items shared between adjacent batches
1801 ========= ==============================================================
1803 All of the parameters are assigned as attributes on the batch object. In
1804 addition, it has several more attributes:
1806 =============== ========================================================
1807 Attribute Description
1808 =============== ========================================================
1809 start indicates the start index of the batch. *Note: unlike
1810 the argument, is a 1-based index (I know, lame)*
1811 first indicates the start index of the batch *as a 0-based
1812 index*
1813 length the actual number of elements in the batch
1814 sequence_length the length of the original, unbatched, sequence.
1815 =============== ========================================================
1817 And several methods:
1819 =============== ========================================================
1820 Method Description
1821 =============== ========================================================
1822 previous returns a new Batch with the previous batch settings
1823 next returns a new Batch with the next batch settings
1824 propchanged detect if the named property changed on the current item
1825 when compared to the last item
1826 =============== ========================================================
1828 An example of batching::
1830 <table class="otherinfo">
1831 <tr><th colspan="4" class="header">Existing Keywords</th></tr>
1832 <tr tal:define="keywords db/keyword/list"
1833 tal:repeat="start python:range(0, len(keywords), 4)">
1834 <td tal:define="batch python:utils.Batch(keywords, 4, start)"
1835 tal:repeat="keyword batch" tal:content="keyword/name">
1836 keyword here</td>
1837 </tr>
1838 </table>
1840 ... which will produce a table with four columns containing the items of
1841 the "keyword" class (well, their "name" anyway).
1843 Displaying Properties
1844 ---------------------
1846 Properties appear in the user interface in three contexts: in indices,
1847 in editors, and as search arguments. For each type of property, there
1848 are several display possibilities. For example, in an index view, a
1849 string property may just be printed as a plain string, but in an editor
1850 view, that property may be displayed in an editable field.
1853 Index Views
1854 -----------
1856 This is one of the class context views. It is also the default view for
1857 classes. The template used is "*classname*.index".
1860 Index View Specifiers
1861 ~~~~~~~~~~~~~~~~~~~~~
1863 An index view specifier (URL fragment) looks like this (whitespace has
1864 been added for clarity)::
1866 /issue?status=unread,in-progress,resolved&
1867 topic=security,ui&
1868 :group=+priority&
1869 :sort==activity&
1870 :filters=status,topic&
1871 :columns=title,status,fixer
1873 The index view is determined by two parts of the specifier: the layout
1874 part and the filter part. The layout part consists of the query
1875 parameters that begin with colons, and it determines the way that the
1876 properties of selected items are displayed. The filter part consists of
1877 all the other query parameters, and it determines the criteria by which
1878 items are selected for display. The filter part is interactively
1879 manipulated with the form widgets displayed in the filter section. The
1880 layout part is interactively manipulated by clicking on the column
1881 headings in the table.
1883 The filter part selects the union of the sets of items with values
1884 matching any specified Link properties and the intersection of the sets
1885 of items with values matching any specified Multilink properties.
1887 The example specifies an index of "issue" items. Only items with a
1888 "status" of either "unread" or "in-progress" or "resolved" are
1889 displayed, and only items with "topic" values including both "security"
1890 and "ui" are displayed. The items are grouped by priority, arranged in
1891 ascending order; and within groups, sorted by activity, arranged in
1892 descending order. The filter section shows filters for the "status" and
1893 "topic" properties, and the table includes columns for the "title",
1894 "status", and "fixer" properties.
1896 Searching Views
1897 ---------------
1899 Note: if you add a new column to the ``:columns`` form variable
1900 potentials then you will need to add the column to the appropriate
1901 `index views`_ template so that it is actually displayed.
1903 This is one of the class context views. The template used is typically
1904 "*classname*.search". The form on this page should have "search" as its
1905 ``@action`` variable. The "search" action:
1907 - sets up additional filtering, as well as performing indexed text
1908 searching
1909 - sets the ``:filter`` variable correctly
1910 - saves the query off if ``:query_name`` is set.
1912 The search page should lay out any fields that you wish to allow the
1913 user to search on. If your schema contains a large number of properties,
1914 you should be wary of making all of those properties available for
1915 searching, as this can cause confusion. If the additional properties are
1916 Strings, consider having their value indexed, and then they will be
1917 searchable using the full text indexed search. This is both faster, and
1918 more useful for the end user.
1920 The two special form values on search pages which are handled by the
1921 "search" action are:
1923 :search_text
1924 Text with which to perform a search of the text index. Results from
1925 that search will be used to limit the results of other filters (using
1926 an intersection operation)
1927 :query_name
1928 If supplied, the search parameters (including :search_text) will be
1929 saved off as a the query item and registered against the user's
1930 queries property. Note that the *classic* template schema has this
1931 ability, but the *minimal* template schema does not.
1934 Item Views
1935 ----------
1937 The basic view of a hyperdb item is provided by the "*classname*.item"
1938 template. It generally has three sections; an "editor", a "spool" and a
1939 "history" section.
1942 Editor Section
1943 ~~~~~~~~~~~~~~
1945 The editor section is used to manipulate the item - it may be a static
1946 display if the user doesn't have permission to edit the item.
1948 Here's an example of a basic editor template (this is the default
1949 "classic" template issue item edit form - from the "issue.item.html"
1950 template)::
1952 <table class="form">
1953 <tr>
1954 <th>Title</th>
1955 <td colspan="3" tal:content="structure python:context.title.field(size=60)">title</td>
1956 </tr>
1958 <tr>
1959 <th>Priority</th>
1960 <td tal:content="structure context/priority/menu">priority</td>
1961 <th>Status</th>
1962 <td tal:content="structure context/status/menu">status</td>
1963 </tr>
1965 <tr>
1966 <th>Superseder</th>
1967 <td>
1968 <span tal:replace="structure python:context.superseder.field(showid=1, size=20)" />
1969 <span tal:replace="structure python:db.issue.classhelp('id,title')" />
1970 <span tal:condition="context/superseder">
1971 <br>View: <span tal:replace="structure python:context.superseder.link(showid=1)" />
1972 </span>
1973 </td>
1974 <th>Nosy List</th>
1975 <td>
1976 <span tal:replace="structure context/nosy/field" />
1977 <span tal:replace="structure python:db.user.classhelp('username,realname,address,phone')" />
1978 </td>
1979 </tr>
1981 <tr>
1982 <th>Assigned To</th>
1983 <td tal:content="structure context/assignedto/menu">
1984 assignedto menu
1985 </td>
1986 <td> </td>
1987 <td> </td>
1988 </tr>
1990 <tr>
1991 <th>Change Note</th>
1992 <td colspan="3">
1993 <textarea name=":note" wrap="hard" rows="5" cols="60"></textarea>
1994 </td>
1995 </tr>
1997 <tr>
1998 <th>File</th>
1999 <td colspan="3"><input type="file" name=":file" size="40"></td>
2000 </tr>
2002 <tr>
2003 <td> </td>
2004 <td colspan="3" tal:content="structure context/submit">
2005 submit button will go here
2006 </td>
2007 </tr>
2008 </table>
2011 When a change is submitted, the system automatically generates a message
2012 describing the changed properties. As shown in the example, the editor
2013 template can use the ":note" and ":file" fields, which are added to the
2014 standard changenote message generated by Roundup.
2017 Form values
2018 :::::::::::
2020 We have a number of ways to pull properties out of the form in order to
2021 meet the various needs of:
2023 1. editing the current item (perhaps an issue item)
2024 2. editing information related to the current item (eg. messages or
2025 attached files)
2026 3. creating new information to be linked to the current item (eg. time
2027 spent on an issue)
2029 In the following, ``<bracketed>`` values are variable, ":" may be one of
2030 ":" or "@", and other text ("required") is fixed.
2032 Properties are specified as form variables:
2034 ``<propname>``
2035 property on the current context item
2037 ``<designator>:<propname>``
2038 property on the indicated item (for editing related information)
2040 ``<classname>-<N>:<propname>``
2041 property on the Nth new item of classname (generally for creating new
2042 items to attach to the current item)
2044 Once we have determined the "propname", we check to see if it is one of
2045 the special form values:
2047 ``@required``
2048 The named property values must be supplied or a ValueError will be
2049 raised.
2051 ``@remove@<propname>=id(s)``
2052 The ids will be removed from the multilink property.
2054 ``:add:<propname>=id(s)``
2055 The ids will be added to the multilink property.
2057 ``:link:<propname>=<designator>``
2058 Used to add a link to new items created during edit. These are
2059 collected and returned in ``all_links``. This will result in an
2060 additional linking operation (either Link set or Multilink append)
2061 after the edit/create is done using ``all_props`` in ``_editnodes``.
2062 The <propname> on the current item will be set/appended the id of the
2063 newly created item of class <designator> (where <designator> must be
2064 <classname>-<N>).
2066 Any of the form variables may be prefixed with a classname or
2067 designator.
2069 Two special form values are supported for backwards compatibility:
2071 ``:note``
2072 create a message (with content, author and date), linked to the
2073 context item. This is ALWAYS designated "msg-1".
2074 ``:file``
2075 create a file, attached to the current item and any message created by
2076 :note. This is ALWAYS designated "file-1".
2079 Spool Section
2080 ~~~~~~~~~~~~~
2082 The spool section lists related information like the messages and files
2083 of an issue.
2085 TODO
2088 History Section
2089 ~~~~~~~~~~~~~~~
2091 The final section displayed is the history of the item - its database
2092 journal. This is generally generated with the template::
2094 <tal:block tal:replace="structure context/history" />
2096 *To be done:*
2098 *The actual history entries of the item may be accessed for manual
2099 templating through the "journal" method of the item*::
2101 <tal:block tal:repeat="entry context/journal">
2102 a journal entry
2103 </tal:block>
2105 *where each journal entry is an HTMLJournalEntry.*
2107 Defining new web actions
2108 ------------------------
2110 You may define new actions to be triggered by the ``@action`` form variable.
2111 These are added to the tracker ``interfaces.py`` as ``Action`` classes that get
2112 called by the the ``Client`` class.
2114 Adding action classes takes three steps; first you `define the new
2115 action class`_, then you `register the action class`_ with the cgi
2116 interface so it may be triggered by the ``@action`` form variable.
2117 Finally you `use the new action`_ in your HTML form.
2119 See "`setting up a "wizard" (or "druid") for controlled adding of
2120 issues`_" for an example.
2123 Define the new action class
2124 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2126 The action classes have the following interface::
2128 class MyAction(Action):
2129 def handle(self):
2130 ''' Perform some action. No return value is required.
2131 '''
2133 The *self.client* attribute is an instance of your tracker ``instance.Client``
2134 class - thus it's mostly implemented by ``roundup.cgi.client.Client``. See the
2135 docstring of that class for details of what it can do.
2137 The method will typically check the ``self.form`` variable's contents.
2138 It may then:
2140 - add information to ``self.client.ok_message`` or ``self.client.error_message``
2141 - change the ``self.client.template`` variable to alter what the user will see
2142 next
2143 - raise Unauthorised, SendStaticFile, SendFile, NotFound or Redirect
2144 exceptions (import them from roundup.cgi.exceptions)
2147 Register the action class
2148 ~~~~~~~~~~~~~~~~~~~~~~~~~~
2150 The class is now written, but isn't available to the user until you add it to
2151 the ``instance.Client`` class ``actions`` variable, like so::
2153 actions = client.Client.actions + (
2154 ('myaction', myActionClass),
2155 )
2157 This maps the action name "myaction" to the action class we defined.
2159 Use the new action
2160 ~~~~~~~~~~~~~~~~~~
2162 In your HTML form, add a hidden form element like so::
2164 <input type="hidden" name="@action" value="myaction">
2166 where "myaction" is the name you registered in the previous step.
2168 Actions may return content to the user
2169 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2171 Actions generally perform some database manipulation and then pass control
2172 on to the rendering of a template in the current context (see `Determining
2173 web context`_ for how that works.) Some actions will want to generate the
2174 actual content returned to the user. Action methods may return their own
2175 content string to be displayed to the user, overriding the templating step.
2176 In this situation, we assume that the content is HTML by default. You may
2177 override the content type indicated to the user by calling ``setHeader``::
2179 self.client.setHeader('Content-Type', 'text/csv')
2181 This example indicates that the value sent back to the user is actually
2182 comma-separated value content (eg. something to be loaded into a
2183 spreadsheet or database).
2186 Examples
2187 ========
2189 .. contents::
2190 :local:
2191 :depth: 1
2194 Adding a new field to the classic schema
2195 ----------------------------------------
2197 This example shows how to add a new constrained property (i.e. a
2198 selection of distinct values) to your tracker.
2201 Introduction
2202 ~~~~~~~~~~~~
2204 To make the classic schema of roundup useful as a TODO tracking system
2205 for a group of systems administrators, it needed an extra data field per
2206 issue: a category.
2208 This would let sysadmins quickly list all TODOs in their particular area
2209 of interest without having to do complex queries, and without relying on
2210 the spelling capabilities of other sysadmins (a losing proposition at
2211 best).
2214 Adding a field to the database
2215 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2217 This is the easiest part of the change. The category would just be a
2218 plain string, nothing fancy. To change what is in the database you need
2219 to add some lines to the ``open()`` function in ``dbinit.py``. Under the
2220 comment::
2222 # add any additional database schema configuration here
2224 add::
2226 category = Class(db, "category", name=String())
2227 category.setkey("name")
2229 Here we are setting up a chunk of the database which we are calling
2230 "category". It contains a string, which we are refering to as "name" for
2231 lack of a more imaginative title. (Since "name" is one of the properties
2232 that Roundup looks for on items if you do not set a key for them, it's
2233 probably a good idea to stick with it for new classes if at all
2234 appropriate.) Then we are setting the key of this chunk of the database
2235 to be that "name". This is equivalent to an index for database types.
2236 This also means that there can only be one category with a given name.
2238 Adding the above lines allows us to create categories, but they're not
2239 tied to the issues that we are going to be creating. It's just a list of
2240 categories off on its own, which isn't much use. We need to link it in
2241 with the issues. To do that, find the lines in the ``open()`` function
2242 in ``dbinit.py`` which set up the "issue" class, and then add a link to
2243 the category::
2245 issue = IssueClass(db, "issue", ... ,
2246 category=Multilink("category"), ... )
2248 The ``Multilink()`` means that each issue can have many categories. If
2249 you were adding something with a one-to-one relationship to issues (such
2250 as the "assignedto" property), use ``Link()`` instead.
2252 That is all you need to do to change the schema. The rest of the effort
2253 is fiddling around so you can actually use the new category.
2256 Populating the new category class
2257 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2259 If you haven't initialised the database with the roundup-admin
2260 "initialise" command, then you can add the following to the tracker
2261 ``dbinit.py`` in the ``init()`` function under the comment::
2263 # add any additional database create steps here - but only if you
2264 # haven't initialised the database with the admin "initialise" command
2266 Add::
2268 category = db.getclass('category')
2269 category.create(name="scipy", order="1")
2270 category.create(name="chaco", order="2")
2271 category.create(name="weave", order="3")
2273 If the database has already been initalised, then you need to use the
2274 ``roundup-admin`` tool::
2276 % roundup-admin -i <tracker home>
2277 Roundup <version> ready for input.
2278 Type "help" for help.
2279 roundup> create category name=scipy order=1
2280 1
2281 roundup> create category name=chaco order=1
2282 2
2283 roundup> create category name=weave order=1
2284 3
2285 roundup> exit...
2286 There are unsaved changes. Commit them (y/N)? y
2288 TODO: explain why order=1 in each case. Also, does key get set to "name"
2289 automatically when added via roundup-admin?
2292 Setting up security on the new objects
2293 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2295 By default only the admin user can look at and change objects. This
2296 doesn't suit us, as we want any user to be able to create new categories
2297 as required, and obviously everyone needs to be able to view the
2298 categories of issues for it to be useful.
2300 We therefore need to change the security of the category objects. This
2301 is also done in the ``open()`` function of ``dbinit.py``.
2303 There are currently two loops which set up permissions and then assign
2304 them to various roles. Simply add the new "category" to both lists::
2306 # new permissions for this schema
2307 for cl in 'issue', 'file', 'msg', 'user', 'category':
2308 db.security.addPermission(name="Edit", klass=cl,
2309 description="User is allowed to edit "+cl)
2310 db.security.addPermission(name="View", klass=cl,
2311 description="User is allowed to access "+cl)
2313 # Assign the access and edit permissions for issue, file and message
2314 # to regular users now
2315 for cl in 'issue', 'file', 'msg', 'category':
2316 p = db.security.getPermission('View', cl)
2317 db.security.addPermissionToRole('User', p)
2318 p = db.security.getPermission('Edit', cl)
2319 db.security.addPermissionToRole('User', p)
2321 So you are in effect doing the following (with 'cl' substituted by its
2322 value)::
2324 db.security.addPermission(name="Edit", klass='category',
2325 description="User is allowed to edit "+'category')
2326 db.security.addPermission(name="View", klass='category',
2327 description="User is allowed to access "+'category')
2329 which is creating two permission types; that of editing and viewing
2330 "category" objects respectively. Then the following lines assign those
2331 new permissions to the "User" role, so that normal users can view and
2332 edit "category" objects::
2334 p = db.security.getPermission('View', 'category')
2335 db.security.addPermissionToRole('User', p)
2337 p = db.security.getPermission('Edit', 'category')
2338 db.security.addPermissionToRole('User', p)
2340 This is all the work that needs to be done for the database. It will
2341 store categories, and let users view and edit them. Now on to the
2342 interface stuff.
2345 Changing the web left hand frame
2346 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2348 We need to give the users the ability to create new categories, and the
2349 place to put the link to this functionality is in the left hand function
2350 bar, under the "Issues" area. The file that defines how this area looks
2351 is ``html/page``, which is what we are going to be editing next.
2353 If you look at this file you can see that it contains a lot of
2354 "classblock" sections which are chunks of HTML that will be included or
2355 excluded in the output depending on whether the condition in the
2356 classblock is met. Under the end of the classblock for issue is where we
2357 are going to add the category code::
2359 <p class="classblock"
2360 tal:condition="python:request.user.hasPermission('View', 'category')">
2361 <b>Categories</b><br>
2362 <a tal:condition="python:request.user.hasPermission('Edit', 'category')"
2363 href="category?@template=item">New Category<br></a>
2364 </p>
2366 The first two lines is the classblock definition, which sets up a
2367 condition that only users who have "View" permission for the "category"
2368 object will have this section included in their output. Next comes a
2369 plain "Categories" header in bold. Everyone who can view categories will
2370 get that.
2372 Next comes the link to the editing area of categories. This link will
2373 only appear if the condition - that the user has "Edit" permissions for
2374 the "category" objects - is matched. If they do have permission then
2375 they will get a link to another page which will let the user add new
2376 categories.
2378 Note that if you have permission to *view* but not to *edit* categories,
2379 then all you will see is a "Categories" header with nothing underneath
2380 it. This is obviously not very good interface design, but will do for
2381 now. I just claim that it is so I can add more links in this section
2382 later on. However to fix the problem you could change the condition in
2383 the classblock statement, so that only users with "Edit" permission
2384 would see the "Categories" stuff.
2387 Setting up a page to edit categories
2388 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2390 We defined code in the previous section which let users with the
2391 appropriate permissions see a link to a page which would let them edit
2392 conditions. Now we have to write that page.
2394 The link was for the *item* template of the *category* object. This
2395 translates into Roundup looking for a file called ``category.item.html``
2396 in the ``html`` tracker directory. This is the file that we are going to
2397 write now.
2399 First we add an info tag in a comment which doesn't affect the outcome
2400 of the code at all, but is useful for debugging. If you load a page in a
2401 browser and look at the page source, you can see which sections come
2402 from which files by looking for these comments::
2404 <!-- category.item -->
2406 Next we need to add in the METAL macro stuff so we get the normal page
2407 trappings::
2409 <tal:block metal:use-macro="templates/page/macros/icing">
2410 <title metal:fill-slot="head_title">Category editing</title>
2411 <td class="page-header-top" metal:fill-slot="body_title">
2412 <h2>Category editing</h2>
2413 </td>
2414 <td class="content" metal:fill-slot="content">
2416 Next we need to setup up a standard HTML form, which is the whole
2417 purpose of this file. We link to some handy javascript which sends the
2418 form through only once. This is to stop users hitting the send button
2419 multiple times when they are impatient and thus having the form sent
2420 multiple times::
2422 <form method="POST" onSubmit="return submit_once()"
2423 enctype="multipart/form-data">
2425 Next we define some code which sets up the minimum list of fields that
2426 we require the user to enter. There will be only one field - "name" - so
2427 they better put something in it, otherwise the whole form is pointless::
2429 <input type="hidden" name="@required" value="name">
2431 To get everything to line up properly we will put everything in a table,
2432 and put a nice big header on it so the user has an idea what is
2433 happening::
2435 <table class="form">
2436 <tr><th class="header" colspan="2">Category</th></tr>
2438 Next, we need the field into which the user is going to enter the new
2439 category. The "context.name.field(size=60)" bit tells Roundup to
2440 generate a normal HTML field of size 60, and the contents of that field
2441 will be the "name" variable of the current context (which is
2442 "category"). The upshot of this is that when the user types something in
2443 to the form, a new category will be created with that name::
2445 <tr>
2446 <th>Name</th>
2447 <td tal:content="structure python:context.name.field(size=60)">
2448 name</td>
2449 </tr>
2451 Then a submit button so that the user can submit the new category::
2453 <tr>
2454 <td> </td>
2455 <td colspan="3" tal:content="structure context/submit">
2456 submit button will go here
2457 </td>
2458 </tr>
2460 Finally we finish off the tags we used at the start to do the METAL
2461 stuff::
2463 </td>
2464 </tal:block>
2466 So putting it all together, and closing the table and form we get::
2468 <!-- category.item -->
2469 <tal:block metal:use-macro="templates/page/macros/icing">
2470 <title metal:fill-slot="head_title">Category editing</title>
2471 <td class="page-header-top" metal:fill-slot="body_title">
2472 <h2>Category editing</h2>
2473 </td>
2474 <td class="content" metal:fill-slot="content">
2475 <form method="POST" onSubmit="return submit_once()"
2476 enctype="multipart/form-data">
2478 <table class="form">
2479 <tr><th class="header" colspan="2">Category</th></tr>
2481 <tr>
2482 <th>Name</th>
2483 <td tal:content="structure python:context.name.field(size=60)">
2484 name</td>
2485 </tr>
2487 <tr>
2488 <td>
2489
2490 <input type="hidden" name="@required" value="name">
2491 </td>
2492 <td colspan="3" tal:content="structure context/submit">
2493 submit button will go here
2494 </td>
2495 </tr>
2496 </table>
2497 </form>
2498 </td>
2499 </tal:block>
2501 This is quite a lot to just ask the user one simple question, but there
2502 is a lot of setup for basically one line (the form line) to do its work.
2503 To add another field to "category" would involve one more line (well,
2504 maybe a few extra to get the formatting correct).
2507 Adding the category to the issue
2508 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2510 We now have the ability to create issues to our heart's content, but
2511 that is pointless unless we can assign categories to issues. Just like
2512 the ``html/category.item.html`` file was used to define how to add a new
2513 category, the ``html/issue.item.html`` is used to define how a new issue
2514 is created.
2516 Just like ``category.issue.html`` this file defines a form which has a
2517 table to lay things out. It doesn't matter where in the table we add new
2518 stuff, it is entirely up to your sense of aesthetics::
2520 <th>Category</th>
2521 <td><span tal:replace="structure context/category/field" />
2522 <span tal:replace="structure db/category/classhelp" />
2523 </td>
2525 First, we define a nice header so that the user knows what the next
2526 section is, then the middle line does what we are most interested in.
2527 This ``context/category/field`` gets replaced by a field which contains
2528 the category in the current context (the current context being the new
2529 issue).
2531 The classhelp lines generate a link (labelled "list") to a popup window
2532 which contains the list of currently known categories.
2535 Searching on categories
2536 ~~~~~~~~~~~~~~~~~~~~~~~
2538 We can add categories, and create issues with categories. The next
2539 obvious thing that we would like to be able to do, would be to search
2540 for issues based on their category, so that, for example, anyone working
2541 on the web server could look at all issues in the category "Web".
2543 If you look for "Search Issues" in the 'html/page.html' file, you will
2544 find that it looks something like
2545 ``<a href="issue?@template=search">Search Issues</a>``. This shows us
2546 that when you click on "Search Issues" it will be looking for a
2547 ``issue.search.html`` file to display. So that is the file that we will
2548 change.
2550 If you look at this file it should be starting to seem familiar, although it
2551 does use some new macros. You can add the new category search code anywhere you
2552 like within that form::
2554 <tr tal:define="name string:category;
2555 db_klass string:category;
2556 db_content string:name;">
2557 <th>Priority:</th>
2558 <td metal:use-macro="search_select"></td>
2559 <td metal:use-macro="column_input"></td>
2560 <td metal:use-macro="sort_input"></td>
2561 <td metal:use-macro="group_input"></td>
2562 </tr>
2564 The definitions in the <tr> opening tag are used by the macros:
2566 - search_select expands to a drop-down box with all categories using db_klass
2567 and db_content.
2568 - column_input expands to a checkbox for selecting what columns should be
2569 displayed.
2570 - sort_input expands to a radio button for selecting what property should be
2571 sorted on.
2572 - group_input expands to a radio button for selecting what property should be
2573 group on.
2575 The category search code above would expand to the following::
2577 <tr>
2578 <th>Category:</th>
2579 <td>
2580 <select name="category">
2581 <option value="">don't care</option>
2582 <option value="">------------</option>
2583 <option value="1">scipy</option>
2584 <option value="2">chaco</option>
2585 <option value="3">weave</option>
2586 </select>
2587 </td>
2588 <td><input type="checkbox" name=":columns" value="category"></td>
2589 <td><input type="radio" name=":sort" value="category"></td>
2590 <td><input type="radio" name=":group" value="category"></td>
2591 </tr>
2593 Adding category to the default view
2594 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2596 We can now add categories, add issues with categories, and search for
2597 issues based on categories. This is everything that we need to do;
2598 however, there is some more icing that we would like. I think the
2599 category of an issue is important enough that it should be displayed by
2600 default when listing all the issues.
2602 Unfortunately, this is a bit less obvious than the previous steps. The
2603 code defining how the issues look is in ``html/issue.index.html``. This
2604 is a large table with a form down at the bottom for redisplaying and so
2605 forth.
2607 Firstly we need to add an appropriate header to the start of the table::
2609 <th tal:condition="request/show/category">Category</th>
2611 The *condition* part of this statement is to avoid displaying the
2612 Category column if the user has selected not to see it.
2614 The rest of the table is a loop which will go through every issue that
2615 matches the display criteria. The loop variable is "i" - which means
2616 that every issue gets assigned to "i" in turn.
2618 The new part of code to display the category will look like this::
2620 <td tal:condition="request/show/category"
2621 tal:content="i/category"></td>
2623 The condition is the same as above: only display the condition when the
2624 user hasn't asked for it to be hidden. The next part is to set the
2625 content of the cell to be the category part of "i" - the current issue.
2627 Finally we have to edit ``html/page.html`` again. This time, we need to
2628 tell it that when the user clicks on "Unasigned Issues" or "All Issues",
2629 the category column should be included in the resulting list. If you
2630 scroll down the page file, you can see the links with lots of options.
2631 The option that we are interested in is the ``:columns=`` one which
2632 tells roundup which fields of the issue to display. Simply add
2633 "category" to that list and it all should work.
2636 Adding in state transition control
2637 ----------------------------------
2639 Sometimes tracker admins want to control the states that users may move
2640 issues to. You can do this by following these steps:
2642 1. make "status" a required variable. This is achieved by adding the
2643 following to the top of the form in the ``issue.item.html``
2644 template::
2646 <input type="hidden" name="@required" value="status">
2648 this will force users to select a status.
2650 2. add a Multilink property to the status class::
2652 stat = Class(db, "status", ... , transitions=Multilink('status'),
2653 ...)
2655 and then edit the statuses already created, either:
2657 a. through the web using the class list -> status class editor, or
2658 b. using the roundup-admin "set" command.
2660 3. add an auditor module ``checktransition.py`` in your tracker's
2661 ``detectors`` directory, for example::
2663 def checktransition(db, cl, nodeid, newvalues):
2664 ''' Check that the desired transition is valid for the "status"
2665 property.
2666 '''
2667 if not newvalues.has_key('status'):
2668 return
2669 current = cl.get(nodeid, 'status')
2670 new = newvalues['status']
2671 if new == current:
2672 return
2673 ok = db.status.get(current, 'transitions')
2674 if new not in ok:
2675 raise ValueError, 'Status not allowed to move from "%s" to "%s"'%(
2676 db.status.get(current, 'name'), db.status.get(new, 'name'))
2678 def init(db):
2679 db.issue.audit('set', checktransition)
2681 4. in the ``issue.item.html`` template, change the status editing bit
2682 from::
2684 <th>Status</th>
2685 <td tal:content="structure context/status/menu">status</td>
2687 to::
2689 <th>Status</th>
2690 <td>
2691 <select tal:condition="context/id" name="status">
2692 <tal:block tal:define="ok context/status/transitions"
2693 tal:repeat="state db/status/list">
2694 <option tal:condition="python:state.id in ok"
2695 tal:attributes="
2696 value state/id;
2697 selected python:state.id == context.status.id"
2698 tal:content="state/name"></option>
2699 </tal:block>
2700 </select>
2701 <tal:block tal:condition="not:context/id"
2702 tal:replace="structure context/status/menu" />
2703 </td>
2705 which displays only the allowed status to transition to.
2708 Displaying only message summaries in the issue display
2709 ------------------------------------------------------
2711 Alter the issue.item template section for messages to::
2713 <table class="messages" tal:condition="context/messages">
2714 <tr><th colspan="5" class="header">Messages</th></tr>
2715 <tr tal:repeat="msg context/messages">
2716 <td><a tal:attributes="href string:msg${msg/id}"
2717 tal:content="string:msg${msg/id}"></a></td>
2718 <td tal:content="msg/author">author</td>
2719 <td class="date" tal:content="msg/date/pretty">date</td>
2720 <td tal:content="msg/summary">summary</td>
2721 <td>
2722 <a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">
2723 remove</a>
2724 </td>
2725 </tr>
2726 </table>
2728 Restricting the list of users that are assignable to a task
2729 -----------------------------------------------------------
2731 1. In your tracker's "dbinit.py", create a new Role, say "Developer"::
2733 db.security.addRole(name='Developer', description='A developer')
2735 2. Just after that, create a new Permission, say "Fixer", specific to
2736 "issue"::
2738 p = db.security.addPermission(name='Fixer', klass='issue',
2739 description='User is allowed to be assigned to fix issues')
2741 3. Then assign the new Permission to your "Developer" Role::
2743 db.security.addPermissionToRole('Developer', p)
2745 4. In the issue item edit page ("html/issue.item.html" in your tracker
2746 directory), use the new Permission in restricting the "assignedto"
2747 list::
2749 <select name="assignedto">
2750 <option value="-1">- no selection -</option>
2751 <tal:block tal:repeat="user db/user/list">
2752 <option tal:condition="python:user.hasPermission(
2753 'Fixer', context._classname)"
2754 tal:attributes="
2755 value user/id;
2756 selected python:user.id == context.assignedto"
2757 tal:content="user/realname"></option>
2758 </tal:block>
2759 </select>
2761 For extra security, you may wish to setup an auditor to enforce the
2762 Permission requirement (install this as "assignedtoFixer.py" in your
2763 tracker "detectors" directory)::
2765 def assignedtoMustBeFixer(db, cl, nodeid, newvalues):
2766 ''' Ensure the assignedto value in newvalues is a used with the
2767 Fixer Permission
2768 '''
2769 if not newvalues.has_key('assignedto'):
2770 # don't care
2771 return
2773 # get the userid
2774 userid = newvalues['assignedto']
2775 if not db.security.hasPermission('Fixer', userid, cl.classname):
2776 raise ValueError, 'You do not have permission to edit %s'%cl.classname
2778 def init(db):
2779 db.issue.audit('set', assignedtoMustBeFixer)
2780 db.issue.audit('create', assignedtoMustBeFixer)
2782 So now, if an edit action attempts to set "assignedto" to a user that
2783 doesn't have the "Fixer" Permission, the error will be raised.
2786 Setting up a "wizard" (or "druid") for controlled adding of issues
2787 ------------------------------------------------------------------
2789 1. Set up the page templates you wish to use for data input. My wizard
2790 is going to be a two-step process: first figuring out what category
2791 of issue the user is submitting, and then getting details specific to
2792 that category. The first page includes a table of help, explaining
2793 what the category names mean, and then the core of the form::
2795 <form method="POST" onSubmit="return submit_once()"
2796 enctype="multipart/form-data">
2797 <input type="hidden" name="@template" value="add_page1">
2798 <input type="hidden" name="@action" value="page1_submit">
2800 <strong>Category:</strong>
2801 <tal:block tal:replace="structure context/category/menu" />
2802 <input type="submit" value="Continue">
2803 </form>
2805 The next page has the usual issue entry information, with the
2806 addition of the following form fragments::
2808 <form method="POST" onSubmit="return submit_once()"
2809 enctype="multipart/form-data"
2810 tal:condition="context/is_edit_ok"
2811 tal:define="cat request/form/category/value">
2813 <input type="hidden" name="@template" value="add_page2">
2814 <input type="hidden" name="@required" value="title">
2815 <input type="hidden" name="category" tal:attributes="value cat">
2816 .
2817 .
2818 .
2819 </form>
2821 Note that later in the form, I test the value of "cat" include form
2822 elements that are appropriate. For example::
2824 <tal:block tal:condition="python:cat in '6 10 13 14 15 16 17'.split()">
2825 <tr>
2826 <th>Operating System</th>
2827 <td tal:content="structure context/os/field"></td>
2828 </tr>
2829 <tr>
2830 <th>Web Browser</th>
2831 <td tal:content="structure context/browser/field"></td>
2832 </tr>
2833 </tal:block>
2835 ... the above section will only be displayed if the category is one
2836 of 6, 10, 13, 14, 15, 16 or 17.
2838 3. Determine what actions need to be taken between the pages - these are
2839 usually to validate user choices and determine what page is next. Now encode
2840 those actions in a new ``Action`` class and insert hooks to those actions in
2841 the "actions" attribute on on the ``interfaces.Client`` class, like so (see
2842 `defining new web actions`_)::
2844 class Page1SubmitAction(Action):
2845 def handle(self):
2846 ''' Verify that the user has selected a category, and then move
2847 on to page 2.
2848 '''
2849 category = self.form['category'].value
2850 if category == '-1':
2851 self.error_message.append('You must select a category of report')
2852 return
2853 # everything's ok, move on to the next page
2854 self.template = 'add_page2'
2856 actions = client.Client.actions + (
2857 ('page1_submit', Page1SubmitAction),
2858 )
2860 4. Use the usual "new" action as the ``@action`` on the final page, and
2861 you're done (the standard context/submit method can do this for you).
2864 Using an external password validation source
2865 --------------------------------------------
2867 We have a centrally-managed password changing system for our users. This
2868 results in a UN*X passwd-style file that we use for verification of
2869 users. Entries in the file consist of ``name:password`` where the
2870 password is encrypted using the standard UN*X ``crypt()`` function (see
2871 the ``crypt`` module in your Python distribution). An example entry
2872 would be::
2874 admin:aamrgyQfDFSHw
2876 Each user of Roundup must still have their information stored in the Roundup
2877 database - we just use the passwd file to check their password. To do this, we
2878 need to override the standard ``verifyPassword`` method defined in
2879 ``roundup.cgi.actions.LoginAction`` and register the new class with our
2880 ``Client`` class in the tracker home ``interfaces.py`` module::
2882 from roundup.cgi.actions import LoginAction
2884 class ExternalPasswordLoginAction(LoginAction):
2885 def verifyPassword(self, userid, password):
2886 # get the user's username
2887 username = self.db.user.get(userid, 'username')
2889 # the passwords are stored in the "passwd.txt" file in the
2890 # tracker home
2891 file = os.path.join(self.db.config.TRACKER_HOME, 'passwd.txt')
2893 # see if we can find a match
2894 for ent in [line.strip().split(':') for line in
2895 open(file).readlines()]:
2896 if ent[0] == username:
2897 return crypt.crypt(password, ent[1][:2]) == ent[1]
2899 # user doesn't exist in the file
2900 return 0
2902 class Client(client.Client):
2903 actions = client.Client.actions + (
2904 ('login', ExternalPasswordLoginAction)
2905 )
2907 What this does is look through the file, line by line, looking for a
2908 name that matches.
2910 We also remove the redundant password fields from the ``user.item``
2911 template.
2914 Adding a "vacation" flag to users for stopping nosy messages
2915 ------------------------------------------------------------
2917 When users go on vacation and set up vacation email bouncing, you'll
2918 start to see a lot of messages come back through Roundup "Fred is on
2919 vacation". Not very useful, and relatively easy to stop.
2921 1. add a "vacation" flag to your users::
2923 user = Class(db, "user",
2924 username=String(), password=Password(),
2925 address=String(), realname=String(),
2926 phone=String(), organisation=String(),
2927 alternate_addresses=String(),
2928 roles=String(), queries=Multilink("query"),
2929 vacation=Boolean())
2931 2. So that users may edit the vacation flags, add something like the
2932 following to your ``user.item`` template::
2934 <tr>
2935 <th>On Vacation</th>
2936 <td tal:content="structure context/vacation/field">vacation</td>
2937 </tr>
2939 3. edit your detector ``nosyreactor.py`` so that the ``nosyreaction()``
2940 consists of::
2942 def nosyreaction(db, cl, nodeid, oldvalues):
2943 users = db.user
2944 messages = db.msg
2945 # send a copy of all new messages to the nosy list
2946 for msgid in determineNewMessages(cl, nodeid, oldvalues):
2947 try:
2948 # figure the recipient ids
2949 sendto = []
2950 seen_message = {}
2951 recipients = messages.get(msgid, 'recipients')
2952 for recipid in messages.get(msgid, 'recipients'):
2953 seen_message[recipid] = 1
2955 # figure the author's id, and indicate they've received
2956 # the message
2957 authid = messages.get(msgid, 'author')
2959 # possibly send the message to the author, as long as
2960 # they aren't anonymous
2961 if (db.config.MESSAGES_TO_AUTHOR == 'yes' and
2962 users.get(authid, 'username') != 'anonymous'):
2963 sendto.append(authid)
2964 seen_message[authid] = 1
2966 # now figure the nosy people who weren't recipients
2967 nosy = cl.get(nodeid, 'nosy')
2968 for nosyid in nosy:
2969 # Don't send nosy mail to the anonymous user (that
2970 # user shouldn't appear in the nosy list, but just
2971 # in case they do...)
2972 if users.get(nosyid, 'username') == 'anonymous':
2973 continue
2974 # make sure they haven't seen the message already
2975 if not seen_message.has_key(nosyid):
2976 # send it to them
2977 sendto.append(nosyid)
2978 recipients.append(nosyid)
2980 # generate a change note
2981 if oldvalues:
2982 note = cl.generateChangeNote(nodeid, oldvalues)
2983 else:
2984 note = cl.generateCreateNote(nodeid)
2986 # we have new recipients
2987 if sendto:
2988 # filter out the people on vacation
2989 sendto = [i for i in sendto
2990 if not users.get(i, 'vacation', 0)]
2992 # map userids to addresses
2993 sendto = [users.get(i, 'address') for i in sendto]
2995 # update the message's recipients list
2996 messages.set(msgid, recipients=recipients)
2998 # send the message
2999 cl.send_message(nodeid, msgid, note, sendto)
3000 except roundupdb.MessageSendError, message:
3001 raise roundupdb.DetectorError, message
3003 Note that this is the standard nosy reaction code, with the small
3004 addition of::
3006 # filter out the people on vacation
3007 sendto = [i for i in sendto if not users.get(i, 'vacation', 0)]
3009 which filters out the users that have the vacation flag set to true.
3012 Adding a time log to your issues
3013 --------------------------------
3015 We want to log the dates and amount of time spent working on issues, and
3016 be able to give a summary of the total time spent on a particular issue.
3018 1. Add a new class to your tracker ``dbinit.py``::
3020 # storage for time logging
3021 timelog = Class(db, "timelog", period=Interval())
3023 Note that we automatically get the date of the time log entry
3024 creation through the standard property "creation".
3026 2. Link to the new class from your issue class (again, in
3027 ``dbinit.py``)::
3029 issue = IssueClass(db, "issue",
3030 assignedto=Link("user"), topic=Multilink("keyword"),
3031 priority=Link("priority"), status=Link("status"),
3032 times=Multilink("timelog"))
3034 the "times" property is the new link to the "timelog" class.
3036 3. We'll need to let people add in times to the issue, so in the web
3037 interface we'll have a new entry field. This is a special field
3038 because unlike the other fields in the issue.item template, it
3039 affects a different item (a timelog item) and not the template's
3040 item, an issue. We have a special syntax for form fields that affect
3041 items other than the template default item (see the cgi
3042 documentation on `special form variables`_). In particular, we add a
3043 field to capture a new timelog item's perdiod::
3045 <tr>
3046 <th>Time Log</th>
3047 <td colspan=3><input type="text" name="timelog-1@period" />
3048 <br />(enter as '3y 1m 4d 2:40:02' or parts thereof)
3049 </td>
3050 </tr>
3052 and another hidden field that links that new timelog item (new
3053 because it's marked as having id "-1") to the issue item. It looks
3054 like this::
3056 <input type="hidden" name="@link@times" value="timelog-1" />
3058 On submission, the "-1" timelog item will be created and assigned a
3059 real item id. The "times" property of the issue will have the new id
3060 added to it.
3062 4. We want to display a total of the time log times that have been
3063 accumulated for an issue. To do this, we'll need to actually write
3064 some Python code, since it's beyond the scope of PageTemplates to
3065 perform such calculations. We do this by adding a method to the
3066 TemplatingUtils class in our tracker ``interfaces.py`` module::
3068 class TemplatingUtils:
3069 ''' Methods implemented on this class will be available to HTML
3070 templates through the 'utils' variable.
3071 '''
3072 def totalTimeSpent(self, times):
3073 ''' Call me with a list of timelog items (which have an
3074 Interval "period" property)
3075 '''
3076 total = Interval('0d')
3077 for time in times:
3078 total += time.period._value
3079 return total
3081 Replace the ``pass`` line if one appears in your TemplatingUtils
3082 class. As indicated in the docstrings, we will be able to access the
3083 ``totalTimeSpent`` method via the ``utils`` variable in our templates.
3085 5. Display the time log for an issue::
3087 <table class="otherinfo" tal:condition="context/times">
3088 <tr><th colspan="3" class="header">Time Log
3089 <tal:block
3090 tal:replace="python:utils.totalTimeSpent(context.times)" />
3091 </th></tr>
3092 <tr><th>Date</th><th>Period</th><th>Logged By</th></tr>
3093 <tr tal:repeat="time context/times">
3094 <td tal:content="time/creation"></td>
3095 <td tal:content="time/period"></td>
3096 <td tal:content="time/creator"></td>
3097 </tr>
3098 </table>
3100 I put this just above the Messages log in my issue display. Note our
3101 use of the ``totalTimeSpent`` method which will total up the times
3102 for the issue and return a new Interval. That will be automatically
3103 displayed in the template as text like "+ 1y 2:40" (1 year, 2 hours
3104 and 40 minutes).
3106 8. If you're using a persistent web server - roundup-server or
3107 mod_python for example - then you'll need to restart that to pick up
3108 the code changes. When that's done, you'll be able to use the new
3109 time logging interface.
3111 Using a UN*X passwd file as the user database
3112 ---------------------------------------------
3114 On some systems the primary store of users is the UN*X passwd file. It
3115 holds information on users such as their username, real name, password
3116 and primary user group.
3118 Roundup can use this store as its primary source of user information,
3119 but it needs additional information too - email address(es), roundup
3120 Roles, vacation flags, roundup hyperdb item ids, etc. Also, "retired"
3121 users must still exist in the user database, unlike some passwd files in
3122 which the users are removed when they no longer have access to a system.
3124 To make use of the passwd file, we therefore synchronise between the two
3125 user stores. We also use the passwd file to validate the user logins, as
3126 described in the previous example, `using an external password
3127 validation source`_. We keep the users lists in sync using a fairly
3128 simple script that runs once a day, or several times an hour if more
3129 immediate access is needed. In short, it:
3131 1. parses the passwd file, finding usernames, passwords and real names,
3132 2. compares that list to the current roundup user list:
3134 a. entries no longer in the passwd file are *retired*
3135 b. entries with mismatching real names are *updated*
3136 c. entries only exist in the passwd file are *created*
3138 3. send an email to administrators to let them know what's been done.
3140 The retiring and updating are simple operations, requiring only a call
3141 to ``retire()`` or ``set()``. The creation operation requires more
3142 information though - the user's email address and their roundup Roles.
3143 We're going to assume that the user's email address is the same as their
3144 login name, so we just append the domain name to that. The Roles are
3145 determined using the passwd group identifier - mapping their UN*X group
3146 to an appropriate set of Roles.
3148 The script to perform all this, broken up into its main components, is
3149 as follows. Firstly, we import the necessary modules and open the
3150 tracker we're to work on::
3152 import sys, os, smtplib
3153 from roundup import instance, date
3155 # open the tracker
3156 tracker_home = sys.argv[1]
3157 tracker = instance.open(tracker_home)
3159 Next we read in the *passwd* file from the tracker home::
3161 # read in the users
3162 file = os.path.join(tracker_home, 'users.passwd')
3163 users = [x.strip().split(':') for x in open(file).readlines()]
3165 Handle special users (those to ignore in the file, and those who don't
3166 appear in the file)::
3168 # users to not keep ever, pre-load with the users I know aren't
3169 # "real" users
3170 ignore = ['ekmmon', 'bfast', 'csrmail']
3172 # users to keep - pre-load with the roundup-specific users
3173 keep = ['comment_pool', 'network_pool', 'admin', 'dev-team',
3174 'cs_pool', 'anonymous', 'system_pool', 'automated']
3176 Now we map the UN*X group numbers to the Roles that users should have::
3178 roles = {
3179 '501': 'User,Tech', # tech
3180 '502': 'User', # finance
3181 '503': 'User,CSR', # customer service reps
3182 '504': 'User', # sales
3183 '505': 'User', # marketing
3184 }
3186 Now we do all the work. Note that the body of the script (where we have
3187 the tracker database open) is wrapped in a ``try`` / ``finally`` clause,
3188 so that we always close the database cleanly when we're finished. So, we
3189 now do all the work::
3191 # open the database
3192 db = tracker.open('admin')
3193 try:
3194 # store away messages to send to the tracker admins
3195 msg = []
3197 # loop over the users list read in from the passwd file
3198 for user,passw,uid,gid,real,home,shell in users:
3199 if user in ignore:
3200 # this user shouldn't appear in our tracker
3201 continue
3202 keep.append(user)
3203 try:
3204 # see if the user exists in the tracker
3205 uid = db.user.lookup(user)
3207 # yes, they do - now check the real name for correctness
3208 if real != db.user.get(uid, 'realname'):
3209 db.user.set(uid, realname=real)
3210 msg.append('FIX %s - %s'%(user, real))
3211 except KeyError:
3212 # nope, the user doesn't exist
3213 db.user.create(username=user, realname=real,
3214 address='%s@ekit-inc.com'%user, roles=roles[gid])
3215 msg.append('ADD %s - %s (%s)'%(user, real, roles[gid]))
3217 # now check that all the users in the tracker are also in our
3218 # "keep" list - retire those who aren't
3219 for uid in db.user.list():
3220 user = db.user.get(uid, 'username')
3221 if user not in keep:
3222 db.user.retire(uid)
3223 msg.append('RET %s'%user)
3225 # if we did work, then send email to the tracker admins
3226 if msg:
3227 # create the email
3228 msg = '''Subject: %s user database maintenance
3230 %s
3231 '''%(db.config.TRACKER_NAME, '\n'.join(msg))
3233 # send the email
3234 smtp = smtplib.SMTP(db.config.MAILHOST)
3235 addr = db.config.ADMIN_EMAIL
3236 smtp.sendmail(addr, addr, msg)
3238 # now we're done - commit the changes
3239 db.commit()
3240 finally:
3241 # always close the database cleanly
3242 db.close()
3244 And that's it!
3247 Using an LDAP database for user information
3248 -------------------------------------------
3250 A script that reads users from an LDAP store using
3251 http://python-ldap.sf.net/ and then compares the list to the users in the
3252 roundup user database would be pretty easy to write. You'd then have it run
3253 once an hour / day (or on demand if you can work that into your LDAP store
3254 workflow). See the example `Using a UN*X passwd file as the user database`_
3255 for more information about doing this.
3257 To authenticate off the LDAP store (rather than using the passwords in the
3258 roundup user database) you'd use the same python-ldap module inside an
3259 extension to the cgi interface. You'd do this by overriding the method called
3260 "verifyPassword" on the LoginAction class in your tracker's interfaces.py
3261 module (see `using an external password validation source`_). The method is
3262 implemented by default as::
3264 def verifyPassword(self, userid, password):
3265 ''' Verify the password that the user has supplied
3266 '''
3267 stored = self.db.user.get(self.userid, 'password')
3268 if password == stored:
3269 return 1
3270 if not password and not stored:
3271 return 1
3272 return 0
3274 So you could reimplement this as something like::
3276 def verifyPassword(self, userid, password):
3277 ''' Verify the password that the user has supplied
3278 '''
3279 # look up some unique LDAP information about the user
3280 username = self.db.user.get(self.userid, 'username')
3281 # now verify the password supplied against the LDAP store
3284 Enabling display of either message summaries or the entire messages
3285 -------------------------------------------------------------------
3287 This is pretty simple - all we need to do is copy the code from the
3288 example `displaying only message summaries in the issue display`_ into
3289 our template alongside the summary display, and then introduce a switch
3290 that shows either one or the other. We'll use a new form variable,
3291 ``@whole_messages`` to achieve this::
3293 <table class="messages" tal:condition="context/messages">
3294 <tal:block tal:condition="not:request/form/@whole_messages/value | python:0">
3295 <tr><th colspan="3" class="header">Messages</th>
3296 <th colspan="2" class="header">
3297 <a href="?@whole_messages=yes">show entire messages</a>
3298 </th>
3299 </tr>
3300 <tr tal:repeat="msg context/messages">
3301 <td><a tal:attributes="href string:msg${msg/id}"
3302 tal:content="string:msg${msg/id}"></a></td>
3303 <td tal:content="msg/author">author</td>
3304 <td class="date" tal:content="msg/date/pretty">date</td>
3305 <td tal:content="msg/summary">summary</td>
3306 <td>
3307 <a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">remove</a>
3308 </td>
3309 </tr>
3310 </tal:block>
3312 <tal:block tal:condition="request/form/@whole_messages/value | python:0">
3313 <tr><th colspan="2" class="header">Messages</th>
3314 <th class="header">
3315 <a href="?@whole_messages=">show only summaries</a>
3316 </th>
3317 </tr>
3318 <tal:block tal:repeat="msg context/messages">
3319 <tr>
3320 <th tal:content="msg/author">author</th>
3321 <th class="date" tal:content="msg/date/pretty">date</th>
3322 <th style="text-align: right">
3323 (<a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">remove</a>)
3324 </th>
3325 </tr>
3326 <tr><td colspan="3" tal:content="msg/content"></td></tr>
3327 </tal:block>
3328 </tal:block>
3329 </table>
3332 Blocking issues that depend on other issues
3333 -------------------------------------------
3335 We needed the ability to mark certain issues as "blockers" - that is,
3336 they can't be resolved until another issue (the blocker) they rely on is
3337 resolved. To achieve this:
3339 1. Create a new property on the issue Class,
3340 ``blockers=Multilink("issue")``. Edit your tracker's dbinit.py file.
3341 Where the "issue" class is defined, something like::
3343 issue = IssueClass(db, "issue",
3344 assignedto=Link("user"), topic=Multilink("keyword"),
3345 priority=Link("priority"), status=Link("status"))
3347 add the blockers entry like so::
3349 issue = IssueClass(db, "issue",
3350 blockers=Multilink("issue"),
3351 assignedto=Link("user"), topic=Multilink("keyword"),
3352 priority=Link("priority"), status=Link("status"))
3354 2. Add the new "blockers" property to the issue.item edit page, using
3355 something like::
3357 <th>Waiting On</th>
3358 <td>
3359 <span tal:replace="structure python:context.blockers.field(showid=1,
3360 size=20)" />
3361 <span tal:replace="structure python:db.issue.classhelp('id,title')" />
3362 <span tal:condition="context/blockers"
3363 tal:repeat="blk context/blockers">
3364 <br>View: <a tal:attributes="href string:issue${blk/id}"
3365 tal:content="blk/id"></a>
3366 </span>
3368 You'll need to fiddle with your item page layout to find an
3369 appropriate place to put it - I'll leave that fun part up to you.
3370 Just make sure it appears in the first table, possibly somewhere near
3371 the "superseders" field.
3373 3. Create a new detector module (attached) which enforces the rules:
3375 - issues may not be resolved if they have blockers
3376 - when a blocker is resolved, it's removed from issues it blocks
3378 The contents of the detector should be something like this::
3380 def blockresolution(db, cl, nodeid, newvalues):
3381 ''' If the issue has blockers, don't allow it to be resolved.
3382 '''
3383 if nodeid is None:
3384 blockers = []
3385 else:
3386 blockers = cl.get(nodeid, 'blockers')
3387 blockers = newvalues.get('blockers', blockers)
3389 # don't do anything if there's no blockers or the status hasn't
3390 # changed
3391 if not blockers or not newvalues.has_key('status'):
3392 return
3394 # get the resolved state ID
3395 resolved_id = db.status.lookup('resolved')
3397 # format the info
3398 u = db.config.TRACKER_WEB
3399 s = ', '.join(['<a href="%sissue%s">%s</a>'%(
3400 u,id,id) for id in blockers])
3401 if len(blockers) == 1:
3402 s = 'issue %s is'%s
3403 else:
3404 s = 'issues %s are'%s
3406 # ok, see if we're trying to resolve
3407 if newvalues['status'] == resolved_id:
3408 raise ValueError, "This issue can't be resolved until %s resolved."%s
3410 def resolveblockers(db, cl, nodeid, newvalues):
3411 ''' When we resolve an issue that's a blocker, remove it from the
3412 blockers list of the issue(s) it blocks.
3413 '''
3414 if not newvalues.has_key('status'):
3415 return
3417 # get the resolved state ID
3418 resolved_id = db.status.lookup('resolved')
3420 # interesting?
3421 if newvalues['status'] != resolved_id:
3422 return
3424 # yes - find all the blocked issues, if any, and remove me from
3425 # their blockers list
3426 issues = cl.find(blockers=nodeid)
3427 for issueid in issues:
3428 blockers = cl.get(issueid, 'blockers')
3429 if nodeid in blockers:
3430 blockers.remove(nodeid)
3431 cl.set(issueid, blockers=blockers)
3434 def init(db):
3435 # might, in an obscure situation, happen in a create
3436 db.issue.audit('create', blockresolution)
3437 db.issue.audit('set', blockresolution)
3439 # can only happen on a set
3440 db.issue.react('set', resolveblockers)
3442 Put the above code in a file called "blockers.py" in your tracker's
3443 "detectors" directory.
3445 4. Finally, and this is an optional step, modify the tracker web page
3446 URLs so they filter out issues with any blockers. You do this by
3447 adding an additional filter on "blockers" for the value "-1". For
3448 example, the existing "Show All" link in the "page" template (in the
3449 tracker's "html" directory) looks like this::
3451 <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>
3453 modify it to add the "blockers" info to the URL (note, both the
3454 ":filter" *and* "blockers" values must be specified)::
3456 <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>
3458 That's it. You should now be able to set blockers on your issues. Note
3459 that if you want to know whether an issue has any other issues dependent
3460 on it (i.e. it's in their blockers list) you can look at the journal
3461 history at the bottom of the issue page - look for a "link" event to
3462 another issue's "blockers" property.
3464 Add users to the nosy list based on the topic
3465 ---------------------------------------------
3467 We need the ability to automatically add users to the nosy list based
3468 on the occurence of a topic. Every user should be allowed to edit his
3469 own list of topics for which he wants to be added to the nosy list.
3471 Below will be showed that such a change can be performed with only
3472 minimal understanding of the roundup system, but with clever use
3473 of Copy and Paste.
3475 This requires three changes to the tracker: a change in the database to
3476 allow per-user recording of the lists of topics for which he wants to
3477 be put on the nosy list, a change in the user view allowing to edit
3478 this list of topics, and addition of an auditor which updates the nosy
3479 list when a topic is set.
3481 Adding the nosy topic list
3482 ~~~~~~~~~~~~~~~~~~~~~~~~~~
3484 The change in the database to make is that for any user there should be
3485 a list of topics for which he wants to be put on the nosy list. Adding
3486 a ``Multilink`` of ``keyword`` seem to fullfill this (note that within
3487 the code topics are called ``keywords``.) As such, all what has to be
3488 done is to add a new field to the definition of ``user`` within the
3489 file ``dbinit.py``. We will call this new field ``nosy_keywords``, and
3490 the updated definition of user will be::
3492 user = Class(db, "user",
3493 username=String(), password=Password(),
3494 address=String(), realname=String(),
3495 phone=String(), organisation=String(),
3496 alternate_addresses=String(),
3497 queries=Multilink('query'), roles=String(),
3498 timezone=String(),
3499 nosy_keywords=Multilink('keyword'))
3501 Changing the user view to allow changing the nosy topic list
3502 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3504 We want any user to be able to change the list of topics for which
3505 he will by default be added to the nosy list. We choose to add this
3506 to the user view, as is generated by the file ``html/user.item.html``.
3507 We easily can
3508 see that the topic field in the issue view has very similar editting
3509 requirements as our nosy topics, both being a list of topics. As
3510 such, we search for Topics in ``issue.item.html``, and extract the
3511 associated parts from there. We add this to ``user.item.html`` at the
3512 bottom of the list of viewed items (i.e. just below the 'Alternate
3513 E-mail addresses' in the classic template)::
3515 <tr>
3516 <th>Nosy Topics</th>
3517 <td>
3518 <span tal:replace="structure context/nosy_keywords/field" />
3519 <span tal:replace="structure python:db.keyword.classhelp(property='nosy_keywords')" />
3520 </td>
3521 </tr>
3524 Addition of an auditor to update the nosy list
3525 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3527 The more difficult part is the addition of the logic to actually
3528 at the users to the nosy list when it is required.
3529 The choice is made to perform this action when the topics on an
3530 item are set, including when an item is created.
3531 Here we choose to start out with a copy of the
3532 ``detectors/nosyreaction.py`` detector, which we copy to the file
3533 ``detectors/nosy_keyword_reaction.py``.
3534 This looks like a good start as it also adds users
3535 to the nosy list. A look through the code reveals that the
3536 ``nosyreaction`` function actually is sending the e-mail, which
3537 we do not need. As such, we can change the init function to::
3539 def init(db):
3540 db.issue.audit('create', update_kw_nosy)
3541 db.issue.audit('set', update_kw_nosy)
3543 After that we rename the ``updatenosy`` function to ``update_kw_nosy``.
3544 The first two blocks of code in that function relate to settings
3545 ``current`` to a combination of the old and new nosy lists. This
3546 functionality is left in the new auditor. The following block of
3547 code, which in ``updatenosy`` handled adding the assignedto user(s)
3548 to the nosy list, should be replaced by a block of code to add the
3549 interested users to the nosy list. We choose here to loop over all
3550 new topics, than loop over all users,
3551 and assign the user to the nosy list when the topic in the user's
3552 nosy_keywords. The next part in ``updatenosy``, adding the author
3553 and/or recipients of a message to the nosy list, obviously is not
3554 relevant here and thus is deleted from the new auditor. The last
3555 part, copying the new nosy list to newvalues, does not have to be changed.
3556 This brings the following function::
3558 def update_kw_nosy(db, cl, nodeid, newvalues):
3559 '''Update the nosy list for changes to the topics
3560 '''
3561 # nodeid will be None if this is a new node
3562 current = {}
3563 if nodeid is None:
3564 ok = ('new', 'yes')
3565 else:
3566 ok = ('yes',)
3567 # old node, get the current values from the node if they haven't
3568 # changed
3569 if not newvalues.has_key('nosy'):
3570 nosy = cl.get(nodeid, 'nosy')
3571 for value in nosy:
3572 if not current.has_key(value):
3573 current[value] = 1
3575 # if the nosy list changed in this transaction, init from the new value
3576 if newvalues.has_key('nosy'):
3577 nosy = newvalues.get('nosy', [])
3578 for value in nosy:
3579 if not db.hasnode('user', value):
3580 continue
3581 if not current.has_key(value):
3582 current[value] = 1
3584 # add users with topic in nosy_keywords to the nosy list
3585 if newvalues.has_key('topic') and newvalues['topic'] is not None:
3586 topic_ids = newvalues['topic']
3587 for topic in topic_ids:
3588 # loop over all users,
3589 # and assign user to nosy when topic in nosy_keywords
3590 for user_id in db.user.list():
3591 nosy_kw = db.user.get(user_id, "nosy_keywords")
3592 found = 0
3593 for kw in nosy_kw:
3594 if kw == topic:
3595 found = 1
3596 if found:
3597 current[user_id] = 1
3599 # that's it, save off the new nosy list
3600 newvalues['nosy'] = current.keys()
3602 and these two function are the only ones needed in the file.
3604 TODO: update this example to use the find() Class method.
3606 Caveats
3607 ~~~~~~~
3609 A few problems with the design here can be noted:
3611 Multiple additions
3612 When a user, after automatic selection, is manually removed
3613 from the nosy list, he again is added to the nosy list when the
3614 topic list of the issue is updated. A better design might be
3615 to only check which topics are new compared to the old list
3616 of topics, and only add users when they have indicated
3617 interest on a new topic.
3619 The code could also be changed to only trigger on the create() event,
3620 rather than also on the set() event, thus only setting the nosy list
3621 when the issue is created.
3623 Scalability
3624 In the auditor there is a loop over all users. For a site with
3625 only few users this will pose no serious problem, however, with
3626 many users this will be a serious performance bottleneck.
3627 A way out will be to link from the topics to the users which
3628 selected these topics a nosy topics. This will eliminate the
3629 loop over all users.
3632 Adding action links to the index page
3633 -------------------------------------
3635 Add a column to the item.index.html template.
3637 Resolving the issue::
3639 <a tal:attributes="href
3640 string:issue${i/id}?:status=resolved&:action=edit">resolve</a>
3642 "Take" the issue::
3644 <a tal:attributes="href
3645 string:issue${i/id}?:assignedto=${request/user/id}&:action=edit">take</a>
3647 ... and so on
3649 Users may only edit their issues
3650 --------------------------------
3652 Users registering themselves are granted Provisional access - meaning they
3653 have access to edit the issues they submit, but not others. We create a new
3654 Role called "Provisional User" which is granted to newly-registered users,
3655 and has limited access. One of the Permissions they have is the new "Edit
3656 Own" on issues (regular users have "Edit".) We back up the permissions with
3657 an auditor.
3659 First up, we create the new Role and Permission structure in
3660 ``dbinit.py``::
3662 # New users not approved by the admin
3663 db.security.addRole(name='Provisional User',
3664 description='New user registered via web or email')
3665 p = db.security.addPermission(name='Edit Own', klass='issue',
3666 description='Can only edit own issues')
3667 db.security.addPermissionToRole('Provisional User', p)
3669 # Assign the access and edit Permissions for issue to new users now
3670 p = db.security.getPermission('View', 'issue')
3671 db.security.addPermissionToRole('Provisional User', p)
3672 p = db.security.getPermission('Edit', 'issue')
3673 db.security.addPermissionToRole('Provisional User', p)
3675 # and give the new users access to the web and email interface
3676 p = db.security.getPermission('Web Access')
3677 db.security.addPermissionToRole('Provisional User', p)
3678 p = db.security.getPermission('Email Access')
3679 db.security.addPermissionToRole('Provisional User', p)
3682 Then in the ``config.py`` we change the Role assigned to newly-registered
3683 users, replacing the existing ``'User'`` values::
3685 NEW_WEB_USER_ROLES = 'Provisional User'
3686 NEW_EMAIL_USER_ROLES = 'Provisional User'
3688 Finally we add a new *auditor* to the ``detectors`` directory called
3689 ``provisional_user_auditor.py``::
3691 def audit_provisionaluser(db, cl, nodeid, newvalues):
3692 ''' New users are only allowed to modify their own issues.
3693 '''
3694 if (db.getuid() != cl.get(nodeid, 'creator')
3695 and db.security.hasPermission('Edit Own', db.getuid(), cl.classname)):
3696 raise ValueError, ('You are only allowed to edit your own %s'
3697 % cl.classname)
3699 def init(db):
3700 # fire before changes are made
3701 db.issue.audit('set', audit_provisionaluser)
3702 db.issue.audit('retire', audit_provisionaluser)
3703 db.issue.audit('restore', audit_provisionaluser)
3705 Note that some older trackers might also want to change the ``page.html``
3706 template as follows::
3708 <p class="classblock"
3709 - tal:condition="python:request.user.username != 'anonymous'">
3710 + tal:condition="python:request.user.hasPermission('View', 'user')">
3711 <b>Administration</b><br>
3712 <tal:block tal:condition="python:request.user.hasPermission('Edit', None)">
3713 <a href="home?:template=classlist">Class List</a><br>
3715 (note that the "-" indicates a removed line, and the "+" indicates an added
3716 line).
3719 Colouring the rows in the issue index according to priority
3720 -----------------------------------------------------------
3722 A simple ``tal:attributes`` statement will do the bulk of the work here. In
3723 the ``issue.index.html`` template, add to the ``<tr>`` that displays the
3724 actual rows of data::
3726 <tr tal:attributes="class string:priority-${i/priority/plain}">
3728 and then in your stylesheet (``style.css``) specify the colouring for the
3729 different priorities, like::
3731 tr.priority-critical td {
3732 background-color: red;
3733 }
3735 tr.priority-urgent td {
3736 background-color: orange;
3737 }
3739 and so on, with far less offensive colours :)
3741 Editing multiple items in an index view
3742 ---------------------------------------
3744 To edit the status of all items in the item index view, edit the
3745 ``issue.item.html``:
3747 1. add a form around the listing table, so at the top it reads::
3749 <form method="POST" tal:attributes="action request/classname">
3750 <table class="list">
3752 and at the bottom of that table::
3754 </table>
3755 </form
3757 making sure you match the ``</table>`` from the list table, not the
3758 navigation table or the subsequent form table.
3760 2. in the display for the issue property, change::
3762 <td tal:condition="request/show/status"
3763 tal:content="python:i.status.plain() or default"> </td>
3765 to::
3767 <td tal:condition="request/show/status"
3768 tal:content="structure i/status/field"> </td>
3770 this will result in an edit field for the status property.
3772 3. after the ``tal:block`` which lists the actual index items (marked by
3773 ``tal:repeat="i batch"``) add a new table row::
3775 <tr>
3776 <td tal:attributes="colspan python:len(request.columns)">
3777 <input type="submit" value=" Save Changes ">
3778 <input type="hidden" name="@action" value="edit">
3779 <tal:block replace="structure request/indexargs_form" />
3780 </td>
3781 </tr>
3783 which gives us a submit button, indicates that we are performing an edit
3784 on any changed statuses and the final block will make sure that the
3785 current index view parameters (filtering, columns, etc) will be used in
3786 rendering the next page (the results of the editing).
3788 -------------------
3790 Back to `Table of Contents`_
3792 .. _`Table of Contents`: index.html
3793 .. _`design documentation`: design.html