25b6628d30c715c67e0ce09e30da78d263483a24
1 ===================
2 Customising Roundup
3 ===================
5 :Version: $Revision: 1.103 $
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 five 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. `access controls`_
26 6. change the `web interface`_
28 The third case is special because it takes two distinctly different forms
29 depending upon whether the tracker has been initialised or not. The other two
30 may be done at any time, before or after tracker initialisation. Yes, this
31 includes adding or removing properties from classes.
34 Trackers in a Nutshell
35 ======================
37 Trackers have the following structure:
39 =================== ========================================================
40 Tracker File Description
41 =================== ========================================================
42 config.py Holds the basic `tracker configuration`_
43 dbinit.py Holds the `tracker schema`_
44 interfaces.py Defines the Web and E-Mail interfaces for the tracker
45 select_db.py Selects the database back-end for the tracker
46 db/ Holds the tracker's database
47 db/files/ Holds the tracker's upload files and messages
48 detectors/ Auditors and reactors for this tracker
49 html/ Web interface templates, images and style sheets
50 =================== ========================================================
52 Tracker Configuration
53 =====================
55 The ``config.py`` located in your tracker home contains the basic
56 configuration for the web and e-mail components of roundup's interfaces.
57 As the name suggests, this file is a Python module. This means that any
58 valid python expression may be used in the file. Mostly though, you'll
59 be setting the configuration variables to string values. Python string
60 values must be quoted with either single or double quotes::
62 'this is a string'
63 "this is also a string - use it when the value has 'single quotes'"
64 this is not a string - it's not quoted
66 Python strings may use formatting that's almost identical to C string
67 formatting. The ``%`` operator is used to perform the formatting, like
68 so::
70 'roundup-admin@%s'%MAIL_DOMAIN
72 this will create a string ``'roundup-admin@tracker.domain.example'`` if
73 MAIL_DOMAIN is set to ``'tracker.domain.example'``.
75 You'll also note some values are set to::
77 os.path.join(TRACKER_HOME, 'db')
79 or similar. This creates a new string which holds the path to the
80 ``'db'`` directory in the TRACKER_HOME directory. This is just a
81 convenience so if the TRACKER_HOME changes you don't have to edit
82 multiple valoues.
84 The configuration variables available are:
86 **TRACKER_HOME** - ``os.path.split(__file__)[0]``
87 The tracker home directory. The above default code will automatically
88 determine the tracker home for you, so you can just leave it alone.
90 **MAILHOST** - ``'localhost'``
91 The SMTP mail host that roundup will use to send e-mail.
93 **MAILUSER** - ``()``
94 If your SMTP mail host requires a username and password for access, then
95 specify them here. eg. ``MAILUSER = ('username', 'password')``
97 **MAILHOST_TLS** - ``'no'``
98 If your SMTP mail host provides or requires TLS (Transport Layer
99 Security) then set ``MAILHOST_TLS = 'yes'``
101 **MAILHOST_TLS_KEYFILE** - ``''``
102 If you're using TLS, you may also set MAILHOST_TLS_KEYFILE to the name of
103 a PEM formatted file that contains your private key.
105 **MAILHOST_TLS_CERTFILE** - ``''``
106 If you're using TLS and have specified a MAILHOST_TLS_KEYFILE, you may
107 also set MAILHOST_TLS_CERTFILE to the name of a PEM formatted certificate
108 chain file.
110 **MAIL_DOMAIN** - ``'tracker.domain.example'``
111 The domain name used for email addresses.
113 **DATABASE** - ``os.path.join(TRACKER_HOME, 'db')``
114 This is the directory that the database is going to be stored in. By default
115 it is in the tracker home.
117 **TEMPLATES** - ``os.path.join(TRACKER_HOME, 'html')``
118 This is the directory that the HTML templates reside in. By default they are
119 in the tracker home.
121 **TRACKER_NAME** - ``'Roundup issue tracker'``
122 A descriptive name for your roundup tracker. This is sent out in e-mails and
123 appears in the heading of CGI pages.
125 **TRACKER_EMAIL** - ``'issue_tracker@%s'%MAIL_DOMAIN``
126 The email address that e-mail sent to roundup should go to. Think of it as the
127 tracker's personal e-mail address.
129 **TRACKER_WEB** - ``'http://tracker.example/cgi-bin/roundup.cgi/bugs/'``
130 The web address that the tracker is viewable at. This will be included in
131 information sent to users of the tracker. The URL **must** include the
132 cgi-bin part or anything else that is required to get to the home page of
133 the tracker. You **must** include a trailing '/' in the URL.
135 **ADMIN_EMAIL** - ``'roundup-admin@%s'%MAIL_DOMAIN``
136 The email address that roundup will complain to if it runs into trouble.
138 **EMAIL_FROM_TAG** - ``''``
139 Additional text to include in the "name" part of the ``From:`` address used
140 in nosy messages. If the sending user is "Foo Bar", the ``From:`` line is
141 usually::
143 "Foo Bar" <issue_tracker@tracker.example>
145 The EMAIL_FROM_TAG goes inside the "Foo Bar" quotes like so::
147 "Foo Bar EMAIL_FROM_TAG" <issue_tracker@tracker.example>
149 **MESSAGES_TO_AUTHOR** - ``'new'``, ``'yes'`` or``'no'``
150 Send nosy messages to the author of the message?
151 If 'new' is used, then the author will only be sent the message when the
152 message creates a new issue. If 'yes' then the author will always be sent
153 a copy of the message they wrote.
155 **ADD_AUTHOR_TO_NOSY** - ``'new'``, ``'yes'`` or ``'no'``
156 Does the author of a message get placed on the nosy list automatically?
157 If ``'new'`` is used, then the author will only be added when a message
158 creates a new issue. If ``'yes'``, then the author will be added on followups
159 too. If ``'no'``, they're never added to the nosy.
161 **ADD_RECIPIENTS_TO_NOSY** - ``'new'``, ``'yes'`` or ``'no'``
162 Do the recipients (To:, Cc:) of a message get placed on the nosy list?
163 If ``'new'`` is used, then the recipients will only be added when a message
164 creates a new issue. If ``'yes'``, then the recipients will be added on
165 followups too. If ``'no'``, they're never added to the nosy.
167 **EMAIL_SIGNATURE_POSITION** - ``'top'``, ``'bottom'`` or ``'none'``
168 Where to place the email signature in messages that Roundup generates.
170 **EMAIL_KEEP_QUOTED_TEXT** - ``'yes'`` or ``'no'``
171 Keep email citations. Citations are the part of e-mail which the sender has
172 quoted in their reply to previous e-mail.
174 **EMAIL_LEAVE_BODY_UNCHANGED** - ``'no'``
175 Preserve the email body as is. Enabiling this will cause the entire message
176 body to be stored, including all citations and signatures. It should be
177 either ``'yes'`` or ``'no'``.
179 **MAIL_DEFAULT_CLASS** - ``'issue'`` or ``''``
180 Default class to use in the mailgw if one isn't supplied in email
181 subjects. To disable, comment out the variable below or leave it blank.
183 The default config.py is given below - as you
184 can see, the MAIL_DOMAIN must be edited before any interaction with the
185 tracker is attempted.::
187 # roundup home is this package's directory
188 TRACKER_HOME=os.path.split(__file__)[0]
190 # The SMTP mail host that roundup will use to send mail
191 MAILHOST = 'localhost'
193 # The domain name used for email addresses.
194 MAIL_DOMAIN = 'your.tracker.email.domain.example'
196 # This is the directory that the database is going to be stored in
197 DATABASE = os.path.join(TRACKER_HOME, 'db')
199 # This is the directory that the HTML templates reside in
200 TEMPLATES = os.path.join(TRACKER_HOME, 'html')
202 # A descriptive name for your roundup tracker
203 TRACKER_NAME = 'Roundup issue tracker'
205 # The email address that mail to roundup should go to
206 TRACKER_EMAIL = 'issue_tracker@%s'%MAIL_DOMAIN
208 # The web address that the tracker is viewable at. This will be
209 # included in information sent to users of the tracker. The URL MUST
210 # include the cgi-bin part or anything else that is required to get
211 # to the home page of the tracker. You MUST include a trailing '/'
212 # in the URL.
213 TRACKER_WEB = 'http://tracker.example/cgi-bin/roundup.cgi/bugs/'
215 # The email address that roundup will complain to if it runs into
216 # trouble
217 ADMIN_EMAIL = 'roundup-admin@%s'%MAIL_DOMAIN
219 # Additional text to include in the "name" part of the From: address
220 # used in nosy messages. If the sending user is "Foo Bar", the From:
221 # line is usually: "Foo Bar" <issue_tracker@tracker.example>
222 # the EMAIL_FROM_TAG goes inside the "Foo Bar" quotes like so:
223 # "Foo Bar EMAIL_FROM_TAG" <issue_tracker@tracker.example>
224 EMAIL_FROM_TAG = ""
226 # Send nosy messages to the author of the message
227 MESSAGES_TO_AUTHOR = 'no' # either 'yes' or 'no'
229 # Does the author of a message get placed on the nosy list
230 # automatically? If 'new' is used, then the author will only be
231 # added when a message creates a new issue. If 'yes', then the
232 # author will be added on followups too. If 'no', they're never
233 # added to the nosy.
234 ADD_AUTHOR_TO_NOSY = 'new' # one of 'yes', 'no', 'new'
236 # Do the recipients (To:, Cc:) of a message get placed on the nosy
237 # list? If 'new' is used, then the recipients will only be added
238 # when a message creates a new issue. If 'yes', then the recipients
239 # will be added on followups too. If 'no', they're never added to
240 # the nosy.
241 ADD_RECIPIENTS_TO_NOSY = 'new' # either 'yes', 'no', 'new'
243 # Where to place the email signature
244 EMAIL_SIGNATURE_POSITION = 'bottom' # one of 'top', 'bottom', 'none'
246 # Keep email citations
247 EMAIL_KEEP_QUOTED_TEXT = 'no' # either 'yes' or 'no'
249 # Preserve the email body as is
250 EMAIL_LEAVE_BODY_UNCHANGED = 'no' # either 'yes' or 'no'
252 # Default class to use in the mailgw if one isn't supplied in email
253 # subjects. To disable, comment out the variable below or leave it
254 # blank. Examples:
255 MAIL_DEFAULT_CLASS = 'issue' # use "issue" class by default
256 #MAIL_DEFAULT_CLASS = '' # disable (or just comment the var out)
258 #
259 # SECURITY DEFINITIONS
260 #
261 # define the Roles that a user gets when they register with the
262 # tracker these are a comma-separated string of role names (e.g.
263 # 'Admin,User')
264 NEW_WEB_USER_ROLES = 'User'
265 NEW_EMAIL_USER_ROLES = 'User'
267 Tracker Schema
268 ==============
270 Note: if you modify the schema, you'll most likely need to edit the
271 `web interface`_ HTML template files and `detectors`_ to reflect
272 your changes.
274 A tracker schema defines what data is stored in the tracker's database.
275 Schemas are defined using Python code in the ``dbinit.py`` module of your
276 tracker. The "classic" schema looks like this (see below for the meaning
277 of ``'setkey'``)::
279 pri = Class(db, "priority", name=String(), order=String())
280 pri.setkey("name")
282 stat = Class(db, "status", name=String(), order=String())
283 stat.setkey("name")
285 keyword = Class(db, "keyword", name=String())
286 keyword.setkey("name")
288 user = Class(db, "user", username=String(), organisation=String(),
289 password=String(), address=String(), realname=String(),
290 phone=String())
291 user.setkey("username")
293 msg = FileClass(db, "msg", author=Link("user"), summary=String(),
294 date=Date(), recipients=Multilink("user"),
295 files=Multilink("file"))
297 file = FileClass(db, "file", name=String(), type=String())
299 issue = IssueClass(db, "issue", topic=Multilink("keyword"),
300 status=Link("status"), assignedto=Link("user"),
301 priority=Link("priority"))
302 issue.setkey('title')
305 What you can't do to the schema
306 -------------------------------
308 You must never:
310 **Remove the users class**
311 This class is the only *required* class in Roundup. Similarly, its
312 username, password and address properties must never be removed.
314 **Change the type of a property**
315 Property types must *never* be changed - the database simply doesn't take
316 this kind of action into account. Note that you can't just remove a
317 property and re-add it as a new type either. If you wanted to make the
318 assignedto property a Multilink, you'd need to create a new property
319 assignedto_list and remove the old assignedto property.
322 What you can do to the schema
323 -----------------------------
325 Your schema may be changed at any time before or after the tracker has been
326 initialised (or used). You may:
328 **Add new properties to classes, or add whole new classes**
329 This is painless and easy to do - there are generally no repurcussions
330 from adding new information to a tracker's schema.
332 **Remove properties**
333 Removing properties is a little more tricky - you need to make sure that
334 the property is no longer used in the `web interface`_ *or* by the
335 detectors_.
339 Classes and Properties - creating a new information store
340 ---------------------------------------------------------
342 In the tracker above, we've defined 7 classes of information:
344 priority
345 Defines the possible levels of urgency for issues.
347 status
348 Defines the possible states of processing the issue may be in.
350 keyword
351 Initially empty, will hold keywords useful for searching issues.
353 user
354 Initially holding the "admin" user, will eventually have an entry
355 for all users using roundup.
357 msg
358 Initially empty, will hold all e-mail messages sent to or
359 generated by roundup.
361 file
362 Initially empty, will hold all files attached to issues.
364 issue
365 Initially empty, this is where the issue information is stored.
367 We define the "priority" and "status" classes to allow two things:
368 reduction in the amount of information stored on the issue and more
369 powerful, accurate searching of issues by priority and status. By only
370 requiring a link on the issue (which is stored as a single number) we
371 reduce the chance that someone mis-types a priority or status - or
372 simply makes a new one up.
375 Class and Items
376 ~~~~~~~~~~~~~~~
378 A Class defines a particular class (or type) of data that will be stored
379 in the database. A class comprises one or more properties, which gives
380 the information about the class items.
382 The actual data entered into the database, using ``class.create()``, are
383 called items. They have a special immutable property called ``'id'``. We
384 sometimes refer to this as the *itemid*.
387 Properties
388 ~~~~~~~~~~
390 A Class is comprised of one or more properties of the following types:
392 * String properties are for storing arbitrary-length strings.
393 * Password properties are for storing encoded arbitrary-length strings.
394 The default encoding is defined on the ``roundup.password.Password``
395 class.
396 * Date properties store date-and-time stamps. Their values are Timestamp
397 objects.
398 * Number properties store numeric values.
399 * Boolean properties store on/off, yes/no, true/false values.
400 * A Link property refers to a single other item selected from a
401 specified class. The class is part of the property; the value is an
402 integer, the id of the chosen item.
403 * A Multilink property refers to possibly many items in a specified
404 class. The value is a list of integers.
407 FileClass
408 ~~~~~~~~~
410 FileClasses save their "content" attribute off in a separate file from
411 the rest of the database. This reduces the number of large entries in
412 the database, which generally makes databases more efficient, and also
413 allows us to use command-line tools to operate on the files. They are
414 stored in the files sub-directory of the ``'db'`` directory in your
415 tracker.
418 IssueClass
419 ~~~~~~~~~~
421 IssueClasses automatically include the "messages", "files", "nosy", and
422 "superseder" properties.
424 The messages and files properties list the links to the messages and
425 files related to the issue. The nosy property is a list of links to
426 users who wish to be informed of changes to the issue - they get "CC'ed"
427 e-mails when messages are sent to or generated by the issue. The nosy
428 reactor (in the ``'detectors'`` directory) handles this action. The
429 superseder link indicates an issue which has superseded this one.
431 They also have the dynamically generated "creation", "activity" and
432 "creator" properties.
434 The value of the "creation" property is the date when an item was
435 created, and the value of the "activity" property is the date when any
436 property on the item was last edited (equivalently, these are the dates
437 on the first and last records in the item's journal). The "creator"
438 property holds a link to the user that created the issue.
441 setkey(property)
442 ~~~~~~~~~~~~~~~~
444 Select a String property of the class to be the key property. The key
445 property must be unique, and allows references to the items in the class
446 by the content of the key property. That is, we can refer to users by
447 their username: for example, let's say that there's an issue in roundup,
448 issue 23. There's also a user, richard, who happens to be user 2. To
449 assign an issue to him, we could do either of::
451 roundup-admin set issue23 assignedto=2
453 or::
455 roundup-admin set issue23 assignedto=richard
457 Note, the same thing can be done in the web and e-mail interfaces.
459 If a class does not have an "order" property, the key is also used to
460 sort instances of the class when it is rendered in the user interface.
461 (If a class has no "order" property, sorting is by the labelproperty of
462 the class. This is computed, in order of precedence, as the key, the
463 "name", the "title", or the first property alphabetically.)
466 create(information)
467 ~~~~~~~~~~~~~~~~~~~
469 Create an item in the database. This is generally used to create items
470 in the "definitional" classes like "priority" and "status".
473 Examples of adding to your schema
474 ---------------------------------
476 TODO
479 Detectors - adding behaviour to your tracker
480 ============================================
481 .. _detectors:
483 Detectors are initialised every time you open your tracker database, so
484 you're free to add and remove them any time, even after the database is
485 initialised via the "roundup-admin initialise" command.
487 The detectors in your tracker fire *before* (**auditors**) and *after*
488 (**reactors**) changes to the contents of your database. They are Python
489 modules that sit in your tracker's ``detectors`` directory. You will
490 have some installed by default - have a look. You can write new
491 detectors or modify the existing ones. The existing detectors installed
492 for you are:
494 **nosyreaction.py**
495 This provides the automatic nosy list maintenance and email sending.
496 The nosy reactor (``nosyreaction``) fires when new messages are added
497 to issues. The nosy auditor (``updatenosy``) fires when issues are
498 changed, and figures out what changes need to be made to the nosy list
499 (such as adding new authors, etc.)
500 **statusauditor.py**
501 This provides the ``chatty`` auditor which changes the issue status
502 from ``unread`` or ``closed`` to ``chatting`` if new messages appear.
503 It also provides the ``presetunread`` auditor which pre-sets the
504 status to ``unread`` on new items if the status isn't explicitly
505 defined.
506 **messagesummary.py**
507 Generates the ``summary`` property for new messages based on the message
508 content.
509 **userauditor.py**
510 Verifies the content of some of the user fields (email addresses and
511 roles lists).
513 If you don't want this default behaviour, you're completely free to change
514 or remove these detectors.
516 See the detectors section in the `design document`__ for details of the
517 interface for detectors.
519 __ design.html
521 Sample additional detectors that have been found useful will appear in
522 the ``'detectors'`` directory of the Roundup distribution. If you want
523 to use one, copy it to the ``'detectors'`` of your tracker instance:
525 **newissuecopy.py**
526 This detector sends an email to a team address whenever a new issue is
527 created. The address is hard-coded into the detector, so edit it
528 before you use it (look for the text 'team@team.host') or you'll get
529 email errors!
531 The detector code::
533 from roundup import roundupdb
535 def newissuecopy(db, cl, nodeid, oldvalues):
536 ''' Copy a message about new issues to a team address.
537 '''
538 # so use all the messages in the create
539 change_note = cl.generateCreateNote(nodeid)
541 # send a copy to the nosy list
542 for msgid in cl.get(nodeid, 'messages'):
543 try:
544 # note: last arg must be a list
545 cl.send_message(nodeid, msgid, change_note,
546 ['team@team.host'])
547 except roundupdb.MessageSendError, message:
548 raise roundupdb.DetectorError, message
550 def init(db):
551 db.issue.react('create', newissuecopy)
554 Database Content
555 ================
557 Note: if you modify the content of definitional classes, you'll most
558 likely need to edit the tracker `detectors`_ to reflect your
559 changes.
561 Customisation of the special "definitional" classes (eg. status,
562 priority, resolution, ...) may be done either before or after the
563 tracker is initialised. The actual method of doing so is completely
564 different in each case though, so be careful to use the right one.
566 **Changing content before tracker initialisation**
567 Edit the dbinit module in your tracker to alter the items created in
568 using the ``create()`` methods.
570 **Changing content after tracker initialisation**
571 As the "admin" user, click on the "class list" link in the web
572 interface to bring up a list of all database classes. Click on the
573 name of the class you wish to change the content of.
575 You may also use the ``roundup-admin`` interface's create, set and
576 retire methods to add, alter or remove items from the classes in
577 question.
579 See "`adding a new field to the classic schema`_" for an example that
580 requires database content changes.
583 Access Controls
584 ===============
586 A set of Permissions is built into the security module by default:
588 - Edit (everything)
589 - View (everything)
591 The default interfaces define:
593 - Web Registration
594 - Web Access
595 - Web Roles
596 - Email Registration
597 - Email Access
599 These are hooked into the default Roles:
601 - Admin (Edit everything, View everything, Web Roles)
602 - User (Web Access, Email Access)
603 - Anonymous (Web Registration, Email Registration)
605 And finally, the "admin" user gets the "Admin" Role, and the "anonymous"
606 user gets "Anonymous" assigned when the database is initialised on
607 installation. The two default schemas then define:
609 - Edit issue, View issue (both)
610 - Edit file, View file (both)
611 - Edit msg, View msg (both)
612 - Edit support, View support (extended only)
614 and assign those Permissions to the "User" Role. Put together, these
615 settings appear in the ``open()`` function of the tracker ``dbinit.py``
616 (the following is taken from the "minimal" template's ``dbinit.py``)::
618 #
619 # SECURITY SETTINGS
620 #
621 # new permissions for this schema
622 for cl in ('user', ):
623 db.security.addPermission(name="Edit", klass=cl,
624 description="User is allowed to edit "+cl)
625 db.security.addPermission(name="View", klass=cl,
626 description="User is allowed to access "+cl)
628 # and give the regular users access to the web and email interface
629 p = db.security.getPermission('Web Access')
630 db.security.addPermissionToRole('User', p)
631 p = db.security.getPermission('Email Access')
632 db.security.addPermissionToRole('User', p)
634 # May users view other user information? Comment these lines out
635 # if you don't want them to
636 p = db.security.getPermission('View', 'user')
637 db.security.addPermissionToRole('User', p)
639 # Assign the appropriate permissions to the anonymous user's
640 # Anonymous role. Choices here are:
641 # - Allow anonymous users to register through the web
642 p = db.security.getPermission('Web Registration')
643 db.security.addPermissionToRole('Anonymous', p)
644 # - Allow anonymous (new) users to register through the email
645 # gateway
646 p = db.security.getPermission('Email Registration')
647 db.security.addPermissionToRole('Anonymous', p)
650 New User Roles
651 --------------
653 New users are assigned the Roles defined in the config file as:
655 - NEW_WEB_USER_ROLES
656 - NEW_EMAIL_USER_ROLES
659 Changing Access Controls
660 ------------------------
662 You may alter the configuration variables to change the Role that new
663 web or email users get, for example to not give them access to the web
664 interface if they register through email.
666 You may use the ``roundup-admin`` "``security``" command to display the
667 current Role and Permission configuration in your tracker.
670 Adding a new Permission
671 ~~~~~~~~~~~~~~~~~~~~~~~
673 When adding a new Permission, you will need to:
675 1. add it to your tracker's dbinit so it is created
676 2. enable it for the Roles that should have it (verify with
677 "``roundup-admin security``")
678 3. add it to the relevant HTML interface templates
679 4. add it to the appropriate xxxPermission methods on in your tracker
680 interfaces module
683 Example Scenarios
684 ~~~~~~~~~~~~~~~~~
686 **automatic registration of users in the e-mail gateway**
687 By giving the "anonymous" user the "Email Registration" Role, any
688 unidentified user will automatically be registered with the tracker
689 (with no password, so they won't be able to log in through the web
690 until an admin sets their password). Note: this is the default
691 behaviour in the tracker templates that ship with Roundup.
693 **anonymous access through the e-mail gateway**
694 Give the "anonymous" user the "Email Access" and ("Edit", "issue")
695 Roles but do not not give them the "Email Registration" Role. This
696 means that when an unknown user sends email into the tracker, they're
697 automatically logged in as "anonymous". Since they don't have the
698 "Email Registration" Role, they won't be automatically registered, but
699 since "anonymous" has permission to use the gateway, they'll still be
700 able to submit issues. Note that the Sender information - their email
701 address - will not be available - they're *anonymous*.
703 **only developers may be assigned issues**
704 Create a new Permission called "Fixer" for the "issue" class. Create a
705 new Role "Developer" which has that Permission, and assign that to the
706 appropriate users. Filter the list of users available in the assignedto
707 list to include only those users. Enforce the Permission with an
708 auditor. See the example
709 `restricting the list of users that are assignable to a task`_.
711 **only managers may sign off issues as complete**
712 Create a new Permission called "Closer" for the "issue" class. Create a
713 new Role "Manager" which has that Permission, and assign that to the
714 appropriate users. In your web interface, only display the "resolved"
715 issue state option when the user has the "Closer" Permissions. Enforce
716 the Permission with an auditor. This is very similar to the previous
717 example, except that the web interface check would look like::
719 <option tal:condition="python:request.user.hasPermission('Closer')"
720 value="resolved">Resolved</option>
722 **don't give web access to users who register through email**
723 Create a new Role called "Email User" which has all the Permissions of
724 the normal "User" Role minus the "Web Access" Permission. This will
725 allow users to send in emails to the tracker, but not access the web
726 interface.
728 **let some users edit the details of all users**
729 Create a new Role called "User Admin" which has the Permission for
730 editing users::
732 db.security.addRole(name='User Admin', description='Managing users')
733 p = db.security.getPermission('Edit', 'user')
734 db.security.addPermissionToRole('User Admin', p)
736 and assign the Role to the users who need the permission.
739 Web Interface
740 =============
742 .. contents::
743 :local:
744 :depth: 1
746 The web interface is provided by the ``roundup.cgi.client`` module and
747 is used by ``roundup.cgi``, ``roundup-server`` and ``ZRoundup``
748 (``ZRoundup`` is broken, until further notice). In all cases, we
749 determine which tracker is being accessed (the first part of the URL
750 path inside the scope of the CGI handler) and pass control on to the
751 tracker ``interfaces.Client`` class - which uses the ``Client`` class
752 from ``roundup.cgi.client`` - which handles the rest of the access
753 through its ``main()`` method. This means that you can do pretty much
754 anything you want as a web interface to your tracker.
756 Repercussions of changing the tracker schema
757 ---------------------------------------------
759 If you choose to change the `tracker schema`_ you will need to ensure
760 the web interface knows about it:
762 1. Index, item and search pages for the relevant classes may need to
763 have properties added or removed,
764 2. The "page" template may require links to be changed, as might the
765 "home" page's content arguments.
767 How requests are processed
768 --------------------------
770 The basic processing of a web request proceeds as follows:
772 1. figure out who we are, defaulting to the "anonymous" user
773 2. figure out what the request is for - we call this the "context"
774 3. handle any requested action (item edit, search, ...)
775 4. render the template requested by the context, resulting in HTML
776 output
778 In some situations, exceptions occur:
780 - HTTP Redirect (generally raised by an action)
781 - SendFile (generally raised by ``determine_context``)
782 here we serve up a FileClass "content" property
783 - SendStaticFile (generally raised by ``determine_context``)
784 here we serve up a file from the tracker "html" directory
785 - Unauthorised (generally raised by an action)
786 here the action is cancelled, the request is rendered and an error
787 message is displayed indicating that permission was not granted for
788 the action to take place
789 - NotFound (raised wherever it needs to be)
790 this exception percolates up to the CGI interface that called the
791 client
793 Determining web context
794 -----------------------
796 To determine the "context" of a request, we look at the URL and the
797 special request variable ``@template``. The URL path after the tracker
798 identifier is examined. Typical URL paths look like:
800 1. ``/tracker/issue``
801 2. ``/tracker/issue1``
802 3. ``/tracker/_file/style.css``
803 4. ``/cgi-bin/roundup.cgi/tracker/file1``
804 5. ``/cgi-bin/roundup.cgi/tracker/file1/kitten.png``
806 where the "tracker identifier" is "tracker" in the above cases. That means
807 we're looking at "issue", "issue1", "_file/style.css", "file1" and
808 "file1/kitten.png" in the cases above. The path is generally only one
809 entry long - longer paths are handled differently.
811 a. if there is no path, then we are in the "home" context.
812 b. if the path starts with "_file" (as in example 3,
813 "/tracker/_file/style.css"), then the additional path entry,
814 "style.css" specifies the filename of a static file we're to serve up
815 from the tracker "html" directory. Raises a SendStaticFile exception.
816 c. if there is something in the path (as in example 1, "issue"), it
817 identifies the tracker class we're to display.
818 d. if the path is an item designator (as in examples 2 and 4, "issue1"
819 and "file1"), then we're to display a specific item.
820 e. if the path starts with an item designator and is longer than one
821 entry (as in example 5, "file1/kitten.png"), then we're assumed to be
822 handling an item of a ``FileClass``, and the extra path information
823 gives the filename that the client is going to label the download
824 with (i.e. "file1/kitten.png" is nicer to download than "file1").
825 This raises a ``SendFile`` exception.
827 Both b. and e. stop before we bother to determine the template we're
828 going to use. That's because they don't actually use templates.
830 The template used is specified by the ``@template`` CGI variable, which
831 defaults to:
833 - only classname suplied: "index"
834 - full item designator supplied: "item"
837 Performing actions in web requests
838 ----------------------------------
840 When a user requests a web page, they may optionally also request for an
841 action to take place. As described in `how requests are processed`_, the
842 action is performed before the requested page is generated. Actions are
843 triggered by using a ``@action`` CGI variable, where the value is one
844 of:
846 **login**
847 Attempt to log a user in.
849 **logout**
850 Log the user out - make them "anonymous".
852 **register**
853 Attempt to create a new user based on the contents of the form and then
854 log them in.
856 **edit**
857 Perform an edit of an item in the database. There are some `special form
858 variables`_ you may use.
860 **new**
861 Add a new item to the database. You may use the same `special form
862 variables`_ as in the "edit" action.
864 **retire**
865 Retire the item in the database.
867 **editCSV**
868 Performs an edit of all of a class' items in one go. See also the
869 *class*.csv templating method which generates the CSV data to be
870 edited, and the ``'_generic.index'`` template which uses both of these
871 features.
873 **search**
874 Mangle some of the form variables:
876 - Set the form ":filter" variable based on the values of the filter
877 variables - if they're set to anything other than "dontcare" then add
878 them to :filter.
880 - Also handle the ":queryname" variable and save off the query to the
881 user's query list.
883 Each of the actions is implemented by a corresponding ``*actionAction*``
884 (where "action" is the name of the action) method on the
885 ``roundup.cgi.Client`` class, which also happens to be available in your
886 tracker instance as ``interfaces.Client``. So if you need to define new
887 actions, you may add them there (see `defining new web actions`_).
889 Each action also has a corresponding ``*actionPermission*`` (where
890 "action" is the name of the action) method which determines whether the
891 action is permissible given the current user. The base permission checks
892 are:
894 **login**
895 Determine whether the user has permission to log in. Base behaviour is
896 to check the user has "Web Access".
897 **logout**
898 No permission checks are made.
899 **register**
900 Determine whether the user has permission to register. Base behaviour
901 is to check the user has the "Web Registration" Permission.
902 **edit**
903 Determine whether the user has permission to edit this item. Base
904 behaviour is to check whether the user can edit this class. If we're
905 editing the "user" class, users are allowed to edit their own details -
906 unless they try to edit the "roles" property, which requires the
907 special Permission "Web Roles".
908 **new**
909 Determine whether the user has permission to create (or edit) this
910 item. Base behaviour is to check the user can edit this class. No
911 additional property checks are made. Additionally, new user items may
912 be created if the user has the "Web Registration" Permission.
913 **editCSV**
914 Determine whether the user has permission to edit this class. Base
915 behaviour is to check whether the user may edit this class.
916 **search**
917 Determine whether the user has permission to search this class. Base
918 behaviour is to check whether the user may view this class.
921 Special form variables
922 ----------------------
924 Item properties and their values are edited with html FORM
925 variables and their values. You can:
927 - Change the value of some property of the current item.
928 - Create a new item of any class, and edit the new item's
929 properties,
930 - Attach newly created items to a multilink property of the
931 current item.
932 - Remove items from a multilink property of the current item.
933 - Specify that some properties are required for the edit
934 operation to be successful.
936 In the following, <bracketed> values are variable, "@" may be
937 either ":" or "@", and other text "required" is fixed.
939 Most properties are specified as form variables:
941 ``<propname>``
942 property on the current context item
944 ``<designator>"@"<propname>``
945 property on the indicated item (for editing related information)
947 Designators name a specific item of a class.
949 ``<classname><N>``
950 Name an existing item of class <classname>.
952 ``<classname>"-"<N>``
953 Name the <N>th new item of class <classname>. If the form
954 submission is successful, a new item of <classname> is
955 created. Within the submitted form, a particular
956 designator of this form always refers to the same new
957 item.
959 Once we have determined the "propname", we look at it to see
960 if it's special:
962 ``@required``
963 The associated form value is a comma-separated list of
964 property names that must be specified when the form is
965 submitted for the edit operation to succeed.
967 When the <designator> is missing, the properties are
968 for the current context item. When <designator> is
969 present, they are for the item specified by
970 <designator>.
972 The "@required" specifier must come before any of the
973 properties it refers to are assigned in the form.
975 ``@remove@<propname>=id(s)`` or ``@add@<propname>=id(s)``
976 The "@add@" and "@remove@" edit actions apply only to
977 Multilink properties. The form value must be a
978 comma-separate list of keys for the class specified by
979 the simple form variable. The listed items are added
980 to (respectively, removed from) the specified
981 property.
983 ``@link@<propname>=<designator>``
984 If the edit action is "@link@", the simple form
985 variable must specify a Link or Multilink property.
986 The form value is a comma-separated list of
987 designators. The item corresponding to each
988 designator is linked to the property given by simple
989 form variable.
991 None of the above (ie. just a simple form value)
992 The value of the form variable is converted
993 appropriately, depending on the type of the property.
995 For a Link('klass') property, the form value is a
996 single key for 'klass', where the key field is
997 specified in dbinit.py.
999 For a Multilink('klass') property, the form value is a
1000 comma-separated list of keys for 'klass', where the
1001 key field is specified in dbinit.py.
1003 Note that for simple-form-variables specifiying Link
1004 and Multilink properties, the linked-to class must
1005 have a key field.
1007 For a String() property specifying a filename, the
1008 file named by the form value is uploaded. This means we
1009 try to set additional properties "filename" and "type" (if
1010 they are valid for the class). Otherwise, the property
1011 is set to the form value.
1013 For Date(), Interval(), Boolean(), and Number()
1014 properties, the form value is converted to the
1015 appropriate
1017 Any of the form variables may be prefixed with a classname or
1018 designator.
1020 Two special form values are supported for backwards compatibility:
1022 @note
1023 This is equivalent to::
1025 @link@messages=msg-1
1026 @msg-1@content=value
1028 except that in addition, the "author" and "date" properties of
1029 "msg-1" are set to the userid of the submitter, and the current
1030 time, respectively.
1032 @file
1033 This is equivalent to::
1035 @link@files=file-1
1036 @file-1@content=value
1038 The String content value is handled as described above for file
1039 uploads.
1041 If both the "@note" and "@file" form variables are
1042 specified, the action::
1044 @link@msg-1@files=file-1
1046 is also performed.
1048 We also check that FileClass items have a "content" property with
1049 actual content, otherwise we remove them from all_props before
1050 returning.
1054 Default templates
1055 -----------------
1057 Most customisation of the web view can be done by modifying the
1058 templates in the tracker ``'html'`` directory. There are several types
1059 of files in there. The *minimal* template includes:
1061 **page.html**
1062 This template usually defines the overall look of your tracker. When
1063 you view an issue, it appears inside this template. When you view an
1064 index, it also appears inside this template. This template defines a
1065 macro called "icing" which is used by almost all other templates as a
1066 coating for their content, using its "content" slot. It also defines
1067 the "head_title" and "body_title" slots to allow setting of the page
1068 title.
1069 **home.html**
1070 the default page displayed when no other page is indicated by the user
1071 **home.classlist.html**
1072 a special version of the default page that lists the classes in the
1073 tracker
1074 **classname.item.html**
1075 displays an item of the *classname* class
1076 **classname.index.html**
1077 displays a list of *classname* items
1078 **classname.search.html**
1079 displays a search page for *classname* items
1080 **_generic.index.html**
1081 used to display a list of items where there is no
1082 ``*classname*.index`` available
1083 **_generic.help.html**
1084 used to display a "class help" page where there is no
1085 ``*classname*.help``
1086 **user.register.html**
1087 a special page just for the user class, that renders the registration
1088 page
1089 **style.css.html**
1090 a static file that is served up as-is
1092 The *classic* template has a number of additional templates.
1094 Note: Remember that you can create any template extension you want to,
1095 so if you just want to play around with the templating for new issues,
1096 you can copy the current "issue.item" template to "issue.test", and then
1097 access the test template using the "@template" URL argument::
1099 http://your.tracker.example/tracker/issue?@template=test
1101 and it won't affect your users using the "issue.item" template.
1104 How the templates work
1105 ----------------------
1108 Basic Templating Actions
1109 ~~~~~~~~~~~~~~~~~~~~~~~~
1111 Roundup's templates consist of special attributes on the HTML tags.
1112 These attributes form the Template Attribute Language, or TAL. The basic
1113 TAL commands are:
1115 **tal:define="variable expression; variable expression; ..."**
1116 Define a new variable that is local to this tag and its contents. For
1117 example::
1119 <html tal:define="title request/description">
1120 <head><title tal:content="title"></title></head>
1121 </html>
1123 In this example, the variable "title" is defined as the result of the
1124 expression "request/description". The "tal:content" command inside the
1125 <html> tag may then use the "title" variable.
1127 **tal:condition="expression"**
1128 Only keep this tag and its contents if the expression is true. For
1129 example::
1131 <p tal:condition="python:request.user.hasPermission('View', 'issue')">
1132 Display some issue information.
1133 </p>
1135 In the example, the <p> tag and its contents are only displayed if
1136 the user has the "View" permission for issues. We consider the number
1137 zero, a blank string, an empty list, and the built-in variable
1138 nothing to be false values. Nearly every other value is true,
1139 including non-zero numbers, and strings with anything in them (even
1140 spaces!).
1142 **tal:repeat="variable expression"**
1143 Repeat this tag and its contents for each element of the sequence
1144 that the expression returns, defining a new local variable and a
1145 special "repeat" variable for each element. For example::
1147 <tr tal:repeat="u user/list">
1148 <td tal:content="u/id"></td>
1149 <td tal:content="u/username"></td>
1150 <td tal:content="u/realname"></td>
1151 </tr>
1153 The example would iterate over the sequence of users returned by
1154 "user/list" and define the local variable "u" for each entry.
1156 **tal:replace="expression"**
1157 Replace this tag with the result of the expression. For example::
1159 <span tal:replace="request/user/realname" />
1161 The example would replace the <span> tag and its contents with the
1162 user's realname. If the user's realname was "Bruce", then the
1163 resultant output would be "Bruce".
1165 **tal:content="expression"**
1166 Replace the contents of this tag with the result of the expression.
1167 For example::
1169 <span tal:content="request/user/realname">user's name appears here
1170 </span>
1172 The example would replace the contents of the <span> tag with the
1173 user's realname. If the user's realname was "Bruce" then the
1174 resultant output would be "<span>Bruce</span>".
1176 **tal:attributes="attribute expression; attribute expression; ..."**
1177 Set attributes on this tag to the results of expressions. For
1178 example::
1180 <a tal:attributes="href string:user${request/user/id}">My Details</a>
1182 In the example, the "href" attribute of the <a> tag is set to the
1183 value of the "string:user${request/user/id}" expression, which will
1184 be something like "user123".
1186 **tal:omit-tag="expression"**
1187 Remove this tag (but not its contents) if the expression is true. For
1188 example::
1190 <span tal:omit-tag="python:1">Hello, world!</span>
1192 would result in output of::
1194 Hello, world!
1196 Note that the commands on a given tag are evaulated in the order above,
1197 so *define* comes before *condition*, and so on.
1199 Additionally, you may include tags such as <tal:block>, which are
1200 removed from output. Its content is kept, but the tag itself is not (so
1201 don't go using any "tal:attributes" commands on it). This is useful for
1202 making arbitrary blocks of HTML conditional or repeatable (very handy
1203 for repeating multiple table rows, which would othewise require an
1204 illegal tag placement to effect the repeat).
1207 Templating Expressions
1208 ~~~~~~~~~~~~~~~~~~~~~~
1210 The expressions you may use in the attribute values may be one of the
1211 following forms:
1213 **Path Expressions** - eg. ``item/status/checklist``
1214 These are object attribute / item accesses. Roughly speaking, the
1215 path ``item/status/checklist`` is broken into parts ``item``,
1216 ``status`` and ``checklist``. The ``item`` part is the root of the
1217 expression. We then look for a ``status`` attribute on ``item``, or
1218 failing that, a ``status`` item (as in ``item['status']``). If that
1219 fails, the path expression fails. When we get to the end, the object
1220 we're left with is evaluated to get a string - if it is a method, it
1221 is called; if it is an object, it is stringified. Path expressions
1222 may have an optional ``path:`` prefix, but they are the default
1223 expression type, so it's not necessary.
1225 If an expression evaluates to ``default``, then the expression is
1226 "cancelled" - whatever HTML already exists in the template will
1227 remain (tag content in the case of ``tal:content``, attributes in the
1228 case of ``tal:attributes``).
1230 If an expression evaluates to ``nothing`` then the target of the
1231 expression is removed (tag content in the case of ``tal:content``,
1232 attributes in the case of ``tal:attributes`` and the tag itself in
1233 the case of ``tal:replace``).
1235 If an element in the path may not exist, then you can use the ``|``
1236 operator in the expression to provide an alternative. So, the
1237 expression ``request/form/foo/value | default`` would simply leave
1238 the current HTML in place if the "foo" form variable doesn't exist.
1240 You may use the python function ``path``, as in
1241 ``path("item/status")``, to embed path expressions in Python
1242 expressions.
1244 **String Expressions** - eg. ``string:hello ${user/name}``
1245 These expressions are simple string interpolations - though they can
1246 be just plain strings with no interpolation if you want. The
1247 expression in the ``${ ... }`` is just a path expression as above.
1249 **Python Expressions** - eg. ``python: 1+1``
1250 These expressions give the full power of Python. All the "root level"
1251 variables are available, so ``python:item.status.checklist()`` would
1252 be equivalent to ``item/status/checklist``, assuming that
1253 ``checklist`` is a method.
1255 Modifiers:
1257 **structure** - eg. ``structure python:msg.content.plain(hyperlink=1)``
1258 The result of expressions are normally *escaped* to be safe for HTML
1259 display (all "<", ">" and "&" are turned into special entities). The
1260 ``structure`` expression modifier turns off this escaping - the
1261 result of the expression is now assumed to be HTML, which is passed
1262 to the web browser for rendering.
1264 **not:** - eg. ``not:python:1=1``
1265 This simply inverts the logical true/false value of another
1266 expression.
1269 Template Macros
1270 ~~~~~~~~~~~~~~~
1272 Macros are used in Roundup to save us from repeating the same common
1273 page stuctures over and over. The most common (and probably only) macro
1274 you'll use is the "icing" macro defined in the "page" template.
1276 Macros are generated and used inside your templates using special
1277 attributes similar to the `basic templating actions`_. In this case,
1278 though, the attributes belong to the Macro Expansion Template Attribute
1279 Language, or METAL. The macro commands are:
1281 **metal:define-macro="macro name"**
1282 Define that the tag and its contents are now a macro that may be
1283 inserted into other templates using the *use-macro* command. For
1284 example::
1286 <html metal:define-macro="page">
1287 ...
1288 </html>
1290 defines a macro called "page" using the ``<html>`` tag and its
1291 contents. Once defined, macros are stored on the template they're
1292 defined on in the ``macros`` attribute. You can access them later on
1293 through the ``templates`` variable, eg. the most common
1294 ``templates/page/macros/icing`` to access the "page" macro of the
1295 "page" template.
1297 **metal:use-macro="path expression"**
1298 Use a macro, which is identified by the path expression (see above).
1299 This will replace the current tag with the identified macro contents.
1300 For example::
1302 <tal:block metal:use-macro="templates/page/macros/icing">
1303 ...
1304 </tal:block>
1306 will replace the tag and its contents with the "page" macro of the
1307 "page" template.
1309 **metal:define-slot="slot name"** and **metal:fill-slot="slot name"**
1310 To define *dynamic* parts of the macro, you define "slots" which may
1311 be filled when the macro is used with a *use-macro* command. For
1312 example, the ``templates/page/macros/icing`` macro defines a slot like
1313 so::
1315 <title metal:define-slot="head_title">title goes here</title>
1317 In your *use-macro* command, you may now use a *fill-slot* command
1318 like this::
1320 <title metal:fill-slot="head_title">My Title</title>
1322 where the tag that fills the slot completely replaces the one defined
1323 as the slot in the macro.
1325 Note that you may not mix METAL and TAL commands on the same tag, but
1326 TAL commands may be used freely inside METAL-using tags (so your
1327 *fill-slots* tags may have all manner of TAL inside them).
1330 Information available to templates
1331 ----------------------------------
1333 Note: this is implemented by
1334 ``roundup.cgi.templating.RoundupPageTemplate``
1336 The following variables are available to templates.
1338 **context**
1339 The current context. This is either None, a `hyperdb class wrapper`_
1340 or a `hyperdb item wrapper`_
1341 **request**
1342 Includes information about the current request, including:
1343 - the current index information (``filterspec``, ``filter`` args,
1344 ``properties``, etc) parsed out of the form.
1345 - methods for easy filterspec link generation
1346 - *user*, the current user item as an HTMLItem instance
1347 - *form*
1348 The current CGI form information as a mapping of form argument name
1349 to value
1350 **config**
1351 This variable holds all the values defined in the tracker config.py
1352 file (eg. TRACKER_NAME, etc.)
1353 **db**
1354 The current database, used to access arbitrary database items.
1355 **templates**
1356 Access to all the tracker templates by name. Used mainly in
1357 *use-macro* commands.
1358 **utils**
1359 This variable makes available some utility functions like batching.
1360 **nothing**
1361 This is a special variable - if an expression evaluates to this, then
1362 the tag (in the case of a ``tal:replace``), its contents (in the case
1363 of ``tal:content``) or some attributes (in the case of
1364 ``tal:attributes``) will not appear in the the output. So, for
1365 example::
1367 <span tal:attributes="class nothing">Hello, World!</span>
1369 would result in::
1371 <span>Hello, World!</span>
1373 **default**
1374 Also a special variable - if an expression evaluates to this, then the
1375 existing HTML in the template will not be replaced or removed, it will
1376 remain. So::
1378 <span tal:replace="default">Hello, World!</span>
1380 would result in::
1382 <span>Hello, World!</span>
1385 The context variable
1386 ~~~~~~~~~~~~~~~~~~~~
1388 The *context* variable is one of three things based on the current
1389 context (see `determining web context`_ for how we figure this out):
1391 1. if we're looking at a "home" page, then it's None
1392 2. if we're looking at a specific hyperdb class, it's a
1393 `hyperdb class wrapper`_.
1394 3. if we're looking at a specific hyperdb item, it's a
1395 `hyperdb item wrapper`_.
1397 If the context is not None, we can access the properties of the class or
1398 item. The only real difference between cases 2 and 3 above are:
1400 1. the properties may have a real value behind them, and this will
1401 appear if the property is displayed through ``context/property`` or
1402 ``context/property/field``.
1403 2. the context's "id" property will be a false value in the second case,
1404 but a real, or true value in the third. Thus we can determine whether
1405 we're looking at a real item from the hyperdb by testing
1406 "context/id".
1408 Hyperdb class wrapper
1409 :::::::::::::::::::::
1411 Note: this is implemented by the ``roundup.cgi.templating.HTMLClass``
1412 class.
1414 This wrapper object provides access to a hyperb class. It is used
1415 primarily in both index view and new item views, but it's also usable
1416 anywhere else that you wish to access information about a class, or the
1417 items of a class, when you don't have a specific item of that class in
1418 mind.
1420 We allow access to properties. There will be no "id" property. The value
1421 accessed through the property will be the current value of the same name
1422 from the CGI form.
1424 There are several methods available on these wrapper objects:
1426 =========== =============================================================
1427 Method Description
1428 =========== =============================================================
1429 properties return a `hyperdb property wrapper`_ for all of this class's
1430 properties.
1431 list lists all of the active (not retired) items in the class.
1432 csv return the items of this class as a chunk of CSV text.
1433 propnames lists the names of the properties of this class.
1434 filter lists of items from this class, filtered and sorted by the
1435 current *request* filterspec/filter/sort/group args
1436 classhelp display a link to a javascript popup containing this class'
1437 "help" template.
1438 submit generate a submit button (and action hidden element)
1439 renderWith render this class with the given template.
1440 history returns 'New node - no history' :)
1441 is_edit_ok is the user allowed to Edit the current class?
1442 is_view_ok is the user allowed to View the current class?
1443 =========== =============================================================
1445 Note that if you have a property of the same name as one of the above
1446 methods, you'll need to access it using a python "item access"
1447 expression. For example::
1449 python:context['list']
1451 will access the "list" property, rather than the list method.
1454 Hyperdb item wrapper
1455 ::::::::::::::::::::
1457 Note: this is implemented by the ``roundup.cgi.templating.HTMLItem``
1458 class.
1460 This wrapper object provides access to a hyperb item.
1462 We allow access to properties. There will be no "id" property. The value
1463 accessed through the property will be the current value of the same name
1464 from the CGI form.
1466 There are several methods available on these wrapper objects:
1468 =============== ========================================================
1469 Method Description
1470 =============== ========================================================
1471 submit generate a submit button (and action hidden element)
1472 journal return the journal of the current item (**not
1473 implemented**)
1474 history render the journal of the current item as HTML
1475 renderQueryForm specific to the "query" class - render the search form
1476 for the query
1477 hasPermission specific to the "user" class - determine whether the
1478 user has a Permission
1479 is_edit_ok is the user allowed to Edit the current item?
1480 is_view_ok is the user allowed to View the current item?
1481 =============== ========================================================
1483 Note that if you have a property of the same name as one of the above
1484 methods, you'll need to access it using a python "item access"
1485 expression. For example::
1487 python:context['journal']
1489 will access the "journal" property, rather than the journal method.
1492 Hyperdb property wrapper
1493 ::::::::::::::::::::::::
1495 Note: this is implemented by subclasses of the
1496 ``roundup.cgi.templating.HTMLProperty`` class (``HTMLStringProperty``,
1497 ``HTMLNumberProperty``, and so on).
1499 This wrapper object provides access to a single property of a class. Its
1500 value may be either:
1502 1. if accessed through a `hyperdb item wrapper`_, then it's a value from
1503 the hyperdb
1504 2. if access through a `hyperdb class wrapper`_, then it's a value from
1505 the CGI form
1508 The property wrapper has some useful attributes:
1510 =============== ========================================================
1511 Attribute Description
1512 =============== ========================================================
1513 _name the name of the property
1514 _value the value of the property if any - this is the actual
1515 value retrieved from the hyperdb for this property
1516 =============== ========================================================
1518 There are several methods available on these wrapper objects:
1520 =========== ================================================================
1521 Method Description
1522 =========== ================================================================
1523 plain render a "plain" representation of the property. This method
1524 may take two arguments:
1526 escape
1527 If true, escape the text so it is HTML safe (default: no). The
1528 reason this defaults to off is that text is usually escaped
1529 at a later stage by the TAL commands, unless the "structure"
1530 option is used in the template. The following ``tal:content``
1531 expressions are all equivalent::
1533 "structure python:msg.content.plain(escape=1)"
1534 "python:msg.content.plain()"
1535 "msg/content/plain"
1536 "msg/content"
1538 Usually you'll only want to use the escape option in a
1539 complex expression.
1541 hyperlink
1542 If true, turn URLs, email addresses and hyperdb item
1543 designators in the text into hyperlinks (default: no). Note
1544 that you'll need to use the "structure" TAL option if you
1545 want to use this ``tal:content`` expression::
1547 "structure python:msg.content.plain(hyperlink=1)"
1549 Note also that the text is automatically HTML-escaped before
1550 the hyperlinking transformation.
1551 hyperlinked The same as msg.content.plain(hyperlink=1), but nicer::
1553 "structure msg/content/hyperlinked"
1555 field render an appropriate form edit field for the property - for
1556 most types this is a text entry box, but for Booleans it's a
1557 tri-state yes/no/neither selection.
1558 stext only on String properties - render the value of the property
1559 as StructuredText (requires the StructureText module to be
1560 installed separately)
1561 multiline only on String properties - render a multiline form edit
1562 field for the property
1563 email only on String properties - render the value of the property
1564 as an obscured email address
1565 confirm only on Password properties - render a second form edit field
1566 for the property, used for confirmation that the user typed
1567 the password correctly. Generates a field with name
1568 "name:confirm".
1569 now only on Date properties - return the current date as a new
1570 property
1571 reldate only on Date properties - render the interval between the date
1572 and now
1573 local only on Date properties - return this date as a new property
1574 with some timezone offset
1575 pretty only on Interval properties - render the interval in a pretty
1576 format (eg. "yesterday")
1577 menu only on Link and Multilink properties - render a form select
1578 list for this property
1579 reverse only on Multilink properties - produce a list of the linked
1580 items in reverse order
1581 =========== ================================================================
1584 The request variable
1585 ~~~~~~~~~~~~~~~~~~~~
1587 Note: this is implemented by the ``roundup.cgi.templating.HTMLRequest``
1588 class.
1590 The request variable is packed with information about the current
1591 request.
1593 .. taken from ``roundup.cgi.templating.HTMLRequest`` docstring
1595 =========== ============================================================
1596 Variable Holds
1597 =========== ============================================================
1598 form the CGI form as a cgi.FieldStorage
1599 env the CGI environment variables
1600 base the base URL for this tracker
1601 user a HTMLUser instance for this user
1602 classname the current classname (possibly None)
1603 template the current template (suffix, also possibly None)
1604 form the current CGI form variables in a FieldStorage
1605 =========== ============================================================
1607 **Index page specific variables (indexing arguments)**
1609 =========== ============================================================
1610 Variable Holds
1611 =========== ============================================================
1612 columns dictionary of the columns to display in an index page
1613 show a convenience access to columns - request/show/colname will
1614 be true if the columns should be displayed, false otherwise
1615 sort index sort column (direction, column name)
1616 group index grouping property (direction, column name)
1617 filter properties to filter the index on
1618 filterspec values to filter the index on
1619 search_text text to perform a full-text search on for an index
1620 =========== ============================================================
1622 There are several methods available on the request variable:
1624 =============== ========================================================
1625 Method Description
1626 =============== ========================================================
1627 description render a description of the request - handle for the
1628 page title
1629 indexargs_form render the current index args as form elements
1630 indexargs_url render the current index args as a URL
1631 base_javascript render some javascript that is used by other components
1632 of the templating
1633 batch run the current index args through a filter and return a
1634 list of items (see `hyperdb item wrapper`_, and
1635 `batching`_)
1636 =============== ========================================================
1638 The form variable
1639 :::::::::::::::::
1641 The form variable is a bit special because it's actually a python
1642 FieldStorage object. That means that you have two ways to access its
1643 contents. For example, to look up the CGI form value for the variable
1644 "name", use the path expression::
1646 request/form/name/value
1648 or the python expression::
1650 python:request.form['name'].value
1652 Note the "item" access used in the python case, and also note the
1653 explicit "value" attribute we have to access. That's because the form
1654 variables are stored as MiniFieldStorages. If there's more than one
1655 "name" value in the form, then the above will break since
1656 ``request/form/name`` is actually a *list* of MiniFieldStorages. So it's
1657 best to know beforehand what you're dealing with.
1660 The db variable
1661 ~~~~~~~~~~~~~~~
1663 Note: this is implemented by the ``roundup.cgi.templating.HTMLDatabase``
1664 class.
1666 Allows access to all hyperdb classes as attributes of this variable. If
1667 you want access to the "user" class, for example, you would use::
1669 db/user
1670 python:db.user
1672 Also, the current id of the current user is available as
1673 ``db.getuid()``. This isn't so useful in templates (where you have
1674 ``request/user``), but it can be useful in detectors or interfaces.
1676 The access results in a `hyperdb class wrapper`_.
1679 The templates variable
1680 ~~~~~~~~~~~~~~~~~~~~~~
1682 Note: this is implemented by the ``roundup.cgi.templating.Templates``
1683 class.
1685 This variable doesn't have any useful methods defined. It supports being
1686 used in expressions to access the templates, and consequently the
1687 template macros. You may access the templates using the following path
1688 expression::
1690 templates/name
1692 or the python expression::
1694 templates[name]
1696 where "name" is the name of the template you wish to access. The
1697 template has one useful attribute, namely "macros". To access a specific
1698 macro (called "macro_name"), use the path expression::
1700 templates/name/macros/macro_name
1702 or the python expression::
1704 templates[name].macros[macro_name]
1707 The utils variable
1708 ~~~~~~~~~~~~~~~~~~
1710 Note: this is implemented by the
1711 ``roundup.cgi.templating.TemplatingUtils`` class, but it may be extended
1712 as described below.
1714 =============== ========================================================
1715 Method Description
1716 =============== ========================================================
1717 Batch return a batch object using the supplied list
1718 =============== ========================================================
1720 You may add additional utility methods by writing them in your tracker
1721 ``interfaces.py`` module's ``TemplatingUtils`` class. See `adding a time
1722 log to your issues`_ for an example. The TemplatingUtils class itself
1723 will have a single attribute, ``client``, which may be used to access
1724 the ``client.db`` when you need to perform arbitrary database queries.
1726 Batching
1727 ::::::::
1729 Use Batch to turn a list of items, or item ids of a given class, into a
1730 series of batches. Its usage is::
1732 python:utils.Batch(sequence, size, start, end=0, orphan=0,
1733 overlap=0)
1735 or, to get the current index batch::
1737 request/batch
1739 The parameters are:
1741 ========= ==============================================================
1742 Parameter Usage
1743 ========= ==============================================================
1744 sequence a list of HTMLItems
1745 size how big to make the sequence.
1746 start where to start (0-indexed) in the sequence.
1747 end where to end (0-indexed) in the sequence.
1748 orphan if the next batch would contain less items than this value,
1749 then it is combined with this batch
1750 overlap the number of items shared between adjacent batches
1751 ========= ==============================================================
1753 All of the parameters are assigned as attributes on the batch object. In
1754 addition, it has several more attributes:
1756 =============== ========================================================
1757 Attribute Description
1758 =============== ========================================================
1759 start indicates the start index of the batch. *Note: unlike
1760 the argument, is a 1-based index (I know, lame)*
1761 first indicates the start index of the batch *as a 0-based
1762 index*
1763 length the actual number of elements in the batch
1764 sequence_length the length of the original, unbatched, sequence.
1765 =============== ========================================================
1767 And several methods:
1769 =============== ========================================================
1770 Method Description
1771 =============== ========================================================
1772 previous returns a new Batch with the previous batch settings
1773 next returns a new Batch with the next batch settings
1774 propchanged detect if the named property changed on the current item
1775 when compared to the last item
1776 =============== ========================================================
1778 An example of batching::
1780 <table class="otherinfo">
1781 <tr><th colspan="4" class="header">Existing Keywords</th></tr>
1782 <tr tal:define="keywords db/keyword/list"
1783 tal:repeat="start python:range(0, len(keywords), 4)">
1784 <td tal:define="batch python:utils.Batch(keywords, 4, start)"
1785 tal:repeat="keyword batch" tal:content="keyword/name">
1786 keyword here</td>
1787 </tr>
1788 </table>
1790 ... which will produce a table with four columns containing the items of
1791 the "keyword" class (well, their "name" anyway).
1793 Displaying Properties
1794 ---------------------
1796 Properties appear in the user interface in three contexts: in indices,
1797 in editors, and as search arguments. For each type of property, there
1798 are several display possibilities. For example, in an index view, a
1799 string property may just be printed as a plain string, but in an editor
1800 view, that property may be displayed in an editable field.
1803 Index Views
1804 -----------
1806 This is one of the class context views. It is also the default view for
1807 classes. The template used is "*classname*.index".
1810 Index View Specifiers
1811 ~~~~~~~~~~~~~~~~~~~~~
1813 An index view specifier (URL fragment) looks like this (whitespace has
1814 been added for clarity)::
1816 /issue?status=unread,in-progress,resolved&
1817 topic=security,ui&
1818 :group=+priority&
1819 :sort==activity&
1820 :filters=status,topic&
1821 :columns=title,status,fixer
1823 The index view is determined by two parts of the specifier: the layout
1824 part and the filter part. The layout part consists of the query
1825 parameters that begin with colons, and it determines the way that the
1826 properties of selected items are displayed. The filter part consists of
1827 all the other query parameters, and it determines the criteria by which
1828 items are selected for display. The filter part is interactively
1829 manipulated with the form widgets displayed in the filter section. The
1830 layout part is interactively manipulated by clicking on the column
1831 headings in the table.
1833 The filter part selects the union of the sets of items with values
1834 matching any specified Link properties and the intersection of the sets
1835 of items with values matching any specified Multilink properties.
1837 The example specifies an index of "issue" items. Only items with a
1838 "status" of either "unread" or "in-progress" or "resolved" are
1839 displayed, and only items with "topic" values including both "security"
1840 and "ui" are displayed. The items are grouped by priority, arranged in
1841 ascending order; and within groups, sorted by activity, arranged in
1842 descending order. The filter section shows filters for the "status" and
1843 "topic" properties, and the table includes columns for the "title",
1844 "status", and "fixer" properties.
1846 Searching Views
1847 ---------------
1849 Note: if you add a new column to the ``:columns`` form variable
1850 potentials then you will need to add the column to the appropriate
1851 `index views`_ template so that it is actually displayed.
1853 This is one of the class context views. The template used is typically
1854 "*classname*.search". The form on this page should have "search" as its
1855 ``@action`` variable. The "search" action:
1857 - sets up additional filtering, as well as performing indexed text
1858 searching
1859 - sets the ``:filter`` variable correctly
1860 - saves the query off if ``:query_name`` is set.
1862 The search page should lay out any fields that you wish to allow the
1863 user to search on. If your schema contains a large number of properties,
1864 you should be wary of making all of those properties available for
1865 searching, as this can cause confusion. If the additional properties are
1866 Strings, consider having their value indexed, and then they will be
1867 searchable using the full text indexed search. This is both faster, and
1868 more useful for the end user.
1870 The two special form values on search pages which are handled by the
1871 "search" action are:
1873 :search_text
1874 Text with which to perform a search of the text index. Results from
1875 that search will be used to limit the results of other filters (using
1876 an intersection operation)
1877 :query_name
1878 If supplied, the search parameters (including :search_text) will be
1879 saved off as a the query item and registered against the user's
1880 queries property. Note that the *classic* template schema has this
1881 ability, but the *minimal* template schema does not.
1884 Item Views
1885 ----------
1887 The basic view of a hyperdb item is provided by the "*classname*.item"
1888 template. It generally has three sections; an "editor", a "spool" and a
1889 "history" section.
1892 Editor Section
1893 ~~~~~~~~~~~~~~
1895 The editor section is used to manipulate the item - it may be a static
1896 display if the user doesn't have permission to edit the item.
1898 Here's an example of a basic editor template (this is the default
1899 "classic" template issue item edit form - from the "issue.item.html"
1900 template)::
1902 <table class="form">
1903 <tr>
1904 <th>Title</th>
1905 <td colspan="3" tal:content="structure python:context.title.field(size=60)">title</td>
1906 </tr>
1908 <tr>
1909 <th>Priority</th>
1910 <td tal:content="structure context/priority/menu">priority</td>
1911 <th>Status</th>
1912 <td tal:content="structure context/status/menu">status</td>
1913 </tr>
1915 <tr>
1916 <th>Superseder</th>
1917 <td>
1918 <span tal:replace="structure python:context.superseder.field(showid=1, size=20)" />
1919 <span tal:replace="structure python:db.issue.classhelp('id,title')" />
1920 <span tal:condition="context/superseder">
1921 <br>View: <span tal:replace="structure python:context.superseder.link(showid=1)" />
1922 </span>
1923 </td>
1924 <th>Nosy List</th>
1925 <td>
1926 <span tal:replace="structure context/nosy/field" />
1927 <span tal:replace="structure python:db.user.classhelp('username,realname,address,phone')" />
1928 </td>
1929 </tr>
1931 <tr>
1932 <th>Assigned To</th>
1933 <td tal:content="structure context/assignedto/menu">
1934 assignedto menu
1935 </td>
1936 <td> </td>
1937 <td> </td>
1938 </tr>
1940 <tr>
1941 <th>Change Note</th>
1942 <td colspan="3">
1943 <textarea name=":note" wrap="hard" rows="5" cols="60"></textarea>
1944 </td>
1945 </tr>
1947 <tr>
1948 <th>File</th>
1949 <td colspan="3"><input type="file" name=":file" size="40"></td>
1950 </tr>
1952 <tr>
1953 <td> </td>
1954 <td colspan="3" tal:content="structure context/submit">
1955 submit button will go here
1956 </td>
1957 </tr>
1958 </table>
1961 When a change is submitted, the system automatically generates a message
1962 describing the changed properties. As shown in the example, the editor
1963 template can use the ":note" and ":file" fields, which are added to the
1964 standard changenote message generated by Roundup.
1967 Form values
1968 :::::::::::
1970 We have a number of ways to pull properties out of the form in order to
1971 meet the various needs of:
1973 1. editing the current item (perhaps an issue item)
1974 2. editing information related to the current item (eg. messages or
1975 attached files)
1976 3. creating new information to be linked to the current item (eg. time
1977 spent on an issue)
1979 In the following, ``<bracketed>`` values are variable, ":" may be one of
1980 ":" or "@", and other text ("required") is fixed.
1982 Properties are specified as form variables:
1984 ``<propname>``
1985 property on the current context item
1987 ``<designator>:<propname>``
1988 property on the indicated item (for editing related information)
1990 ``<classname>-<N>:<propname>``
1991 property on the Nth new item of classname (generally for creating new
1992 items to attach to the current item)
1994 Once we have determined the "propname", we check to see if it is one of
1995 the special form values:
1997 ``@required``
1998 The named property values must be supplied or a ValueError will be
1999 raised.
2001 ``@remove@<propname>=id(s)``
2002 The ids will be removed from the multilink property.
2004 ``:add:<propname>=id(s)``
2005 The ids will be added to the multilink property.
2007 ``:link:<propname>=<designator>``
2008 Used to add a link to new items created during edit. These are
2009 collected and returned in ``all_links``. This will result in an
2010 additional linking operation (either Link set or Multilink append)
2011 after the edit/create is done using ``all_props`` in ``_editnodes``.
2012 The <propname> on the current item will be set/appended the id of the
2013 newly created item of class <designator> (where <designator> must be
2014 <classname>-<N>).
2016 Any of the form variables may be prefixed with a classname or
2017 designator.
2019 Two special form values are supported for backwards compatibility:
2021 ``:note``
2022 create a message (with content, author and date), linked to the
2023 context item. This is ALWAYS designated "msg-1".
2024 ``:file``
2025 create a file, attached to the current item and any message created by
2026 :note. This is ALWAYS designated "file-1".
2029 Spool Section
2030 ~~~~~~~~~~~~~
2032 The spool section lists related information like the messages and files
2033 of an issue.
2035 TODO
2038 History Section
2039 ~~~~~~~~~~~~~~~
2041 The final section displayed is the history of the item - its database
2042 journal. This is generally generated with the template::
2044 <tal:block tal:replace="structure context/history" />
2046 *To be done:*
2048 *The actual history entries of the item may be accessed for manual
2049 templating through the "journal" method of the item*::
2051 <tal:block tal:repeat="entry context/journal">
2052 a journal entry
2053 </tal:block>
2055 *where each journal entry is an HTMLJournalEntry.*
2057 Defining new web actions
2058 ------------------------
2060 You may define new actions to be triggered by the ``@action`` form
2061 variable. These are added to the tracker ``interfaces.py`` as methods on
2062 the ``Client`` class.
2064 Adding action methods takes three steps; first you `define the new
2065 action method`_, then you `register the action method`_ with the cgi
2066 interface so it may be triggered by the ``@action`` form variable.
2067 Finally you `use the new action`_ in your HTML form.
2069 See "`setting up a "wizard" (or "druid") for controlled adding of
2070 issues`_" for an example.
2073 Define the new action method
2074 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2076 The action methods have the following interface::
2078 def myActionMethod(self):
2079 ''' Perform some action. No return value is required.
2080 '''
2082 The *self* argument is an instance of your tracker ``instance.Client``
2083 class - thus it's mostly implemented by ``roundup.cgi.Client``. See the
2084 docstring of that class for details of what it can do.
2086 The method will typically check the ``self.form`` variable's contents.
2087 It may then:
2089 - add information to ``self.ok_message`` or ``self.error_message``
2090 - change the ``self.template`` variable to alter what the user will see
2091 next
2092 - raise Unauthorised, SendStaticFile, SendFile, NotFound or Redirect
2093 exceptions
2096 Register the action method
2097 ~~~~~~~~~~~~~~~~~~~~~~~~~~
2099 The method is now written, but isn't available to the user until you add
2100 it to the `instance.Client`` class ``actions`` variable, like so::
2102 actions = client.Class.actions + (
2103 ('myaction', 'myActionMethod'),
2104 )
2106 This maps the action name "myaction" to the action method we defined.
2109 Use the new action
2110 ~~~~~~~~~~~~~~~~~~
2112 In your HTML form, add a hidden form element like so::
2114 <input type="hidden" name="@action" value="myaction">
2116 where "myaction" is the name you registered in the previous step.
2119 Examples
2120 ========
2122 .. contents::
2123 :local:
2124 :depth: 1
2127 Adding a new field to the classic schema
2128 ----------------------------------------
2130 This example shows how to add a new constrained property (i.e. a
2131 selection of distinct values) to your tracker.
2134 Introduction
2135 ~~~~~~~~~~~~
2137 To make the classic schema of roundup useful as a TODO tracking system
2138 for a group of systems administrators, it needed an extra data field per
2139 issue: a category.
2141 This would let sysadmins quickly list all TODOs in their particular area
2142 of interest without having to do complex queries, and without relying on
2143 the spelling capabilities of other sysadmins (a losing proposition at
2144 best).
2147 Adding a field to the database
2148 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2150 This is the easiest part of the change. The category would just be a
2151 plain string, nothing fancy. To change what is in the database you need
2152 to add some lines to the ``open()`` function in ``dbinit.py``. Under the
2153 comment::
2155 # add any additional database schema configuration here
2157 add::
2159 category = Class(db, "category", name=String())
2160 category.setkey("name")
2162 Here we are setting up a chunk of the database which we are calling
2163 "category". It contains a string, which we are refering to as "name" for
2164 lack of a more imaginative title. (Since "name" is one of the properties
2165 that Roundup looks for on items if you do not set a key for them, it's
2166 probably a good idea to stick with it for new classes if at all
2167 appropriate.) Then we are setting the key of this chunk of the database
2168 to be that "name". This is equivalent to an index for database types.
2169 This also means that there can only be one category with a given name.
2171 Adding the above lines allows us to create categories, but they're not
2172 tied to the issues that we are going to be creating. It's just a list of
2173 categories off on its own, which isn't much use. We need to link it in
2174 with the issues. To do that, find the lines in the ``open()`` function
2175 in ``dbinit.py`` which set up the "issue" class, and then add a link to
2176 the category::
2178 issue = IssueClass(db, "issue", ... ,
2179 category=Multilink("category"), ... )
2181 The ``Multilink()`` means that each issue can have many categories. If
2182 you were adding something with a one-to-one relationship to issues (such
2183 as the "assignedto" property), use ``Link()`` instead.
2185 That is all you need to do to change the schema. The rest of the effort
2186 is fiddling around so you can actually use the new category.
2189 Populating the new category class
2190 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2192 If you haven't initialised the database with the roundup-admin
2193 "initialise" command, then you can add the following to the tracker
2194 ``dbinit.py`` in the ``init()`` function under the comment::
2196 # add any additional database create steps here - but only if you
2197 # haven't initialised the database with the admin "initialise" command
2199 Add::
2201 category = db.getclass('category')
2202 category.create(name="scipy", order="1")
2203 category.create(name="chaco", order="2")
2204 category.create(name="weave", order="3")
2206 If the database has already been initalised, then you need to use the
2207 ``roundup-admin`` tool::
2209 % roundup-admin -i <tracker home>
2210 Roundup <version> ready for input.
2211 Type "help" for help.
2212 roundup> create category name=scipy order=1
2213 1
2214 roundup> create category name=chaco order=1
2215 2
2216 roundup> create category name=weave order=1
2217 3
2218 roundup> exit...
2219 There are unsaved changes. Commit them (y/N)? y
2221 TODO: explain why order=1 in each case. Also, does key get set to "name"
2222 automatically when added via roundup-admin?
2225 Setting up security on the new objects
2226 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2228 By default only the admin user can look at and change objects. This
2229 doesn't suit us, as we want any user to be able to create new categories
2230 as required, and obviously everyone needs to be able to view the
2231 categories of issues for it to be useful.
2233 We therefore need to change the security of the category objects. This
2234 is also done in the ``open()`` function of ``dbinit.py``.
2236 There are currently two loops which set up permissions and then assign
2237 them to various roles. Simply add the new "category" to both lists::
2239 # new permissions for this schema
2240 for cl in 'issue', 'file', 'msg', 'user', 'category':
2241 db.security.addPermission(name="Edit", klass=cl,
2242 description="User is allowed to edit "+cl)
2243 db.security.addPermission(name="View", klass=cl,
2244 description="User is allowed to access "+cl)
2246 # Assign the access and edit permissions for issue, file and message
2247 # to regular users now
2248 for cl in 'issue', 'file', 'msg', 'category':
2249 p = db.security.getPermission('View', cl)
2250 db.security.addPermissionToRole('User', p)
2251 p = db.security.getPermission('Edit', cl)
2252 db.security.addPermissionToRole('User', p)
2254 So you are in effect doing the following (with 'cl' substituted by its
2255 value)::
2257 db.security.addPermission(name="Edit", klass='category',
2258 description="User is allowed to edit "+'category')
2259 db.security.addPermission(name="View", klass='category',
2260 description="User is allowed to access "+'category')
2262 which is creating two permission types; that of editing and viewing
2263 "category" objects respectively. Then the following lines assign those
2264 new permissions to the "User" role, so that normal users can view and
2265 edit "category" objects::
2267 p = db.security.getPermission('View', 'category')
2268 db.security.addPermissionToRole('User', p)
2270 p = db.security.getPermission('Edit', 'category')
2271 db.security.addPermissionToRole('User', p)
2273 This is all the work that needs to be done for the database. It will
2274 store categories, and let users view and edit them. Now on to the
2275 interface stuff.
2278 Changing the web left hand frame
2279 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2281 We need to give the users the ability to create new categories, and the
2282 place to put the link to this functionality is in the left hand function
2283 bar, under the "Issues" area. The file that defines how this area looks
2284 is ``html/page``, which is what we are going to be editing next.
2286 If you look at this file you can see that it contains a lot of
2287 "classblock" sections which are chunks of HTML that will be included or
2288 excluded in the output depending on whether the condition in the
2289 classblock is met. Under the end of the classblock for issue is where we
2290 are going to add the category code::
2292 <p class="classblock"
2293 tal:condition="python:request.user.hasPermission('View', 'category')">
2294 <b>Categories</b><br>
2295 <a tal:condition="python:request.user.hasPermission('Edit', 'category')"
2296 href="category?@template=item">New Category<br></a>
2297 </p>
2299 The first two lines is the classblock definition, which sets up a
2300 condition that only users who have "View" permission for the "category"
2301 object will have this section included in their output. Next comes a
2302 plain "Categories" header in bold. Everyone who can view categories will
2303 get that.
2305 Next comes the link to the editing area of categories. This link will
2306 only appear if the condition - that the user has "Edit" permissions for
2307 the "category" objects - is matched. If they do have permission then
2308 they will get a link to another page which will let the user add new
2309 categories.
2311 Note that if you have permission to *view* but not to *edit* categories,
2312 then all you will see is a "Categories" header with nothing underneath
2313 it. This is obviously not very good interface design, but will do for
2314 now. I just claim that it is so I can add more links in this section
2315 later on. However to fix the problem you could change the condition in
2316 the classblock statement, so that only users with "Edit" permission
2317 would see the "Categories" stuff.
2320 Setting up a page to edit categories
2321 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2323 We defined code in the previous section which let users with the
2324 appropriate permissions see a link to a page which would let them edit
2325 conditions. Now we have to write that page.
2327 The link was for the *item* template of the *category* object. This
2328 translates into Roundup looking for a file called ``category.item.html``
2329 in the ``html`` tracker directory. This is the file that we are going to
2330 write now.
2332 First we add an info tag in a comment which doesn't affect the outcome
2333 of the code at all, but is useful for debugging. If you load a page in a
2334 browser and look at the page source, you can see which sections come
2335 from which files by looking for these comments::
2337 <!-- category.item -->
2339 Next we need to add in the METAL macro stuff so we get the normal page
2340 trappings::
2342 <tal:block metal:use-macro="templates/page/macros/icing">
2343 <title metal:fill-slot="head_title">Category editing</title>
2344 <td class="page-header-top" metal:fill-slot="body_title">
2345 <h2>Category editing</h2>
2346 </td>
2347 <td class="content" metal:fill-slot="content">
2349 Next we need to setup up a standard HTML form, which is the whole
2350 purpose of this file. We link to some handy javascript which sends the
2351 form through only once. This is to stop users hitting the send button
2352 multiple times when they are impatient and thus having the form sent
2353 multiple times::
2355 <form method="POST" onSubmit="return submit_once()"
2356 enctype="multipart/form-data">
2358 Next we define some code which sets up the minimum list of fields that
2359 we require the user to enter. There will be only one field - "name" - so
2360 they better put something in it, otherwise the whole form is pointless::
2362 <input type="hidden" name="@required" value="name">
2364 To get everything to line up properly we will put everything in a table,
2365 and put a nice big header on it so the user has an idea what is
2366 happening::
2368 <table class="form">
2369 <tr><th class="header" colspan="2">Category</th></tr>
2371 Next, we need the field into which the user is going to enter the new
2372 category. The "context.name.field(size=60)" bit tells Roundup to
2373 generate a normal HTML field of size 60, and the contents of that field
2374 will be the "name" variable of the current context (which is
2375 "category"). The upshot of this is that when the user types something in
2376 to the form, a new category will be created with that name::
2378 <tr>
2379 <th>Name</th>
2380 <td tal:content="structure python:context.name.field(size=60)">
2381 name</td>
2382 </tr>
2384 Then a submit button so that the user can submit the new category::
2386 <tr>
2387 <td> </td>
2388 <td colspan="3" tal:content="structure context/submit">
2389 submit button will go here
2390 </td>
2391 </tr>
2393 Finally we finish off the tags we used at the start to do the METAL
2394 stuff::
2396 </td>
2397 </tal:block>
2399 So putting it all together, and closing the table and form we get::
2401 <!-- category.item -->
2402 <tal:block metal:use-macro="templates/page/macros/icing">
2403 <title metal:fill-slot="head_title">Category editing</title>
2404 <td class="page-header-top" metal:fill-slot="body_title">
2405 <h2>Category editing</h2>
2406 </td>
2407 <td class="content" metal:fill-slot="content">
2408 <form method="POST" onSubmit="return submit_once()"
2409 enctype="multipart/form-data">
2411 <table class="form">
2412 <tr><th class="header" colspan="2">Category</th></tr>
2414 <tr>
2415 <th>Name</th>
2416 <td tal:content="structure python:context.name.field(size=60)">
2417 name</td>
2418 </tr>
2420 <tr>
2421 <td>
2422
2423 <input type="hidden" name="@required" value="name">
2424 </td>
2425 <td colspan="3" tal:content="structure context/submit">
2426 submit button will go here
2427 </td>
2428 </tr>
2429 </table>
2430 </form>
2431 </td>
2432 </tal:block>
2434 This is quite a lot to just ask the user one simple question, but there
2435 is a lot of setup for basically one line (the form line) to do its work.
2436 To add another field to "category" would involve one more line (well,
2437 maybe a few extra to get the formatting correct).
2440 Adding the category to the issue
2441 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2443 We now have the ability to create issues to our heart's content, but
2444 that is pointless unless we can assign categories to issues. Just like
2445 the ``html/category.item.html`` file was used to define how to add a new
2446 category, the ``html/issue.item.html`` is used to define how a new issue
2447 is created.
2449 Just like ``category.issue.html`` this file defines a form which has a
2450 table to lay things out. It doesn't matter where in the table we add new
2451 stuff, it is entirely up to your sense of aesthetics::
2453 <th>Category</th>
2454 <td><span tal:replace="structure context/category/field" />
2455 <span tal:replace="structure db/category/classhelp" />
2456 </td>
2458 First, we define a nice header so that the user knows what the next
2459 section is, then the middle line does what we are most interested in.
2460 This ``context/category/field`` gets replaced by a field which contains
2461 the category in the current context (the current context being the new
2462 issue).
2464 The classhelp lines generate a link (labelled "list") to a popup window
2465 which contains the list of currently known categories.
2468 Searching on categories
2469 ~~~~~~~~~~~~~~~~~~~~~~~
2471 We can add categories, and create issues with categories. The next
2472 obvious thing that we would like to be able to do, would be to search
2473 for issues based on their category, so that, for example, anyone working
2474 on the web server could look at all issues in the category "Web".
2476 If you look for "Search Issues" in the 'html/page.html' file, you will
2477 find that it looks something like
2478 ``<a href="issue?@template=search">Search Issues</a>``. This shows us
2479 that when you click on "Search Issues" it will be looking for a
2480 ``issue.search.html`` file to display. So that is the file that we will
2481 change.
2483 If you look at this file it should be starting to seem familiar, although it
2484 does use some new macros. You can add the new category search code anywhere you
2485 like within that form::
2487 <tr tal:define="name string:category;
2488 db_klass string:category;
2489 db_content string:name;">
2490 <th>Priority:</th>
2491 <td metal:use-macro="search_select"></td>
2492 <td metal:use-macro="column_input"></td>
2493 <td metal:use-macro="sort_input"></td>
2494 <td metal:use-macro="group_input"></td>
2495 </tr>
2497 The definitions in the <tr> opening tag are used by the macros:
2499 - search_select expands to a drop-down box with all categories using db_klass
2500 and db_content.
2501 - column_input expands to a checkbox for selecting what columns should be
2502 displayed.
2503 - sort_input expands to a radio button for selecting what property should be
2504 sorted on.
2505 - group_input expands to a radio button for selecting what property should be
2506 group on.
2508 The category search code above would expand to the following::
2510 <tr>
2511 <th>Category:</th>
2512 <td>
2513 <select name="category">
2514 <option value="">don't care</option>
2515 <option value="">------------</option>
2516 <option value="1">scipy</option>
2517 <option value="2">chaco</option>
2518 <option value="3">weave</option>
2519 </select>
2520 </td>
2521 <td><input type="checkbox" name=":columns" value="category"></td>
2522 <td><input type="radio" name=":sort" value="category"></td>
2523 <td><input type="radio" name=":group" value="category"></td>
2524 </tr>
2526 Adding category to the default view
2527 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2529 We can now add categories, add issues with categories, and search for
2530 issues based on categories. This is everything that we need to do;
2531 however, there is some more icing that we would like. I think the
2532 category of an issue is important enough that it should be displayed by
2533 default when listing all the issues.
2535 Unfortunately, this is a bit less obvious than the previous steps. The
2536 code defining how the issues look is in ``html/issue.index.html``. This
2537 is a large table with a form down at the bottom for redisplaying and so
2538 forth.
2540 Firstly we need to add an appropriate header to the start of the table::
2542 <th tal:condition="request/show/category">Category</th>
2544 The *condition* part of this statement is to avoid displaying the
2545 Category column if the user has selected not to see it.
2547 The rest of the table is a loop which will go through every issue that
2548 matches the display criteria. The loop variable is "i" - which means
2549 that every issue gets assigned to "i" in turn.
2551 The new part of code to display the category will look like this::
2553 <td tal:condition="request/show/category"
2554 tal:content="i/category"></td>
2556 The condition is the same as above: only display the condition when the
2557 user hasn't asked for it to be hidden. The next part is to set the
2558 content of the cell to be the category part of "i" - the current issue.
2560 Finally we have to edit ``html/page.html`` again. This time, we need to
2561 tell it that when the user clicks on "Unasigned Issues" or "All Issues",
2562 the category column should be included in the resulting list. If you
2563 scroll down the page file, you can see the links with lots of options.
2564 The option that we are interested in is the ``:columns=`` one which
2565 tells roundup which fields of the issue to display. Simply add
2566 "category" to that list and it all should work.
2569 Adding in state transition control
2570 ----------------------------------
2572 Sometimes tracker admins want to control the states that users may move
2573 issues to. You can do this by following these steps:
2575 1. make "status" a required variable. This is achieved by adding the
2576 following to the top of the form in the ``issue.item.html``
2577 template::
2579 <input type="hidden" name="@required" value="status">
2581 this will force users to select a status.
2583 2. add a Multilink property to the status class::
2585 stat = Class(db, "status", ... , transitions=Multilink('status'),
2586 ...)
2588 and then edit the statuses already created, either:
2590 a. through the web using the class list -> status class editor, or
2591 b. using the roundup-admin "set" command.
2593 3. add an auditor module ``checktransition.py`` in your tracker's
2594 ``detectors`` directory, for example::
2596 def checktransition(db, cl, nodeid, newvalues):
2597 ''' Check that the desired transition is valid for the "status"
2598 property.
2599 '''
2600 if not newvalues.has_key('status'):
2601 return
2602 current = cl.get(nodeid, 'status')
2603 new = newvalues['status']
2604 if new == current:
2605 return
2606 ok = db.status.get(current, 'transitions')
2607 if new not in ok:
2608 raise ValueError, 'Status not allowed to move from "%s" to "%s"'%(
2609 db.status.get(current, 'name'), db.status.get(new, 'name'))
2611 def init(db):
2612 db.issue.audit('set', checktransition)
2614 4. in the ``issue.item.html`` template, change the status editing bit
2615 from::
2617 <th>Status</th>
2618 <td tal:content="structure context/status/menu">status</td>
2620 to::
2622 <th>Status</th>
2623 <td>
2624 <select tal:condition="context/id" name="status">
2625 <tal:block tal:define="ok context/status/transitions"
2626 tal:repeat="state db/status/list">
2627 <option tal:condition="python:state.id in ok"
2628 tal:attributes="
2629 value state/id;
2630 selected python:state.id == context.status.id"
2631 tal:content="state/name"></option>
2632 </tal:block>
2633 </select>
2634 <tal:block tal:condition="not:context/id"
2635 tal:replace="structure context/status/menu" />
2636 </td>
2638 which displays only the allowed status to transition to.
2641 Displaying only message summaries in the issue display
2642 ------------------------------------------------------
2644 Alter the issue.item template section for messages to::
2646 <table class="messages" tal:condition="context/messages">
2647 <tr><th colspan="5" class="header">Messages</th></tr>
2648 <tr tal:repeat="msg context/messages">
2649 <td><a tal:attributes="href string:msg${msg/id}"
2650 tal:content="string:msg${msg/id}"></a></td>
2651 <td tal:content="msg/author">author</td>
2652 <td class="date" tal:content="msg/date/pretty">date</td>
2653 <td tal:content="msg/summary">summary</td>
2654 <td>
2655 <a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">
2656 remove</a>
2657 </td>
2658 </tr>
2659 </table>
2661 Restricting the list of users that are assignable to a task
2662 -----------------------------------------------------------
2664 1. In your tracker's "dbinit.py", create a new Role, say "Developer"::
2666 db.security.addRole(name='Developer', description='A developer')
2668 2. Just after that, create a new Permission, say "Fixer", specific to
2669 "issue"::
2671 p = db.security.addPermission(name='Fixer', klass='issue',
2672 description='User is allowed to be assigned to fix issues')
2674 3. Then assign the new Permission to your "Developer" Role::
2676 db.security.addPermissionToRole('Developer', p)
2678 4. In the issue item edit page ("html/issue.item.html" in your tracker
2679 directory), use the new Permission in restricting the "assignedto"
2680 list::
2682 <select name="assignedto">
2683 <option value="-1">- no selection -</option>
2684 <tal:block tal:repeat="user db/user/list">
2685 <option tal:condition="python:user.hasPermission(
2686 'Fixer', context._classname)"
2687 tal:attributes="
2688 value user/id;
2689 selected python:user.id == context.assignedto"
2690 tal:content="user/realname"></option>
2691 </tal:block>
2692 </select>
2694 For extra security, you may wish to setup an auditor to enforce the
2695 Permission requirement (install this as "assignedtoFixer.py" in your
2696 tracker "detectors" directory)::
2698 def assignedtoMustBeFixer(db, cl, nodeid, newvalues):
2699 ''' Ensure the assignedto value in newvalues is a used with the
2700 Fixer Permission
2701 '''
2702 if not newvalues.has_key('assignedto'):
2703 # don't care
2704 return
2706 # get the userid
2707 userid = newvalues['assignedto']
2708 if not db.security.hasPermission('Fixer', userid, cl.classname):
2709 raise ValueError, 'You do not have permission to edit %s'%cl.classname
2711 def init(db):
2712 db.issue.audit('set', assignedtoMustBeFixer)
2713 db.issue.audit('create', assignedtoMustBeFixer)
2715 So now, if an edit action attempts to set "assignedto" to a user that
2716 doesn't have the "Fixer" Permission, the error will be raised.
2719 Setting up a "wizard" (or "druid") for controlled adding of issues
2720 ------------------------------------------------------------------
2722 1. Set up the page templates you wish to use for data input. My wizard
2723 is going to be a two-step process: first figuring out what category
2724 of issue the user is submitting, and then getting details specific to
2725 that category. The first page includes a table of help, explaining
2726 what the category names mean, and then the core of the form::
2728 <form method="POST" onSubmit="return submit_once()"
2729 enctype="multipart/form-data">
2730 <input type="hidden" name="@template" value="add_page1">
2731 <input type="hidden" name="@action" value="page1submit">
2733 <strong>Category:</strong>
2734 <tal:block tal:replace="structure context/category/menu" />
2735 <input type="submit" value="Continue">
2736 </form>
2738 The next page has the usual issue entry information, with the
2739 addition of the following form fragments::
2741 <form method="POST" onSubmit="return submit_once()"
2742 enctype="multipart/form-data"
2743 tal:condition="context/is_edit_ok"
2744 tal:define="cat request/form/category/value">
2746 <input type="hidden" name="@template" value="add_page2">
2747 <input type="hidden" name="@required" value="title">
2748 <input type="hidden" name="category" tal:attributes="value cat">
2749 .
2750 .
2751 .
2752 </form>
2754 Note that later in the form, I test the value of "cat" include form
2755 elements that are appropriate. For example::
2757 <tal:block tal:condition="python:cat in '6 10 13 14 15 16 17'.split()">
2758 <tr>
2759 <th>Operating System</th>
2760 <td tal:content="structure context/os/field"></td>
2761 </tr>
2762 <tr>
2763 <th>Web Browser</th>
2764 <td tal:content="structure context/browser/field"></td>
2765 </tr>
2766 </tal:block>
2768 ... the above section will only be displayed if the category is one
2769 of 6, 10, 13, 14, 15, 16 or 17.
2771 3. Determine what actions need to be taken between the pages - these are
2772 usually to validate user choices and determine what page is next. Now
2773 encode those actions in methods on the ``interfaces.Client`` class
2774 and insert hooks to those actions in the "actions" attribute on that
2775 class, like so::
2777 actions = client.Client.actions + (
2778 ('page1_submit', 'page1SubmitAction'),
2779 )
2781 def page1SubmitAction(self):
2782 ''' Verify that the user has selected a category, and then move
2783 on to page 2.
2784 '''
2785 category = self.form['category'].value
2786 if category == '-1':
2787 self.error_message.append('You must select a category of report')
2788 return
2789 # everything's ok, move on to the next page
2790 self.template = 'add_page2'
2792 4. Use the usual "new" action as the ``@action`` on the final page, and
2793 you're done (the standard context/submit method can do this for you).
2796 Using an external password validation source
2797 --------------------------------------------
2799 We have a centrally-managed password changing system for our users. This
2800 results in a UN*X passwd-style file that we use for verification of
2801 users. Entries in the file consist of ``name:password`` where the
2802 password is encrypted using the standard UN*X ``crypt()`` function (see
2803 the ``crypt`` module in your Python distribution). An example entry
2804 would be::
2806 admin:aamrgyQfDFSHw
2808 Each user of Roundup must still have their information stored in the
2809 Roundup database - we just use the passwd file to check their password.
2810 To do this, we add the following code to our ``Client`` class in the
2811 tracker home ``interfaces.py`` module::
2813 def verifyPassword(self, userid, password):
2814 # get the user's username
2815 username = self.db.user.get(userid, 'username')
2817 # the passwords are stored in the "passwd.txt" file in the
2818 # tracker home
2819 file = os.path.join(self.db.config.TRACKER_HOME, 'passwd.txt')
2821 # see if we can find a match
2822 for ent in [line.strip().split(':') for line in
2823 open(file).readlines()]:
2824 if ent[0] == username:
2825 return crypt.crypt(password, ent[1][:2]) == ent[1]
2827 # user doesn't exist in the file
2828 return 0
2830 What this does is look through the file, line by line, looking for a
2831 name that matches.
2833 We also remove the redundant password fields from the ``user.item``
2834 template.
2837 Adding a "vacation" flag to users for stopping nosy messages
2838 ------------------------------------------------------------
2840 When users go on vacation and set up vacation email bouncing, you'll
2841 start to see a lot of messages come back through Roundup "Fred is on
2842 vacation". Not very useful, and relatively easy to stop.
2844 1. add a "vacation" flag to your users::
2846 user = Class(db, "user",
2847 username=String(), password=Password(),
2848 address=String(), realname=String(),
2849 phone=String(), organisation=String(),
2850 alternate_addresses=String(),
2851 roles=String(), queries=Multilink("query"),
2852 vacation=Boolean())
2854 2. So that users may edit the vacation flags, add something like the
2855 following to your ``user.item`` template::
2857 <tr>
2858 <th>On Vacation</th>
2859 <td tal:content="structure context/vacation/field">vacation</td>
2860 </tr>
2862 3. edit your detector ``nosyreactor.py`` so that the ``nosyreaction()``
2863 consists of::
2865 def nosyreaction(db, cl, nodeid, oldvalues):
2866 # send a copy of all new messages to the nosy list
2867 for msgid in determineNewMessages(cl, nodeid, oldvalues):
2868 try:
2869 users = db.user
2870 messages = db.msg
2872 # figure the recipient ids
2873 sendto = []
2874 r = {}
2875 recipients = messages.get(msgid, 'recipients')
2876 for recipid in messages.get(msgid, 'recipients'):
2877 r[recipid] = 1
2879 # figure the author's id, and indicate they've received
2880 # the message
2881 authid = messages.get(msgid, 'author')
2883 # possibly send the message to the author, as long as
2884 # they aren't anonymous
2885 if (db.config.MESSAGES_TO_AUTHOR == 'yes' and
2886 users.get(authid, 'username') != 'anonymous'):
2887 sendto.append(authid)
2888 r[authid] = 1
2890 # now figure the nosy people who weren't recipients
2891 nosy = cl.get(nodeid, 'nosy')
2892 for nosyid in nosy:
2893 # Don't send nosy mail to the anonymous user (that
2894 # user shouldn't appear in the nosy list, but just
2895 # in case they do...)
2896 if users.get(nosyid, 'username') == 'anonymous':
2897 continue
2898 # make sure they haven't seen the message already
2899 if not r.has_key(nosyid):
2900 # send it to them
2901 sendto.append(nosyid)
2902 recipients.append(nosyid)
2904 # generate a change note
2905 if oldvalues:
2906 note = cl.generateChangeNote(nodeid, oldvalues)
2907 else:
2908 note = cl.generateCreateNote(nodeid)
2910 # we have new recipients
2911 if sendto:
2912 # filter out the people on vacation
2913 sendto = [i for i in sendto
2914 if not users.get(i, 'vacation', 0)]
2916 # map userids to addresses
2917 sendto = [users.get(i, 'address') for i in sendto]
2919 # update the message's recipients list
2920 messages.set(msgid, recipients=recipients)
2922 # send the message
2923 cl.send_message(nodeid, msgid, note, sendto)
2924 except roundupdb.MessageSendError, message:
2925 raise roundupdb.DetectorError, message
2927 Note that this is the standard nosy reaction code, with the small
2928 addition of::
2930 # filter out the people on vacation
2931 sendto = [i for i in sendto if not users.get(i, 'vacation', 0)]
2933 which filters out the users that have the vacation flag set to true.
2936 Adding a time log to your issues
2937 --------------------------------
2939 We want to log the dates and amount of time spent working on issues, and
2940 be able to give a summary of the total time spent on a particular issue.
2942 1. Add a new class to your tracker ``dbinit.py``::
2944 # storage for time logging
2945 timelog = Class(db, "timelog", period=Interval())
2947 Note that we automatically get the date of the time log entry
2948 creation through the standard property "creation".
2950 2. Link to the new class from your issue class (again, in
2951 ``dbinit.py``)::
2953 issue = IssueClass(db, "issue",
2954 assignedto=Link("user"), topic=Multilink("keyword"),
2955 priority=Link("priority"), status=Link("status"),
2956 times=Multilink("timelog"))
2958 the "times" property is the new link to the "timelog" class.
2960 3. We'll need to let people add in times to the issue, so in the web
2961 interface we'll have a new entry field. This is a special field
2962 because unlike the other fields in the issue.item template, it
2963 affects a different item (a timelog item) and not the template's
2964 item, an issue. We have a special syntax for form fields that affect
2965 items other than the template default item (see the cgi
2966 documentation on `special form variables`_). In particular, we add a
2967 field to capture a new timelog item's perdiod::
2969 <tr>
2970 <th>Time Log</th>
2971 <td colspan=3><input type="text" name="timelog-1@period" />
2972 <br />(enter as '3y 1m 4d 2:40:02' or parts thereof)
2973 </td>
2974 </tr>
2976 and another hidden field that links that new timelog item (new
2977 because it's marked as having id "-1") to the issue item. It looks
2978 like this::
2980 <input type="hidden" name="@link@times" value="timelog-1" />
2982 On submission, the "-1" timelog item will be created and assigned a
2983 real item id. The "times" property of the issue will have the new id
2984 added to it.
2986 4. We want to display a total of the time log times that have been
2987 accumulated for an issue. To do this, we'll need to actually write
2988 some Python code, since it's beyond the scope of PageTemplates to
2989 perform such calculations. We do this by adding a method to the
2990 TemplatingUtils class in our tracker ``interfaces.py`` module::
2992 class TemplatingUtils:
2993 ''' Methods implemented on this class will be available to HTML
2994 templates through the 'utils' variable.
2995 '''
2996 def totalTimeSpent(self, times):
2997 ''' Call me with a list of timelog items (which have an
2998 Interval "period" property)
2999 '''
3000 total = Interval('')
3001 for time in times:
3002 total += time.period._value
3003 return total
3005 Replace the ``pass`` line as we did in step 4 above with the Client
3006 class. As indicated in the docstrings, we will be able to access the
3007 ``totalTimeSpent`` method via the ``utils`` variable in our
3008 templates.
3010 5. Display the time log for an issue::
3012 <table class="otherinfo" tal:condition="context/times">
3013 <tr><th colspan="3" class="header">Time Log
3014 <tal:block
3015 tal:replace="python:utils.totalTimeSpent(context.times)" />
3016 </th></tr>
3017 <tr><th>Date</th><th>Period</th><th>Logged By</th></tr>
3018 <tr tal:repeat="time context/times">
3019 <td tal:content="time/creation"></td>
3020 <td tal:content="time/period"></td>
3021 <td tal:content="time/creator"></td>
3022 </tr>
3023 </table>
3025 I put this just above the Messages log in my issue display. Note our
3026 use of the ``totalTimeSpent`` method which will total up the times
3027 for the issue and return a new Interval. That will be automatically
3028 displayed in the template as text like "+ 1y 2:40" (1 year, 2 hours
3029 and 40 minutes).
3031 8. If you're using a persistent web server - roundup-server or
3032 mod_python for example - then you'll need to restart that to pick up
3033 the code changes. When that's done, you'll be able to use the new
3034 time logging interface.
3036 Using a UN*X passwd file as the user database
3037 ---------------------------------------------
3039 On some systems the primary store of users is the UN*X passwd file. It
3040 holds information on users such as their username, real name, password
3041 and primary user group.
3043 Roundup can use this store as its primary source of user information,
3044 but it needs additional information too - email address(es), roundup
3045 Roles, vacation flags, roundup hyperdb item ids, etc. Also, "retired"
3046 users must still exist in the user database, unlike some passwd files in
3047 which the users are removed when they no longer have access to a system.
3049 To make use of the passwd file, we therefore synchronise between the two
3050 user stores. We also use the passwd file to validate the user logins, as
3051 described in the previous example, `using an external password
3052 validation source`_. We keep the users lists in sync using a fairly
3053 simple script that runs once a day, or several times an hour if more
3054 immediate access is needed. In short, it:
3056 1. parses the passwd file, finding usernames, passwords and real names,
3057 2. compares that list to the current roundup user list:
3059 a. entries no longer in the passwd file are *retired*
3060 b. entries with mismatching real names are *updated*
3061 c. entries only exist in the passwd file are *created*
3063 3. send an email to administrators to let them know what's been done.
3065 The retiring and updating are simple operations, requiring only a call
3066 to ``retire()`` or ``set()``. The creation operation requires more
3067 information though - the user's email address and their roundup Roles.
3068 We're going to assume that the user's email address is the same as their
3069 login name, so we just append the domain name to that. The Roles are
3070 determined using the passwd group identifier - mapping their UN*X group
3071 to an appropriate set of Roles.
3073 The script to perform all this, broken up into its main components, is
3074 as follows. Firstly, we import the necessary modules and open the
3075 tracker we're to work on::
3077 import sys, os, smtplib
3078 from roundup import instance, date
3080 # open the tracker
3081 tracker_home = sys.argv[1]
3082 tracker = instance.open(tracker_home)
3084 Next we read in the *passwd* file from the tracker home::
3086 # read in the users
3087 file = os.path.join(tracker_home, 'users.passwd')
3088 users = [x.strip().split(':') for x in open(file).readlines()]
3090 Handle special users (those to ignore in the file, and those who don't
3091 appear in the file)::
3093 # users to not keep ever, pre-load with the users I know aren't
3094 # "real" users
3095 ignore = ['ekmmon', 'bfast', 'csrmail']
3097 # users to keep - pre-load with the roundup-specific users
3098 keep = ['comment_pool', 'network_pool', 'admin', 'dev-team',
3099 'cs_pool', 'anonymous', 'system_pool', 'automated']
3101 Now we map the UN*X group numbers to the Roles that users should have::
3103 roles = {
3104 '501': 'User,Tech', # tech
3105 '502': 'User', # finance
3106 '503': 'User,CSR', # customer service reps
3107 '504': 'User', # sales
3108 '505': 'User', # marketing
3109 }
3111 Now we do all the work. Note that the body of the script (where we have
3112 the tracker database open) is wrapped in a ``try`` / ``finally`` clause,
3113 so that we always close the database cleanly when we're finished. So, we
3114 now do all the work::
3116 # open the database
3117 db = tracker.open('admin')
3118 try:
3119 # store away messages to send to the tracker admins
3120 msg = []
3122 # loop over the users list read in from the passwd file
3123 for user,passw,uid,gid,real,home,shell in users:
3124 if user in ignore:
3125 # this user shouldn't appear in our tracker
3126 continue
3127 keep.append(user)
3128 try:
3129 # see if the user exists in the tracker
3130 uid = db.user.lookup(user)
3132 # yes, they do - now check the real name for correctness
3133 if real != db.user.get(uid, 'realname'):
3134 db.user.set(uid, realname=real)
3135 msg.append('FIX %s - %s'%(user, real))
3136 except KeyError:
3137 # nope, the user doesn't exist
3138 db.user.create(username=user, realname=real,
3139 address='%s@ekit-inc.com'%user, roles=roles[gid])
3140 msg.append('ADD %s - %s (%s)'%(user, real, roles[gid]))
3142 # now check that all the users in the tracker are also in our
3143 # "keep" list - retire those who aren't
3144 for uid in db.user.list():
3145 user = db.user.get(uid, 'username')
3146 if user not in keep:
3147 db.user.retire(uid)
3148 msg.append('RET %s'%user)
3150 # if we did work, then send email to the tracker admins
3151 if msg:
3152 # create the email
3153 msg = '''Subject: %s user database maintenance
3155 %s
3156 '''%(db.config.TRACKER_NAME, '\n'.join(msg))
3158 # send the email
3159 smtp = smtplib.SMTP(db.config.MAILHOST)
3160 addr = db.config.ADMIN_EMAIL
3161 smtp.sendmail(addr, addr, msg)
3163 # now we're done - commit the changes
3164 db.commit()
3165 finally:
3166 # always close the database cleanly
3167 db.close()
3169 And that's it!
3172 Using an LDAP database for user information
3173 -------------------------------------------
3175 A script that reads users from an LDAP store using
3176 http://python-ldap.sf.net/ and then compares the list to the users in the
3177 roundup user database would be pretty easy to write. You'd then have it run
3178 once an hour / day (or on demand if you can work that into your LDAP store
3179 workflow). See the example `Using a UN*X passwd file as the user database`_
3180 for more information about doing this.
3182 To authenticate off the LDAP store (rather than using the passwords in the
3183 roundup user database) you'd use the same python-ldap module inside an
3184 extension to the cgi interface. You'd do this by adding a method called
3185 "verifyPassword" to the Client class in your tracker's interfaces.py
3186 module. The method is implemented by default as::
3188 def verifyPassword(self, userid, password):
3189 ''' Verify the password that the user has supplied
3190 '''
3191 stored = self.db.user.get(self.userid, 'password')
3192 if password == stored:
3193 return 1
3194 if not password and not stored:
3195 return 1
3196 return 0
3198 So you could reimplement this as something like::
3200 def verifyPassword(self, userid, password):
3201 ''' Verify the password that the user has supplied
3202 '''
3203 # look up some unique LDAP information about the user
3204 username = self.db.user.get(self.userid, 'username')
3205 # now verify the password supplied against the LDAP store
3208 Enabling display of either message summaries or the entire messages
3209 -------------------------------------------------------------------
3211 This is pretty simple - all we need to do is copy the code from the
3212 example `displaying only message summaries in the issue display`_ into
3213 our template alongside the summary display, and then introduce a switch
3214 that shows either one or the other. We'll use a new form variable,
3215 ``@whole_messages`` to achieve this::
3217 <table class="messages" tal:condition="context/messages">
3218 <tal:block tal:condition="not:request/form/@whole_messages/value | python:0">
3219 <tr><th colspan="3" class="header">Messages</th>
3220 <th colspan="2" class="header">
3221 <a href="?@whole_messages=yes">show entire messages</a>
3222 </th>
3223 </tr>
3224 <tr tal:repeat="msg context/messages">
3225 <td><a tal:attributes="href string:msg${msg/id}"
3226 tal:content="string:msg${msg/id}"></a></td>
3227 <td tal:content="msg/author">author</td>
3228 <td class="date" tal:content="msg/date/pretty">date</td>
3229 <td tal:content="msg/summary">summary</td>
3230 <td>
3231 <a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">remove</a>
3232 </td>
3233 </tr>
3234 </tal:block>
3236 <tal:block tal:condition="request/form/@whole_messages/value | python:0">
3237 <tr><th colspan="2" class="header">Messages</th>
3238 <th class="header">
3239 <a href="?@whole_messages=">show only summaries</a>
3240 </th>
3241 </tr>
3242 <tal:block tal:repeat="msg context/messages">
3243 <tr>
3244 <th tal:content="msg/author">author</th>
3245 <th class="date" tal:content="msg/date/pretty">date</th>
3246 <th style="text-align: right">
3247 (<a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">remove</a>)
3248 </th>
3249 </tr>
3250 <tr><td colspan="3" tal:content="msg/content"></td></tr>
3251 </tal:block>
3252 </tal:block>
3253 </table>
3256 Blocking issues that depend on other issues
3257 -------------------------------------------
3259 We needed the ability to mark certain issues as "blockers" - that is,
3260 they can't be resolved until another issue (the blocker) they rely on is
3261 resolved. To achieve this:
3263 1. Create a new property on the issue Class,
3264 ``blockers=Multilink("issue")``. Edit your tracker's dbinit.py file.
3265 Where the "issue" class is defined, something like::
3267 issue = IssueClass(db, "issue",
3268 assignedto=Link("user"), topic=Multilink("keyword"),
3269 priority=Link("priority"), status=Link("status"))
3271 add the blockers entry like so::
3273 issue = IssueClass(db, "issue",
3274 blockers=Multilink("issue"),
3275 assignedto=Link("user"), topic=Multilink("keyword"),
3276 priority=Link("priority"), status=Link("status"))
3278 2. Add the new "blockers" property to the issue.item edit page, using
3279 something like::
3281 <th>Waiting On</th>
3282 <td>
3283 <span tal:replace="structure python:context.blockers.field(showid=1,
3284 size=20)" />
3285 <span tal:replace="structure python:db.issue.classhelp('id,title')" />
3286 <span tal:condition="context/blockers"
3287 tal:repeat="blk context/blockers">
3288 <br>View: <a tal:attributes="href string:issue${blk/id}"
3289 tal:content="blk/id"></a>
3290 </span>
3292 You'll need to fiddle with your item page layout to find an
3293 appropriate place to put it - I'll leave that fun part up to you.
3294 Just make sure it appears in the first table, possibly somewhere near
3295 the "superseders" field.
3297 3. Create a new detector module (attached) which enforces the rules:
3299 - issues may not be resolved if they have blockers
3300 - when a blocker is resolved, it's removed from issues it blocks
3302 The contents of the detector should be something like this::
3304 def blockresolution(db, cl, nodeid, newvalues):
3305 ''' If the issue has blockers, don't allow it to be resolved.
3306 '''
3307 if nodeid is None:
3308 blockers = []
3309 else:
3310 blockers = cl.get(nodeid, 'blockers')
3311 blockers = newvalues.get('blockers', blockers)
3313 # don't do anything if there's no blockers or the status hasn't
3314 # changed
3315 if not blockers or not newvalues.has_key('status'):
3316 return
3318 # get the resolved state ID
3319 resolved_id = db.status.lookup('resolved')
3321 # format the info
3322 u = db.config.TRACKER_WEB
3323 s = ', '.join(['<a href="%sissue%s">%s</a>'%(
3324 u,id,id) for id in blockers])
3325 if len(blockers) == 1:
3326 s = 'issue %s is'%s
3327 else:
3328 s = 'issues %s are'%s
3330 # ok, see if we're trying to resolve
3331 if newvalues['status'] == resolved_id:
3332 raise ValueError, "This issue can't be resolved until %s resolved."%s
3334 def resolveblockers(db, cl, nodeid, newvalues):
3335 ''' When we resolve an issue that's a blocker, remove it from the
3336 blockers list of the issue(s) it blocks.
3337 '''
3338 if not newvalues.has_key('status'):
3339 return
3341 # get the resolved state ID
3342 resolved_id = db.status.lookup('resolved')
3344 # interesting?
3345 if newvalues['status'] != resolved_id:
3346 return
3348 # yes - find all the blocked issues, if any, and remove me from
3349 # their blockers list
3350 issues = cl.find(blockers=nodeid)
3351 for issueid in issues:
3352 blockers = cl.get(issueid, 'blockers')
3353 if nodeid in blockers:
3354 blockers.remove(nodeid)
3355 cl.set(issueid, blockers=blockers)
3358 def init(db):
3359 # might, in an obscure situation, happen in a create
3360 db.issue.audit('create', blockresolution)
3361 db.issue.audit('set', blockresolution)
3363 # can only happen on a set
3364 db.issue.react('set', resolveblockers)
3366 Put the above code in a file called "blockers.py" in your tracker's
3367 "detectors" directory.
3369 4. Finally, and this is an optional step, modify the tracker web page
3370 URLs so they filter out issues with any blockers. You do this by
3371 adding an additional filter on "blockers" for the value "-1". For
3372 example, the existing "Show All" link in the "page" template (in the
3373 tracker's "html" directory) looks like this::
3375 <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>
3377 modify it to add the "blockers" info to the URL (note, both the
3378 ":filter" *and* "blockers" values must be specified)::
3380 <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>
3382 That's it. You should now be able to set blockers on your issues. Note
3383 that if you want to know whether an issue has any other issues dependent
3384 on it (i.e. it's in their blockers list) you can look at the journal
3385 history at the bottom of the issue page - look for a "link" event to
3386 another issue's "blockers" property.
3388 Add users to the nosy list based on the topic
3389 ---------------------------------------------
3391 We need the ability to automatically add users to the nosy list based
3392 on the occurence of a topic. Every user should be allowed to edit his
3393 own list of topics for which he wants to be added to the nosy list.
3395 Below will be showed that such a change can be performed with only
3396 minimal understanding of the roundup system, but with clever use
3397 of Copy and Paste.
3399 This requires three changes to the tracker: a change in the database to
3400 allow per-user recording of the lists of topics for which he wants to
3401 be put on the nosy list, a change in the user view allowing to edit
3402 this list of topics, and addition of an auditor which updates the nosy
3403 list when a topic is set.
3405 Adding the nosy topic list
3406 ~~~~~~~~~~~~~~~~~~~~~~~~~~
3408 The change in the database to make is that for any user there should be
3409 a list of topics for which he wants to be put on the nosy list. Adding
3410 a ``Multilink`` of ``keyword`` seem to fullfill this (note that within
3411 the code topics are called ``keywords``.) As such, all what has to be
3412 done is to add a new field to the definition of ``user`` within the
3413 file ``dbinit.py``. We will call this new field ``nosy_keywords``, and
3414 the updated definition of user will be::
3416 user = Class(db, "user",
3417 username=String(), password=Password(),
3418 address=String(), realname=String(),
3419 phone=String(), organisation=String(),
3420 alternate_addresses=String(),
3421 queries=Multilink('query'), roles=String(),
3422 timezone=String(),
3423 nosy_keywords=Multilink('keyword'))
3425 Changing the user view to allow changing the nosy topic list
3426 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3428 We want any user to be able to change the list of topics for which
3429 he will by default be added to the nosy list. We choose to add this
3430 to the user view, as is generated by the file ``html/user.item.html``.
3431 We easily can
3432 see that the topic field in the issue view has very similar editting
3433 requirements as our nosy topics, both being a list of topics. As
3434 such, we search for Topics in ``issue.item.html``, and extract the
3435 associated parts from there. We add this to ``user.item.html`` at the
3436 bottom of the list of viewed items (i.e. just below the 'Alternate
3437 E-mail addresses' in the classic template)::
3439 <tr>
3440 <th>Nosy Topics</th>
3441 <td>
3442 <span tal:replace="structure context/nosy_keywords/field" />
3443 <span tal:replace="structure python:db.keyword.classhelp(property='nosy_keywords')" />
3444 </td>
3445 </tr>
3448 Addition of an auditor to update the nosy list
3449 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3451 The more difficult part is the addition of the logic to actually
3452 at the users to the nosy list when it is required.
3453 The choice is made to perform this action when the topics on an
3454 item are set, including when an item is created.
3455 Here we choose to start out with a copy of the
3456 ``detectors/nosyreaction.py`` detector, which we copy to the file
3457 ``detectors/nosy_keyword_reaction.py``.
3458 This looks like a good start as it also adds users
3459 to the nosy list. A look through the code reveals that the
3460 ``nosyreaction`` function actually is sending the e-mail, which
3461 we do not need. As such, we can change the init function to::
3463 def init(db):
3464 db.issue.audit('create', update_kw_nosy)
3465 db.issue.audit('set', update_kw_nosy)
3467 After that we rename the ``updatenosy`` function to ``update_kw_nosy``.
3468 The first two blocks of code in that function relate to settings
3469 ``current`` to a combination of the old and new nosy lists. This
3470 functionality is left in the new auditor. The following block of
3471 code, which in ``updatenosy`` handled adding the assignedto user(s)
3472 to the nosy list, should be replaced by a block of code to add the
3473 interested users to the nosy list. We choose here to loop over all
3474 new topics, than loop over all users,
3475 and assign the user to the nosy list when the topic in the user's
3476 nosy_keywords. The next part in ``updatenosy``, adding the author
3477 and/or recipients of a message to the nosy list, obviously is not
3478 relevant here and thus is deleted from the new auditor. The last
3479 part, copying the new nosy list to newvalues, does not have to be changed.
3480 This brings the following function::
3482 def update_kw_nosy(db, cl, nodeid, newvalues):
3483 '''Update the nosy list for changes to the topics
3484 '''
3485 # nodeid will be None if this is a new node
3486 current = {}
3487 if nodeid is None:
3488 ok = ('new', 'yes')
3489 else:
3490 ok = ('yes',)
3491 # old node, get the current values from the node if they haven't
3492 # changed
3493 if not newvalues.has_key('nosy'):
3494 nosy = cl.get(nodeid, 'nosy')
3495 for value in nosy:
3496 if not current.has_key(value):
3497 current[value] = 1
3499 # if the nosy list changed in this transaction, init from the new value
3500 if newvalues.has_key('nosy'):
3501 nosy = newvalues.get('nosy', [])
3502 for value in nosy:
3503 if not db.hasnode('user', value):
3504 continue
3505 if not current.has_key(value):
3506 current[value] = 1
3508 # add users with topic in nosy_keywords to the nosy list
3509 if newvalues.has_key('topic') and newvalues['topic'] is not None:
3510 topic_ids = newvalues['topic']
3511 for topic in topic_ids:
3512 # loop over all users,
3513 # and assign user to nosy when topic in nosy_keywords
3514 for user_id in db.user.list():
3515 nosy_kw = db.user.get(user_id, "nosy_keywords")
3516 found = 0
3517 for kw in nosy_kw:
3518 if kw == topic:
3519 found = 1
3520 if found:
3521 current[user_id] = 1
3523 # that's it, save off the new nosy list
3524 newvalues['nosy'] = current.keys()
3526 and these two function are the only ones needed in the file.
3528 TODO: update this example to use the find() Class method.
3530 Caveats
3531 ~~~~~~~
3533 A few problems with the design here can be noted:
3535 Multiple additions
3536 When a user, after automatic selection, is manually removed
3537 from the nosy list, he again is added to the nosy list when the
3538 topic list of the issue is updated. A better design might be
3539 to only check which topics are new compared to the old list
3540 of topics, and only add users when they have indicated
3541 interest on a new topic.
3543 The code could also be changed to only trigger on the create() event,
3544 rather than also on the set() event, thus only setting the nosy list
3545 when the issue is created.
3547 Scalability
3548 In the auditor there is a loop over all users. For a site with
3549 only few users this will pose no serious problem, however, with
3550 many users this will be a serious performance bottleneck.
3551 A way out will be to link from the topics to the users which
3552 selected these topics a nosy topics. This will eliminate the
3553 loop over all users.
3556 Adding action links to the index page
3557 -------------------------------------
3559 Add a column to the item.index.html template.
3561 Resolving the issue::
3563 <a tal:attributes="href
3564 string:issue${i/id}?:status=resolved&:action=edit">resolve</a>
3566 "Take" the issue::
3568 <a tal:attributes="href
3569 string:issue${i/id}?:assignedto=${request/user/id}&:action=edit">take</a>
3571 ... and so on
3573 -------------------
3575 Back to `Table of Contents`_
3577 .. _`Table of Contents`: index.html
3578 .. _`design documentation`: design.html