1 ===================
2 Customising Roundup
3 ===================
5 :Version: $Revision: 1.108 $
7 .. This document borrows from the ZopeBook section on ZPT. The original is at:
8 http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
10 .. contents::
11 :depth: 1
13 What You Can Do
14 ===============
16 Before you get too far, it's probably worth having a quick read of the Roundup
17 `design documentation`_.
19 Customisation of Roundup can take one of six forms:
21 1. `tracker configuration`_ file changes
22 2. database, or `tracker schema`_ changes
23 3. "definition" class `database content`_ changes
24 4. behavioural changes, through detectors_
25 5. `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 **HTML_VERSION** - ``'html4'`` or ``'xhtml'``
184 HTML version to generate. The templates are html4 by default. If you
185 wish to make them xhtml, then you'll need to change this var to 'xhtml'
186 too so all auto-generated HTML is compliant.
188 The default config.py is given below - as you
189 can see, the MAIL_DOMAIN must be edited before any interaction with the
190 tracker is attempted.::
192 # roundup home is this package's directory
193 TRACKER_HOME=os.path.split(__file__)[0]
195 # The SMTP mail host that roundup will use to send mail
196 MAILHOST = 'localhost'
198 # The domain name used for email addresses.
199 MAIL_DOMAIN = 'your.tracker.email.domain.example'
201 # This is the directory that the database is going to be stored in
202 DATABASE = os.path.join(TRACKER_HOME, 'db')
204 # This is the directory that the HTML templates reside in
205 TEMPLATES = os.path.join(TRACKER_HOME, 'html')
207 # A descriptive name for your roundup tracker
208 TRACKER_NAME = 'Roundup issue tracker'
210 # The email address that mail to roundup should go to
211 TRACKER_EMAIL = 'issue_tracker@%s'%MAIL_DOMAIN
213 # The web address that the tracker is viewable at. This will be
214 # included in information sent to users of the tracker. The URL MUST
215 # include the cgi-bin part or anything else that is required to get
216 # to the home page of the tracker. You MUST include a trailing '/'
217 # in the URL.
218 TRACKER_WEB = 'http://tracker.example/cgi-bin/roundup.cgi/bugs/'
220 # The email address that roundup will complain to if it runs into
221 # trouble
222 ADMIN_EMAIL = 'roundup-admin@%s'%MAIL_DOMAIN
224 # Additional text to include in the "name" part of the From: address
225 # used in nosy messages. If the sending user is "Foo Bar", the From:
226 # line is usually: "Foo Bar" <issue_tracker@tracker.example>
227 # the EMAIL_FROM_TAG goes inside the "Foo Bar" quotes like so:
228 # "Foo Bar EMAIL_FROM_TAG" <issue_tracker@tracker.example>
229 EMAIL_FROM_TAG = ""
231 # Send nosy messages to the author of the message
232 MESSAGES_TO_AUTHOR = 'no' # either 'yes' or 'no'
234 # Does the author of a message get placed on the nosy list
235 # automatically? If 'new' is used, then the author will only be
236 # added when a message creates a new issue. If 'yes', then the
237 # author will be added on followups too. If 'no', they're never
238 # added to the nosy.
239 ADD_AUTHOR_TO_NOSY = 'new' # one of 'yes', 'no', 'new'
241 # Do the recipients (To:, Cc:) of a message get placed on the nosy
242 # list? If 'new' is used, then the recipients will only be added
243 # when a message creates a new issue. If 'yes', then the recipients
244 # will be added on followups too. If 'no', they're never added to
245 # the nosy.
246 ADD_RECIPIENTS_TO_NOSY = 'new' # either 'yes', 'no', 'new'
248 # Where to place the email signature
249 EMAIL_SIGNATURE_POSITION = 'bottom' # one of 'top', 'bottom', 'none'
251 # Keep email citations
252 EMAIL_KEEP_QUOTED_TEXT = 'no' # either 'yes' or 'no'
254 # Preserve the email body as is
255 EMAIL_LEAVE_BODY_UNCHANGED = 'no' # either 'yes' or 'no'
257 # Default class to use in the mailgw if one isn't supplied in email
258 # subjects. To disable, comment out the variable below or leave it
259 # blank. Examples:
260 MAIL_DEFAULT_CLASS = 'issue' # use "issue" class by default
261 #MAIL_DEFAULT_CLASS = '' # disable (or just comment the var out)
263 # HTML version to generate. The templates are html4 by default. If you
264 # wish to make them xhtml, then you'll need to change this var to 'xhtml'
265 # too so all auto-generated HTML is compliant.
266 HTML_VERSION = 'html4' # either 'html4' or 'xhtml'
268 #
269 # SECURITY DEFINITIONS
270 #
271 # define the Roles that a user gets when they register with the
272 # tracker these are a comma-separated string of role names (e.g.
273 # 'Admin,User')
274 NEW_WEB_USER_ROLES = 'User'
275 NEW_EMAIL_USER_ROLES = 'User'
277 Tracker Schema
278 ==============
280 Note: if you modify the schema, you'll most likely need to edit the
281 `web interface`_ HTML template files and `detectors`_ to reflect
282 your changes.
284 A tracker schema defines what data is stored in the tracker's database.
285 Schemas are defined using Python code in the ``dbinit.py`` module of your
286 tracker. The "classic" schema looks like this (see below for the meaning
287 of ``'setkey'``)::
289 pri = Class(db, "priority", name=String(), order=String())
290 pri.setkey("name")
292 stat = Class(db, "status", name=String(), order=String())
293 stat.setkey("name")
295 keyword = Class(db, "keyword", name=String())
296 keyword.setkey("name")
298 user = Class(db, "user", username=String(), organisation=String(),
299 password=String(), address=String(), realname=String(),
300 phone=String())
301 user.setkey("username")
303 msg = FileClass(db, "msg", author=Link("user"), summary=String(),
304 date=Date(), recipients=Multilink("user"),
305 files=Multilink("file"))
307 file = FileClass(db, "file", name=String(), type=String())
309 issue = IssueClass(db, "issue", topic=Multilink("keyword"),
310 status=Link("status"), assignedto=Link("user"),
311 priority=Link("priority"))
312 issue.setkey('title')
315 What you can't do to the schema
316 -------------------------------
318 You must never:
320 **Remove the users class**
321 This class is the only *required* class in Roundup. Similarly, its
322 username, password and address properties must never be removed.
324 **Change the type of a property**
325 Property types must *never* be changed - the database simply doesn't take
326 this kind of action into account. Note that you can't just remove a
327 property and re-add it as a new type either. If you wanted to make the
328 assignedto property a Multilink, you'd need to create a new property
329 assignedto_list and remove the old assignedto property.
332 What you can do to the schema
333 -----------------------------
335 Your schema may be changed at any time before or after the tracker has been
336 initialised (or used). You may:
338 **Add new properties to classes, or add whole new classes**
339 This is painless and easy to do - there are generally no repurcussions
340 from adding new information to a tracker's schema.
342 **Remove properties**
343 Removing properties is a little more tricky - you need to make sure that
344 the property is no longer used in the `web interface`_ *or* by the
345 detectors_.
349 Classes and Properties - creating a new information store
350 ---------------------------------------------------------
352 In the tracker above, we've defined 7 classes of information:
354 priority
355 Defines the possible levels of urgency for issues.
357 status
358 Defines the possible states of processing the issue may be in.
360 keyword
361 Initially empty, will hold keywords useful for searching issues.
363 user
364 Initially holding the "admin" user, will eventually have an entry
365 for all users using roundup.
367 msg
368 Initially empty, will hold all e-mail messages sent to or
369 generated by roundup.
371 file
372 Initially empty, will hold all files attached to issues.
374 issue
375 Initially empty, this is where the issue information is stored.
377 We define the "priority" and "status" classes to allow two things:
378 reduction in the amount of information stored on the issue and more
379 powerful, accurate searching of issues by priority and status. By only
380 requiring a link on the issue (which is stored as a single number) we
381 reduce the chance that someone mis-types a priority or status - or
382 simply makes a new one up.
385 Class and Items
386 ~~~~~~~~~~~~~~~
388 A Class defines a particular class (or type) of data that will be stored
389 in the database. A class comprises one or more properties, which gives
390 the information about the class items.
392 The actual data entered into the database, using ``class.create()``, are
393 called items. They have a special immutable property called ``'id'``. We
394 sometimes refer to this as the *itemid*.
397 Properties
398 ~~~~~~~~~~
400 A Class is comprised of one or more properties of the following types:
402 * String properties are for storing arbitrary-length strings.
403 * Password properties are for storing encoded arbitrary-length strings.
404 The default encoding is defined on the ``roundup.password.Password``
405 class.
406 * Date properties store date-and-time stamps. Their values are Timestamp
407 objects.
408 * Number properties store numeric values.
409 * Boolean properties store on/off, yes/no, true/false values.
410 * A Link property refers to a single other item selected from a
411 specified class. The class is part of the property; the value is an
412 integer, the id of the chosen item.
413 * A Multilink property refers to possibly many items in a specified
414 class. The value is a list of integers.
417 FileClass
418 ~~~~~~~~~
420 FileClasses save their "content" attribute off in a separate file from
421 the rest of the database. This reduces the number of large entries in
422 the database, which generally makes databases more efficient, and also
423 allows us to use command-line tools to operate on the files. They are
424 stored in the files sub-directory of the ``'db'`` directory in your
425 tracker.
428 IssueClass
429 ~~~~~~~~~~
431 IssueClasses automatically include the "messages", "files", "nosy", and
432 "superseder" properties.
434 The messages and files properties list the links to the messages and
435 files related to the issue. The nosy property is a list of links to
436 users who wish to be informed of changes to the issue - they get "CC'ed"
437 e-mails when messages are sent to or generated by the issue. The nosy
438 reactor (in the ``'detectors'`` directory) handles this action. The
439 superseder link indicates an issue which has superseded this one.
441 They also have the dynamically generated "creation", "activity" and
442 "creator" properties.
444 The value of the "creation" property is the date when an item was
445 created, and the value of the "activity" property is the date when any
446 property on the item was last edited (equivalently, these are the dates
447 on the first and last records in the item's journal). The "creator"
448 property holds a link to the user that created the issue.
451 setkey(property)
452 ~~~~~~~~~~~~~~~~
454 Select a String property of the class to be the key property. The key
455 property must be unique, and allows references to the items in the class
456 by the content of the key property. That is, we can refer to users by
457 their username: for example, let's say that there's an issue in roundup,
458 issue 23. There's also a user, richard, who happens to be user 2. To
459 assign an issue to him, we could do either of::
461 roundup-admin set issue23 assignedto=2
463 or::
465 roundup-admin set issue23 assignedto=richard
467 Note, the same thing can be done in the web and e-mail interfaces.
469 If a class does not have an "order" property, the key is also used to
470 sort instances of the class when it is rendered in the user interface.
471 (If a class has no "order" property, sorting is by the labelproperty of
472 the class. This is computed, in order of precedence, as the key, the
473 "name", the "title", or the first property alphabetically.)
476 create(information)
477 ~~~~~~~~~~~~~~~~~~~
479 Create an item in the database. This is generally used to create items
480 in the "definitional" classes like "priority" and "status".
483 Examples of adding to your schema
484 ---------------------------------
486 TODO
489 Detectors - adding behaviour to your tracker
490 ============================================
491 .. _detectors:
493 Detectors are initialised every time you open your tracker database, so
494 you're free to add and remove them any time, even after the database is
495 initialised via the "roundup-admin initialise" command.
497 The detectors in your tracker fire *before* (**auditors**) and *after*
498 (**reactors**) changes to the contents of your database. They are Python
499 modules that sit in your tracker's ``detectors`` directory. You will
500 have some installed by default - have a look. You can write new
501 detectors or modify the existing ones. The existing detectors installed
502 for you are:
504 **nosyreaction.py**
505 This provides the automatic nosy list maintenance and email sending.
506 The nosy reactor (``nosyreaction``) fires when new messages are added
507 to issues. The nosy auditor (``updatenosy``) fires when issues are
508 changed, and figures out what changes need to be made to the nosy list
509 (such as adding new authors, etc.)
510 **statusauditor.py**
511 This provides the ``chatty`` auditor which changes the issue status
512 from ``unread`` or ``closed`` to ``chatting`` if new messages appear.
513 It also provides the ``presetunread`` auditor which pre-sets the
514 status to ``unread`` on new items if the status isn't explicitly
515 defined.
516 **messagesummary.py**
517 Generates the ``summary`` property for new messages based on the message
518 content.
519 **userauditor.py**
520 Verifies the content of some of the user fields (email addresses and
521 roles lists).
523 If you don't want this default behaviour, you're completely free to change
524 or remove these detectors.
526 See the detectors section in the `design document`__ for details of the
527 interface for detectors.
529 __ design.html
531 Sample additional detectors that have been found useful will appear in
532 the ``'detectors'`` directory of the Roundup distribution. If you want
533 to use one, copy it to the ``'detectors'`` of your tracker instance:
535 **newissuecopy.py**
536 This detector sends an email to a team address whenever a new issue is
537 created. The address is hard-coded into the detector, so edit it
538 before you use it (look for the text 'team@team.host') or you'll get
539 email errors!
541 The detector code::
543 from roundup import roundupdb
545 def newissuecopy(db, cl, nodeid, oldvalues):
546 ''' Copy a message about new issues to a team address.
547 '''
548 # so use all the messages in the create
549 change_note = cl.generateCreateNote(nodeid)
551 # send a copy to the nosy list
552 for msgid in cl.get(nodeid, 'messages'):
553 try:
554 # note: last arg must be a list
555 cl.send_message(nodeid, msgid, change_note,
556 ['team@team.host'])
557 except roundupdb.MessageSendError, message:
558 raise roundupdb.DetectorError, message
560 def init(db):
561 db.issue.react('create', newissuecopy)
564 Database Content
565 ================
567 Note: if you modify the content of definitional classes, you'll most
568 likely need to edit the tracker `detectors`_ to reflect your
569 changes.
571 Customisation of the special "definitional" classes (eg. status,
572 priority, resolution, ...) may be done either before or after the
573 tracker is initialised. The actual method of doing so is completely
574 different in each case though, so be careful to use the right one.
576 **Changing content before tracker initialisation**
577 Edit the dbinit module in your tracker to alter the items created in
578 using the ``create()`` methods.
580 **Changing content after tracker initialisation**
581 As the "admin" user, click on the "class list" link in the web
582 interface to bring up a list of all database classes. Click on the
583 name of the class you wish to change the content of.
585 You may also use the ``roundup-admin`` interface's create, set and
586 retire methods to add, alter or remove items from the classes in
587 question.
589 See "`adding a new field to the classic schema`_" for an example that
590 requires database content changes.
593 Access Controls
594 ===============
596 A set of Permissions is built into the security module by default:
598 - Edit (everything)
599 - View (everything)
601 The default interfaces define:
603 - Web Registration
604 - Web Access
605 - Web Roles
606 - Email Registration
607 - Email Access
609 These are hooked into the default Roles:
611 - Admin (Edit everything, View everything, Web Roles)
612 - User (Web Access, Email Access)
613 - Anonymous (Web Registration, Email Registration)
615 And finally, the "admin" user gets the "Admin" Role, and the "anonymous"
616 user gets "Anonymous" assigned when the database is initialised on
617 installation. The two default schemas then define:
619 - Edit issue, View issue (both)
620 - Edit file, View file (both)
621 - Edit msg, View msg (both)
622 - Edit support, View support (extended only)
624 and assign those Permissions to the "User" Role. Put together, these
625 settings appear in the ``open()`` function of the tracker ``dbinit.py``
626 (the following is taken from the "minimal" template's ``dbinit.py``)::
628 #
629 # SECURITY SETTINGS
630 #
631 # new permissions for this schema
632 for cl in ('user', ):
633 db.security.addPermission(name="Edit", klass=cl,
634 description="User is allowed to edit "+cl)
635 db.security.addPermission(name="View", klass=cl,
636 description="User is allowed to access "+cl)
638 # and give the regular users access to the web and email interface
639 p = db.security.getPermission('Web Access')
640 db.security.addPermissionToRole('User', p)
641 p = db.security.getPermission('Email Access')
642 db.security.addPermissionToRole('User', p)
644 # May users view other user information? Comment these lines out
645 # if you don't want them to
646 p = db.security.getPermission('View', 'user')
647 db.security.addPermissionToRole('User', p)
649 # Assign the appropriate permissions to the anonymous user's
650 # Anonymous role. Choices here are:
651 # - Allow anonymous users to register through the web
652 p = db.security.getPermission('Web Registration')
653 db.security.addPermissionToRole('Anonymous', p)
654 # - Allow anonymous (new) users to register through the email
655 # gateway
656 p = db.security.getPermission('Email Registration')
657 db.security.addPermissionToRole('Anonymous', p)
660 New User Roles
661 --------------
663 New users are assigned the Roles defined in the config file as:
665 - NEW_WEB_USER_ROLES
666 - NEW_EMAIL_USER_ROLES
669 Changing Access Controls
670 ------------------------
672 You may alter the configuration variables to change the Role that new
673 web or email users get, for example to not give them access to the web
674 interface if they register through email.
676 You may use the ``roundup-admin`` "``security``" command to display the
677 current Role and Permission configuration in your tracker.
680 Adding a new Permission
681 ~~~~~~~~~~~~~~~~~~~~~~~
683 When adding a new Permission, you will need to:
685 1. add it to your tracker's dbinit so it is created
686 2. enable it for the Roles that should have it (verify with
687 "``roundup-admin security``")
688 3. add it to the relevant HTML interface templates
689 4. add it to the appropriate xxxPermission methods on in your tracker
690 interfaces module
693 Example Scenarios
694 ~~~~~~~~~~~~~~~~~
696 **automatic registration of users in the e-mail gateway**
697 By giving the "anonymous" user the "Email Registration" Role, any
698 unidentified user will automatically be registered with the tracker
699 (with no password, so they won't be able to log in through the web
700 until an admin sets their password). Note: this is the default
701 behaviour in the tracker templates that ship with Roundup.
703 **anonymous access through the e-mail gateway**
704 Give the "anonymous" user the "Email Access" and ("Edit", "issue")
705 Roles but do not not give them the "Email Registration" Role. This
706 means that when an unknown user sends email into the tracker, they're
707 automatically logged in as "anonymous". Since they don't have the
708 "Email Registration" Role, they won't be automatically registered, but
709 since "anonymous" has permission to use the gateway, they'll still be
710 able to submit issues. Note that the Sender information - their email
711 address - will not be available - they're *anonymous*.
713 **only developers may be assigned issues**
714 Create a new Permission called "Fixer" for the "issue" class. Create a
715 new Role "Developer" which has that Permission, and assign that to the
716 appropriate users. Filter the list of users available in the assignedto
717 list to include only those users. Enforce the Permission with an
718 auditor. See the example
719 `restricting the list of users that are assignable to a task`_.
721 **only managers may sign off issues as complete**
722 Create a new Permission called "Closer" for the "issue" class. Create a
723 new Role "Manager" which has that Permission, and assign that to the
724 appropriate users. In your web interface, only display the "resolved"
725 issue state option when the user has the "Closer" Permissions. Enforce
726 the Permission with an auditor. This is very similar to the previous
727 example, except that the web interface check would look like::
729 <option tal:condition="python:request.user.hasPermission('Closer')"
730 value="resolved">Resolved</option>
732 **don't give web access to users who register through email**
733 Create a new Role called "Email User" which has all the Permissions of
734 the normal "User" Role minus the "Web Access" Permission. This will
735 allow users to send in emails to the tracker, but not access the web
736 interface.
738 **let some users edit the details of all users**
739 Create a new Role called "User Admin" which has the Permission for
740 editing users::
742 db.security.addRole(name='User Admin', description='Managing users')
743 p = db.security.getPermission('Edit', 'user')
744 db.security.addPermissionToRole('User Admin', p)
746 and assign the Role to the users who need the permission.
749 Web Interface
750 =============
752 .. contents::
753 :local:
754 :depth: 1
756 The web interface is provided by the ``roundup.cgi.client`` module and
757 is used by ``roundup.cgi``, ``roundup-server`` and ``ZRoundup``
758 (``ZRoundup`` is broken, until further notice). In all cases, we
759 determine which tracker is being accessed (the first part of the URL
760 path inside the scope of the CGI handler) and pass control on to the
761 tracker ``interfaces.Client`` class - which uses the ``Client`` class
762 from ``roundup.cgi.client`` - which handles the rest of the access
763 through its ``main()`` method. This means that you can do pretty much
764 anything you want as a web interface to your tracker.
766 Repercussions of changing the tracker schema
767 ---------------------------------------------
769 If you choose to change the `tracker schema`_ you will need to ensure
770 the web interface knows about it:
772 1. Index, item and search pages for the relevant classes may need to
773 have properties added or removed,
774 2. The "page" template may require links to be changed, as might the
775 "home" page's content arguments.
777 How requests are processed
778 --------------------------
780 The basic processing of a web request proceeds as follows:
782 1. figure out who we are, defaulting to the "anonymous" user
783 2. figure out what the request is for - we call this the "context"
784 3. handle any requested action (item edit, search, ...)
785 4. render the template requested by the context, resulting in HTML
786 output
788 In some situations, exceptions occur:
790 - HTTP Redirect (generally raised by an action)
791 - SendFile (generally raised by ``determine_context``)
792 here we serve up a FileClass "content" property
793 - SendStaticFile (generally raised by ``determine_context``)
794 here we serve up a file from the tracker "html" directory
795 - Unauthorised (generally raised by an action)
796 here the action is cancelled, the request is rendered and an error
797 message is displayed indicating that permission was not granted for
798 the action to take place
799 - NotFound (raised wherever it needs to be)
800 this exception percolates up to the CGI interface that called the
801 client
803 Determining web context
804 -----------------------
806 To determine the "context" of a request, we look at the URL and the
807 special request variable ``@template``. The URL path after the tracker
808 identifier is examined. Typical URL paths look like:
810 1. ``/tracker/issue``
811 2. ``/tracker/issue1``
812 3. ``/tracker/_file/style.css``
813 4. ``/cgi-bin/roundup.cgi/tracker/file1``
814 5. ``/cgi-bin/roundup.cgi/tracker/file1/kitten.png``
816 where the "tracker identifier" is "tracker" in the above cases. That means
817 we're looking at "issue", "issue1", "_file/style.css", "file1" and
818 "file1/kitten.png" in the cases above. The path is generally only one
819 entry long - longer paths are handled differently.
821 a. if there is no path, then we are in the "home" context.
822 b. if the path starts with "_file" (as in example 3,
823 "/tracker/_file/style.css"), then the additional path entry,
824 "style.css" specifies the filename of a static file we're to serve up
825 from the tracker "html" directory. Raises a SendStaticFile exception.
826 c. if there is something in the path (as in example 1, "issue"), it
827 identifies the tracker class we're to display.
828 d. if the path is an item designator (as in examples 2 and 4, "issue1"
829 and "file1"), then we're to display a specific item.
830 e. if the path starts with an item designator and is longer than one
831 entry (as in example 5, "file1/kitten.png"), then we're assumed to be
832 handling an item of a ``FileClass``, and the extra path information
833 gives the filename that the client is going to label the download
834 with (i.e. "file1/kitten.png" is nicer to download than "file1").
835 This raises a ``SendFile`` exception.
837 Both b. and e. stop before we bother to determine the template we're
838 going to use. That's because they don't actually use templates.
840 The template used is specified by the ``@template`` CGI variable, which
841 defaults to:
843 - only classname suplied: "index"
844 - full item designator supplied: "item"
847 Performing actions in web requests
848 ----------------------------------
850 When a user requests a web page, they may optionally also request for an
851 action to take place. As described in `how requests are processed`_, the
852 action is performed before the requested page is generated. Actions are
853 triggered by using a ``@action`` CGI variable, where the value is one
854 of:
856 **login**
857 Attempt to log a user in.
859 **logout**
860 Log the user out - make them "anonymous".
862 **register**
863 Attempt to create a new user based on the contents of the form and then
864 log them in.
866 **edit**
867 Perform an edit of an item in the database. There are some `special form
868 variables`_ you may use.
870 **new**
871 Add a new item to the database. You may use the same `special form
872 variables`_ as in the "edit" action.
874 **retire**
875 Retire the item in the database.
877 **editCSV**
878 Performs an edit of all of a class' items in one go. See also the
879 *class*.csv templating method which generates the CSV data to be
880 edited, and the ``'_generic.index'`` template which uses both of these
881 features.
883 **search**
884 Mangle some of the form variables:
886 - Set the form ":filter" variable based on the values of the filter
887 variables - if they're set to anything other than "dontcare" then add
888 them to :filter.
890 - Also handle the ":queryname" variable and save off the query to the
891 user's query list.
893 Each of the actions is implemented by a corresponding ``*actionAction*``
894 (where "action" is the name of the action) method on the
895 ``roundup.cgi.Client`` class, which also happens to be available in your
896 tracker instance as ``interfaces.Client``. So if you need to define new
897 actions, you may add them there (see `defining new web actions`_).
899 Each action also has a corresponding ``*actionPermission*`` (where
900 "action" is the name of the action) method which determines whether the
901 action is permissible given the current user. The base permission checks
902 are:
904 **login**
905 Determine whether the user has permission to log in. Base behaviour is
906 to check the user has "Web Access".
907 **logout**
908 No permission checks are made.
909 **register**
910 Determine whether the user has permission to register. Base behaviour
911 is to check the user has the "Web Registration" Permission.
912 **edit**
913 Determine whether the user has permission to edit this item. Base
914 behaviour is to check whether the user can edit this class. If we're
915 editing the "user" class, users are allowed to edit their own details -
916 unless they try to edit the "roles" property, which requires the
917 special Permission "Web Roles".
918 **new**
919 Determine whether the user has permission to create (or edit) this
920 item. Base behaviour is to check the user can edit this class. No
921 additional property checks are made. Additionally, new user items may
922 be created if the user has the "Web Registration" Permission.
923 **editCSV**
924 Determine whether the user has permission to edit this class. Base
925 behaviour is to check whether the user may edit this class.
926 **search**
927 Determine whether the user has permission to search this class. Base
928 behaviour is to check whether the user may view this class.
931 Special form variables
932 ----------------------
934 Item properties and their values are edited with html FORM
935 variables and their values. You can:
937 - Change the value of some property of the current item.
938 - Create a new item of any class, and edit the new item's
939 properties,
940 - Attach newly created items to a multilink property of the
941 current item.
942 - Remove items from a multilink property of the current item.
943 - Specify that some properties are required for the edit
944 operation to be successful.
946 In the following, <bracketed> values are variable, "@" may be
947 either ":" or "@", and other text "required" is fixed.
949 Most properties are specified as form variables:
951 ``<propname>``
952 property on the current context item
954 ``<designator>"@"<propname>``
955 property on the indicated item (for editing related information)
957 Designators name a specific item of a class.
959 ``<classname><N>``
960 Name an existing item of class <classname>.
962 ``<classname>"-"<N>``
963 Name the <N>th new item of class <classname>. If the form
964 submission is successful, a new item of <classname> is
965 created. Within the submitted form, a particular
966 designator of this form always refers to the same new
967 item.
969 Once we have determined the "propname", we look at it to see
970 if it's special:
972 ``@required``
973 The associated form value is a comma-separated list of
974 property names that must be specified when the form is
975 submitted for the edit operation to succeed.
977 When the <designator> is missing, the properties are
978 for the current context item. When <designator> is
979 present, they are for the item specified by
980 <designator>.
982 The "@required" specifier must come before any of the
983 properties it refers to are assigned in the form.
985 ``@remove@<propname>=id(s)`` or ``@add@<propname>=id(s)``
986 The "@add@" and "@remove@" edit actions apply only to
987 Multilink properties. The form value must be a
988 comma-separate list of keys for the class specified by
989 the simple form variable. The listed items are added
990 to (respectively, removed from) the specified
991 property.
993 ``@link@<propname>=<designator>``
994 If the edit action is "@link@", the simple form
995 variable must specify a Link or Multilink property.
996 The form value is a comma-separated list of
997 designators. The item corresponding to each
998 designator is linked to the property given by simple
999 form variable.
1001 None of the above (ie. just a simple form value)
1002 The value of the form variable is converted
1003 appropriately, depending on the type of the property.
1005 For a Link('klass') property, the form value is a
1006 single key for 'klass', where the key field is
1007 specified in dbinit.py.
1009 For a Multilink('klass') property, the form value is a
1010 comma-separated list of keys for 'klass', where the
1011 key field is specified in dbinit.py.
1013 Note that for simple-form-variables specifiying Link
1014 and Multilink properties, the linked-to class must
1015 have a key field.
1017 For a String() property specifying a filename, the
1018 file named by the form value is uploaded. This means we
1019 try to set additional properties "filename" and "type" (if
1020 they are valid for the class). Otherwise, the property
1021 is set to the form value.
1023 For Date(), Interval(), Boolean(), and Number()
1024 properties, the form value is converted to the
1025 appropriate
1027 Any of the form variables may be prefixed with a classname or
1028 designator.
1030 Two special form values are supported for backwards compatibility:
1032 @note
1033 This is equivalent to::
1035 @link@messages=msg-1
1036 msg-1@content=value
1038 except that in addition, the "author" and "date" properties of
1039 "msg-1" are set to the userid of the submitter, and the current
1040 time, respectively.
1042 @file
1043 This is equivalent to::
1045 @link@files=file-1
1046 file-1@content=value
1048 The String content value is handled as described above for file
1049 uploads.
1051 If both the "@note" and "@file" form variables are
1052 specified, the action::
1054 @link@msg-1@files=file-1
1056 is also performed.
1058 We also check that FileClass items have a "content" property with
1059 actual content, otherwise we remove them from all_props before
1060 returning.
1064 Default templates
1065 -----------------
1067 The default templates are html4 compliant. If you wish to change them to be
1068 xhtml compliant, you'll need to change the ``HTML_VERSION`` configuration
1069 variable in ``config.py`` to ``'xhtml'`` instead of ``'html4'``.
1071 Most customisation of the web view can be done by modifying the
1072 templates in the tracker ``'html'`` directory. There are several types
1073 of files in there. The *minimal* template includes:
1075 **page.html**
1076 This template usually defines the overall look of your tracker. When
1077 you view an issue, it appears inside this template. When you view an
1078 index, it also appears inside this template. This template defines a
1079 macro called "icing" which is used by almost all other templates as a
1080 coating for their content, using its "content" slot. It also defines
1081 the "head_title" and "body_title" slots to allow setting of the page
1082 title.
1083 **home.html**
1084 the default page displayed when no other page is indicated by the user
1085 **home.classlist.html**
1086 a special version of the default page that lists the classes in the
1087 tracker
1088 **classname.item.html**
1089 displays an item of the *classname* class
1090 **classname.index.html**
1091 displays a list of *classname* items
1092 **classname.search.html**
1093 displays a search page for *classname* items
1094 **_generic.index.html**
1095 used to display a list of items where there is no
1096 ``*classname*.index`` available
1097 **_generic.help.html**
1098 used to display a "class help" page where there is no
1099 ``*classname*.help``
1100 **user.register.html**
1101 a special page just for the user class, that renders the registration
1102 page
1103 **style.css.html**
1104 a static file that is served up as-is
1106 The *classic* template has a number of additional templates.
1108 Note: Remember that you can create any template extension you want to,
1109 so if you just want to play around with the templating for new issues,
1110 you can copy the current "issue.item" template to "issue.test", and then
1111 access the test template using the "@template" URL argument::
1113 http://your.tracker.example/tracker/issue?@template=test
1115 and it won't affect your users using the "issue.item" template.
1118 How the templates work
1119 ----------------------
1122 Basic Templating Actions
1123 ~~~~~~~~~~~~~~~~~~~~~~~~
1125 Roundup's templates consist of special attributes on the HTML tags.
1126 These attributes form the Template Attribute Language, or TAL. The basic
1127 TAL commands are:
1129 **tal:define="variable expression; variable expression; ..."**
1130 Define a new variable that is local to this tag and its contents. For
1131 example::
1133 <html tal:define="title request/description">
1134 <head><title tal:content="title"></title></head>
1135 </html>
1137 In this example, the variable "title" is defined as the result of the
1138 expression "request/description". The "tal:content" command inside the
1139 <html> tag may then use the "title" variable.
1141 **tal:condition="expression"**
1142 Only keep this tag and its contents if the expression is true. For
1143 example::
1145 <p tal:condition="python:request.user.hasPermission('View', 'issue')">
1146 Display some issue information.
1147 </p>
1149 In the example, the <p> tag and its contents are only displayed if
1150 the user has the "View" permission for issues. We consider the number
1151 zero, a blank string, an empty list, and the built-in variable
1152 nothing to be false values. Nearly every other value is true,
1153 including non-zero numbers, and strings with anything in them (even
1154 spaces!).
1156 **tal:repeat="variable expression"**
1157 Repeat this tag and its contents for each element of the sequence
1158 that the expression returns, defining a new local variable and a
1159 special "repeat" variable for each element. For example::
1161 <tr tal:repeat="u user/list">
1162 <td tal:content="u/id"></td>
1163 <td tal:content="u/username"></td>
1164 <td tal:content="u/realname"></td>
1165 </tr>
1167 The example would iterate over the sequence of users returned by
1168 "user/list" and define the local variable "u" for each entry.
1170 **tal:replace="expression"**
1171 Replace this tag with the result of the expression. For example::
1173 <span tal:replace="request/user/realname" />
1175 The example would replace the <span> tag and its contents with the
1176 user's realname. If the user's realname was "Bruce", then the
1177 resultant output would be "Bruce".
1179 **tal:content="expression"**
1180 Replace the contents of this tag with the result of the expression.
1181 For example::
1183 <span tal:content="request/user/realname">user's name appears here
1184 </span>
1186 The example would replace the contents of the <span> tag with the
1187 user's realname. If the user's realname was "Bruce" then the
1188 resultant output would be "<span>Bruce</span>".
1190 **tal:attributes="attribute expression; attribute expression; ..."**
1191 Set attributes on this tag to the results of expressions. For
1192 example::
1194 <a tal:attributes="href string:user${request/user/id}">My Details</a>
1196 In the example, the "href" attribute of the <a> tag is set to the
1197 value of the "string:user${request/user/id}" expression, which will
1198 be something like "user123".
1200 **tal:omit-tag="expression"**
1201 Remove this tag (but not its contents) if the expression is true. For
1202 example::
1204 <span tal:omit-tag="python:1">Hello, world!</span>
1206 would result in output of::
1208 Hello, world!
1210 Note that the commands on a given tag are evaulated in the order above,
1211 so *define* comes before *condition*, and so on.
1213 Additionally, you may include tags such as <tal:block>, which are
1214 removed from output. Its content is kept, but the tag itself is not (so
1215 don't go using any "tal:attributes" commands on it). This is useful for
1216 making arbitrary blocks of HTML conditional or repeatable (very handy
1217 for repeating multiple table rows, which would othewise require an
1218 illegal tag placement to effect the repeat).
1221 Templating Expressions
1222 ~~~~~~~~~~~~~~~~~~~~~~
1224 The expressions you may use in the attribute values may be one of the
1225 following forms:
1227 **Path Expressions** - eg. ``item/status/checklist``
1228 These are object attribute / item accesses. Roughly speaking, the
1229 path ``item/status/checklist`` is broken into parts ``item``,
1230 ``status`` and ``checklist``. The ``item`` part is the root of the
1231 expression. We then look for a ``status`` attribute on ``item``, or
1232 failing that, a ``status`` item (as in ``item['status']``). If that
1233 fails, the path expression fails. When we get to the end, the object
1234 we're left with is evaluated to get a string - if it is a method, it
1235 is called; if it is an object, it is stringified. Path expressions
1236 may have an optional ``path:`` prefix, but they are the default
1237 expression type, so it's not necessary.
1239 If an expression evaluates to ``default``, then the expression is
1240 "cancelled" - whatever HTML already exists in the template will
1241 remain (tag content in the case of ``tal:content``, attributes in the
1242 case of ``tal:attributes``).
1244 If an expression evaluates to ``nothing`` then the target of the
1245 expression is removed (tag content in the case of ``tal:content``,
1246 attributes in the case of ``tal:attributes`` and the tag itself in
1247 the case of ``tal:replace``).
1249 If an element in the path may not exist, then you can use the ``|``
1250 operator in the expression to provide an alternative. So, the
1251 expression ``request/form/foo/value | default`` would simply leave
1252 the current HTML in place if the "foo" form variable doesn't exist.
1254 You may use the python function ``path``, as in
1255 ``path("item/status")``, to embed path expressions in Python
1256 expressions.
1258 **String Expressions** - eg. ``string:hello ${user/name}``
1259 These expressions are simple string interpolations - though they can
1260 be just plain strings with no interpolation if you want. The
1261 expression in the ``${ ... }`` is just a path expression as above.
1263 **Python Expressions** - eg. ``python: 1+1``
1264 These expressions give the full power of Python. All the "root level"
1265 variables are available, so ``python:item.status.checklist()`` would
1266 be equivalent to ``item/status/checklist``, assuming that
1267 ``checklist`` is a method.
1269 Modifiers:
1271 **structure** - eg. ``structure python:msg.content.plain(hyperlink=1)``
1272 The result of expressions are normally *escaped* to be safe for HTML
1273 display (all "<", ">" and "&" are turned into special entities). The
1274 ``structure`` expression modifier turns off this escaping - the
1275 result of the expression is now assumed to be HTML, which is passed
1276 to the web browser for rendering.
1278 **not:** - eg. ``not:python:1=1``
1279 This simply inverts the logical true/false value of another
1280 expression.
1283 Template Macros
1284 ~~~~~~~~~~~~~~~
1286 Macros are used in Roundup to save us from repeating the same common
1287 page stuctures over and over. The most common (and probably only) macro
1288 you'll use is the "icing" macro defined in the "page" template.
1290 Macros are generated and used inside your templates using special
1291 attributes similar to the `basic templating actions`_. In this case,
1292 though, the attributes belong to the Macro Expansion Template Attribute
1293 Language, or METAL. The macro commands are:
1295 **metal:define-macro="macro name"**
1296 Define that the tag and its contents are now a macro that may be
1297 inserted into other templates using the *use-macro* command. For
1298 example::
1300 <html metal:define-macro="page">
1301 ...
1302 </html>
1304 defines a macro called "page" using the ``<html>`` tag and its
1305 contents. Once defined, macros are stored on the template they're
1306 defined on in the ``macros`` attribute. You can access them later on
1307 through the ``templates`` variable, eg. the most common
1308 ``templates/page/macros/icing`` to access the "page" macro of the
1309 "page" template.
1311 **metal:use-macro="path expression"**
1312 Use a macro, which is identified by the path expression (see above).
1313 This will replace the current tag with the identified macro contents.
1314 For example::
1316 <tal:block metal:use-macro="templates/page/macros/icing">
1317 ...
1318 </tal:block>
1320 will replace the tag and its contents with the "page" macro of the
1321 "page" template.
1323 **metal:define-slot="slot name"** and **metal:fill-slot="slot name"**
1324 To define *dynamic* parts of the macro, you define "slots" which may
1325 be filled when the macro is used with a *use-macro* command. For
1326 example, the ``templates/page/macros/icing`` macro defines a slot like
1327 so::
1329 <title metal:define-slot="head_title">title goes here</title>
1331 In your *use-macro* command, you may now use a *fill-slot* command
1332 like this::
1334 <title metal:fill-slot="head_title">My Title</title>
1336 where the tag that fills the slot completely replaces the one defined
1337 as the slot in the macro.
1339 Note that you may not mix METAL and TAL commands on the same tag, but
1340 TAL commands may be used freely inside METAL-using tags (so your
1341 *fill-slots* tags may have all manner of TAL inside them).
1344 Information available to templates
1345 ----------------------------------
1347 Note: this is implemented by
1348 ``roundup.cgi.templating.RoundupPageTemplate``
1350 The following variables are available to templates.
1352 **context**
1353 The current context. This is either None, a `hyperdb class wrapper`_
1354 or a `hyperdb item wrapper`_
1355 **request**
1356 Includes information about the current request, including:
1357 - the current index information (``filterspec``, ``filter`` args,
1358 ``properties``, etc) parsed out of the form.
1359 - methods for easy filterspec link generation
1360 - *user*, the current user item as an HTMLItem instance
1361 - *form*
1362 The current CGI form information as a mapping of form argument name
1363 to value
1364 **config**
1365 This variable holds all the values defined in the tracker config.py
1366 file (eg. TRACKER_NAME, etc.)
1367 **db**
1368 The current database, used to access arbitrary database items.
1369 **templates**
1370 Access to all the tracker templates by name. Used mainly in
1371 *use-macro* commands.
1372 **utils**
1373 This variable makes available some utility functions like batching.
1374 **nothing**
1375 This is a special variable - if an expression evaluates to this, then
1376 the tag (in the case of a ``tal:replace``), its contents (in the case
1377 of ``tal:content``) or some attributes (in the case of
1378 ``tal:attributes``) will not appear in the the output. So, for
1379 example::
1381 <span tal:attributes="class nothing">Hello, World!</span>
1383 would result in::
1385 <span>Hello, World!</span>
1387 **default**
1388 Also a special variable - if an expression evaluates to this, then the
1389 existing HTML in the template will not be replaced or removed, it will
1390 remain. So::
1392 <span tal:replace="default">Hello, World!</span>
1394 would result in::
1396 <span>Hello, World!</span>
1399 The context variable
1400 ~~~~~~~~~~~~~~~~~~~~
1402 The *context* variable is one of three things based on the current
1403 context (see `determining web context`_ for how we figure this out):
1405 1. if we're looking at a "home" page, then it's None
1406 2. if we're looking at a specific hyperdb class, it's a
1407 `hyperdb class wrapper`_.
1408 3. if we're looking at a specific hyperdb item, it's a
1409 `hyperdb item wrapper`_.
1411 If the context is not None, we can access the properties of the class or
1412 item. The only real difference between cases 2 and 3 above are:
1414 1. the properties may have a real value behind them, and this will
1415 appear if the property is displayed through ``context/property`` or
1416 ``context/property/field``.
1417 2. the context's "id" property will be a false value in the second case,
1418 but a real, or true value in the third. Thus we can determine whether
1419 we're looking at a real item from the hyperdb by testing
1420 "context/id".
1422 Hyperdb class wrapper
1423 :::::::::::::::::::::
1425 Note: this is implemented by the ``roundup.cgi.templating.HTMLClass``
1426 class.
1428 This wrapper object provides access to a hyperb class. It is used
1429 primarily in both index view and new item views, but it's also usable
1430 anywhere else that you wish to access information about a class, or the
1431 items of a class, when you don't have a specific item of that class in
1432 mind.
1434 We allow access to properties. There will be no "id" property. The value
1435 accessed through the property will be the current value of the same name
1436 from the CGI form.
1438 There are several methods available on these wrapper objects:
1440 =========== =============================================================
1441 Method Description
1442 =========== =============================================================
1443 properties return a `hyperdb property wrapper`_ for all of this class's
1444 properties.
1445 list lists all of the active (not retired) items in the class.
1446 csv return the items of this class as a chunk of CSV text.
1447 propnames lists the names of the properties of this class.
1448 filter lists of items from this class, filtered and sorted by the
1449 current *request* filterspec/filter/sort/group args
1450 classhelp display a link to a javascript popup containing this class'
1451 "help" template.
1452 submit generate a submit button (and action hidden element)
1453 renderWith render this class with the given template.
1454 history returns 'New node - no history' :)
1455 is_edit_ok is the user allowed to Edit the current class?
1456 is_view_ok is the user allowed to View the current class?
1457 =========== =============================================================
1459 Note that if you have a property of the same name as one of the above
1460 methods, you'll need to access it using a python "item access"
1461 expression. For example::
1463 python:context['list']
1465 will access the "list" property, rather than the list method.
1468 Hyperdb item wrapper
1469 ::::::::::::::::::::
1471 Note: this is implemented by the ``roundup.cgi.templating.HTMLItem``
1472 class.
1474 This wrapper object provides access to a hyperb item.
1476 We allow access to properties. There will be no "id" property. The value
1477 accessed through the property will be the current value of the same name
1478 from the CGI form.
1480 There are several methods available on these wrapper objects:
1482 =============== ========================================================
1483 Method Description
1484 =============== ========================================================
1485 submit generate a submit button (and action hidden element)
1486 journal return the journal of the current item (**not
1487 implemented**)
1488 history render the journal of the current item as HTML
1489 renderQueryForm specific to the "query" class - render the search form
1490 for the query
1491 hasPermission specific to the "user" class - determine whether the
1492 user has a Permission
1493 is_edit_ok is the user allowed to Edit the current item?
1494 is_view_ok is the user allowed to View the current item?
1495 =============== ========================================================
1497 Note that if you have a property of the same name as one of the above
1498 methods, you'll need to access it using a python "item access"
1499 expression. For example::
1501 python:context['journal']
1503 will access the "journal" property, rather than the journal method.
1506 Hyperdb property wrapper
1507 ::::::::::::::::::::::::
1509 Note: this is implemented by subclasses of the
1510 ``roundup.cgi.templating.HTMLProperty`` class (``HTMLStringProperty``,
1511 ``HTMLNumberProperty``, and so on).
1513 This wrapper object provides access to a single property of a class. Its
1514 value may be either:
1516 1. if accessed through a `hyperdb item wrapper`_, then it's a value from
1517 the hyperdb
1518 2. if access through a `hyperdb class wrapper`_, then it's a value from
1519 the CGI form
1522 The property wrapper has some useful attributes:
1524 =============== ========================================================
1525 Attribute Description
1526 =============== ========================================================
1527 _name the name of the property
1528 _value the value of the property if any - this is the actual
1529 value retrieved from the hyperdb for this property
1530 =============== ========================================================
1532 There are several methods available on these wrapper objects:
1534 =========== ================================================================
1535 Method Description
1536 =========== ================================================================
1537 plain render a "plain" representation of the property. This method
1538 may take two arguments:
1540 escape
1541 If true, escape the text so it is HTML safe (default: no). The
1542 reason this defaults to off is that text is usually escaped
1543 at a later stage by the TAL commands, unless the "structure"
1544 option is used in the template. The following ``tal:content``
1545 expressions are all equivalent::
1547 "structure python:msg.content.plain(escape=1)"
1548 "python:msg.content.plain()"
1549 "msg/content/plain"
1550 "msg/content"
1552 Usually you'll only want to use the escape option in a
1553 complex expression.
1555 hyperlink
1556 If true, turn URLs, email addresses and hyperdb item
1557 designators in the text into hyperlinks (default: no). Note
1558 that you'll need to use the "structure" TAL option if you
1559 want to use this ``tal:content`` expression::
1561 "structure python:msg.content.plain(hyperlink=1)"
1563 Note also that the text is automatically HTML-escaped before
1564 the hyperlinking transformation.
1565 hyperlinked The same as msg.content.plain(hyperlink=1), but nicer::
1567 "structure msg/content/hyperlinked"
1569 field render an appropriate form edit field for the property - for
1570 most types this is a text entry box, but for Booleans it's a
1571 tri-state yes/no/neither selection.
1572 stext only on String properties - render the value of the property
1573 as StructuredText (requires the StructureText module to be
1574 installed separately)
1575 multiline only on String properties - render a multiline form edit
1576 field for the property
1577 email only on String properties - render the value of the property
1578 as an obscured email address
1579 confirm only on Password properties - render a second form edit field
1580 for the property, used for confirmation that the user typed
1581 the password correctly. Generates a field with name
1582 "name:confirm".
1583 now only on Date properties - return the current date as a new
1584 property
1585 reldate only on Date properties - render the interval between the date
1586 and now
1587 local only on Date properties - return this date as a new property
1588 with some timezone offset
1589 pretty only on Interval properties - render the interval in a pretty
1590 format (eg. "yesterday")
1591 menu only on Link and Multilink properties - render a form select
1592 list for this property
1593 reverse only on Multilink properties - produce a list of the linked
1594 items in reverse order
1595 =========== ================================================================
1598 The request variable
1599 ~~~~~~~~~~~~~~~~~~~~
1601 Note: this is implemented by the ``roundup.cgi.templating.HTMLRequest``
1602 class.
1604 The request variable is packed with information about the current
1605 request.
1607 .. taken from ``roundup.cgi.templating.HTMLRequest`` docstring
1609 =========== ============================================================
1610 Variable Holds
1611 =========== ============================================================
1612 form the CGI form as a cgi.FieldStorage
1613 env the CGI environment variables
1614 base the base URL for this tracker
1615 user a HTMLUser instance for this user
1616 classname the current classname (possibly None)
1617 template the current template (suffix, also possibly None)
1618 form the current CGI form variables in a FieldStorage
1619 =========== ============================================================
1621 **Index page specific variables (indexing arguments)**
1623 =========== ============================================================
1624 Variable Holds
1625 =========== ============================================================
1626 columns dictionary of the columns to display in an index page
1627 show a convenience access to columns - request/show/colname will
1628 be true if the columns should be displayed, false otherwise
1629 sort index sort column (direction, column name)
1630 group index grouping property (direction, column name)
1631 filter properties to filter the index on
1632 filterspec values to filter the index on
1633 search_text text to perform a full-text search on for an index
1634 =========== ============================================================
1636 There are several methods available on the request variable:
1638 =============== ========================================================
1639 Method Description
1640 =============== ========================================================
1641 description render a description of the request - handle for the
1642 page title
1643 indexargs_form render the current index args as form elements
1644 indexargs_url render the current index args as a URL
1645 base_javascript render some javascript that is used by other components
1646 of the templating
1647 batch run the current index args through a filter and return a
1648 list of items (see `hyperdb item wrapper`_, and
1649 `batching`_)
1650 =============== ========================================================
1652 The form variable
1653 :::::::::::::::::
1655 The form variable is a bit special because it's actually a python
1656 FieldStorage object. That means that you have two ways to access its
1657 contents. For example, to look up the CGI form value for the variable
1658 "name", use the path expression::
1660 request/form/name/value
1662 or the python expression::
1664 python:request.form['name'].value
1666 Note the "item" access used in the python case, and also note the
1667 explicit "value" attribute we have to access. That's because the form
1668 variables are stored as MiniFieldStorages. If there's more than one
1669 "name" value in the form, then the above will break since
1670 ``request/form/name`` is actually a *list* of MiniFieldStorages. So it's
1671 best to know beforehand what you're dealing with.
1674 The db variable
1675 ~~~~~~~~~~~~~~~
1677 Note: this is implemented by the ``roundup.cgi.templating.HTMLDatabase``
1678 class.
1680 Allows access to all hyperdb classes as attributes of this variable. If
1681 you want access to the "user" class, for example, you would use::
1683 db/user
1684 python:db.user
1686 Also, the current id of the current user is available as
1687 ``db.getuid()``. This isn't so useful in templates (where you have
1688 ``request/user``), but it can be useful in detectors or interfaces.
1690 The access results in a `hyperdb class wrapper`_.
1693 The templates variable
1694 ~~~~~~~~~~~~~~~~~~~~~~
1696 Note: this is implemented by the ``roundup.cgi.templating.Templates``
1697 class.
1699 This variable doesn't have any useful methods defined. It supports being
1700 used in expressions to access the templates, and consequently the
1701 template macros. You may access the templates using the following path
1702 expression::
1704 templates/name
1706 or the python expression::
1708 templates[name]
1710 where "name" is the name of the template you wish to access. The
1711 template has one useful attribute, namely "macros". To access a specific
1712 macro (called "macro_name"), use the path expression::
1714 templates/name/macros/macro_name
1716 or the python expression::
1718 templates[name].macros[macro_name]
1721 The utils variable
1722 ~~~~~~~~~~~~~~~~~~
1724 Note: this is implemented by the
1725 ``roundup.cgi.templating.TemplatingUtils`` class, but it may be extended
1726 as described below.
1728 =============== ========================================================
1729 Method Description
1730 =============== ========================================================
1731 Batch return a batch object using the supplied list
1732 =============== ========================================================
1734 You may add additional utility methods by writing them in your tracker
1735 ``interfaces.py`` module's ``TemplatingUtils`` class. See `adding a time
1736 log to your issues`_ for an example. The TemplatingUtils class itself
1737 will have a single attribute, ``client``, which may be used to access
1738 the ``client.db`` when you need to perform arbitrary database queries.
1740 Batching
1741 ::::::::
1743 Use Batch to turn a list of items, or item ids of a given class, into a
1744 series of batches. Its usage is::
1746 python:utils.Batch(sequence, size, start, end=0, orphan=0,
1747 overlap=0)
1749 or, to get the current index batch::
1751 request/batch
1753 The parameters are:
1755 ========= ==============================================================
1756 Parameter Usage
1757 ========= ==============================================================
1758 sequence a list of HTMLItems
1759 size how big to make the sequence.
1760 start where to start (0-indexed) in the sequence.
1761 end where to end (0-indexed) in the sequence.
1762 orphan if the next batch would contain less items than this value,
1763 then it is combined with this batch
1764 overlap the number of items shared between adjacent batches
1765 ========= ==============================================================
1767 All of the parameters are assigned as attributes on the batch object. In
1768 addition, it has several more attributes:
1770 =============== ========================================================
1771 Attribute Description
1772 =============== ========================================================
1773 start indicates the start index of the batch. *Note: unlike
1774 the argument, is a 1-based index (I know, lame)*
1775 first indicates the start index of the batch *as a 0-based
1776 index*
1777 length the actual number of elements in the batch
1778 sequence_length the length of the original, unbatched, sequence.
1779 =============== ========================================================
1781 And several methods:
1783 =============== ========================================================
1784 Method Description
1785 =============== ========================================================
1786 previous returns a new Batch with the previous batch settings
1787 next returns a new Batch with the next batch settings
1788 propchanged detect if the named property changed on the current item
1789 when compared to the last item
1790 =============== ========================================================
1792 An example of batching::
1794 <table class="otherinfo">
1795 <tr><th colspan="4" class="header">Existing Keywords</th></tr>
1796 <tr tal:define="keywords db/keyword/list"
1797 tal:repeat="start python:range(0, len(keywords), 4)">
1798 <td tal:define="batch python:utils.Batch(keywords, 4, start)"
1799 tal:repeat="keyword batch" tal:content="keyword/name">
1800 keyword here</td>
1801 </tr>
1802 </table>
1804 ... which will produce a table with four columns containing the items of
1805 the "keyword" class (well, their "name" anyway).
1807 Displaying Properties
1808 ---------------------
1810 Properties appear in the user interface in three contexts: in indices,
1811 in editors, and as search arguments. For each type of property, there
1812 are several display possibilities. For example, in an index view, a
1813 string property may just be printed as a plain string, but in an editor
1814 view, that property may be displayed in an editable field.
1817 Index Views
1818 -----------
1820 This is one of the class context views. It is also the default view for
1821 classes. The template used is "*classname*.index".
1824 Index View Specifiers
1825 ~~~~~~~~~~~~~~~~~~~~~
1827 An index view specifier (URL fragment) looks like this (whitespace has
1828 been added for clarity)::
1830 /issue?status=unread,in-progress,resolved&
1831 topic=security,ui&
1832 :group=+priority&
1833 :sort==activity&
1834 :filters=status,topic&
1835 :columns=title,status,fixer
1837 The index view is determined by two parts of the specifier: the layout
1838 part and the filter part. The layout part consists of the query
1839 parameters that begin with colons, and it determines the way that the
1840 properties of selected items are displayed. The filter part consists of
1841 all the other query parameters, and it determines the criteria by which
1842 items are selected for display. The filter part is interactively
1843 manipulated with the form widgets displayed in the filter section. The
1844 layout part is interactively manipulated by clicking on the column
1845 headings in the table.
1847 The filter part selects the union of the sets of items with values
1848 matching any specified Link properties and the intersection of the sets
1849 of items with values matching any specified Multilink properties.
1851 The example specifies an index of "issue" items. Only items with a
1852 "status" of either "unread" or "in-progress" or "resolved" are
1853 displayed, and only items with "topic" values including both "security"
1854 and "ui" are displayed. The items are grouped by priority, arranged in
1855 ascending order; and within groups, sorted by activity, arranged in
1856 descending order. The filter section shows filters for the "status" and
1857 "topic" properties, and the table includes columns for the "title",
1858 "status", and "fixer" properties.
1860 Searching Views
1861 ---------------
1863 Note: if you add a new column to the ``:columns`` form variable
1864 potentials then you will need to add the column to the appropriate
1865 `index views`_ template so that it is actually displayed.
1867 This is one of the class context views. The template used is typically
1868 "*classname*.search". The form on this page should have "search" as its
1869 ``@action`` variable. The "search" action:
1871 - sets up additional filtering, as well as performing indexed text
1872 searching
1873 - sets the ``:filter`` variable correctly
1874 - saves the query off if ``:query_name`` is set.
1876 The search page should lay out any fields that you wish to allow the
1877 user to search on. If your schema contains a large number of properties,
1878 you should be wary of making all of those properties available for
1879 searching, as this can cause confusion. If the additional properties are
1880 Strings, consider having their value indexed, and then they will be
1881 searchable using the full text indexed search. This is both faster, and
1882 more useful for the end user.
1884 The two special form values on search pages which are handled by the
1885 "search" action are:
1887 :search_text
1888 Text with which to perform a search of the text index. Results from
1889 that search will be used to limit the results of other filters (using
1890 an intersection operation)
1891 :query_name
1892 If supplied, the search parameters (including :search_text) will be
1893 saved off as a the query item and registered against the user's
1894 queries property. Note that the *classic* template schema has this
1895 ability, but the *minimal* template schema does not.
1898 Item Views
1899 ----------
1901 The basic view of a hyperdb item is provided by the "*classname*.item"
1902 template. It generally has three sections; an "editor", a "spool" and a
1903 "history" section.
1906 Editor Section
1907 ~~~~~~~~~~~~~~
1909 The editor section is used to manipulate the item - it may be a static
1910 display if the user doesn't have permission to edit the item.
1912 Here's an example of a basic editor template (this is the default
1913 "classic" template issue item edit form - from the "issue.item.html"
1914 template)::
1916 <table class="form">
1917 <tr>
1918 <th>Title</th>
1919 <td colspan="3" tal:content="structure python:context.title.field(size=60)">title</td>
1920 </tr>
1922 <tr>
1923 <th>Priority</th>
1924 <td tal:content="structure context/priority/menu">priority</td>
1925 <th>Status</th>
1926 <td tal:content="structure context/status/menu">status</td>
1927 </tr>
1929 <tr>
1930 <th>Superseder</th>
1931 <td>
1932 <span tal:replace="structure python:context.superseder.field(showid=1, size=20)" />
1933 <span tal:replace="structure python:db.issue.classhelp('id,title')" />
1934 <span tal:condition="context/superseder">
1935 <br>View: <span tal:replace="structure python:context.superseder.link(showid=1)" />
1936 </span>
1937 </td>
1938 <th>Nosy List</th>
1939 <td>
1940 <span tal:replace="structure context/nosy/field" />
1941 <span tal:replace="structure python:db.user.classhelp('username,realname,address,phone')" />
1942 </td>
1943 </tr>
1945 <tr>
1946 <th>Assigned To</th>
1947 <td tal:content="structure context/assignedto/menu">
1948 assignedto menu
1949 </td>
1950 <td> </td>
1951 <td> </td>
1952 </tr>
1954 <tr>
1955 <th>Change Note</th>
1956 <td colspan="3">
1957 <textarea name=":note" wrap="hard" rows="5" cols="60"></textarea>
1958 </td>
1959 </tr>
1961 <tr>
1962 <th>File</th>
1963 <td colspan="3"><input type="file" name=":file" size="40"></td>
1964 </tr>
1966 <tr>
1967 <td> </td>
1968 <td colspan="3" tal:content="structure context/submit">
1969 submit button will go here
1970 </td>
1971 </tr>
1972 </table>
1975 When a change is submitted, the system automatically generates a message
1976 describing the changed properties. As shown in the example, the editor
1977 template can use the ":note" and ":file" fields, which are added to the
1978 standard changenote message generated by Roundup.
1981 Form values
1982 :::::::::::
1984 We have a number of ways to pull properties out of the form in order to
1985 meet the various needs of:
1987 1. editing the current item (perhaps an issue item)
1988 2. editing information related to the current item (eg. messages or
1989 attached files)
1990 3. creating new information to be linked to the current item (eg. time
1991 spent on an issue)
1993 In the following, ``<bracketed>`` values are variable, ":" may be one of
1994 ":" or "@", and other text ("required") is fixed.
1996 Properties are specified as form variables:
1998 ``<propname>``
1999 property on the current context item
2001 ``<designator>:<propname>``
2002 property on the indicated item (for editing related information)
2004 ``<classname>-<N>:<propname>``
2005 property on the Nth new item of classname (generally for creating new
2006 items to attach to the current item)
2008 Once we have determined the "propname", we check to see if it is one of
2009 the special form values:
2011 ``@required``
2012 The named property values must be supplied or a ValueError will be
2013 raised.
2015 ``@remove@<propname>=id(s)``
2016 The ids will be removed from the multilink property.
2018 ``:add:<propname>=id(s)``
2019 The ids will be added to the multilink property.
2021 ``:link:<propname>=<designator>``
2022 Used to add a link to new items created during edit. These are
2023 collected and returned in ``all_links``. This will result in an
2024 additional linking operation (either Link set or Multilink append)
2025 after the edit/create is done using ``all_props`` in ``_editnodes``.
2026 The <propname> on the current item will be set/appended the id of the
2027 newly created item of class <designator> (where <designator> must be
2028 <classname>-<N>).
2030 Any of the form variables may be prefixed with a classname or
2031 designator.
2033 Two special form values are supported for backwards compatibility:
2035 ``:note``
2036 create a message (with content, author and date), linked to the
2037 context item. This is ALWAYS designated "msg-1".
2038 ``:file``
2039 create a file, attached to the current item and any message created by
2040 :note. This is ALWAYS designated "file-1".
2043 Spool Section
2044 ~~~~~~~~~~~~~
2046 The spool section lists related information like the messages and files
2047 of an issue.
2049 TODO
2052 History Section
2053 ~~~~~~~~~~~~~~~
2055 The final section displayed is the history of the item - its database
2056 journal. This is generally generated with the template::
2058 <tal:block tal:replace="structure context/history" />
2060 *To be done:*
2062 *The actual history entries of the item may be accessed for manual
2063 templating through the "journal" method of the item*::
2065 <tal:block tal:repeat="entry context/journal">
2066 a journal entry
2067 </tal:block>
2069 *where each journal entry is an HTMLJournalEntry.*
2071 Defining new web actions
2072 ------------------------
2074 You may define new actions to be triggered by the ``@action`` form
2075 variable. These are added to the tracker ``interfaces.py`` as methods on
2076 the ``Client`` class.
2078 Adding action methods takes three steps; first you `define the new
2079 action method`_, then you `register the action method`_ with the cgi
2080 interface so it may be triggered by the ``@action`` form variable.
2081 Finally you `use the new action`_ in your HTML form.
2083 See "`setting up a "wizard" (or "druid") for controlled adding of
2084 issues`_" for an example.
2087 Define the new action method
2088 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2090 The action methods have the following interface::
2092 def myActionMethod(self):
2093 ''' Perform some action. No return value is required.
2094 '''
2096 The *self* argument is an instance of your tracker ``instance.Client``
2097 class - thus it's mostly implemented by ``roundup.cgi.Client``. See the
2098 docstring of that class for details of what it can do.
2100 The method will typically check the ``self.form`` variable's contents.
2101 It may then:
2103 - add information to ``self.ok_message`` or ``self.error_message``
2104 - change the ``self.template`` variable to alter what the user will see
2105 next
2106 - raise Unauthorised, SendStaticFile, SendFile, NotFound or Redirect
2107 exceptions
2110 Register the action method
2111 ~~~~~~~~~~~~~~~~~~~~~~~~~~
2113 The method is now written, but isn't available to the user until you add
2114 it to the `instance.Client`` class ``actions`` variable, like so::
2116 actions = client.Class.actions + (
2117 ('myaction', 'myActionMethod'),
2118 )
2120 This maps the action name "myaction" to the action method we defined.
2123 Use the new action
2124 ~~~~~~~~~~~~~~~~~~
2126 In your HTML form, add a hidden form element like so::
2128 <input type="hidden" name="@action" value="myaction">
2130 where "myaction" is the name you registered in the previous step.
2133 Examples
2134 ========
2136 .. contents::
2137 :local:
2138 :depth: 1
2141 Adding a new field to the classic schema
2142 ----------------------------------------
2144 This example shows how to add a new constrained property (i.e. a
2145 selection of distinct values) to your tracker.
2148 Introduction
2149 ~~~~~~~~~~~~
2151 To make the classic schema of roundup useful as a TODO tracking system
2152 for a group of systems administrators, it needed an extra data field per
2153 issue: a category.
2155 This would let sysadmins quickly list all TODOs in their particular area
2156 of interest without having to do complex queries, and without relying on
2157 the spelling capabilities of other sysadmins (a losing proposition at
2158 best).
2161 Adding a field to the database
2162 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2164 This is the easiest part of the change. The category would just be a
2165 plain string, nothing fancy. To change what is in the database you need
2166 to add some lines to the ``open()`` function in ``dbinit.py``. Under the
2167 comment::
2169 # add any additional database schema configuration here
2171 add::
2173 category = Class(db, "category", name=String())
2174 category.setkey("name")
2176 Here we are setting up a chunk of the database which we are calling
2177 "category". It contains a string, which we are refering to as "name" for
2178 lack of a more imaginative title. (Since "name" is one of the properties
2179 that Roundup looks for on items if you do not set a key for them, it's
2180 probably a good idea to stick with it for new classes if at all
2181 appropriate.) Then we are setting the key of this chunk of the database
2182 to be that "name". This is equivalent to an index for database types.
2183 This also means that there can only be one category with a given name.
2185 Adding the above lines allows us to create categories, but they're not
2186 tied to the issues that we are going to be creating. It's just a list of
2187 categories off on its own, which isn't much use. We need to link it in
2188 with the issues. To do that, find the lines in the ``open()`` function
2189 in ``dbinit.py`` which set up the "issue" class, and then add a link to
2190 the category::
2192 issue = IssueClass(db, "issue", ... ,
2193 category=Multilink("category"), ... )
2195 The ``Multilink()`` means that each issue can have many categories. If
2196 you were adding something with a one-to-one relationship to issues (such
2197 as the "assignedto" property), use ``Link()`` instead.
2199 That is all you need to do to change the schema. The rest of the effort
2200 is fiddling around so you can actually use the new category.
2203 Populating the new category class
2204 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2206 If you haven't initialised the database with the roundup-admin
2207 "initialise" command, then you can add the following to the tracker
2208 ``dbinit.py`` in the ``init()`` function under the comment::
2210 # add any additional database create steps here - but only if you
2211 # haven't initialised the database with the admin "initialise" command
2213 Add::
2215 category = db.getclass('category')
2216 category.create(name="scipy", order="1")
2217 category.create(name="chaco", order="2")
2218 category.create(name="weave", order="3")
2220 If the database has already been initalised, then you need to use the
2221 ``roundup-admin`` tool::
2223 % roundup-admin -i <tracker home>
2224 Roundup <version> ready for input.
2225 Type "help" for help.
2226 roundup> create category name=scipy order=1
2227 1
2228 roundup> create category name=chaco order=1
2229 2
2230 roundup> create category name=weave order=1
2231 3
2232 roundup> exit...
2233 There are unsaved changes. Commit them (y/N)? y
2235 TODO: explain why order=1 in each case. Also, does key get set to "name"
2236 automatically when added via roundup-admin?
2239 Setting up security on the new objects
2240 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2242 By default only the admin user can look at and change objects. This
2243 doesn't suit us, as we want any user to be able to create new categories
2244 as required, and obviously everyone needs to be able to view the
2245 categories of issues for it to be useful.
2247 We therefore need to change the security of the category objects. This
2248 is also done in the ``open()`` function of ``dbinit.py``.
2250 There are currently two loops which set up permissions and then assign
2251 them to various roles. Simply add the new "category" to both lists::
2253 # new permissions for this schema
2254 for cl in 'issue', 'file', 'msg', 'user', 'category':
2255 db.security.addPermission(name="Edit", klass=cl,
2256 description="User is allowed to edit "+cl)
2257 db.security.addPermission(name="View", klass=cl,
2258 description="User is allowed to access "+cl)
2260 # Assign the access and edit permissions for issue, file and message
2261 # to regular users now
2262 for cl in 'issue', 'file', 'msg', 'category':
2263 p = db.security.getPermission('View', cl)
2264 db.security.addPermissionToRole('User', p)
2265 p = db.security.getPermission('Edit', cl)
2266 db.security.addPermissionToRole('User', p)
2268 So you are in effect doing the following (with 'cl' substituted by its
2269 value)::
2271 db.security.addPermission(name="Edit", klass='category',
2272 description="User is allowed to edit "+'category')
2273 db.security.addPermission(name="View", klass='category',
2274 description="User is allowed to access "+'category')
2276 which is creating two permission types; that of editing and viewing
2277 "category" objects respectively. Then the following lines assign those
2278 new permissions to the "User" role, so that normal users can view and
2279 edit "category" objects::
2281 p = db.security.getPermission('View', 'category')
2282 db.security.addPermissionToRole('User', p)
2284 p = db.security.getPermission('Edit', 'category')
2285 db.security.addPermissionToRole('User', p)
2287 This is all the work that needs to be done for the database. It will
2288 store categories, and let users view and edit them. Now on to the
2289 interface stuff.
2292 Changing the web left hand frame
2293 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2295 We need to give the users the ability to create new categories, and the
2296 place to put the link to this functionality is in the left hand function
2297 bar, under the "Issues" area. The file that defines how this area looks
2298 is ``html/page``, which is what we are going to be editing next.
2300 If you look at this file you can see that it contains a lot of
2301 "classblock" sections which are chunks of HTML that will be included or
2302 excluded in the output depending on whether the condition in the
2303 classblock is met. Under the end of the classblock for issue is where we
2304 are going to add the category code::
2306 <p class="classblock"
2307 tal:condition="python:request.user.hasPermission('View', 'category')">
2308 <b>Categories</b><br>
2309 <a tal:condition="python:request.user.hasPermission('Edit', 'category')"
2310 href="category?@template=item">New Category<br></a>
2311 </p>
2313 The first two lines is the classblock definition, which sets up a
2314 condition that only users who have "View" permission for the "category"
2315 object will have this section included in their output. Next comes a
2316 plain "Categories" header in bold. Everyone who can view categories will
2317 get that.
2319 Next comes the link to the editing area of categories. This link will
2320 only appear if the condition - that the user has "Edit" permissions for
2321 the "category" objects - is matched. If they do have permission then
2322 they will get a link to another page which will let the user add new
2323 categories.
2325 Note that if you have permission to *view* but not to *edit* categories,
2326 then all you will see is a "Categories" header with nothing underneath
2327 it. This is obviously not very good interface design, but will do for
2328 now. I just claim that it is so I can add more links in this section
2329 later on. However to fix the problem you could change the condition in
2330 the classblock statement, so that only users with "Edit" permission
2331 would see the "Categories" stuff.
2334 Setting up a page to edit categories
2335 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2337 We defined code in the previous section which let users with the
2338 appropriate permissions see a link to a page which would let them edit
2339 conditions. Now we have to write that page.
2341 The link was for the *item* template of the *category* object. This
2342 translates into Roundup looking for a file called ``category.item.html``
2343 in the ``html`` tracker directory. This is the file that we are going to
2344 write now.
2346 First we add an info tag in a comment which doesn't affect the outcome
2347 of the code at all, but is useful for debugging. If you load a page in a
2348 browser and look at the page source, you can see which sections come
2349 from which files by looking for these comments::
2351 <!-- category.item -->
2353 Next we need to add in the METAL macro stuff so we get the normal page
2354 trappings::
2356 <tal:block metal:use-macro="templates/page/macros/icing">
2357 <title metal:fill-slot="head_title">Category editing</title>
2358 <td class="page-header-top" metal:fill-slot="body_title">
2359 <h2>Category editing</h2>
2360 </td>
2361 <td class="content" metal:fill-slot="content">
2363 Next we need to setup up a standard HTML form, which is the whole
2364 purpose of this file. We link to some handy javascript which sends the
2365 form through only once. This is to stop users hitting the send button
2366 multiple times when they are impatient and thus having the form sent
2367 multiple times::
2369 <form method="POST" onSubmit="return submit_once()"
2370 enctype="multipart/form-data">
2372 Next we define some code which sets up the minimum list of fields that
2373 we require the user to enter. There will be only one field - "name" - so
2374 they better put something in it, otherwise the whole form is pointless::
2376 <input type="hidden" name="@required" value="name">
2378 To get everything to line up properly we will put everything in a table,
2379 and put a nice big header on it so the user has an idea what is
2380 happening::
2382 <table class="form">
2383 <tr><th class="header" colspan="2">Category</th></tr>
2385 Next, we need the field into which the user is going to enter the new
2386 category. The "context.name.field(size=60)" bit tells Roundup to
2387 generate a normal HTML field of size 60, and the contents of that field
2388 will be the "name" variable of the current context (which is
2389 "category"). The upshot of this is that when the user types something in
2390 to the form, a new category will be created with that name::
2392 <tr>
2393 <th>Name</th>
2394 <td tal:content="structure python:context.name.field(size=60)">
2395 name</td>
2396 </tr>
2398 Then a submit button so that the user can submit the new category::
2400 <tr>
2401 <td> </td>
2402 <td colspan="3" tal:content="structure context/submit">
2403 submit button will go here
2404 </td>
2405 </tr>
2407 Finally we finish off the tags we used at the start to do the METAL
2408 stuff::
2410 </td>
2411 </tal:block>
2413 So putting it all together, and closing the table and form we get::
2415 <!-- category.item -->
2416 <tal:block metal:use-macro="templates/page/macros/icing">
2417 <title metal:fill-slot="head_title">Category editing</title>
2418 <td class="page-header-top" metal:fill-slot="body_title">
2419 <h2>Category editing</h2>
2420 </td>
2421 <td class="content" metal:fill-slot="content">
2422 <form method="POST" onSubmit="return submit_once()"
2423 enctype="multipart/form-data">
2425 <table class="form">
2426 <tr><th class="header" colspan="2">Category</th></tr>
2428 <tr>
2429 <th>Name</th>
2430 <td tal:content="structure python:context.name.field(size=60)">
2431 name</td>
2432 </tr>
2434 <tr>
2435 <td>
2436
2437 <input type="hidden" name="@required" value="name">
2438 </td>
2439 <td colspan="3" tal:content="structure context/submit">
2440 submit button will go here
2441 </td>
2442 </tr>
2443 </table>
2444 </form>
2445 </td>
2446 </tal:block>
2448 This is quite a lot to just ask the user one simple question, but there
2449 is a lot of setup for basically one line (the form line) to do its work.
2450 To add another field to "category" would involve one more line (well,
2451 maybe a few extra to get the formatting correct).
2454 Adding the category to the issue
2455 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2457 We now have the ability to create issues to our heart's content, but
2458 that is pointless unless we can assign categories to issues. Just like
2459 the ``html/category.item.html`` file was used to define how to add a new
2460 category, the ``html/issue.item.html`` is used to define how a new issue
2461 is created.
2463 Just like ``category.issue.html`` this file defines a form which has a
2464 table to lay things out. It doesn't matter where in the table we add new
2465 stuff, it is entirely up to your sense of aesthetics::
2467 <th>Category</th>
2468 <td><span tal:replace="structure context/category/field" />
2469 <span tal:replace="structure db/category/classhelp" />
2470 </td>
2472 First, we define a nice header so that the user knows what the next
2473 section is, then the middle line does what we are most interested in.
2474 This ``context/category/field`` gets replaced by a field which contains
2475 the category in the current context (the current context being the new
2476 issue).
2478 The classhelp lines generate a link (labelled "list") to a popup window
2479 which contains the list of currently known categories.
2482 Searching on categories
2483 ~~~~~~~~~~~~~~~~~~~~~~~
2485 We can add categories, and create issues with categories. The next
2486 obvious thing that we would like to be able to do, would be to search
2487 for issues based on their category, so that, for example, anyone working
2488 on the web server could look at all issues in the category "Web".
2490 If you look for "Search Issues" in the 'html/page.html' file, you will
2491 find that it looks something like
2492 ``<a href="issue?@template=search">Search Issues</a>``. This shows us
2493 that when you click on "Search Issues" it will be looking for a
2494 ``issue.search.html`` file to display. So that is the file that we will
2495 change.
2497 If you look at this file it should be starting to seem familiar, although it
2498 does use some new macros. You can add the new category search code anywhere you
2499 like within that form::
2501 <tr tal:define="name string:category;
2502 db_klass string:category;
2503 db_content string:name;">
2504 <th>Priority:</th>
2505 <td metal:use-macro="search_select"></td>
2506 <td metal:use-macro="column_input"></td>
2507 <td metal:use-macro="sort_input"></td>
2508 <td metal:use-macro="group_input"></td>
2509 </tr>
2511 The definitions in the <tr> opening tag are used by the macros:
2513 - search_select expands to a drop-down box with all categories using db_klass
2514 and db_content.
2515 - column_input expands to a checkbox for selecting what columns should be
2516 displayed.
2517 - sort_input expands to a radio button for selecting what property should be
2518 sorted on.
2519 - group_input expands to a radio button for selecting what property should be
2520 group on.
2522 The category search code above would expand to the following::
2524 <tr>
2525 <th>Category:</th>
2526 <td>
2527 <select name="category">
2528 <option value="">don't care</option>
2529 <option value="">------------</option>
2530 <option value="1">scipy</option>
2531 <option value="2">chaco</option>
2532 <option value="3">weave</option>
2533 </select>
2534 </td>
2535 <td><input type="checkbox" name=":columns" value="category"></td>
2536 <td><input type="radio" name=":sort" value="category"></td>
2537 <td><input type="radio" name=":group" value="category"></td>
2538 </tr>
2540 Adding category to the default view
2541 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2543 We can now add categories, add issues with categories, and search for
2544 issues based on categories. This is everything that we need to do;
2545 however, there is some more icing that we would like. I think the
2546 category of an issue is important enough that it should be displayed by
2547 default when listing all the issues.
2549 Unfortunately, this is a bit less obvious than the previous steps. The
2550 code defining how the issues look is in ``html/issue.index.html``. This
2551 is a large table with a form down at the bottom for redisplaying and so
2552 forth.
2554 Firstly we need to add an appropriate header to the start of the table::
2556 <th tal:condition="request/show/category">Category</th>
2558 The *condition* part of this statement is to avoid displaying the
2559 Category column if the user has selected not to see it.
2561 The rest of the table is a loop which will go through every issue that
2562 matches the display criteria. The loop variable is "i" - which means
2563 that every issue gets assigned to "i" in turn.
2565 The new part of code to display the category will look like this::
2567 <td tal:condition="request/show/category"
2568 tal:content="i/category"></td>
2570 The condition is the same as above: only display the condition when the
2571 user hasn't asked for it to be hidden. The next part is to set the
2572 content of the cell to be the category part of "i" - the current issue.
2574 Finally we have to edit ``html/page.html`` again. This time, we need to
2575 tell it that when the user clicks on "Unasigned Issues" or "All Issues",
2576 the category column should be included in the resulting list. If you
2577 scroll down the page file, you can see the links with lots of options.
2578 The option that we are interested in is the ``:columns=`` one which
2579 tells roundup which fields of the issue to display. Simply add
2580 "category" to that list and it all should work.
2583 Adding in state transition control
2584 ----------------------------------
2586 Sometimes tracker admins want to control the states that users may move
2587 issues to. You can do this by following these steps:
2589 1. make "status" a required variable. This is achieved by adding the
2590 following to the top of the form in the ``issue.item.html``
2591 template::
2593 <input type="hidden" name="@required" value="status">
2595 this will force users to select a status.
2597 2. add a Multilink property to the status class::
2599 stat = Class(db, "status", ... , transitions=Multilink('status'),
2600 ...)
2602 and then edit the statuses already created, either:
2604 a. through the web using the class list -> status class editor, or
2605 b. using the roundup-admin "set" command.
2607 3. add an auditor module ``checktransition.py`` in your tracker's
2608 ``detectors`` directory, for example::
2610 def checktransition(db, cl, nodeid, newvalues):
2611 ''' Check that the desired transition is valid for the "status"
2612 property.
2613 '''
2614 if not newvalues.has_key('status'):
2615 return
2616 current = cl.get(nodeid, 'status')
2617 new = newvalues['status']
2618 if new == current:
2619 return
2620 ok = db.status.get(current, 'transitions')
2621 if new not in ok:
2622 raise ValueError, 'Status not allowed to move from "%s" to "%s"'%(
2623 db.status.get(current, 'name'), db.status.get(new, 'name'))
2625 def init(db):
2626 db.issue.audit('set', checktransition)
2628 4. in the ``issue.item.html`` template, change the status editing bit
2629 from::
2631 <th>Status</th>
2632 <td tal:content="structure context/status/menu">status</td>
2634 to::
2636 <th>Status</th>
2637 <td>
2638 <select tal:condition="context/id" name="status">
2639 <tal:block tal:define="ok context/status/transitions"
2640 tal:repeat="state db/status/list">
2641 <option tal:condition="python:state.id in ok"
2642 tal:attributes="
2643 value state/id;
2644 selected python:state.id == context.status.id"
2645 tal:content="state/name"></option>
2646 </tal:block>
2647 </select>
2648 <tal:block tal:condition="not:context/id"
2649 tal:replace="structure context/status/menu" />
2650 </td>
2652 which displays only the allowed status to transition to.
2655 Displaying only message summaries in the issue display
2656 ------------------------------------------------------
2658 Alter the issue.item template section for messages to::
2660 <table class="messages" tal:condition="context/messages">
2661 <tr><th colspan="5" class="header">Messages</th></tr>
2662 <tr tal:repeat="msg context/messages">
2663 <td><a tal:attributes="href string:msg${msg/id}"
2664 tal:content="string:msg${msg/id}"></a></td>
2665 <td tal:content="msg/author">author</td>
2666 <td class="date" tal:content="msg/date/pretty">date</td>
2667 <td tal:content="msg/summary">summary</td>
2668 <td>
2669 <a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">
2670 remove</a>
2671 </td>
2672 </tr>
2673 </table>
2675 Restricting the list of users that are assignable to a task
2676 -----------------------------------------------------------
2678 1. In your tracker's "dbinit.py", create a new Role, say "Developer"::
2680 db.security.addRole(name='Developer', description='A developer')
2682 2. Just after that, create a new Permission, say "Fixer", specific to
2683 "issue"::
2685 p = db.security.addPermission(name='Fixer', klass='issue',
2686 description='User is allowed to be assigned to fix issues')
2688 3. Then assign the new Permission to your "Developer" Role::
2690 db.security.addPermissionToRole('Developer', p)
2692 4. In the issue item edit page ("html/issue.item.html" in your tracker
2693 directory), use the new Permission in restricting the "assignedto"
2694 list::
2696 <select name="assignedto">
2697 <option value="-1">- no selection -</option>
2698 <tal:block tal:repeat="user db/user/list">
2699 <option tal:condition="python:user.hasPermission(
2700 'Fixer', context._classname)"
2701 tal:attributes="
2702 value user/id;
2703 selected python:user.id == context.assignedto"
2704 tal:content="user/realname"></option>
2705 </tal:block>
2706 </select>
2708 For extra security, you may wish to setup an auditor to enforce the
2709 Permission requirement (install this as "assignedtoFixer.py" in your
2710 tracker "detectors" directory)::
2712 def assignedtoMustBeFixer(db, cl, nodeid, newvalues):
2713 ''' Ensure the assignedto value in newvalues is a used with the
2714 Fixer Permission
2715 '''
2716 if not newvalues.has_key('assignedto'):
2717 # don't care
2718 return
2720 # get the userid
2721 userid = newvalues['assignedto']
2722 if not db.security.hasPermission('Fixer', userid, cl.classname):
2723 raise ValueError, 'You do not have permission to edit %s'%cl.classname
2725 def init(db):
2726 db.issue.audit('set', assignedtoMustBeFixer)
2727 db.issue.audit('create', assignedtoMustBeFixer)
2729 So now, if an edit action attempts to set "assignedto" to a user that
2730 doesn't have the "Fixer" Permission, the error will be raised.
2733 Setting up a "wizard" (or "druid") for controlled adding of issues
2734 ------------------------------------------------------------------
2736 1. Set up the page templates you wish to use for data input. My wizard
2737 is going to be a two-step process: first figuring out what category
2738 of issue the user is submitting, and then getting details specific to
2739 that category. The first page includes a table of help, explaining
2740 what the category names mean, and then the core of the form::
2742 <form method="POST" onSubmit="return submit_once()"
2743 enctype="multipart/form-data">
2744 <input type="hidden" name="@template" value="add_page1">
2745 <input type="hidden" name="@action" value="page1submit">
2747 <strong>Category:</strong>
2748 <tal:block tal:replace="structure context/category/menu" />
2749 <input type="submit" value="Continue">
2750 </form>
2752 The next page has the usual issue entry information, with the
2753 addition of the following form fragments::
2755 <form method="POST" onSubmit="return submit_once()"
2756 enctype="multipart/form-data"
2757 tal:condition="context/is_edit_ok"
2758 tal:define="cat request/form/category/value">
2760 <input type="hidden" name="@template" value="add_page2">
2761 <input type="hidden" name="@required" value="title">
2762 <input type="hidden" name="category" tal:attributes="value cat">
2763 .
2764 .
2765 .
2766 </form>
2768 Note that later in the form, I test the value of "cat" include form
2769 elements that are appropriate. For example::
2771 <tal:block tal:condition="python:cat in '6 10 13 14 15 16 17'.split()">
2772 <tr>
2773 <th>Operating System</th>
2774 <td tal:content="structure context/os/field"></td>
2775 </tr>
2776 <tr>
2777 <th>Web Browser</th>
2778 <td tal:content="structure context/browser/field"></td>
2779 </tr>
2780 </tal:block>
2782 ... the above section will only be displayed if the category is one
2783 of 6, 10, 13, 14, 15, 16 or 17.
2785 3. Determine what actions need to be taken between the pages - these are
2786 usually to validate user choices and determine what page is next. Now
2787 encode those actions in methods on the ``interfaces.Client`` class
2788 and insert hooks to those actions in the "actions" attribute on that
2789 class, like so::
2791 actions = client.Client.actions + (
2792 ('page1_submit', 'page1SubmitAction'),
2793 )
2795 def page1SubmitAction(self):
2796 ''' Verify that the user has selected a category, and then move
2797 on to page 2.
2798 '''
2799 category = self.form['category'].value
2800 if category == '-1':
2801 self.error_message.append('You must select a category of report')
2802 return
2803 # everything's ok, move on to the next page
2804 self.template = 'add_page2'
2806 4. Use the usual "new" action as the ``@action`` on the final page, and
2807 you're done (the standard context/submit method can do this for you).
2810 Using an external password validation source
2811 --------------------------------------------
2813 We have a centrally-managed password changing system for our users. This
2814 results in a UN*X passwd-style file that we use for verification of
2815 users. Entries in the file consist of ``name:password`` where the
2816 password is encrypted using the standard UN*X ``crypt()`` function (see
2817 the ``crypt`` module in your Python distribution). An example entry
2818 would be::
2820 admin:aamrgyQfDFSHw
2822 Each user of Roundup must still have their information stored in the
2823 Roundup database - we just use the passwd file to check their password.
2824 To do this, we add the following code to our ``Client`` class in the
2825 tracker home ``interfaces.py`` module::
2827 def verifyPassword(self, userid, password):
2828 # get the user's username
2829 username = self.db.user.get(userid, 'username')
2831 # the passwords are stored in the "passwd.txt" file in the
2832 # tracker home
2833 file = os.path.join(self.db.config.TRACKER_HOME, 'passwd.txt')
2835 # see if we can find a match
2836 for ent in [line.strip().split(':') for line in
2837 open(file).readlines()]:
2838 if ent[0] == username:
2839 return crypt.crypt(password, ent[1][:2]) == ent[1]
2841 # user doesn't exist in the file
2842 return 0
2844 What this does is look through the file, line by line, looking for a
2845 name that matches.
2847 We also remove the redundant password fields from the ``user.item``
2848 template.
2851 Adding a "vacation" flag to users for stopping nosy messages
2852 ------------------------------------------------------------
2854 When users go on vacation and set up vacation email bouncing, you'll
2855 start to see a lot of messages come back through Roundup "Fred is on
2856 vacation". Not very useful, and relatively easy to stop.
2858 1. add a "vacation" flag to your users::
2860 user = Class(db, "user",
2861 username=String(), password=Password(),
2862 address=String(), realname=String(),
2863 phone=String(), organisation=String(),
2864 alternate_addresses=String(),
2865 roles=String(), queries=Multilink("query"),
2866 vacation=Boolean())
2868 2. So that users may edit the vacation flags, add something like the
2869 following to your ``user.item`` template::
2871 <tr>
2872 <th>On Vacation</th>
2873 <td tal:content="structure context/vacation/field">vacation</td>
2874 </tr>
2876 3. edit your detector ``nosyreactor.py`` so that the ``nosyreaction()``
2877 consists of::
2879 def nosyreaction(db, cl, nodeid, oldvalues):
2880 # send a copy of all new messages to the nosy list
2881 for msgid in determineNewMessages(cl, nodeid, oldvalues):
2882 try:
2883 users = db.user
2884 messages = db.msg
2886 # figure the recipient ids
2887 sendto = []
2888 r = {}
2889 recipients = messages.get(msgid, 'recipients')
2890 for recipid in messages.get(msgid, 'recipients'):
2891 r[recipid] = 1
2893 # figure the author's id, and indicate they've received
2894 # the message
2895 authid = messages.get(msgid, 'author')
2897 # possibly send the message to the author, as long as
2898 # they aren't anonymous
2899 if (db.config.MESSAGES_TO_AUTHOR == 'yes' and
2900 users.get(authid, 'username') != 'anonymous'):
2901 sendto.append(authid)
2902 r[authid] = 1
2904 # now figure the nosy people who weren't recipients
2905 nosy = cl.get(nodeid, 'nosy')
2906 for nosyid in nosy:
2907 # Don't send nosy mail to the anonymous user (that
2908 # user shouldn't appear in the nosy list, but just
2909 # in case they do...)
2910 if users.get(nosyid, 'username') == 'anonymous':
2911 continue
2912 # make sure they haven't seen the message already
2913 if not r.has_key(nosyid):
2914 # send it to them
2915 sendto.append(nosyid)
2916 recipients.append(nosyid)
2918 # generate a change note
2919 if oldvalues:
2920 note = cl.generateChangeNote(nodeid, oldvalues)
2921 else:
2922 note = cl.generateCreateNote(nodeid)
2924 # we have new recipients
2925 if sendto:
2926 # filter out the people on vacation
2927 sendto = [i for i in sendto
2928 if not users.get(i, 'vacation', 0)]
2930 # map userids to addresses
2931 sendto = [users.get(i, 'address') for i in sendto]
2933 # update the message's recipients list
2934 messages.set(msgid, recipients=recipients)
2936 # send the message
2937 cl.send_message(nodeid, msgid, note, sendto)
2938 except roundupdb.MessageSendError, message:
2939 raise roundupdb.DetectorError, message
2941 Note that this is the standard nosy reaction code, with the small
2942 addition of::
2944 # filter out the people on vacation
2945 sendto = [i for i in sendto if not users.get(i, 'vacation', 0)]
2947 which filters out the users that have the vacation flag set to true.
2950 Adding a time log to your issues
2951 --------------------------------
2953 We want to log the dates and amount of time spent working on issues, and
2954 be able to give a summary of the total time spent on a particular issue.
2956 1. Add a new class to your tracker ``dbinit.py``::
2958 # storage for time logging
2959 timelog = Class(db, "timelog", period=Interval())
2961 Note that we automatically get the date of the time log entry
2962 creation through the standard property "creation".
2964 2. Link to the new class from your issue class (again, in
2965 ``dbinit.py``)::
2967 issue = IssueClass(db, "issue",
2968 assignedto=Link("user"), topic=Multilink("keyword"),
2969 priority=Link("priority"), status=Link("status"),
2970 times=Multilink("timelog"))
2972 the "times" property is the new link to the "timelog" class.
2974 3. We'll need to let people add in times to the issue, so in the web
2975 interface we'll have a new entry field. This is a special field
2976 because unlike the other fields in the issue.item template, it
2977 affects a different item (a timelog item) and not the template's
2978 item, an issue. We have a special syntax for form fields that affect
2979 items other than the template default item (see the cgi
2980 documentation on `special form variables`_). In particular, we add a
2981 field to capture a new timelog item's perdiod::
2983 <tr>
2984 <th>Time Log</th>
2985 <td colspan=3><input type="text" name="timelog-1@period" />
2986 <br />(enter as '3y 1m 4d 2:40:02' or parts thereof)
2987 </td>
2988 </tr>
2990 and another hidden field that links that new timelog item (new
2991 because it's marked as having id "-1") to the issue item. It looks
2992 like this::
2994 <input type="hidden" name="@link@times" value="timelog-1" />
2996 On submission, the "-1" timelog item will be created and assigned a
2997 real item id. The "times" property of the issue will have the new id
2998 added to it.
3000 4. We want to display a total of the time log times that have been
3001 accumulated for an issue. To do this, we'll need to actually write
3002 some Python code, since it's beyond the scope of PageTemplates to
3003 perform such calculations. We do this by adding a method to the
3004 TemplatingUtils class in our tracker ``interfaces.py`` module::
3006 class TemplatingUtils:
3007 ''' Methods implemented on this class will be available to HTML
3008 templates through the 'utils' variable.
3009 '''
3010 def totalTimeSpent(self, times):
3011 ''' Call me with a list of timelog items (which have an
3012 Interval "period" property)
3013 '''
3014 total = Interval('')
3015 for time in times:
3016 total += time.period._value
3017 return total
3019 Replace the ``pass`` line as we did in step 4 above with the Client
3020 class. As indicated in the docstrings, we will be able to access the
3021 ``totalTimeSpent`` method via the ``utils`` variable in our
3022 templates.
3024 5. Display the time log for an issue::
3026 <table class="otherinfo" tal:condition="context/times">
3027 <tr><th colspan="3" class="header">Time Log
3028 <tal:block
3029 tal:replace="python:utils.totalTimeSpent(context.times)" />
3030 </th></tr>
3031 <tr><th>Date</th><th>Period</th><th>Logged By</th></tr>
3032 <tr tal:repeat="time context/times">
3033 <td tal:content="time/creation"></td>
3034 <td tal:content="time/period"></td>
3035 <td tal:content="time/creator"></td>
3036 </tr>
3037 </table>
3039 I put this just above the Messages log in my issue display. Note our
3040 use of the ``totalTimeSpent`` method which will total up the times
3041 for the issue and return a new Interval. That will be automatically
3042 displayed in the template as text like "+ 1y 2:40" (1 year, 2 hours
3043 and 40 minutes).
3045 8. If you're using a persistent web server - roundup-server or
3046 mod_python for example - then you'll need to restart that to pick up
3047 the code changes. When that's done, you'll be able to use the new
3048 time logging interface.
3050 Using a UN*X passwd file as the user database
3051 ---------------------------------------------
3053 On some systems the primary store of users is the UN*X passwd file. It
3054 holds information on users such as their username, real name, password
3055 and primary user group.
3057 Roundup can use this store as its primary source of user information,
3058 but it needs additional information too - email address(es), roundup
3059 Roles, vacation flags, roundup hyperdb item ids, etc. Also, "retired"
3060 users must still exist in the user database, unlike some passwd files in
3061 which the users are removed when they no longer have access to a system.
3063 To make use of the passwd file, we therefore synchronise between the two
3064 user stores. We also use the passwd file to validate the user logins, as
3065 described in the previous example, `using an external password
3066 validation source`_. We keep the users lists in sync using a fairly
3067 simple script that runs once a day, or several times an hour if more
3068 immediate access is needed. In short, it:
3070 1. parses the passwd file, finding usernames, passwords and real names,
3071 2. compares that list to the current roundup user list:
3073 a. entries no longer in the passwd file are *retired*
3074 b. entries with mismatching real names are *updated*
3075 c. entries only exist in the passwd file are *created*
3077 3. send an email to administrators to let them know what's been done.
3079 The retiring and updating are simple operations, requiring only a call
3080 to ``retire()`` or ``set()``. The creation operation requires more
3081 information though - the user's email address and their roundup Roles.
3082 We're going to assume that the user's email address is the same as their
3083 login name, so we just append the domain name to that. The Roles are
3084 determined using the passwd group identifier - mapping their UN*X group
3085 to an appropriate set of Roles.
3087 The script to perform all this, broken up into its main components, is
3088 as follows. Firstly, we import the necessary modules and open the
3089 tracker we're to work on::
3091 import sys, os, smtplib
3092 from roundup import instance, date
3094 # open the tracker
3095 tracker_home = sys.argv[1]
3096 tracker = instance.open(tracker_home)
3098 Next we read in the *passwd* file from the tracker home::
3100 # read in the users
3101 file = os.path.join(tracker_home, 'users.passwd')
3102 users = [x.strip().split(':') for x in open(file).readlines()]
3104 Handle special users (those to ignore in the file, and those who don't
3105 appear in the file)::
3107 # users to not keep ever, pre-load with the users I know aren't
3108 # "real" users
3109 ignore = ['ekmmon', 'bfast', 'csrmail']
3111 # users to keep - pre-load with the roundup-specific users
3112 keep = ['comment_pool', 'network_pool', 'admin', 'dev-team',
3113 'cs_pool', 'anonymous', 'system_pool', 'automated']
3115 Now we map the UN*X group numbers to the Roles that users should have::
3117 roles = {
3118 '501': 'User,Tech', # tech
3119 '502': 'User', # finance
3120 '503': 'User,CSR', # customer service reps
3121 '504': 'User', # sales
3122 '505': 'User', # marketing
3123 }
3125 Now we do all the work. Note that the body of the script (where we have
3126 the tracker database open) is wrapped in a ``try`` / ``finally`` clause,
3127 so that we always close the database cleanly when we're finished. So, we
3128 now do all the work::
3130 # open the database
3131 db = tracker.open('admin')
3132 try:
3133 # store away messages to send to the tracker admins
3134 msg = []
3136 # loop over the users list read in from the passwd file
3137 for user,passw,uid,gid,real,home,shell in users:
3138 if user in ignore:
3139 # this user shouldn't appear in our tracker
3140 continue
3141 keep.append(user)
3142 try:
3143 # see if the user exists in the tracker
3144 uid = db.user.lookup(user)
3146 # yes, they do - now check the real name for correctness
3147 if real != db.user.get(uid, 'realname'):
3148 db.user.set(uid, realname=real)
3149 msg.append('FIX %s - %s'%(user, real))
3150 except KeyError:
3151 # nope, the user doesn't exist
3152 db.user.create(username=user, realname=real,
3153 address='%s@ekit-inc.com'%user, roles=roles[gid])
3154 msg.append('ADD %s - %s (%s)'%(user, real, roles[gid]))
3156 # now check that all the users in the tracker are also in our
3157 # "keep" list - retire those who aren't
3158 for uid in db.user.list():
3159 user = db.user.get(uid, 'username')
3160 if user not in keep:
3161 db.user.retire(uid)
3162 msg.append('RET %s'%user)
3164 # if we did work, then send email to the tracker admins
3165 if msg:
3166 # create the email
3167 msg = '''Subject: %s user database maintenance
3169 %s
3170 '''%(db.config.TRACKER_NAME, '\n'.join(msg))
3172 # send the email
3173 smtp = smtplib.SMTP(db.config.MAILHOST)
3174 addr = db.config.ADMIN_EMAIL
3175 smtp.sendmail(addr, addr, msg)
3177 # now we're done - commit the changes
3178 db.commit()
3179 finally:
3180 # always close the database cleanly
3181 db.close()
3183 And that's it!
3186 Using an LDAP database for user information
3187 -------------------------------------------
3189 A script that reads users from an LDAP store using
3190 http://python-ldap.sf.net/ and then compares the list to the users in the
3191 roundup user database would be pretty easy to write. You'd then have it run
3192 once an hour / day (or on demand if you can work that into your LDAP store
3193 workflow). See the example `Using a UN*X passwd file as the user database`_
3194 for more information about doing this.
3196 To authenticate off the LDAP store (rather than using the passwords in the
3197 roundup user database) you'd use the same python-ldap module inside an
3198 extension to the cgi interface. You'd do this by adding a method called
3199 "verifyPassword" to the Client class in your tracker's interfaces.py
3200 module. The method is implemented by default as::
3202 def verifyPassword(self, userid, password):
3203 ''' Verify the password that the user has supplied
3204 '''
3205 stored = self.db.user.get(self.userid, 'password')
3206 if password == stored:
3207 return 1
3208 if not password and not stored:
3209 return 1
3210 return 0
3212 So you could reimplement this as something like::
3214 def verifyPassword(self, userid, password):
3215 ''' Verify the password that the user has supplied
3216 '''
3217 # look up some unique LDAP information about the user
3218 username = self.db.user.get(self.userid, 'username')
3219 # now verify the password supplied against the LDAP store
3222 Enabling display of either message summaries or the entire messages
3223 -------------------------------------------------------------------
3225 This is pretty simple - all we need to do is copy the code from the
3226 example `displaying only message summaries in the issue display`_ into
3227 our template alongside the summary display, and then introduce a switch
3228 that shows either one or the other. We'll use a new form variable,
3229 ``@whole_messages`` to achieve this::
3231 <table class="messages" tal:condition="context/messages">
3232 <tal:block tal:condition="not:request/form/@whole_messages/value | python:0">
3233 <tr><th colspan="3" class="header">Messages</th>
3234 <th colspan="2" class="header">
3235 <a href="?@whole_messages=yes">show entire messages</a>
3236 </th>
3237 </tr>
3238 <tr tal:repeat="msg context/messages">
3239 <td><a tal:attributes="href string:msg${msg/id}"
3240 tal:content="string:msg${msg/id}"></a></td>
3241 <td tal:content="msg/author">author</td>
3242 <td class="date" tal:content="msg/date/pretty">date</td>
3243 <td tal:content="msg/summary">summary</td>
3244 <td>
3245 <a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">remove</a>
3246 </td>
3247 </tr>
3248 </tal:block>
3250 <tal:block tal:condition="request/form/@whole_messages/value | python:0">
3251 <tr><th colspan="2" class="header">Messages</th>
3252 <th class="header">
3253 <a href="?@whole_messages=">show only summaries</a>
3254 </th>
3255 </tr>
3256 <tal:block tal:repeat="msg context/messages">
3257 <tr>
3258 <th tal:content="msg/author">author</th>
3259 <th class="date" tal:content="msg/date/pretty">date</th>
3260 <th style="text-align: right">
3261 (<a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">remove</a>)
3262 </th>
3263 </tr>
3264 <tr><td colspan="3" tal:content="msg/content"></td></tr>
3265 </tal:block>
3266 </tal:block>
3267 </table>
3270 Blocking issues that depend on other issues
3271 -------------------------------------------
3273 We needed the ability to mark certain issues as "blockers" - that is,
3274 they can't be resolved until another issue (the blocker) they rely on is
3275 resolved. To achieve this:
3277 1. Create a new property on the issue Class,
3278 ``blockers=Multilink("issue")``. Edit your tracker's dbinit.py file.
3279 Where the "issue" class is defined, something like::
3281 issue = IssueClass(db, "issue",
3282 assignedto=Link("user"), topic=Multilink("keyword"),
3283 priority=Link("priority"), status=Link("status"))
3285 add the blockers entry like so::
3287 issue = IssueClass(db, "issue",
3288 blockers=Multilink("issue"),
3289 assignedto=Link("user"), topic=Multilink("keyword"),
3290 priority=Link("priority"), status=Link("status"))
3292 2. Add the new "blockers" property to the issue.item edit page, using
3293 something like::
3295 <th>Waiting On</th>
3296 <td>
3297 <span tal:replace="structure python:context.blockers.field(showid=1,
3298 size=20)" />
3299 <span tal:replace="structure python:db.issue.classhelp('id,title')" />
3300 <span tal:condition="context/blockers"
3301 tal:repeat="blk context/blockers">
3302 <br>View: <a tal:attributes="href string:issue${blk/id}"
3303 tal:content="blk/id"></a>
3304 </span>
3306 You'll need to fiddle with your item page layout to find an
3307 appropriate place to put it - I'll leave that fun part up to you.
3308 Just make sure it appears in the first table, possibly somewhere near
3309 the "superseders" field.
3311 3. Create a new detector module (attached) which enforces the rules:
3313 - issues may not be resolved if they have blockers
3314 - when a blocker is resolved, it's removed from issues it blocks
3316 The contents of the detector should be something like this::
3318 def blockresolution(db, cl, nodeid, newvalues):
3319 ''' If the issue has blockers, don't allow it to be resolved.
3320 '''
3321 if nodeid is None:
3322 blockers = []
3323 else:
3324 blockers = cl.get(nodeid, 'blockers')
3325 blockers = newvalues.get('blockers', blockers)
3327 # don't do anything if there's no blockers or the status hasn't
3328 # changed
3329 if not blockers or not newvalues.has_key('status'):
3330 return
3332 # get the resolved state ID
3333 resolved_id = db.status.lookup('resolved')
3335 # format the info
3336 u = db.config.TRACKER_WEB
3337 s = ', '.join(['<a href="%sissue%s">%s</a>'%(
3338 u,id,id) for id in blockers])
3339 if len(blockers) == 1:
3340 s = 'issue %s is'%s
3341 else:
3342 s = 'issues %s are'%s
3344 # ok, see if we're trying to resolve
3345 if newvalues['status'] == resolved_id:
3346 raise ValueError, "This issue can't be resolved until %s resolved."%s
3348 def resolveblockers(db, cl, nodeid, newvalues):
3349 ''' When we resolve an issue that's a blocker, remove it from the
3350 blockers list of the issue(s) it blocks.
3351 '''
3352 if not newvalues.has_key('status'):
3353 return
3355 # get the resolved state ID
3356 resolved_id = db.status.lookup('resolved')
3358 # interesting?
3359 if newvalues['status'] != resolved_id:
3360 return
3362 # yes - find all the blocked issues, if any, and remove me from
3363 # their blockers list
3364 issues = cl.find(blockers=nodeid)
3365 for issueid in issues:
3366 blockers = cl.get(issueid, 'blockers')
3367 if nodeid in blockers:
3368 blockers.remove(nodeid)
3369 cl.set(issueid, blockers=blockers)
3372 def init(db):
3373 # might, in an obscure situation, happen in a create
3374 db.issue.audit('create', blockresolution)
3375 db.issue.audit('set', blockresolution)
3377 # can only happen on a set
3378 db.issue.react('set', resolveblockers)
3380 Put the above code in a file called "blockers.py" in your tracker's
3381 "detectors" directory.
3383 4. Finally, and this is an optional step, modify the tracker web page
3384 URLs so they filter out issues with any blockers. You do this by
3385 adding an additional filter on "blockers" for the value "-1". For
3386 example, the existing "Show All" link in the "page" template (in the
3387 tracker's "html" directory) looks like this::
3389 <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>
3391 modify it to add the "blockers" info to the URL (note, both the
3392 ":filter" *and* "blockers" values must be specified)::
3394 <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>
3396 That's it. You should now be able to set blockers on your issues. Note
3397 that if you want to know whether an issue has any other issues dependent
3398 on it (i.e. it's in their blockers list) you can look at the journal
3399 history at the bottom of the issue page - look for a "link" event to
3400 another issue's "blockers" property.
3402 Add users to the nosy list based on the topic
3403 ---------------------------------------------
3405 We need the ability to automatically add users to the nosy list based
3406 on the occurence of a topic. Every user should be allowed to edit his
3407 own list of topics for which he wants to be added to the nosy list.
3409 Below will be showed that such a change can be performed with only
3410 minimal understanding of the roundup system, but with clever use
3411 of Copy and Paste.
3413 This requires three changes to the tracker: a change in the database to
3414 allow per-user recording of the lists of topics for which he wants to
3415 be put on the nosy list, a change in the user view allowing to edit
3416 this list of topics, and addition of an auditor which updates the nosy
3417 list when a topic is set.
3419 Adding the nosy topic list
3420 ~~~~~~~~~~~~~~~~~~~~~~~~~~
3422 The change in the database to make is that for any user there should be
3423 a list of topics for which he wants to be put on the nosy list. Adding
3424 a ``Multilink`` of ``keyword`` seem to fullfill this (note that within
3425 the code topics are called ``keywords``.) As such, all what has to be
3426 done is to add a new field to the definition of ``user`` within the
3427 file ``dbinit.py``. We will call this new field ``nosy_keywords``, and
3428 the updated definition of user will be::
3430 user = Class(db, "user",
3431 username=String(), password=Password(),
3432 address=String(), realname=String(),
3433 phone=String(), organisation=String(),
3434 alternate_addresses=String(),
3435 queries=Multilink('query'), roles=String(),
3436 timezone=String(),
3437 nosy_keywords=Multilink('keyword'))
3439 Changing the user view to allow changing the nosy topic list
3440 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3442 We want any user to be able to change the list of topics for which
3443 he will by default be added to the nosy list. We choose to add this
3444 to the user view, as is generated by the file ``html/user.item.html``.
3445 We easily can
3446 see that the topic field in the issue view has very similar editting
3447 requirements as our nosy topics, both being a list of topics. As
3448 such, we search for Topics in ``issue.item.html``, and extract the
3449 associated parts from there. We add this to ``user.item.html`` at the
3450 bottom of the list of viewed items (i.e. just below the 'Alternate
3451 E-mail addresses' in the classic template)::
3453 <tr>
3454 <th>Nosy Topics</th>
3455 <td>
3456 <span tal:replace="structure context/nosy_keywords/field" />
3457 <span tal:replace="structure python:db.keyword.classhelp(property='nosy_keywords')" />
3458 </td>
3459 </tr>
3462 Addition of an auditor to update the nosy list
3463 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3465 The more difficult part is the addition of the logic to actually
3466 at the users to the nosy list when it is required.
3467 The choice is made to perform this action when the topics on an
3468 item are set, including when an item is created.
3469 Here we choose to start out with a copy of the
3470 ``detectors/nosyreaction.py`` detector, which we copy to the file
3471 ``detectors/nosy_keyword_reaction.py``.
3472 This looks like a good start as it also adds users
3473 to the nosy list. A look through the code reveals that the
3474 ``nosyreaction`` function actually is sending the e-mail, which
3475 we do not need. As such, we can change the init function to::
3477 def init(db):
3478 db.issue.audit('create', update_kw_nosy)
3479 db.issue.audit('set', update_kw_nosy)
3481 After that we rename the ``updatenosy`` function to ``update_kw_nosy``.
3482 The first two blocks of code in that function relate to settings
3483 ``current`` to a combination of the old and new nosy lists. This
3484 functionality is left in the new auditor. The following block of
3485 code, which in ``updatenosy`` handled adding the assignedto user(s)
3486 to the nosy list, should be replaced by a block of code to add the
3487 interested users to the nosy list. We choose here to loop over all
3488 new topics, than loop over all users,
3489 and assign the user to the nosy list when the topic in the user's
3490 nosy_keywords. The next part in ``updatenosy``, adding the author
3491 and/or recipients of a message to the nosy list, obviously is not
3492 relevant here and thus is deleted from the new auditor. The last
3493 part, copying the new nosy list to newvalues, does not have to be changed.
3494 This brings the following function::
3496 def update_kw_nosy(db, cl, nodeid, newvalues):
3497 '''Update the nosy list for changes to the topics
3498 '''
3499 # nodeid will be None if this is a new node
3500 current = {}
3501 if nodeid is None:
3502 ok = ('new', 'yes')
3503 else:
3504 ok = ('yes',)
3505 # old node, get the current values from the node if they haven't
3506 # changed
3507 if not newvalues.has_key('nosy'):
3508 nosy = cl.get(nodeid, 'nosy')
3509 for value in nosy:
3510 if not current.has_key(value):
3511 current[value] = 1
3513 # if the nosy list changed in this transaction, init from the new value
3514 if newvalues.has_key('nosy'):
3515 nosy = newvalues.get('nosy', [])
3516 for value in nosy:
3517 if not db.hasnode('user', value):
3518 continue
3519 if not current.has_key(value):
3520 current[value] = 1
3522 # add users with topic in nosy_keywords to the nosy list
3523 if newvalues.has_key('topic') and newvalues['topic'] is not None:
3524 topic_ids = newvalues['topic']
3525 for topic in topic_ids:
3526 # loop over all users,
3527 # and assign user to nosy when topic in nosy_keywords
3528 for user_id in db.user.list():
3529 nosy_kw = db.user.get(user_id, "nosy_keywords")
3530 found = 0
3531 for kw in nosy_kw:
3532 if kw == topic:
3533 found = 1
3534 if found:
3535 current[user_id] = 1
3537 # that's it, save off the new nosy list
3538 newvalues['nosy'] = current.keys()
3540 and these two function are the only ones needed in the file.
3542 TODO: update this example to use the find() Class method.
3544 Caveats
3545 ~~~~~~~
3547 A few problems with the design here can be noted:
3549 Multiple additions
3550 When a user, after automatic selection, is manually removed
3551 from the nosy list, he again is added to the nosy list when the
3552 topic list of the issue is updated. A better design might be
3553 to only check which topics are new compared to the old list
3554 of topics, and only add users when they have indicated
3555 interest on a new topic.
3557 The code could also be changed to only trigger on the create() event,
3558 rather than also on the set() event, thus only setting the nosy list
3559 when the issue is created.
3561 Scalability
3562 In the auditor there is a loop over all users. For a site with
3563 only few users this will pose no serious problem, however, with
3564 many users this will be a serious performance bottleneck.
3565 A way out will be to link from the topics to the users which
3566 selected these topics a nosy topics. This will eliminate the
3567 loop over all users.
3570 Adding action links to the index page
3571 -------------------------------------
3573 Add a column to the item.index.html template.
3575 Resolving the issue::
3577 <a tal:attributes="href
3578 string:issue${i/id}?:status=resolved&:action=edit">resolve</a>
3580 "Take" the issue::
3582 <a tal:attributes="href
3583 string:issue${i/id}?:assignedto=${request/user/id}&:action=edit">take</a>
3585 ... and so on
3587 Users may only edit their issues
3588 --------------------------------
3590 Users registering themselves are granted Provisional access - meaning they
3591 have access to edit the issues they submit, but not others. We create a new
3592 Role called "Provisional User" which is granted to newly-registered users,
3593 and has limited access. One of the Permissions they have is the new "Edit
3594 Own" on issues (regular users have "Edit".) We back up the permissions with
3595 an auditor.
3597 First up, we create the new Role and Permission structure in
3598 ``dbinit.py``::
3600 # New users not approved by the admin
3601 db.security.addRole(name='Provisional User',
3602 description='New user registered via web or email')
3603 p = db.security.addPermission(name='Edit Own', klass='issue',
3604 description='Can only edit own issues')
3605 db.security.addPermissionToRole('Provisional User', p)
3607 # Assign the access and edit Permissions for issue to new users now
3608 p = db.security.getPermission('View', 'issue')
3609 db.security.addPermissionToRole('Provisional User', p)
3610 p = db.security.getPermission('Edit', 'issue')
3611 db.security.addPermissionToRole('Provisional User', p)
3613 # and give the new users access to the web and email interface
3614 p = db.security.getPermission('Web Access')
3615 db.security.addPermissionToRole('Provisional User', p)
3616 p = db.security.getPermission('Email Access')
3617 db.security.addPermissionToRole('Provisional User', p)
3620 Then in the ``config.py`` we change the Role assigned to newly-registered
3621 users, replacing the existing ``'User'`` values::
3623 NEW_WEB_USER_ROLES = 'Provisional User'
3624 NEW_EMAIL_USER_ROLES = 'Provisional User'
3626 Finally we add a new *auditor* to the ``detectors`` directory called
3627 ``provisional_user_auditor.py``::
3629 def audit_provisionaluser(db, cl, nodeid, newvalues):
3630 ''' New users are only allowed to modify their own issues.
3631 '''
3632 if (db.getuid() != cl.get(nodeid, 'creator')
3633 and db.security.hasPermission('Edit Own', db.getuid(), cl.classname)):
3634 raise ValueError, ('You are only allowed to edit your own %s'
3635 % cl.classname)
3637 def init(db):
3638 # fire before changes are made
3639 db.issue.audit('set', audit_provisionaluser)
3640 db.issue.audit('retire', audit_provisionaluser)
3641 db.issue.audit('restore', audit_provisionaluser)
3643 Note that some older trackers might also want to change the ``page.html``
3644 template as follows::
3646 <p class="classblock"
3647 - tal:condition="python:request.user.username != 'anonymous'">
3648 + tal:condition="python:request.user.hasPermission('View', 'user')">
3649 <b>Administration</b><br>
3650 <tal:block tal:condition="python:request.user.hasPermission('Edit', None)">
3651 <a href="home?:template=classlist">Class List</a><br>
3653 (note that the "-" indicates a removed line, and the "+" indicates an added
3654 line).
3657 Colouring the rows in the issue index according to priority
3658 -----------------------------------------------------------
3660 A simple ``tal:attributes`` statement will do the bulk of the work here. In
3661 the ``issue.index.html`` template, add to the ``<tr>`` that displays the
3662 actual rows of data::
3664 <tr tal:attributes="class string:priority-${i/priority/plain}">
3666 and then in your stylesheet (``style.css``) specify the colouring for the
3667 different priorities, like::
3669 tr.priority-critical td {
3670 background-color: red;
3671 }
3673 tr.priority-urgent td {
3674 background-color: orange;
3675 }
3677 and so on, with far less offensive colours :)
3679 -------------------
3681 Back to `Table of Contents`_
3683 .. _`Table of Contents`: index.html
3684 .. _`design documentation`: design.html