e5170c32c13e25001b8a4490a8ee0546b08a2c01
1 ===================
2 Customising Roundup
3 ===================
5 :Version: $Revision: 1.119 $
7 .. This document borrows from the ZopeBook section on ZPT. The original is at:
8 http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
10 .. contents::
11 :depth: 1
13 What You Can Do
14 ===============
16 Before you get too far, it's probably worth having a quick read of the Roundup
17 `design documentation`_.
19 Customisation of Roundup can take one of six forms:
21 1. `tracker configuration`_ file changes
22 2. database, or `tracker schema`_ changes
23 3. "definition" class `database content`_ changes
24 4. behavioural changes, through detectors_
25 5. `security / access controls`_
26 6. change the `web interface`_
28 The third case is special because it takes two distinctly different forms
29 depending upon whether the tracker has been initialised or not. The other two
30 may be done at any time, before or after tracker initialisation. Yes, this
31 includes adding or removing properties from classes.
34 Trackers in a Nutshell
35 ======================
37 Trackers have the following structure:
39 =================== ========================================================
40 Tracker File Description
41 =================== ========================================================
42 config.py Holds the basic `tracker configuration`_
43 dbinit.py Holds the `tracker schema`_
44 interfaces.py Defines the Web and E-Mail interfaces for the tracker
45 select_db.py Selects the database back-end for the tracker
46 db/ Holds the tracker's database
47 db/files/ Holds the tracker's upload files and messages
48 detectors/ Auditors and reactors for this tracker
49 html/ Web interface templates, images and style sheets
50 =================== ========================================================
52 Tracker Configuration
53 =====================
55 The ``config.py`` located in your tracker home contains the basic
56 configuration for the web and e-mail components of roundup's interfaces.
57 As the name suggests, this file is a Python module. This means that any
58 valid python expression may be used in the file. Mostly though, you'll
59 be setting the configuration variables to string values. Python string
60 values must be quoted with either single or double quotes::
62 'this is a string'
63 "this is also a string - use it when the value has 'single quotes'"
64 this is not a string - it's not quoted
66 Python strings may use formatting that's almost identical to C string
67 formatting. The ``%`` operator is used to perform the formatting, like
68 so::
70 'roundup-admin@%s'%MAIL_DOMAIN
72 this will create a string ``'roundup-admin@tracker.domain.example'`` if
73 MAIL_DOMAIN is set to ``'tracker.domain.example'``.
75 You'll also note some values are set to::
77 os.path.join(TRACKER_HOME, 'db')
79 or similar. This creates a new string which holds the path to the
80 ``'db'`` directory in the TRACKER_HOME directory. This is just a
81 convenience so if the TRACKER_HOME changes you don't have to edit
82 multiple valoues.
84 The configuration variables available are:
86 **TRACKER_HOME** - ``os.path.split(__file__)[0]``
87 The tracker home directory. The above default code will automatically
88 determine the tracker home for you, so you can just leave it alone.
90 **MAILHOST** - ``'localhost'``
91 The SMTP mail host that roundup will use to send e-mail.
93 **MAILUSER** - ``()``
94 If your SMTP mail host requires a username and password for access, then
95 specify them here. eg. ``MAILUSER = ('username', 'password')``
97 **MAILHOST_TLS** - ``'no'``
98 If your SMTP mail host provides or requires TLS (Transport Layer
99 Security) then set ``MAILHOST_TLS = 'yes'``
101 **MAILHOST_TLS_KEYFILE** - ``''``
102 If you're using TLS, you may also set MAILHOST_TLS_KEYFILE to the name of
103 a PEM formatted file that contains your private key.
105 **MAILHOST_TLS_CERTFILE** - ``''``
106 If you're using TLS and have specified a MAILHOST_TLS_KEYFILE, you may
107 also set MAILHOST_TLS_CERTFILE to the name of a PEM formatted certificate
108 chain file.
110 **MAIL_DOMAIN** - ``'tracker.domain.example'``
111 The domain name used for email addresses.
113 **DATABASE** - ``os.path.join(TRACKER_HOME, 'db')``
114 This is the directory that the database is going to be stored in. By default
115 it is in the tracker home.
117 **TEMPLATES** - ``os.path.join(TRACKER_HOME, 'html')``
118 This is the directory that the HTML templates reside in. By default they are
119 in the tracker home.
121 **TRACKER_NAME** - ``'Roundup issue tracker'``
122 A descriptive name for your roundup tracker. This is sent out in e-mails and
123 appears in the heading of CGI pages.
125 **TRACKER_EMAIL** - ``'issue_tracker@%s'%MAIL_DOMAIN``
126 The email address that e-mail sent to roundup should go to. Think of it as the
127 tracker's personal e-mail address.
129 **TRACKER_WEB** - ``'http://tracker.example/cgi-bin/roundup.cgi/bugs/'``
130 The web address that the tracker is viewable at. This will be included in
131 information sent to users of the tracker. The URL **must** include the
132 cgi-bin part or anything else that is required to get to the home page of
133 the tracker. You **must** include a trailing '/' in the URL.
135 **ADMIN_EMAIL** - ``'roundup-admin@%s'%MAIL_DOMAIN``
136 The email address that roundup will complain to if it runs into trouble.
138 **EMAIL_FROM_TAG** - ``''``
139 Additional text to include in the "name" part of the ``From:`` address used
140 in nosy messages. If the sending user is "Foo Bar", the ``From:`` line is
141 usually::
143 "Foo Bar" <issue_tracker@tracker.example>
145 The EMAIL_FROM_TAG goes inside the "Foo Bar" quotes like so::
147 "Foo Bar EMAIL_FROM_TAG" <issue_tracker@tracker.example>
149 **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 with ``>`` or ``|`` characters at
173 the start of the line.
175 **EMAIL_LEAVE_BODY_UNCHANGED** - ``'no'``
176 Preserve the email body as is. Enabiling this will cause the entire message
177 body to be stored, including all citations, signatures and Outlook-quoted
178 sections (ie. "Original Message" blocks). It should be either ``'yes'``
179 or ``'no'``.
181 **MAIL_DEFAULT_CLASS** - ``'issue'`` or ``''``
182 Default class to use in the mailgw if one isn't supplied in email
183 subjects. To disable, comment out the variable below or leave it blank.
185 **HTML_VERSION** - ``'html4'`` or ``'xhtml'``
186 HTML version to generate. The templates are html4 by default. If you
187 wish to make them xhtml, then you'll need to change this var to 'xhtml'
188 too so all auto-generated HTML is compliant.
190 **EMAIL_CHARSET** - ``utf-8`` (or ``iso-8859-1`` for Eudora users)
191 Character set to encode email headers with. We use utf-8 by default, as
192 it's the most flexible. Some mail readers (eg. Eudora) can't cope with
193 that, so you might need to specify a more limited character set (eg.
194 'iso-8859-1'.
196 The default config.py is given below - as you
197 can see, the MAIL_DOMAIN must be edited before any interaction with the
198 tracker is attempted.::
200 # roundup home is this package's directory
201 TRACKER_HOME=os.path.split(__file__)[0]
203 # The SMTP mail host that roundup will use to send mail
204 MAILHOST = 'localhost'
206 # The domain name used for email addresses.
207 MAIL_DOMAIN = 'your.tracker.email.domain.example'
209 # This is the directory that the database is going to be stored in
210 DATABASE = os.path.join(TRACKER_HOME, 'db')
212 # This is the directory that the HTML templates reside in
213 TEMPLATES = os.path.join(TRACKER_HOME, 'html')
215 # A descriptive name for your roundup tracker
216 TRACKER_NAME = 'Roundup issue tracker'
218 # The email address that mail to roundup should go to
219 TRACKER_EMAIL = 'issue_tracker@%s'%MAIL_DOMAIN
221 # The web address that the tracker is viewable at. This will be
222 # included in information sent to users of the tracker. The URL MUST
223 # include the cgi-bin part or anything else that is required to get
224 # to the home page of the tracker. You MUST include a trailing '/'
225 # in the URL.
226 TRACKER_WEB = 'http://tracker.example/cgi-bin/roundup.cgi/bugs/'
228 # The email address that roundup will complain to if it runs into
229 # trouble
230 ADMIN_EMAIL = 'roundup-admin@%s'%MAIL_DOMAIN
232 # Additional text to include in the "name" part of the From: address
233 # used in nosy messages. If the sending user is "Foo Bar", the From:
234 # line is usually: "Foo Bar" <issue_tracker@tracker.example>
235 # the EMAIL_FROM_TAG goes inside the "Foo Bar" quotes like so:
236 # "Foo Bar EMAIL_FROM_TAG" <issue_tracker@tracker.example>
237 EMAIL_FROM_TAG = ""
239 # Send nosy messages to the author of the message
240 MESSAGES_TO_AUTHOR = 'no' # either 'yes' or 'no'
242 # Does the author of a message get placed on the nosy list
243 # automatically? If 'new' is used, then the author will only be
244 # added when a message creates a new issue. If 'yes', then the
245 # author will be added on followups too. If 'no', they're never
246 # added to the nosy.
247 ADD_AUTHOR_TO_NOSY = 'new' # one of 'yes', 'no', 'new'
249 # Do the recipients (To:, Cc:) of a message get placed on the nosy
250 # list? If 'new' is used, then the recipients will only be added
251 # when a message creates a new issue. If 'yes', then the recipients
252 # will be added on followups too. If 'no', they're never added to
253 # the nosy.
254 ADD_RECIPIENTS_TO_NOSY = 'new' # either 'yes', 'no', 'new'
256 # Where to place the email signature
257 EMAIL_SIGNATURE_POSITION = 'bottom' # one of 'top', 'bottom', 'none'
259 # Keep email citations
260 EMAIL_KEEP_QUOTED_TEXT = 'no' # either 'yes' or 'no'
262 # Preserve the email body as is
263 EMAIL_LEAVE_BODY_UNCHANGED = 'no' # either 'yes' or 'no'
265 # Default class to use in the mailgw if one isn't supplied in email
266 # subjects. To disable, comment out the variable below or leave it
267 # blank. Examples:
268 MAIL_DEFAULT_CLASS = 'issue' # use "issue" class by default
269 #MAIL_DEFAULT_CLASS = '' # disable (or just comment the var out)
271 # HTML version to generate. The templates are html4 by default. If you
272 # wish to make them xhtml, then you'll need to change this var to 'xhtml'
273 # too so all auto-generated HTML is compliant.
274 HTML_VERSION = 'html4' # either 'html4' or 'xhtml'
276 # Character set to encode email headers with. We use utf-8 by default, as
277 # it's the most flexible. Some mail readers (eg. Eudora) can't cope with
278 # that, so you might need to specify a more limited character set (eg.
279 # 'iso-8859-1'.
280 EMAIL_CHARSET = 'utf-8'
281 #EMAIL_CHARSET = 'iso-8859-1' # use this instead for Eudora users
283 #
284 # SECURITY DEFINITIONS
285 #
286 # define the Roles that a user gets when they register with the
287 # tracker these are a comma-separated string of role names (e.g.
288 # 'Admin,User')
289 NEW_WEB_USER_ROLES = 'User'
290 NEW_EMAIL_USER_ROLES = 'User'
292 Tracker Schema
293 ==============
295 Note: if you modify the schema, you'll most likely need to edit the
296 `web interface`_ HTML template files and `detectors`_ to reflect
297 your changes.
299 A tracker schema defines what data is stored in the tracker's database.
300 Schemas are defined using Python code in the ``dbinit.py`` module of your
301 tracker. The "classic" schema looks like this (see below for the meaning
302 of ``'setkey'``)::
304 pri = Class(db, "priority", name=String(), order=String())
305 pri.setkey("name")
307 stat = Class(db, "status", name=String(), order=String())
308 stat.setkey("name")
310 keyword = Class(db, "keyword", name=String())
311 keyword.setkey("name")
313 user = Class(db, "user", username=String(), organisation=String(),
314 password=String(), address=String(), realname=String(),
315 phone=String())
316 user.setkey("username")
318 msg = FileClass(db, "msg", author=Link("user"), summary=String(),
319 date=Date(), recipients=Multilink("user"),
320 files=Multilink("file"))
322 file = FileClass(db, "file", name=String(), type=String())
324 issue = IssueClass(db, "issue", topic=Multilink("keyword"),
325 status=Link("status"), assignedto=Link("user"),
326 priority=Link("priority"))
327 issue.setkey('title')
330 What you can't do to the schema
331 -------------------------------
333 You must never:
335 **Remove the users class**
336 This class is the only *required* class in Roundup. Similarly, its
337 username, password and address properties must never be removed.
339 **Change the type of a property**
340 Property types must *never* be changed - the database simply doesn't take
341 this kind of action into account. Note that you can't just remove a
342 property and re-add it as a new type either. If you wanted to make the
343 assignedto property a Multilink, you'd need to create a new property
344 assignedto_list and remove the old assignedto property.
347 What you can do to the schema
348 -----------------------------
350 Your schema may be changed at any time before or after the tracker has been
351 initialised (or used). You may:
353 **Add new properties to classes, or add whole new classes**
354 This is painless and easy to do - there are generally no repurcussions
355 from adding new information to a tracker's schema.
357 **Remove properties**
358 Removing properties is a little more tricky - you need to make sure that
359 the property is no longer used in the `web interface`_ *or* by the
360 detectors_.
364 Classes and Properties - creating a new information store
365 ---------------------------------------------------------
367 In the tracker above, we've defined 7 classes of information:
369 priority
370 Defines the possible levels of urgency for issues.
372 status
373 Defines the possible states of processing the issue may be in.
375 keyword
376 Initially empty, will hold keywords useful for searching issues.
378 user
379 Initially holding the "admin" user, will eventually have an entry
380 for all users using roundup.
382 msg
383 Initially empty, will hold all e-mail messages sent to or
384 generated by roundup.
386 file
387 Initially empty, will hold all files attached to issues.
389 issue
390 Initially empty, this is where the issue information is stored.
392 We define the "priority" and "status" classes to allow two things:
393 reduction in the amount of information stored on the issue and more
394 powerful, accurate searching of issues by priority and status. By only
395 requiring a link on the issue (which is stored as a single number) we
396 reduce the chance that someone mis-types a priority or status - or
397 simply makes a new one up.
400 Class and Items
401 ~~~~~~~~~~~~~~~
403 A Class defines a particular class (or type) of data that will be stored
404 in the database. A class comprises one or more properties, which gives
405 the information about the class items.
407 The actual data entered into the database, using ``class.create()``, are
408 called items. They have a special immutable property called ``'id'``. We
409 sometimes refer to this as the *itemid*.
412 Properties
413 ~~~~~~~~~~
415 A Class is comprised of one or more properties of the following types:
417 * String properties are for storing arbitrary-length strings.
418 * Password properties are for storing encoded arbitrary-length strings.
419 The default encoding is defined on the ``roundup.password.Password``
420 class.
421 * Date properties store date-and-time stamps. Their values are Timestamp
422 objects.
423 * Number properties store numeric values.
424 * Boolean properties store on/off, yes/no, true/false values.
425 * A Link property refers to a single other item selected from a
426 specified class. The class is part of the property; the value is an
427 integer, the id of the chosen item.
428 * A Multilink property refers to possibly many items in a specified
429 class. The value is a list of integers.
432 FileClass
433 ~~~~~~~~~
435 FileClasses save their "content" attribute off in a separate file from
436 the rest of the database. This reduces the number of large entries in
437 the database, which generally makes databases more efficient, and also
438 allows us to use command-line tools to operate on the files. They are
439 stored in the files sub-directory of the ``'db'`` directory in your
440 tracker.
443 IssueClass
444 ~~~~~~~~~~
446 IssueClasses automatically include the "messages", "files", "nosy", and
447 "superseder" properties.
449 The messages and files properties list the links to the messages and
450 files related to the issue. The nosy property is a list of links to
451 users who wish to be informed of changes to the issue - they get "CC'ed"
452 e-mails when messages are sent to or generated by the issue. The nosy
453 reactor (in the ``'detectors'`` directory) handles this action. The
454 superseder link indicates an issue which has superseded this one.
456 They also have the dynamically generated "creation", "activity" and
457 "creator" properties.
459 The value of the "creation" property is the date when an item was
460 created, and the value of the "activity" property is the date when any
461 property on the item was last edited (equivalently, these are the dates
462 on the first and last records in the item's journal). The "creator"
463 property holds a link to the user that created the issue.
466 setkey(property)
467 ~~~~~~~~~~~~~~~~
469 Select a String property of the class to be the key property. The key
470 property must be unique, and allows references to the items in the class
471 by the content of the key property. That is, we can refer to users by
472 their username: for example, let's say that there's an issue in roundup,
473 issue 23. There's also a user, richard, who happens to be user 2. To
474 assign an issue to him, we could do either of::
476 roundup-admin set issue23 assignedto=2
478 or::
480 roundup-admin set issue23 assignedto=richard
482 Note, the same thing can be done in the web and e-mail interfaces.
484 If a class does not have an "order" property, the key is also used to
485 sort instances of the class when it is rendered in the user interface.
486 (If a class has no "order" property, sorting is by the labelproperty of
487 the class. This is computed, in order of precedence, as the key, the
488 "name", the "title", or the first property alphabetically.)
491 create(information)
492 ~~~~~~~~~~~~~~~~~~~
494 Create an item in the database. This is generally used to create items
495 in the "definitional" classes like "priority" and "status".
498 Examples of adding to your schema
499 ---------------------------------
501 TODO
504 Detectors - adding behaviour to your tracker
505 ============================================
506 .. _detectors:
508 Detectors are initialised every time you open your tracker database, so
509 you're free to add and remove them any time, even after the database is
510 initialised via the "roundup-admin initialise" command.
512 The detectors in your tracker fire *before* (**auditors**) and *after*
513 (**reactors**) changes to the contents of your database. They are Python
514 modules that sit in your tracker's ``detectors`` directory. You will
515 have some installed by default - have a look. You can write new
516 detectors or modify the existing ones. The existing detectors installed
517 for you are:
519 **nosyreaction.py**
520 This provides the automatic nosy list maintenance and email sending.
521 The nosy reactor (``nosyreaction``) fires when new messages are added
522 to issues. The nosy auditor (``updatenosy``) fires when issues are
523 changed, and figures out what changes need to be made to the nosy list
524 (such as adding new authors, etc.)
525 **statusauditor.py**
526 This provides the ``chatty`` auditor which changes the issue status
527 from ``unread`` or ``closed`` to ``chatting`` if new messages appear.
528 It also provides the ``presetunread`` auditor which pre-sets the
529 status to ``unread`` on new items if the status isn't explicitly
530 defined.
531 **messagesummary.py**
532 Generates the ``summary`` property for new messages based on the message
533 content.
534 **userauditor.py**
535 Verifies the content of some of the user fields (email addresses and
536 roles lists).
538 If you don't want this default behaviour, you're completely free to change
539 or remove these detectors.
541 See the detectors section in the `design document`__ for details of the
542 interface for detectors.
544 __ design.html
546 Sample additional detectors that have been found useful will appear in
547 the ``'detectors'`` directory of the Roundup distribution. If you want
548 to use one, copy it to the ``'detectors'`` of your tracker instance:
550 **newissuecopy.py**
551 This detector sends an email to a team address whenever a new issue is
552 created. The address is hard-coded into the detector, so edit it
553 before you use it (look for the text 'team@team.host') or you'll get
554 email errors!
556 The detector code::
558 from roundup import roundupdb
560 def newissuecopy(db, cl, nodeid, oldvalues):
561 ''' Copy a message about new issues to a team address.
562 '''
563 # so use all the messages in the create
564 change_note = cl.generateCreateNote(nodeid)
566 # send a copy to the nosy list
567 for msgid in cl.get(nodeid, 'messages'):
568 try:
569 # note: last arg must be a list
570 cl.send_message(nodeid, msgid, change_note,
571 ['team@team.host'])
572 except roundupdb.MessageSendError, message:
573 raise roundupdb.DetectorError, message
575 def init(db):
576 db.issue.react('create', newissuecopy)
579 Database Content
580 ================
582 Note: if you modify the content of definitional classes, you'll most
583 likely need to edit the tracker `detectors`_ to reflect your
584 changes.
586 Customisation of the special "definitional" classes (eg. status,
587 priority, resolution, ...) may be done either before or after the
588 tracker is initialised. The actual method of doing so is completely
589 different in each case though, so be careful to use the right one.
591 **Changing content before tracker initialisation**
592 Edit the dbinit module in your tracker to alter the items created in
593 using the ``create()`` methods.
595 **Changing content after tracker initialisation**
596 As the "admin" user, click on the "class list" link in the web
597 interface to bring up a list of all database classes. Click on the
598 name of the class you wish to change the content of.
600 You may also use the ``roundup-admin`` interface's create, set and
601 retire methods to add, alter or remove items from the classes in
602 question.
604 See "`adding a new field to the classic schema`_" for an example that
605 requires database content changes.
608 Security / Access Controls
609 ==========================
611 A set of Permissions is built into the security module by default:
613 - Edit (everything)
614 - View (everything)
616 Every Class you define in your tracker's schema also gets an Edit and View
617 Permission of its own.
619 The default interfaces define:
621 - Web Registration
622 - Web Access
623 - Web Roles
624 - Email Registration
625 - Email Access
627 These are hooked into the default Roles:
629 - Admin (Edit everything, View everything, Web Roles)
630 - User (Web Access, Email Access)
631 - Anonymous (Web Registration, Email Registration)
633 And finally, the "admin" user gets the "Admin" Role, and the "anonymous"
634 user gets "Anonymous" assigned when the database is initialised on
635 installation. The two default schemas then define:
637 - Edit issue, View issue (both)
638 - Edit file, View file (both)
639 - Edit msg, View msg (both)
640 - Edit support, View support (extended only)
642 and assign those Permissions to the "User" Role. Put together, these
643 settings appear in the ``open()`` function of the tracker ``dbinit.py``
644 (the following is taken from the "minimal" template's ``dbinit.py``)::
646 #
647 # SECURITY SETTINGS
648 #
649 # and give the regular users access to the web and email interface
650 p = db.security.getPermission('Web Access')
651 db.security.addPermissionToRole('User', p)
652 p = db.security.getPermission('Email Access')
653 db.security.addPermissionToRole('User', p)
655 # May users view other user information? Comment these lines out
656 # if you don't want them to
657 p = db.security.getPermission('View', 'user')
658 db.security.addPermissionToRole('User', p)
660 # Assign the appropriate permissions to the anonymous user's
661 # Anonymous role. Choices here are:
662 # - Allow anonymous users to register through the web
663 p = db.security.getPermission('Web Registration')
664 db.security.addPermissionToRole('Anonymous', p)
665 # - Allow anonymous (new) users to register through the email
666 # gateway
667 p = db.security.getPermission('Email Registration')
668 db.security.addPermissionToRole('Anonymous', p)
671 New User Roles
672 --------------
674 New users are assigned the Roles defined in the config file as:
676 - NEW_WEB_USER_ROLES
677 - NEW_EMAIL_USER_ROLES
680 Changing Access Controls
681 ------------------------
683 You may alter the configuration variables to change the Role that new
684 web or email users get, for example to not give them access to the web
685 interface if they register through email.
687 You may use the ``roundup-admin`` "``security``" command to display the
688 current Role and Permission configuration in your tracker.
691 Adding a new Permission
692 ~~~~~~~~~~~~~~~~~~~~~~~
694 When adding a new Permission, you will need to:
696 1. add it to your tracker's dbinit so it is created, using
697 ``security.addPermission``, for example::
699 self.security.addPermission(name="View", klass='frozzle',
700 description="User is allowed to access frozzles")
702 will set up a new "View" permission on the Class "frozzle".
703 2. enable it for the Roles that should have it (verify with
704 "``roundup-admin security``")
705 3. add it to the relevant HTML interface templates
706 4. add it to the appropriate xxxPermission methods on in your tracker
707 interfaces module
710 Example Scenarios
711 ~~~~~~~~~~~~~~~~~
713 **automatic registration of users in the e-mail gateway**
714 By giving the "anonymous" user the "Email Registration" Role, any
715 unidentified user will automatically be registered with the tracker
716 (with no password, so they won't be able to log in through the web
717 until an admin sets their password). Note: this is the default
718 behaviour in the tracker templates that ship with Roundup.
720 **anonymous access through the e-mail gateway**
721 Give the "anonymous" user the "Email Access" and ("Edit", "issue")
722 Roles but do not not give them the "Email Registration" Role. This
723 means that when an unknown user sends email into the tracker, they're
724 automatically logged in as "anonymous". Since they don't have the
725 "Email Registration" Role, they won't be automatically registered, but
726 since "anonymous" has permission to use the gateway, they'll still be
727 able to submit issues. Note that the Sender information - their email
728 address - will not be available - they're *anonymous*.
730 **only developers may be assigned issues**
731 Create a new Permission called "Fixer" for the "issue" class. Create a
732 new Role "Developer" which has that Permission, and assign that to the
733 appropriate users. Filter the list of users available in the assignedto
734 list to include only those users. Enforce the Permission with an
735 auditor. See the example
736 `restricting the list of users that are assignable to a task`_.
738 **only managers may sign off issues as complete**
739 Create a new Permission called "Closer" for the "issue" class. Create a
740 new Role "Manager" which has that Permission, and assign that to the
741 appropriate users. In your web interface, only display the "resolved"
742 issue state option when the user has the "Closer" Permissions. Enforce
743 the Permission with an auditor. This is very similar to the previous
744 example, except that the web interface check would look like::
746 <option tal:condition="python:request.user.hasPermission('Closer')"
747 value="resolved">Resolved</option>
749 **don't give web access to users who register through email**
750 Create a new Role called "Email User" which has all the Permissions of
751 the normal "User" Role minus the "Web Access" Permission. This will
752 allow users to send in emails to the tracker, but not access the web
753 interface.
755 **let some users edit the details of all users**
756 Create a new Role called "User Admin" which has the Permission for
757 editing users::
759 db.security.addRole(name='User Admin', description='Managing users')
760 p = db.security.getPermission('Edit', 'user')
761 db.security.addPermissionToRole('User Admin', p)
763 and assign the Role to the users who need the permission.
766 Web Interface
767 =============
769 .. contents::
770 :local:
771 :depth: 1
773 The web interface is provided by the ``roundup.cgi.client`` module and
774 is used by ``roundup.cgi``, ``roundup-server`` and ``ZRoundup``
775 (``ZRoundup`` is broken, until further notice). In all cases, we
776 determine which tracker is being accessed (the first part of the URL
777 path inside the scope of the CGI handler) and pass control on to the
778 tracker ``interfaces.Client`` class - which uses the ``Client`` class
779 from ``roundup.cgi.client`` - which handles the rest of the access
780 through its ``main()`` method. This means that you can do pretty much
781 anything you want as a web interface to your tracker.
783 Repercussions of changing the tracker schema
784 ---------------------------------------------
786 If you choose to change the `tracker schema`_ you will need to ensure
787 the web interface knows about it:
789 1. Index, item and search pages for the relevant classes may need to
790 have properties added or removed,
791 2. The "page" template may require links to be changed, as might the
792 "home" page's content arguments.
794 How requests are processed
795 --------------------------
797 The basic processing of a web request proceeds as follows:
799 1. figure out who we are, defaulting to the "anonymous" user
800 2. figure out what the request is for - we call this the "context"
801 3. handle any requested action (item edit, search, ...)
802 4. render the template requested by the context, resulting in HTML
803 output
805 In some situations, exceptions occur:
807 - HTTP Redirect (generally raised by an action)
808 - SendFile (generally raised by ``determine_context``)
809 here we serve up a FileClass "content" property
810 - SendStaticFile (generally raised by ``determine_context``)
811 here we serve up a file from the tracker "html" directory
812 - Unauthorised (generally raised by an action)
813 here the action is cancelled, the request is rendered and an error
814 message is displayed indicating that permission was not granted for
815 the action to take place
816 - NotFound (raised wherever it needs to be)
817 this exception percolates up to the CGI interface that called the
818 client
820 Determining web context
821 -----------------------
823 To determine the "context" of a request, we look at the URL and the
824 special request variable ``@template``. The URL path after the tracker
825 identifier is examined. Typical URL paths look like:
827 1. ``/tracker/issue``
828 2. ``/tracker/issue1``
829 3. ``/tracker/_file/style.css``
830 4. ``/cgi-bin/roundup.cgi/tracker/file1``
831 5. ``/cgi-bin/roundup.cgi/tracker/file1/kitten.png``
833 where the "tracker identifier" is "tracker" in the above cases. That means
834 we're looking at "issue", "issue1", "_file/style.css", "file1" and
835 "file1/kitten.png" in the cases above. The path is generally only one
836 entry long - longer paths are handled differently.
838 a. if there is no path, then we are in the "home" context.
839 b. if the path starts with "_file" (as in example 3,
840 "/tracker/_file/style.css"), then the additional path entry,
841 "style.css" specifies the filename of a static file we're to serve up
842 from the tracker "html" directory. Raises a SendStaticFile exception.
843 c. if there is something in the path (as in example 1, "issue"), it
844 identifies the tracker class we're to display.
845 d. if the path is an item designator (as in examples 2 and 4, "issue1"
846 and "file1"), then we're to display a specific item.
847 e. if the path starts with an item designator and is longer than one
848 entry (as in example 5, "file1/kitten.png"), then we're assumed to be
849 handling an item of a ``FileClass``, and the extra path information
850 gives the filename that the client is going to label the download
851 with (i.e. "file1/kitten.png" is nicer to download than "file1").
852 This raises a ``SendFile`` exception.
854 Both b. and e. stop before we bother to determine the template we're
855 going to use. That's because they don't actually use templates.
857 The template used is specified by the ``@template`` CGI variable, which
858 defaults to:
860 - only classname suplied: "index"
861 - full item designator supplied: "item"
864 Performing actions in web requests
865 ----------------------------------
867 When a user requests a web page, they may optionally also request for an
868 action to take place. As described in `how requests are processed`_, the
869 action is performed before the requested page is generated. Actions are
870 triggered by using a ``@action`` CGI variable, where the value is one
871 of:
873 **login**
874 Attempt to log a user in.
876 **logout**
877 Log the user out - make them "anonymous".
879 **register**
880 Attempt to create a new user based on the contents of the form and then
881 log them in.
883 **edit**
884 Perform an edit of an item in the database. There are some `special form
885 variables`_ you may use.
887 **new**
888 Add a new item to the database. You may use the same `special form
889 variables`_ as in the "edit" action.
891 **retire**
892 Retire the item in the database.
894 **editCSV**
895 Performs an edit of all of a class' items in one go. See also the
896 *class*.csv templating method which generates the CSV data to be
897 edited, and the ``'_generic.index'`` template which uses both of these
898 features.
900 **search**
901 Mangle some of the form variables:
903 - Set the form ":filter" variable based on the values of the filter
904 variables - if they're set to anything other than "dontcare" then add
905 them to :filter.
907 - Also handle the ":queryname" variable and save off the query to the
908 user's query list.
910 Each of the actions is implemented by a corresponding ``*XxxAction*`` (where
911 "Xxx" is the name of the action) class in the ``roundup.cgi.actions`` module.
912 These classes are registered with ``roundup.cgi.client.Client`` which also
913 happens to be available in your tracker instance as ``interfaces.Client``. So
914 if you need to define new actions, you may add them there (see `defining new
915 web actions`_).
917 Each action class also has a ``*permission*`` method which determines whether
918 the action is permissible given the current user. The base permission checks
919 are:
921 **login**
922 Determine whether the user has permission to log in. Base behaviour is
923 to check the user has "Web Access".
924 **logout**
925 No permission checks are made.
926 **register**
927 Determine whether the user has permission to register. Base behaviour
928 is to check the user has the "Web Registration" Permission.
929 **edit**
930 Determine whether the user has permission to edit this item. Base
931 behaviour is to check whether the user can edit this class. If we're
932 editing the "user" class, users are allowed to edit their own details -
933 unless they try to edit the "roles" property, which requires the
934 special Permission "Web Roles".
935 **new**
936 Determine whether the user has permission to create (or edit) this
937 item. Base behaviour is to check the user can edit this class. No
938 additional property checks are made. Additionally, new user items may
939 be created if the user has the "Web Registration" Permission.
940 **editCSV**
941 Determine whether the user has permission to edit this class. Base
942 behaviour is to check whether the user may edit this class.
943 **search**
944 Determine whether the user has permission to search this class. Base
945 behaviour is to check whether the user may view this class.
948 Special form variables
949 ----------------------
951 Item properties and their values are edited with html FORM
952 variables and their values. You can:
954 - Change the value of some property of the current item.
955 - Create a new item of any class, and edit the new item's
956 properties,
957 - Attach newly created items to a multilink property of the
958 current item.
959 - Remove items from a multilink property of the current item.
960 - Specify that some properties are required for the edit
961 operation to be successful.
963 In the following, <bracketed> values are variable, "@" may be
964 either ":" or "@", and other text "required" is fixed.
966 Most properties are specified as form variables:
968 ``<propname>``
969 property on the current context item
971 ``<designator>"@"<propname>``
972 property on the indicated item (for editing related information)
974 Designators name a specific item of a class.
976 ``<classname><N>``
977 Name an existing item of class <classname>.
979 ``<classname>"-"<N>``
980 Name the <N>th new item of class <classname>. If the form
981 submission is successful, a new item of <classname> is
982 created. Within the submitted form, a particular
983 designator of this form always refers to the same new
984 item.
986 Once we have determined the "propname", we look at it to see
987 if it's special:
989 ``@required``
990 The associated form value is a comma-separated list of
991 property names that must be specified when the form is
992 submitted for the edit operation to succeed.
994 When the <designator> is missing, the properties are
995 for the current context item. When <designator> is
996 present, they are for the item specified by
997 <designator>.
999 The "@required" specifier must come before any of the
1000 properties it refers to are assigned in the form.
1002 ``@remove@<propname>=id(s)`` or ``@add@<propname>=id(s)``
1003 The "@add@" and "@remove@" edit actions apply only to
1004 Multilink properties. The form value must be a
1005 comma-separate list of keys for the class specified by
1006 the simple form variable. The listed items are added
1007 to (respectively, removed from) the specified
1008 property.
1010 ``@link@<propname>=<designator>``
1011 If the edit action is "@link@", the simple form
1012 variable must specify a Link or Multilink property.
1013 The form value is a comma-separated list of
1014 designators. The item corresponding to each
1015 designator is linked to the property given by simple
1016 form variable.
1018 None of the above (ie. just a simple form value)
1019 The value of the form variable is converted
1020 appropriately, depending on the type of the property.
1022 For a Link('klass') property, the form value is a
1023 single key for 'klass', where the key field is
1024 specified in dbinit.py.
1026 For a Multilink('klass') property, the form value is a
1027 comma-separated list of keys for 'klass', where the
1028 key field is specified in dbinit.py.
1030 Note that for simple-form-variables specifiying Link
1031 and Multilink properties, the linked-to class must
1032 have a key field.
1034 For a String() property specifying a filename, the
1035 file named by the form value is uploaded. This means we
1036 try to set additional properties "filename" and "type" (if
1037 they are valid for the class). Otherwise, the property
1038 is set to the form value.
1040 For Date(), Interval(), Boolean(), and Number()
1041 properties, the form value is converted to the
1042 appropriate
1044 Any of the form variables may be prefixed with a classname or
1045 designator.
1047 Two special form values are supported for backwards compatibility:
1049 @note
1050 This is equivalent to::
1052 @link@messages=msg-1
1053 msg-1@content=value
1055 except that in addition, the "author" and "date" properties of
1056 "msg-1" are set to the userid of the submitter, and the current
1057 time, respectively.
1059 @file
1060 This is equivalent to::
1062 @link@files=file-1
1063 file-1@content=value
1065 The String content value is handled as described above for file
1066 uploads.
1068 If both the "@note" and "@file" form variables are
1069 specified, the action::
1071 @link@msg-1@files=file-1
1073 is also performed.
1075 We also check that FileClass items have a "content" property with
1076 actual content, otherwise we remove them from all_props before
1077 returning.
1081 Default templates
1082 -----------------
1084 The default templates are html4 compliant. If you wish to change them to be
1085 xhtml compliant, you'll need to change the ``HTML_VERSION`` configuration
1086 variable in ``config.py`` to ``'xhtml'`` instead of ``'html4'``.
1088 Most customisation of the web view can be done by modifying the
1089 templates in the tracker ``'html'`` directory. There are several types
1090 of files in there. The *minimal* template includes:
1092 **page.html**
1093 This template usually defines the overall look of your tracker. When
1094 you view an issue, it appears inside this template. When you view an
1095 index, it also appears inside this template. This template defines a
1096 macro called "icing" which is used by almost all other templates as a
1097 coating for their content, using its "content" slot. It also defines
1098 the "head_title" and "body_title" slots to allow setting of the page
1099 title.
1100 **home.html**
1101 the default page displayed when no other page is indicated by the user
1102 **home.classlist.html**
1103 a special version of the default page that lists the classes in the
1104 tracker
1105 **classname.item.html**
1106 displays an item of the *classname* class
1107 **classname.index.html**
1108 displays a list of *classname* items
1109 **classname.search.html**
1110 displays a search page for *classname* items
1111 **_generic.index.html**
1112 used to display a list of items where there is no
1113 ``*classname*.index`` available
1114 **_generic.help.html**
1115 used to display a "class help" page where there is no
1116 ``*classname*.help``
1117 **user.register.html**
1118 a special page just for the user class, that renders the registration
1119 page
1120 **style.css.html**
1121 a static file that is served up as-is
1123 The *classic* template has a number of additional templates.
1125 Note: Remember that you can create any template extension you want to,
1126 so if you just want to play around with the templating for new issues,
1127 you can copy the current "issue.item" template to "issue.test", and then
1128 access the test template using the "@template" URL argument::
1130 http://your.tracker.example/tracker/issue?@template=test
1132 and it won't affect your users using the "issue.item" template.
1135 How the templates work
1136 ----------------------
1139 Basic Templating Actions
1140 ~~~~~~~~~~~~~~~~~~~~~~~~
1142 Roundup's templates consist of special attributes on the HTML tags.
1143 These attributes form the Template Attribute Language, or TAL. The basic
1144 TAL commands are:
1146 **tal:define="variable expression; variable expression; ..."**
1147 Define a new variable that is local to this tag and its contents. For
1148 example::
1150 <html tal:define="title request/description">
1151 <head><title tal:content="title"></title></head>
1152 </html>
1154 In this example, the variable "title" is defined as the result of the
1155 expression "request/description". The "tal:content" command inside the
1156 <html> tag may then use the "title" variable.
1158 **tal:condition="expression"**
1159 Only keep this tag and its contents if the expression is true. For
1160 example::
1162 <p tal:condition="python:request.user.hasPermission('View', 'issue')">
1163 Display some issue information.
1164 </p>
1166 In the example, the <p> tag and its contents are only displayed if
1167 the user has the "View" permission for issues. We consider the number
1168 zero, a blank string, an empty list, and the built-in variable
1169 nothing to be false values. Nearly every other value is true,
1170 including non-zero numbers, and strings with anything in them (even
1171 spaces!).
1173 **tal:repeat="variable expression"**
1174 Repeat this tag and its contents for each element of the sequence
1175 that the expression returns, defining a new local variable and a
1176 special "repeat" variable for each element. For example::
1178 <tr tal:repeat="u user/list">
1179 <td tal:content="u/id"></td>
1180 <td tal:content="u/username"></td>
1181 <td tal:content="u/realname"></td>
1182 </tr>
1184 The example would iterate over the sequence of users returned by
1185 "user/list" and define the local variable "u" for each entry.
1187 **tal:replace="expression"**
1188 Replace this tag with the result of the expression. For example::
1190 <span tal:replace="request/user/realname" />
1192 The example would replace the <span> tag and its contents with the
1193 user's realname. If the user's realname was "Bruce", then the
1194 resultant output would be "Bruce".
1196 **tal:content="expression"**
1197 Replace the contents of this tag with the result of the expression.
1198 For example::
1200 <span tal:content="request/user/realname">user's name appears here
1201 </span>
1203 The example would replace the contents of the <span> tag with the
1204 user's realname. If the user's realname was "Bruce" then the
1205 resultant output would be "<span>Bruce</span>".
1207 **tal:attributes="attribute expression; attribute expression; ..."**
1208 Set attributes on this tag to the results of expressions. For
1209 example::
1211 <a tal:attributes="href string:user${request/user/id}">My Details</a>
1213 In the example, the "href" attribute of the <a> tag is set to the
1214 value of the "string:user${request/user/id}" expression, which will
1215 be something like "user123".
1217 **tal:omit-tag="expression"**
1218 Remove this tag (but not its contents) if the expression is true. For
1219 example::
1221 <span tal:omit-tag="python:1">Hello, world!</span>
1223 would result in output of::
1225 Hello, world!
1227 Note that the commands on a given tag are evaulated in the order above,
1228 so *define* comes before *condition*, and so on.
1230 Additionally, you may include tags such as <tal:block>, which are
1231 removed from output. Its content is kept, but the tag itself is not (so
1232 don't go using any "tal:attributes" commands on it). This is useful for
1233 making arbitrary blocks of HTML conditional or repeatable (very handy
1234 for repeating multiple table rows, which would othewise require an
1235 illegal tag placement to effect the repeat).
1238 Templating Expressions
1239 ~~~~~~~~~~~~~~~~~~~~~~
1241 The expressions you may use in the attribute values may be one of the
1242 following forms:
1244 **Path Expressions** - eg. ``item/status/checklist``
1245 These are object attribute / item accesses. Roughly speaking, the
1246 path ``item/status/checklist`` is broken into parts ``item``,
1247 ``status`` and ``checklist``. The ``item`` part is the root of the
1248 expression. We then look for a ``status`` attribute on ``item``, or
1249 failing that, a ``status`` item (as in ``item['status']``). If that
1250 fails, the path expression fails. When we get to the end, the object
1251 we're left with is evaluated to get a string - if it is a method, it
1252 is called; if it is an object, it is stringified. Path expressions
1253 may have an optional ``path:`` prefix, but they are the default
1254 expression type, so it's not necessary.
1256 If an expression evaluates to ``default``, then the expression is
1257 "cancelled" - whatever HTML already exists in the template will
1258 remain (tag content in the case of ``tal:content``, attributes in the
1259 case of ``tal:attributes``).
1261 If an expression evaluates to ``nothing`` then the target of the
1262 expression is removed (tag content in the case of ``tal:content``,
1263 attributes in the case of ``tal:attributes`` and the tag itself in
1264 the case of ``tal:replace``).
1266 If an element in the path may not exist, then you can use the ``|``
1267 operator in the expression to provide an alternative. So, the
1268 expression ``request/form/foo/value | default`` would simply leave
1269 the current HTML in place if the "foo" form variable doesn't exist.
1271 You may use the python function ``path``, as in
1272 ``path("item/status")``, to embed path expressions in Python
1273 expressions.
1275 **String Expressions** - eg. ``string:hello ${user/name}``
1276 These expressions are simple string interpolations - though they can
1277 be just plain strings with no interpolation if you want. The
1278 expression in the ``${ ... }`` is just a path expression as above.
1280 **Python Expressions** - eg. ``python: 1+1``
1281 These expressions give the full power of Python. All the "root level"
1282 variables are available, so ``python:item.status.checklist()`` would
1283 be equivalent to ``item/status/checklist``, assuming that
1284 ``checklist`` is a method.
1286 Modifiers:
1288 **structure** - eg. ``structure python:msg.content.plain(hyperlink=1)``
1289 The result of expressions are normally *escaped* to be safe for HTML
1290 display (all "<", ">" and "&" are turned into special entities). The
1291 ``structure`` expression modifier turns off this escaping - the
1292 result of the expression is now assumed to be HTML, which is passed
1293 to the web browser for rendering.
1295 **not:** - eg. ``not:python:1=1``
1296 This simply inverts the logical true/false value of another
1297 expression.
1300 Template Macros
1301 ~~~~~~~~~~~~~~~
1303 Macros are used in Roundup to save us from repeating the same common
1304 page stuctures over and over. The most common (and probably only) macro
1305 you'll use is the "icing" macro defined in the "page" template.
1307 Macros are generated and used inside your templates using special
1308 attributes similar to the `basic templating actions`_. In this case,
1309 though, the attributes belong to the Macro Expansion Template Attribute
1310 Language, or METAL. The macro commands are:
1312 **metal:define-macro="macro name"**
1313 Define that the tag and its contents are now a macro that may be
1314 inserted into other templates using the *use-macro* command. For
1315 example::
1317 <html metal:define-macro="page">
1318 ...
1319 </html>
1321 defines a macro called "page" using the ``<html>`` tag and its
1322 contents. Once defined, macros are stored on the template they're
1323 defined on in the ``macros`` attribute. You can access them later on
1324 through the ``templates`` variable, eg. the most common
1325 ``templates/page/macros/icing`` to access the "page" macro of the
1326 "page" template.
1328 **metal:use-macro="path expression"**
1329 Use a macro, which is identified by the path expression (see above).
1330 This will replace the current tag with the identified macro contents.
1331 For example::
1333 <tal:block metal:use-macro="templates/page/macros/icing">
1334 ...
1335 </tal:block>
1337 will replace the tag and its contents with the "page" macro of the
1338 "page" template.
1340 **metal:define-slot="slot name"** and **metal:fill-slot="slot name"**
1341 To define *dynamic* parts of the macro, you define "slots" which may
1342 be filled when the macro is used with a *use-macro* command. For
1343 example, the ``templates/page/macros/icing`` macro defines a slot like
1344 so::
1346 <title metal:define-slot="head_title">title goes here</title>
1348 In your *use-macro* command, you may now use a *fill-slot* command
1349 like this::
1351 <title metal:fill-slot="head_title">My Title</title>
1353 where the tag that fills the slot completely replaces the one defined
1354 as the slot in the macro.
1356 Note that you may not mix METAL and TAL commands on the same tag, but
1357 TAL commands may be used freely inside METAL-using tags (so your
1358 *fill-slots* tags may have all manner of TAL inside them).
1361 Information available to templates
1362 ----------------------------------
1364 Note: this is implemented by
1365 ``roundup.cgi.templating.RoundupPageTemplate``
1367 The following variables are available to templates.
1369 **context**
1370 The current context. This is either None, a `hyperdb class wrapper`_
1371 or a `hyperdb item wrapper`_
1372 **request**
1373 Includes information about the current request, including:
1374 - the current index information (``filterspec``, ``filter`` args,
1375 ``properties``, etc) parsed out of the form.
1376 - methods for easy filterspec link generation
1377 - *user*, the current user item as an HTMLItem instance
1378 - *form*
1379 The current CGI form information as a mapping of form argument name
1380 to value
1381 **config**
1382 This variable holds all the values defined in the tracker config.py
1383 file (eg. TRACKER_NAME, etc.)
1384 **db**
1385 The current database, used to access arbitrary database items.
1386 **templates**
1387 Access to all the tracker templates by name. Used mainly in
1388 *use-macro* commands.
1389 **utils**
1390 This variable makes available some utility functions like batching.
1391 **nothing**
1392 This is a special variable - if an expression evaluates to this, then
1393 the tag (in the case of a ``tal:replace``), its contents (in the case
1394 of ``tal:content``) or some attributes (in the case of
1395 ``tal:attributes``) will not appear in the the output. So, for
1396 example::
1398 <span tal:attributes="class nothing">Hello, World!</span>
1400 would result in::
1402 <span>Hello, World!</span>
1404 **default**
1405 Also a special variable - if an expression evaluates to this, then the
1406 existing HTML in the template will not be replaced or removed, it will
1407 remain. So::
1409 <span tal:replace="default">Hello, World!</span>
1411 would result in::
1413 <span>Hello, World!</span>
1416 The context variable
1417 ~~~~~~~~~~~~~~~~~~~~
1419 The *context* variable is one of three things based on the current
1420 context (see `determining web context`_ for how we figure this out):
1422 1. if we're looking at a "home" page, then it's None
1423 2. if we're looking at a specific hyperdb class, it's a
1424 `hyperdb class wrapper`_.
1425 3. if we're looking at a specific hyperdb item, it's a
1426 `hyperdb item wrapper`_.
1428 If the context is not None, we can access the properties of the class or
1429 item. The only real difference between cases 2 and 3 above are:
1431 1. the properties may have a real value behind them, and this will
1432 appear if the property is displayed through ``context/property`` or
1433 ``context/property/field``.
1434 2. the context's "id" property will be a false value in the second case,
1435 but a real, or true value in the third. Thus we can determine whether
1436 we're looking at a real item from the hyperdb by testing
1437 "context/id".
1439 Hyperdb class wrapper
1440 :::::::::::::::::::::
1442 Note: this is implemented by the ``roundup.cgi.templating.HTMLClass``
1443 class.
1445 This wrapper object provides access to a hyperb class. It is used
1446 primarily in both index view and new item views, but it's also usable
1447 anywhere else that you wish to access information about a class, or the
1448 items of a class, when you don't have a specific item of that class in
1449 mind.
1451 We allow access to properties. There will be no "id" property. The value
1452 accessed through the property will be the current value of the same name
1453 from the CGI form.
1455 There are several methods available on these wrapper objects:
1457 =========== =============================================================
1458 Method Description
1459 =========== =============================================================
1460 properties return a `hyperdb property wrapper`_ for all of this class's
1461 properties.
1462 list lists all of the active (not retired) items in the class.
1463 csv return the items of this class as a chunk of CSV text.
1464 propnames lists the names of the properties of this class.
1465 filter lists of items from this class, filtered and sorted by the
1466 current *request* filterspec/filter/sort/group args
1467 classhelp display a link to a javascript popup containing this class'
1468 "help" template.
1469 submit generate a submit button (and action hidden element)
1470 renderWith render this class with the given template.
1471 history returns 'New node - no history' :)
1472 is_edit_ok is the user allowed to Edit the current class?
1473 is_view_ok is the user allowed to View the current class?
1474 =========== =============================================================
1476 Note that if you have a property of the same name as one of the above
1477 methods, you'll need to access it using a python "item access"
1478 expression. For example::
1480 python:context['list']
1482 will access the "list" property, rather than the list method.
1485 Hyperdb item wrapper
1486 ::::::::::::::::::::
1488 Note: this is implemented by the ``roundup.cgi.templating.HTMLItem``
1489 class.
1491 This wrapper object provides access to a hyperb item.
1493 We allow access to properties. There will be no "id" property. The value
1494 accessed through the property will be the current value of the same name
1495 from the CGI form.
1497 There are several methods available on these wrapper objects:
1499 =============== ========================================================
1500 Method Description
1501 =============== ========================================================
1502 submit generate a submit button (and action hidden element)
1503 journal return the journal of the current item (**not
1504 implemented**)
1505 history render the journal of the current item as HTML
1506 renderQueryForm specific to the "query" class - render the search form
1507 for the query
1508 hasPermission specific to the "user" class - determine whether the
1509 user has a Permission
1510 is_edit_ok is the user allowed to Edit the current item?
1511 is_view_ok is the user allowed to View the current item?
1512 =============== ========================================================
1514 Note that if you have a property of the same name as one of the above
1515 methods, you'll need to access it using a python "item access"
1516 expression. For example::
1518 python:context['journal']
1520 will access the "journal" property, rather than the journal method.
1523 Hyperdb property wrapper
1524 ::::::::::::::::::::::::
1526 Note: this is implemented by subclasses of the
1527 ``roundup.cgi.templating.HTMLProperty`` class (``HTMLStringProperty``,
1528 ``HTMLNumberProperty``, and so on).
1530 This wrapper object provides access to a single property of a class. Its
1531 value may be either:
1533 1. if accessed through a `hyperdb item wrapper`_, then it's a value from
1534 the hyperdb
1535 2. if access through a `hyperdb class wrapper`_, then it's a value from
1536 the CGI form
1539 The property wrapper has some useful attributes:
1541 =============== ========================================================
1542 Attribute Description
1543 =============== ========================================================
1544 _name the name of the property
1545 _value the value of the property if any - this is the actual
1546 value retrieved from the hyperdb for this property
1547 =============== ========================================================
1549 There are several methods available on these wrapper objects:
1551 =========== ================================================================
1552 Method Description
1553 =========== ================================================================
1554 plain render a "plain" representation of the property. This method
1555 may take two arguments:
1557 escape
1558 If true, escape the text so it is HTML safe (default: no). The
1559 reason this defaults to off is that text is usually escaped
1560 at a later stage by the TAL commands, unless the "structure"
1561 option is used in the template. The following ``tal:content``
1562 expressions are all equivalent::
1564 "structure python:msg.content.plain(escape=1)"
1565 "python:msg.content.plain()"
1566 "msg/content/plain"
1567 "msg/content"
1569 Usually you'll only want to use the escape option in a
1570 complex expression.
1572 hyperlink
1573 If true, turn URLs, email addresses and hyperdb item
1574 designators in the text into hyperlinks (default: no). Note
1575 that you'll need to use the "structure" TAL option if you
1576 want to use this ``tal:content`` expression::
1578 "structure python:msg.content.plain(hyperlink=1)"
1580 Note also that the text is automatically HTML-escaped before
1581 the hyperlinking transformation.
1582 hyperlinked The same as msg.content.plain(hyperlink=1), but nicer::
1584 "structure msg/content/hyperlinked"
1586 field render an appropriate form edit field for the property - for
1587 most types this is a text entry box, but for Booleans it's a
1588 tri-state yes/no/neither selection.
1589 stext only on String properties - render the value of the property
1590 as StructuredText (requires the StructureText module to be
1591 installed separately)
1592 multiline only on String properties - render a multiline form edit
1593 field for the property
1594 email only on String properties - render the value of the property
1595 as an obscured email address
1596 confirm only on Password properties - render a second form edit field
1597 for the property, used for confirmation that the user typed
1598 the password correctly. Generates a field with name
1599 "name:confirm".
1600 now only on Date properties - return the current date as a new
1601 property
1602 reldate only on Date properties - render the interval between the date
1603 and now
1604 local only on Date properties - return this date as a new property
1605 with some timezone offset, for example::
1607 python:context.creation.local(10)
1609 will render the date with a +10 hour offset.
1610 pretty only on Interval properties - render the interval in a pretty
1611 format (eg. "yesterday")
1612 menu only on Link and Multilink properties - render a form select
1613 list for this property
1614 reverse only on Multilink properties - produce a list of the linked
1615 items in reverse order
1616 =========== ================================================================
1619 The request variable
1620 ~~~~~~~~~~~~~~~~~~~~
1622 Note: this is implemented by the ``roundup.cgi.templating.HTMLRequest``
1623 class.
1625 The request variable is packed with information about the current
1626 request.
1628 .. taken from ``roundup.cgi.templating.HTMLRequest`` docstring
1630 =========== ============================================================
1631 Variable Holds
1632 =========== ============================================================
1633 form the CGI form as a cgi.FieldStorage
1634 env the CGI environment variables
1635 base the base URL for this tracker
1636 user a HTMLUser instance for this user
1637 classname the current classname (possibly None)
1638 template the current template (suffix, also possibly None)
1639 form the current CGI form variables in a FieldStorage
1640 =========== ============================================================
1642 **Index page specific variables (indexing arguments)**
1644 =========== ============================================================
1645 Variable Holds
1646 =========== ============================================================
1647 columns dictionary of the columns to display in an index page
1648 show a convenience access to columns - request/show/colname will
1649 be true if the columns should be displayed, false otherwise
1650 sort index sort column (direction, column name)
1651 group index grouping property (direction, column name)
1652 filter properties to filter the index on
1653 filterspec values to filter the index on
1654 search_text text to perform a full-text search on for an index
1655 =========== ============================================================
1657 There are several methods available on the request variable:
1659 =============== ========================================================
1660 Method Description
1661 =============== ========================================================
1662 description render a description of the request - handle for the
1663 page title
1664 indexargs_form render the current index args as form elements
1665 indexargs_url render the current index args as a URL
1666 base_javascript render some javascript that is used by other components
1667 of the templating
1668 batch run the current index args through a filter and return a
1669 list of items (see `hyperdb item wrapper`_, and
1670 `batching`_)
1671 =============== ========================================================
1673 The form variable
1674 :::::::::::::::::
1676 The form variable is a bit special because it's actually a python
1677 FieldStorage object. That means that you have two ways to access its
1678 contents. For example, to look up the CGI form value for the variable
1679 "name", use the path expression::
1681 request/form/name/value
1683 or the python expression::
1685 python:request.form['name'].value
1687 Note the "item" access used in the python case, and also note the
1688 explicit "value" attribute we have to access. That's because the form
1689 variables are stored as MiniFieldStorages. If there's more than one
1690 "name" value in the form, then the above will break since
1691 ``request/form/name`` is actually a *list* of MiniFieldStorages. So it's
1692 best to know beforehand what you're dealing with.
1695 The db variable
1696 ~~~~~~~~~~~~~~~
1698 Note: this is implemented by the ``roundup.cgi.templating.HTMLDatabase``
1699 class.
1701 Allows access to all hyperdb classes as attributes of this variable. If
1702 you want access to the "user" class, for example, you would use::
1704 db/user
1705 python:db.user
1707 Also, the current id of the current user is available as
1708 ``db.getuid()``. This isn't so useful in templates (where you have
1709 ``request/user``), but it can be useful in detectors or interfaces.
1711 The access results in a `hyperdb class wrapper`_.
1714 The templates variable
1715 ~~~~~~~~~~~~~~~~~~~~~~
1717 Note: this is implemented by the ``roundup.cgi.templating.Templates``
1718 class.
1720 This variable doesn't have any useful methods defined. It supports being
1721 used in expressions to access the templates, and consequently the
1722 template macros. You may access the templates using the following path
1723 expression::
1725 templates/name
1727 or the python expression::
1729 templates[name]
1731 where "name" is the name of the template you wish to access. The
1732 template has one useful attribute, namely "macros". To access a specific
1733 macro (called "macro_name"), use the path expression::
1735 templates/name/macros/macro_name
1737 or the python expression::
1739 templates[name].macros[macro_name]
1742 The utils variable
1743 ~~~~~~~~~~~~~~~~~~
1745 Note: this is implemented by the
1746 ``roundup.cgi.templating.TemplatingUtils`` class, but it may be extended
1747 as described below.
1749 =============== ========================================================
1750 Method Description
1751 =============== ========================================================
1752 Batch return a batch object using the supplied list
1753 =============== ========================================================
1755 You may add additional utility methods by writing them in your tracker
1756 ``interfaces.py`` module's ``TemplatingUtils`` class. See `adding a time
1757 log to your issues`_ for an example. The TemplatingUtils class itself
1758 will have a single attribute, ``client``, which may be used to access
1759 the ``client.db`` when you need to perform arbitrary database queries.
1761 Batching
1762 ::::::::
1764 Use Batch to turn a list of items, or item ids of a given class, into a
1765 series of batches. Its usage is::
1767 python:utils.Batch(sequence, size, start, end=0, orphan=0,
1768 overlap=0)
1770 or, to get the current index batch::
1772 request/batch
1774 The parameters are:
1776 ========= ==============================================================
1777 Parameter Usage
1778 ========= ==============================================================
1779 sequence a list of HTMLItems
1780 size how big to make the sequence.
1781 start where to start (0-indexed) in the sequence.
1782 end where to end (0-indexed) in the sequence.
1783 orphan if the next batch would contain less items than this value,
1784 then it is combined with this batch
1785 overlap the number of items shared between adjacent batches
1786 ========= ==============================================================
1788 All of the parameters are assigned as attributes on the batch object. In
1789 addition, it has several more attributes:
1791 =============== ========================================================
1792 Attribute Description
1793 =============== ========================================================
1794 start indicates the start index of the batch. *Note: unlike
1795 the argument, is a 1-based index (I know, lame)*
1796 first indicates the start index of the batch *as a 0-based
1797 index*
1798 length the actual number of elements in the batch
1799 sequence_length the length of the original, unbatched, sequence.
1800 =============== ========================================================
1802 And several methods:
1804 =============== ========================================================
1805 Method Description
1806 =============== ========================================================
1807 previous returns a new Batch with the previous batch settings
1808 next returns a new Batch with the next batch settings
1809 propchanged detect if the named property changed on the current item
1810 when compared to the last item
1811 =============== ========================================================
1813 An example of batching::
1815 <table class="otherinfo">
1816 <tr><th colspan="4" class="header">Existing Keywords</th></tr>
1817 <tr tal:define="keywords db/keyword/list"
1818 tal:repeat="start python:range(0, len(keywords), 4)">
1819 <td tal:define="batch python:utils.Batch(keywords, 4, start)"
1820 tal:repeat="keyword batch" tal:content="keyword/name">
1821 keyword here</td>
1822 </tr>
1823 </table>
1825 ... which will produce a table with four columns containing the items of
1826 the "keyword" class (well, their "name" anyway).
1828 Displaying Properties
1829 ---------------------
1831 Properties appear in the user interface in three contexts: in indices,
1832 in editors, and as search arguments. For each type of property, there
1833 are several display possibilities. For example, in an index view, a
1834 string property may just be printed as a plain string, but in an editor
1835 view, that property may be displayed in an editable field.
1838 Index Views
1839 -----------
1841 This is one of the class context views. It is also the default view for
1842 classes. The template used is "*classname*.index".
1845 Index View Specifiers
1846 ~~~~~~~~~~~~~~~~~~~~~
1848 An index view specifier (URL fragment) looks like this (whitespace has
1849 been added for clarity)::
1851 /issue?status=unread,in-progress,resolved&
1852 topic=security,ui&
1853 :group=+priority&
1854 :sort==activity&
1855 :filters=status,topic&
1856 :columns=title,status,fixer
1858 The index view is determined by two parts of the specifier: the layout
1859 part and the filter part. The layout part consists of the query
1860 parameters that begin with colons, and it determines the way that the
1861 properties of selected items are displayed. The filter part consists of
1862 all the other query parameters, and it determines the criteria by which
1863 items are selected for display. The filter part is interactively
1864 manipulated with the form widgets displayed in the filter section. The
1865 layout part is interactively manipulated by clicking on the column
1866 headings in the table.
1868 The filter part selects the union of the sets of items with values
1869 matching any specified Link properties and the intersection of the sets
1870 of items with values matching any specified Multilink properties.
1872 The example specifies an index of "issue" items. Only items with a
1873 "status" of either "unread" or "in-progress" or "resolved" are
1874 displayed, and only items with "topic" values including both "security"
1875 and "ui" are displayed. The items are grouped by priority, arranged in
1876 ascending order; and within groups, sorted by activity, arranged in
1877 descending order. The filter section shows filters for the "status" and
1878 "topic" properties, and the table includes columns for the "title",
1879 "status", and "fixer" properties.
1881 Searching Views
1882 ---------------
1884 Note: if you add a new column to the ``:columns`` form variable
1885 potentials then you will need to add the column to the appropriate
1886 `index views`_ template so that it is actually displayed.
1888 This is one of the class context views. The template used is typically
1889 "*classname*.search". The form on this page should have "search" as its
1890 ``@action`` variable. The "search" action:
1892 - sets up additional filtering, as well as performing indexed text
1893 searching
1894 - sets the ``:filter`` variable correctly
1895 - saves the query off if ``:query_name`` is set.
1897 The search page should lay out any fields that you wish to allow the
1898 user to search on. If your schema contains a large number of properties,
1899 you should be wary of making all of those properties available for
1900 searching, as this can cause confusion. If the additional properties are
1901 Strings, consider having their value indexed, and then they will be
1902 searchable using the full text indexed search. This is both faster, and
1903 more useful for the end user.
1905 The two special form values on search pages which are handled by the
1906 "search" action are:
1908 :search_text
1909 Text with which to perform a search of the text index. Results from
1910 that search will be used to limit the results of other filters (using
1911 an intersection operation)
1912 :query_name
1913 If supplied, the search parameters (including :search_text) will be
1914 saved off as a the query item and registered against the user's
1915 queries property. Note that the *classic* template schema has this
1916 ability, but the *minimal* template schema does not.
1919 Item Views
1920 ----------
1922 The basic view of a hyperdb item is provided by the "*classname*.item"
1923 template. It generally has three sections; an "editor", a "spool" and a
1924 "history" section.
1927 Editor Section
1928 ~~~~~~~~~~~~~~
1930 The editor section is used to manipulate the item - it may be a static
1931 display if the user doesn't have permission to edit the item.
1933 Here's an example of a basic editor template (this is the default
1934 "classic" template issue item edit form - from the "issue.item.html"
1935 template)::
1937 <table class="form">
1938 <tr>
1939 <th>Title</th>
1940 <td colspan="3" tal:content="structure python:context.title.field(size=60)">title</td>
1941 </tr>
1943 <tr>
1944 <th>Priority</th>
1945 <td tal:content="structure context/priority/menu">priority</td>
1946 <th>Status</th>
1947 <td tal:content="structure context/status/menu">status</td>
1948 </tr>
1950 <tr>
1951 <th>Superseder</th>
1952 <td>
1953 <span tal:replace="structure python:context.superseder.field(showid=1, size=20)" />
1954 <span tal:replace="structure python:db.issue.classhelp('id,title')" />
1955 <span tal:condition="context/superseder">
1956 <br>View: <span tal:replace="structure python:context.superseder.link(showid=1)" />
1957 </span>
1958 </td>
1959 <th>Nosy List</th>
1960 <td>
1961 <span tal:replace="structure context/nosy/field" />
1962 <span tal:replace="structure python:db.user.classhelp('username,realname,address,phone')" />
1963 </td>
1964 </tr>
1966 <tr>
1967 <th>Assigned To</th>
1968 <td tal:content="structure context/assignedto/menu">
1969 assignedto menu
1970 </td>
1971 <td> </td>
1972 <td> </td>
1973 </tr>
1975 <tr>
1976 <th>Change Note</th>
1977 <td colspan="3">
1978 <textarea name=":note" wrap="hard" rows="5" cols="60"></textarea>
1979 </td>
1980 </tr>
1982 <tr>
1983 <th>File</th>
1984 <td colspan="3"><input type="file" name=":file" size="40"></td>
1985 </tr>
1987 <tr>
1988 <td> </td>
1989 <td colspan="3" tal:content="structure context/submit">
1990 submit button will go here
1991 </td>
1992 </tr>
1993 </table>
1996 When a change is submitted, the system automatically generates a message
1997 describing the changed properties. As shown in the example, the editor
1998 template can use the ":note" and ":file" fields, which are added to the
1999 standard changenote message generated by Roundup.
2002 Form values
2003 :::::::::::
2005 We have a number of ways to pull properties out of the form in order to
2006 meet the various needs of:
2008 1. editing the current item (perhaps an issue item)
2009 2. editing information related to the current item (eg. messages or
2010 attached files)
2011 3. creating new information to be linked to the current item (eg. time
2012 spent on an issue)
2014 In the following, ``<bracketed>`` values are variable, ":" may be one of
2015 ":" or "@", and other text ("required") is fixed.
2017 Properties are specified as form variables:
2019 ``<propname>``
2020 property on the current context item
2022 ``<designator>:<propname>``
2023 property on the indicated item (for editing related information)
2025 ``<classname>-<N>:<propname>``
2026 property on the Nth new item of classname (generally for creating new
2027 items to attach to the current item)
2029 Once we have determined the "propname", we check to see if it is one of
2030 the special form values:
2032 ``@required``
2033 The named property values must be supplied or a ValueError will be
2034 raised.
2036 ``@remove@<propname>=id(s)``
2037 The ids will be removed from the multilink property.
2039 ``:add:<propname>=id(s)``
2040 The ids will be added to the multilink property.
2042 ``:link:<propname>=<designator>``
2043 Used to add a link to new items created during edit. These are
2044 collected and returned in ``all_links``. This will result in an
2045 additional linking operation (either Link set or Multilink append)
2046 after the edit/create is done using ``all_props`` in ``_editnodes``.
2047 The <propname> on the current item will be set/appended the id of the
2048 newly created item of class <designator> (where <designator> must be
2049 <classname>-<N>).
2051 Any of the form variables may be prefixed with a classname or
2052 designator.
2054 Two special form values are supported for backwards compatibility:
2056 ``:note``
2057 create a message (with content, author and date), linked to the
2058 context item. This is ALWAYS designated "msg-1".
2059 ``:file``
2060 create a file, attached to the current item and any message created by
2061 :note. This is ALWAYS designated "file-1".
2064 Spool Section
2065 ~~~~~~~~~~~~~
2067 The spool section lists related information like the messages and files
2068 of an issue.
2070 TODO
2073 History Section
2074 ~~~~~~~~~~~~~~~
2076 The final section displayed is the history of the item - its database
2077 journal. This is generally generated with the template::
2079 <tal:block tal:replace="structure context/history" />
2081 *To be done:*
2083 *The actual history entries of the item may be accessed for manual
2084 templating through the "journal" method of the item*::
2086 <tal:block tal:repeat="entry context/journal">
2087 a journal entry
2088 </tal:block>
2090 *where each journal entry is an HTMLJournalEntry.*
2092 Defining new web actions
2093 ------------------------
2095 You may define new actions to be triggered by the ``@action`` form variable.
2096 These are added to the tracker ``interfaces.py`` as ``Action`` classes that get
2097 called by the the ``Client`` class.
2099 Adding action classes takes three steps; first you `define the new
2100 action class`_, then you `register the action class`_ with the cgi
2101 interface so it may be triggered by the ``@action`` form variable.
2102 Finally you `use the new action`_ in your HTML form.
2104 See "`setting up a "wizard" (or "druid") for controlled adding of
2105 issues`_" for an example.
2108 Define the new action class
2109 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2111 The action classes have the following interface::
2113 class MyAction(Action):
2114 def handle(self):
2115 ''' Perform some action. No return value is required.
2116 '''
2118 The *self.client* attribute is an instance of your tracker ``instance.Client``
2119 class - thus it's mostly implemented by ``roundup.cgi.client.Client``. See the
2120 docstring of that class for details of what it can do.
2122 The method will typically check the ``self.form`` variable's contents.
2123 It may then:
2125 - add information to ``self.client.ok_message`` or ``self.client.error_message``
2126 - change the ``self.client.template`` variable to alter what the user will see
2127 next
2128 - raise Unauthorised, SendStaticFile, SendFile, NotFound or Redirect
2129 exceptions (import them from roundup.cgi.exceptions)
2132 Register the action class
2133 ~~~~~~~~~~~~~~~~~~~~~~~~~~
2135 The class is now written, but isn't available to the user until you add it to
2136 the ``instance.Client`` class ``actions`` variable, like so::
2138 actions = client.Client.actions + (
2139 ('myaction', myActionClass),
2140 )
2142 This maps the action name "myaction" to the action class we defined.
2144 Use the new action
2145 ~~~~~~~~~~~~~~~~~~
2147 In your HTML form, add a hidden form element like so::
2149 <input type="hidden" name="@action" value="myaction">
2151 where "myaction" is the name you registered in the previous step.
2153 Actions may return content to the user
2154 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2156 Actions generally perform some database manipulation and then pass control
2157 on to the rendering of a template in the current context (see `Determining
2158 web context`_ for how that works.) Some actions will want to generate the
2159 actual content returned to the user. Action methods may return their own
2160 content string to be displayed to the user, overriding the templating step.
2161 In this situation, we assume that the content is HTML by default. You may
2162 override the content type indicated to the user by calling ``setHeader``::
2164 self.client.setHeader('Content-Type', 'text/csv')
2166 This example indicates that the value sent back to the user is actually
2167 comma-separated value content (eg. something to be loaded into a
2168 spreadsheet or database).
2171 Examples
2172 ========
2174 .. contents::
2175 :local:
2176 :depth: 1
2179 Adding a new field to the classic schema
2180 ----------------------------------------
2182 This example shows how to add a new constrained property (i.e. a
2183 selection of distinct values) to your tracker.
2186 Introduction
2187 ~~~~~~~~~~~~
2189 To make the classic schema of roundup useful as a TODO tracking system
2190 for a group of systems administrators, it needed an extra data field per
2191 issue: a category.
2193 This would let sysadmins quickly list all TODOs in their particular area
2194 of interest without having to do complex queries, and without relying on
2195 the spelling capabilities of other sysadmins (a losing proposition at
2196 best).
2199 Adding a field to the database
2200 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2202 This is the easiest part of the change. The category would just be a
2203 plain string, nothing fancy. To change what is in the database you need
2204 to add some lines to the ``open()`` function in ``dbinit.py``. Under the
2205 comment::
2207 # add any additional database schema configuration here
2209 add::
2211 category = Class(db, "category", name=String())
2212 category.setkey("name")
2214 Here we are setting up a chunk of the database which we are calling
2215 "category". It contains a string, which we are refering to as "name" for
2216 lack of a more imaginative title. (Since "name" is one of the properties
2217 that Roundup looks for on items if you do not set a key for them, it's
2218 probably a good idea to stick with it for new classes if at all
2219 appropriate.) Then we are setting the key of this chunk of the database
2220 to be that "name". This is equivalent to an index for database types.
2221 This also means that there can only be one category with a given name.
2223 Adding the above lines allows us to create categories, but they're not
2224 tied to the issues that we are going to be creating. It's just a list of
2225 categories off on its own, which isn't much use. We need to link it in
2226 with the issues. To do that, find the lines in the ``open()`` function
2227 in ``dbinit.py`` which set up the "issue" class, and then add a link to
2228 the category::
2230 issue = IssueClass(db, "issue", ... ,
2231 category=Multilink("category"), ... )
2233 The ``Multilink()`` means that each issue can have many categories. If
2234 you were adding something with a one-to-one relationship to issues (such
2235 as the "assignedto" property), use ``Link()`` instead.
2237 That is all you need to do to change the schema. The rest of the effort
2238 is fiddling around so you can actually use the new category.
2241 Populating the new category class
2242 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2244 If you haven't initialised the database with the roundup-admin
2245 "initialise" command, then you can add the following to the tracker
2246 ``dbinit.py`` in the ``init()`` function under the comment::
2248 # add any additional database create steps here - but only if you
2249 # haven't initialised the database with the admin "initialise" command
2251 Add::
2253 category = db.getclass('category')
2254 category.create(name="scipy", order="1")
2255 category.create(name="chaco", order="2")
2256 category.create(name="weave", order="3")
2258 If the database has already been initalised, then you need to use the
2259 ``roundup-admin`` tool::
2261 % roundup-admin -i <tracker home>
2262 Roundup <version> ready for input.
2263 Type "help" for help.
2264 roundup> create category name=scipy order=1
2265 1
2266 roundup> create category name=chaco order=1
2267 2
2268 roundup> create category name=weave order=1
2269 3
2270 roundup> exit...
2271 There are unsaved changes. Commit them (y/N)? y
2273 TODO: explain why order=1 in each case. Also, does key get set to "name"
2274 automatically when added via roundup-admin?
2277 Setting up security on the new objects
2278 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2280 By default only the admin user can look at and change objects. This
2281 doesn't suit us, as we want any user to be able to create new categories
2282 as required, and obviously everyone needs to be able to view the
2283 categories of issues for it to be useful.
2285 We therefore need to change the security of the category objects. This
2286 is also done in the ``open()`` function of ``dbinit.py``.
2288 There are currently two loops which set up permissions and then assign
2289 them to various roles. Simply add the new "category" to both lists::
2291 # new permissions for this schema
2292 for cl in 'issue', 'file', 'msg', 'user', 'category':
2293 db.security.addPermission(name="Edit", klass=cl,
2294 description="User is allowed to edit "+cl)
2295 db.security.addPermission(name="View", klass=cl,
2296 description="User is allowed to access "+cl)
2298 # Assign the access and edit permissions for issue, file and message
2299 # to regular users now
2300 for cl in 'issue', 'file', 'msg', 'category':
2301 p = db.security.getPermission('View', cl)
2302 db.security.addPermissionToRole('User', p)
2303 p = db.security.getPermission('Edit', cl)
2304 db.security.addPermissionToRole('User', p)
2306 So you are in effect doing the following (with 'cl' substituted by its
2307 value)::
2309 db.security.addPermission(name="Edit", klass='category',
2310 description="User is allowed to edit "+'category')
2311 db.security.addPermission(name="View", klass='category',
2312 description="User is allowed to access "+'category')
2314 which is creating two permission types; that of editing and viewing
2315 "category" objects respectively. Then the following lines assign those
2316 new permissions to the "User" role, so that normal users can view and
2317 edit "category" objects::
2319 p = db.security.getPermission('View', 'category')
2320 db.security.addPermissionToRole('User', p)
2322 p = db.security.getPermission('Edit', 'category')
2323 db.security.addPermissionToRole('User', p)
2325 This is all the work that needs to be done for the database. It will
2326 store categories, and let users view and edit them. Now on to the
2327 interface stuff.
2330 Changing the web left hand frame
2331 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2333 We need to give the users the ability to create new categories, and the
2334 place to put the link to this functionality is in the left hand function
2335 bar, under the "Issues" area. The file that defines how this area looks
2336 is ``html/page``, which is what we are going to be editing next.
2338 If you look at this file you can see that it contains a lot of
2339 "classblock" sections which are chunks of HTML that will be included or
2340 excluded in the output depending on whether the condition in the
2341 classblock is met. Under the end of the classblock for issue is where we
2342 are going to add the category code::
2344 <p class="classblock"
2345 tal:condition="python:request.user.hasPermission('View', 'category')">
2346 <b>Categories</b><br>
2347 <a tal:condition="python:request.user.hasPermission('Edit', 'category')"
2348 href="category?@template=item">New Category<br></a>
2349 </p>
2351 The first two lines is the classblock definition, which sets up a
2352 condition that only users who have "View" permission for the "category"
2353 object will have this section included in their output. Next comes a
2354 plain "Categories" header in bold. Everyone who can view categories will
2355 get that.
2357 Next comes the link to the editing area of categories. This link will
2358 only appear if the condition - that the user has "Edit" permissions for
2359 the "category" objects - is matched. If they do have permission then
2360 they will get a link to another page which will let the user add new
2361 categories.
2363 Note that if you have permission to *view* but not to *edit* categories,
2364 then all you will see is a "Categories" header with nothing underneath
2365 it. This is obviously not very good interface design, but will do for
2366 now. I just claim that it is so I can add more links in this section
2367 later on. However to fix the problem you could change the condition in
2368 the classblock statement, so that only users with "Edit" permission
2369 would see the "Categories" stuff.
2372 Setting up a page to edit categories
2373 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2375 We defined code in the previous section which let users with the
2376 appropriate permissions see a link to a page which would let them edit
2377 conditions. Now we have to write that page.
2379 The link was for the *item* template of the *category* object. This
2380 translates into Roundup looking for a file called ``category.item.html``
2381 in the ``html`` tracker directory. This is the file that we are going to
2382 write now.
2384 First we add an info tag in a comment which doesn't affect the outcome
2385 of the code at all, but is useful for debugging. If you load a page in a
2386 browser and look at the page source, you can see which sections come
2387 from which files by looking for these comments::
2389 <!-- category.item -->
2391 Next we need to add in the METAL macro stuff so we get the normal page
2392 trappings::
2394 <tal:block metal:use-macro="templates/page/macros/icing">
2395 <title metal:fill-slot="head_title">Category editing</title>
2396 <td class="page-header-top" metal:fill-slot="body_title">
2397 <h2>Category editing</h2>
2398 </td>
2399 <td class="content" metal:fill-slot="content">
2401 Next we need to setup up a standard HTML form, which is the whole
2402 purpose of this file. We link to some handy javascript which sends the
2403 form through only once. This is to stop users hitting the send button
2404 multiple times when they are impatient and thus having the form sent
2405 multiple times::
2407 <form method="POST" onSubmit="return submit_once()"
2408 enctype="multipart/form-data">
2410 Next we define some code which sets up the minimum list of fields that
2411 we require the user to enter. There will be only one field - "name" - so
2412 they better put something in it, otherwise the whole form is pointless::
2414 <input type="hidden" name="@required" value="name">
2416 To get everything to line up properly we will put everything in a table,
2417 and put a nice big header on it so the user has an idea what is
2418 happening::
2420 <table class="form">
2421 <tr><th class="header" colspan="2">Category</th></tr>
2423 Next, we need the field into which the user is going to enter the new
2424 category. The "context.name.field(size=60)" bit tells Roundup to
2425 generate a normal HTML field of size 60, and the contents of that field
2426 will be the "name" variable of the current context (which is
2427 "category"). The upshot of this is that when the user types something in
2428 to the form, a new category will be created with that name::
2430 <tr>
2431 <th>Name</th>
2432 <td tal:content="structure python:context.name.field(size=60)">
2433 name</td>
2434 </tr>
2436 Then a submit button so that the user can submit the new category::
2438 <tr>
2439 <td> </td>
2440 <td colspan="3" tal:content="structure context/submit">
2441 submit button will go here
2442 </td>
2443 </tr>
2445 Finally we finish off the tags we used at the start to do the METAL
2446 stuff::
2448 </td>
2449 </tal:block>
2451 So putting it all together, and closing the table and form we get::
2453 <!-- category.item -->
2454 <tal:block metal:use-macro="templates/page/macros/icing">
2455 <title metal:fill-slot="head_title">Category editing</title>
2456 <td class="page-header-top" metal:fill-slot="body_title">
2457 <h2>Category editing</h2>
2458 </td>
2459 <td class="content" metal:fill-slot="content">
2460 <form method="POST" onSubmit="return submit_once()"
2461 enctype="multipart/form-data">
2463 <table class="form">
2464 <tr><th class="header" colspan="2">Category</th></tr>
2466 <tr>
2467 <th>Name</th>
2468 <td tal:content="structure python:context.name.field(size=60)">
2469 name</td>
2470 </tr>
2472 <tr>
2473 <td>
2474
2475 <input type="hidden" name="@required" value="name">
2476 </td>
2477 <td colspan="3" tal:content="structure context/submit">
2478 submit button will go here
2479 </td>
2480 </tr>
2481 </table>
2482 </form>
2483 </td>
2484 </tal:block>
2486 This is quite a lot to just ask the user one simple question, but there
2487 is a lot of setup for basically one line (the form line) to do its work.
2488 To add another field to "category" would involve one more line (well,
2489 maybe a few extra to get the formatting correct).
2492 Adding the category to the issue
2493 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2495 We now have the ability to create issues to our heart's content, but
2496 that is pointless unless we can assign categories to issues. Just like
2497 the ``html/category.item.html`` file was used to define how to add a new
2498 category, the ``html/issue.item.html`` is used to define how a new issue
2499 is created.
2501 Just like ``category.issue.html`` this file defines a form which has a
2502 table to lay things out. It doesn't matter where in the table we add new
2503 stuff, it is entirely up to your sense of aesthetics::
2505 <th>Category</th>
2506 <td><span tal:replace="structure context/category/field" />
2507 <span tal:replace="structure db/category/classhelp" />
2508 </td>
2510 First, we define a nice header so that the user knows what the next
2511 section is, then the middle line does what we are most interested in.
2512 This ``context/category/field`` gets replaced by a field which contains
2513 the category in the current context (the current context being the new
2514 issue).
2516 The classhelp lines generate a link (labelled "list") to a popup window
2517 which contains the list of currently known categories.
2520 Searching on categories
2521 ~~~~~~~~~~~~~~~~~~~~~~~
2523 We can add categories, and create issues with categories. The next
2524 obvious thing that we would like to be able to do, would be to search
2525 for issues based on their category, so that, for example, anyone working
2526 on the web server could look at all issues in the category "Web".
2528 If you look for "Search Issues" in the 'html/page.html' file, you will
2529 find that it looks something like
2530 ``<a href="issue?@template=search">Search Issues</a>``. This shows us
2531 that when you click on "Search Issues" it will be looking for a
2532 ``issue.search.html`` file to display. So that is the file that we will
2533 change.
2535 If you look at this file it should be starting to seem familiar, although it
2536 does use some new macros. You can add the new category search code anywhere you
2537 like within that form::
2539 <tr tal:define="name string:category;
2540 db_klass string:category;
2541 db_content string:name;">
2542 <th>Priority:</th>
2543 <td metal:use-macro="search_select"></td>
2544 <td metal:use-macro="column_input"></td>
2545 <td metal:use-macro="sort_input"></td>
2546 <td metal:use-macro="group_input"></td>
2547 </tr>
2549 The definitions in the <tr> opening tag are used by the macros:
2551 - search_select expands to a drop-down box with all categories using db_klass
2552 and db_content.
2553 - column_input expands to a checkbox for selecting what columns should be
2554 displayed.
2555 - sort_input expands to a radio button for selecting what property should be
2556 sorted on.
2557 - group_input expands to a radio button for selecting what property should be
2558 group on.
2560 The category search code above would expand to the following::
2562 <tr>
2563 <th>Category:</th>
2564 <td>
2565 <select name="category">
2566 <option value="">don't care</option>
2567 <option value="">------------</option>
2568 <option value="1">scipy</option>
2569 <option value="2">chaco</option>
2570 <option value="3">weave</option>
2571 </select>
2572 </td>
2573 <td><input type="checkbox" name=":columns" value="category"></td>
2574 <td><input type="radio" name=":sort" value="category"></td>
2575 <td><input type="radio" name=":group" value="category"></td>
2576 </tr>
2578 Adding category to the default view
2579 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2581 We can now add categories, add issues with categories, and search for
2582 issues based on categories. This is everything that we need to do;
2583 however, there is some more icing that we would like. I think the
2584 category of an issue is important enough that it should be displayed by
2585 default when listing all the issues.
2587 Unfortunately, this is a bit less obvious than the previous steps. The
2588 code defining how the issues look is in ``html/issue.index.html``. This
2589 is a large table with a form down at the bottom for redisplaying and so
2590 forth.
2592 Firstly we need to add an appropriate header to the start of the table::
2594 <th tal:condition="request/show/category">Category</th>
2596 The *condition* part of this statement is to avoid displaying the
2597 Category column if the user has selected not to see it.
2599 The rest of the table is a loop which will go through every issue that
2600 matches the display criteria. The loop variable is "i" - which means
2601 that every issue gets assigned to "i" in turn.
2603 The new part of code to display the category will look like this::
2605 <td tal:condition="request/show/category"
2606 tal:content="i/category"></td>
2608 The condition is the same as above: only display the condition when the
2609 user hasn't asked for it to be hidden. The next part is to set the
2610 content of the cell to be the category part of "i" - the current issue.
2612 Finally we have to edit ``html/page.html`` again. This time, we need to
2613 tell it that when the user clicks on "Unasigned Issues" or "All Issues",
2614 the category column should be included in the resulting list. If you
2615 scroll down the page file, you can see the links with lots of options.
2616 The option that we are interested in is the ``:columns=`` one which
2617 tells roundup which fields of the issue to display. Simply add
2618 "category" to that list and it all should work.
2621 Adding in state transition control
2622 ----------------------------------
2624 Sometimes tracker admins want to control the states that users may move
2625 issues to. You can do this by following these steps:
2627 1. make "status" a required variable. This is achieved by adding the
2628 following to the top of the form in the ``issue.item.html``
2629 template::
2631 <input type="hidden" name="@required" value="status">
2633 this will force users to select a status.
2635 2. add a Multilink property to the status class::
2637 stat = Class(db, "status", ... , transitions=Multilink('status'),
2638 ...)
2640 and then edit the statuses already created, either:
2642 a. through the web using the class list -> status class editor, or
2643 b. using the roundup-admin "set" command.
2645 3. add an auditor module ``checktransition.py`` in your tracker's
2646 ``detectors`` directory, for example::
2648 def checktransition(db, cl, nodeid, newvalues):
2649 ''' Check that the desired transition is valid for the "status"
2650 property.
2651 '''
2652 if not newvalues.has_key('status'):
2653 return
2654 current = cl.get(nodeid, 'status')
2655 new = newvalues['status']
2656 if new == current:
2657 return
2658 ok = db.status.get(current, 'transitions')
2659 if new not in ok:
2660 raise ValueError, 'Status not allowed to move from "%s" to "%s"'%(
2661 db.status.get(current, 'name'), db.status.get(new, 'name'))
2663 def init(db):
2664 db.issue.audit('set', checktransition)
2666 4. in the ``issue.item.html`` template, change the status editing bit
2667 from::
2669 <th>Status</th>
2670 <td tal:content="structure context/status/menu">status</td>
2672 to::
2674 <th>Status</th>
2675 <td>
2676 <select tal:condition="context/id" name="status">
2677 <tal:block tal:define="ok context/status/transitions"
2678 tal:repeat="state db/status/list">
2679 <option tal:condition="python:state.id in ok"
2680 tal:attributes="
2681 value state/id;
2682 selected python:state.id == context.status.id"
2683 tal:content="state/name"></option>
2684 </tal:block>
2685 </select>
2686 <tal:block tal:condition="not:context/id"
2687 tal:replace="structure context/status/menu" />
2688 </td>
2690 which displays only the allowed status to transition to.
2693 Displaying only message summaries in the issue display
2694 ------------------------------------------------------
2696 Alter the issue.item template section for messages to::
2698 <table class="messages" tal:condition="context/messages">
2699 <tr><th colspan="5" class="header">Messages</th></tr>
2700 <tr tal:repeat="msg context/messages">
2701 <td><a tal:attributes="href string:msg${msg/id}"
2702 tal:content="string:msg${msg/id}"></a></td>
2703 <td tal:content="msg/author">author</td>
2704 <td class="date" tal:content="msg/date/pretty">date</td>
2705 <td tal:content="msg/summary">summary</td>
2706 <td>
2707 <a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">
2708 remove</a>
2709 </td>
2710 </tr>
2711 </table>
2713 Restricting the list of users that are assignable to a task
2714 -----------------------------------------------------------
2716 1. In your tracker's "dbinit.py", create a new Role, say "Developer"::
2718 db.security.addRole(name='Developer', description='A developer')
2720 2. Just after that, create a new Permission, say "Fixer", specific to
2721 "issue"::
2723 p = db.security.addPermission(name='Fixer', klass='issue',
2724 description='User is allowed to be assigned to fix issues')
2726 3. Then assign the new Permission to your "Developer" Role::
2728 db.security.addPermissionToRole('Developer', p)
2730 4. In the issue item edit page ("html/issue.item.html" in your tracker
2731 directory), use the new Permission in restricting the "assignedto"
2732 list::
2734 <select name="assignedto">
2735 <option value="-1">- no selection -</option>
2736 <tal:block tal:repeat="user db/user/list">
2737 <option tal:condition="python:user.hasPermission(
2738 'Fixer', context._classname)"
2739 tal:attributes="
2740 value user/id;
2741 selected python:user.id == context.assignedto"
2742 tal:content="user/realname"></option>
2743 </tal:block>
2744 </select>
2746 For extra security, you may wish to setup an auditor to enforce the
2747 Permission requirement (install this as "assignedtoFixer.py" in your
2748 tracker "detectors" directory)::
2750 def assignedtoMustBeFixer(db, cl, nodeid, newvalues):
2751 ''' Ensure the assignedto value in newvalues is a used with the
2752 Fixer Permission
2753 '''
2754 if not newvalues.has_key('assignedto'):
2755 # don't care
2756 return
2758 # get the userid
2759 userid = newvalues['assignedto']
2760 if not db.security.hasPermission('Fixer', userid, cl.classname):
2761 raise ValueError, 'You do not have permission to edit %s'%cl.classname
2763 def init(db):
2764 db.issue.audit('set', assignedtoMustBeFixer)
2765 db.issue.audit('create', assignedtoMustBeFixer)
2767 So now, if an edit action attempts to set "assignedto" to a user that
2768 doesn't have the "Fixer" Permission, the error will be raised.
2771 Setting up a "wizard" (or "druid") for controlled adding of issues
2772 ------------------------------------------------------------------
2774 1. Set up the page templates you wish to use for data input. My wizard
2775 is going to be a two-step process: first figuring out what category
2776 of issue the user is submitting, and then getting details specific to
2777 that category. The first page includes a table of help, explaining
2778 what the category names mean, and then the core of the form::
2780 <form method="POST" onSubmit="return submit_once()"
2781 enctype="multipart/form-data">
2782 <input type="hidden" name="@template" value="add_page1">
2783 <input type="hidden" name="@action" value="page1_submit">
2785 <strong>Category:</strong>
2786 <tal:block tal:replace="structure context/category/menu" />
2787 <input type="submit" value="Continue">
2788 </form>
2790 The next page has the usual issue entry information, with the
2791 addition of the following form fragments::
2793 <form method="POST" onSubmit="return submit_once()"
2794 enctype="multipart/form-data"
2795 tal:condition="context/is_edit_ok"
2796 tal:define="cat request/form/category/value">
2798 <input type="hidden" name="@template" value="add_page2">
2799 <input type="hidden" name="@required" value="title">
2800 <input type="hidden" name="category" tal:attributes="value cat">
2801 .
2802 .
2803 .
2804 </form>
2806 Note that later in the form, I test the value of "cat" include form
2807 elements that are appropriate. For exsample::
2809 <tal:block tal:condition="python:cat in '6 10 13 14 15 16 17'.split()">
2810 <tr>
2811 <th>Operating System</th>
2812 <td tal:content="structure context/os/field"></td>
2813 </tr>
2814 <tr>
2815 <th>Web Browser</th>
2816 <td tal:content="structure context/browser/field"></td>
2817 </tr>
2818 </tal:block>
2820 ... the above section will only be displayed if the category is one
2821 of 6, 10, 13, 14, 15, 16 or 17.
2823 3. Determine what actions need to be taken between the pages - these are
2824 usually to validate user choices and determine what page is next. Now encode
2825 those actions in a new ``Action`` class and insert hooks to those actions in
2826 the "actions" attribute on on the ``interfaces.Client`` class, like so (see
2827 `defining new web actions`_)::
2829 class Page1SubmitAction(Action):
2830 def handle(self):
2831 ''' Verify that the user has selected a category, and then move
2832 on to page 2.
2833 '''
2834 category = self.form['category'].value
2835 if category == '-1':
2836 self.error_message.append('You must select a category of report')
2837 return
2838 # everything's ok, move on to the next page
2839 self.template = 'add_page2'
2841 actions = client.Client.actions + (
2842 ('page1_submit', Page1SubmitAction),
2843 )
2845 4. Use the usual "new" action as the ``@action`` on the final page, and
2846 you're done (the standard context/submit method can do this for you).
2849 Using an external password validation source
2850 --------------------------------------------
2852 We have a centrally-managed password changing system for our users. This
2853 results in a UN*X passwd-style file that we use for verification of
2854 users. Entries in the file consist of ``name:password`` where the
2855 password is encrypted using the standard UN*X ``crypt()`` function (see
2856 the ``crypt`` module in your Python distribution). An example entry
2857 would be::
2859 admin:aamrgyQfDFSHw
2861 Each user of Roundup must still have their information stored in the Roundup
2862 database - we just use the passwd file to check their password. To do this, we
2863 need to override the standard ``verifyPassword`` method defined in
2864 ``roundup.cgi.actions.LoginAction`` and register the new class with our
2865 ``Client`` class in the tracker home ``interfaces.py`` module::
2867 from roundup.cgi.actions import LoginAction
2869 class ExternalPasswordLoginAction(LoginAction):
2870 def verifyPassword(self, userid, password):
2871 # get the user's username
2872 username = self.db.user.get(userid, 'username')
2874 # the passwords are stored in the "passwd.txt" file in the
2875 # tracker home
2876 file = os.path.join(self.db.config.TRACKER_HOME, 'passwd.txt')
2878 # see if we can find a match
2879 for ent in [line.strip().split(':') for line in
2880 open(file).readlines()]:
2881 if ent[0] == username:
2882 return crypt.crypt(password, ent[1][:2]) == ent[1]
2884 # user doesn't exist in the file
2885 return 0
2887 class Client(client.Client):
2888 actions = client.Client.actions + (
2889 ('login', ExternalPasswordLoginAction)
2890 )
2892 What this does is look through the file, line by line, looking for a
2893 name that matches.
2895 We also remove the redundant password fields from the ``user.item``
2896 template.
2899 Adding a "vacation" flag to users for stopping nosy messages
2900 ------------------------------------------------------------
2902 When users go on vacation and set up vacation email bouncing, you'll
2903 start to see a lot of messages come back through Roundup "Fred is on
2904 vacation". Not very useful, and relatively easy to stop.
2906 1. add a "vacation" flag to your users::
2908 user = Class(db, "user",
2909 username=String(), password=Password(),
2910 address=String(), realname=String(),
2911 phone=String(), organisation=String(),
2912 alternate_addresses=String(),
2913 roles=String(), queries=Multilink("query"),
2914 vacation=Boolean())
2916 2. So that users may edit the vacation flags, add something like the
2917 following to your ``user.item`` template::
2919 <tr>
2920 <th>On Vacation</th>
2921 <td tal:content="structure context/vacation/field">vacation</td>
2922 </tr>
2924 3. edit your detector ``nosyreactor.py`` so that the ``nosyreaction()``
2925 consists of::
2927 def nosyreaction(db, cl, nodeid, oldvalues):
2928 users = db.user
2929 messages = db.msg
2930 # send a copy of all new messages to the nosy list
2931 for msgid in determineNewMessages(cl, nodeid, oldvalues):
2932 try:
2933 # figure the recipient ids
2934 sendto = []
2935 seen_message = {}
2936 recipients = messages.get(msgid, 'recipients')
2937 for recipid in messages.get(msgid, 'recipients'):
2938 seen_message[recipid] = 1
2940 # figure the author's id, and indicate they've received
2941 # the message
2942 authid = messages.get(msgid, 'author')
2944 # possibly send the message to the author, as long as
2945 # they aren't anonymous
2946 if (db.config.MESSAGES_TO_AUTHOR == 'yes' and
2947 users.get(authid, 'username') != 'anonymous'):
2948 sendto.append(authid)
2949 seen_message[authid] = 1
2951 # now figure the nosy people who weren't recipients
2952 nosy = cl.get(nodeid, 'nosy')
2953 for nosyid in nosy:
2954 # Don't send nosy mail to the anonymous user (that
2955 # user shouldn't appear in the nosy list, but just
2956 # in case they do...)
2957 if users.get(nosyid, 'username') == 'anonymous':
2958 continue
2959 # make sure they haven't seen the message already
2960 if not seen_message.has_key(nosyid):
2961 # send it to them
2962 sendto.append(nosyid)
2963 recipients.append(nosyid)
2965 # generate a change note
2966 if oldvalues:
2967 note = cl.generateChangeNote(nodeid, oldvalues)
2968 else:
2969 note = cl.generateCreateNote(nodeid)
2971 # we have new recipients
2972 if sendto:
2973 # filter out the people on vacation
2974 sendto = [i for i in sendto
2975 if not users.get(i, 'vacation', 0)]
2977 # map userids to addresses
2978 sendto = [users.get(i, 'address') for i in sendto]
2980 # update the message's recipients list
2981 messages.set(msgid, recipients=recipients)
2983 # send the message
2984 cl.send_message(nodeid, msgid, note, sendto)
2985 except roundupdb.MessageSendError, message:
2986 raise roundupdb.DetectorError, message
2988 Note that this is the standard nosy reaction code, with the small
2989 addition of::
2991 # filter out the people on vacation
2992 sendto = [i for i in sendto if not users.get(i, 'vacation', 0)]
2994 which filters out the users that have the vacation flag set to true.
2997 Adding a time log to your issues
2998 --------------------------------
3000 We want to log the dates and amount of time spent working on issues, and
3001 be able to give a summary of the total time spent on a particular issue.
3003 1. Add a new class to your tracker ``dbinit.py``::
3005 # storage for time logging
3006 timelog = Class(db, "timelog", period=Interval())
3008 Note that we automatically get the date of the time log entry
3009 creation through the standard property "creation".
3011 2. Link to the new class from your issue class (again, in
3012 ``dbinit.py``)::
3014 issue = IssueClass(db, "issue",
3015 assignedto=Link("user"), topic=Multilink("keyword"),
3016 priority=Link("priority"), status=Link("status"),
3017 times=Multilink("timelog"))
3019 the "times" property is the new link to the "timelog" class.
3021 3. We'll need to let people add in times to the issue, so in the web
3022 interface we'll have a new entry field. This is a special field
3023 because unlike the other fields in the issue.item template, it
3024 affects a different item (a timelog item) and not the template's
3025 item, an issue. We have a special syntax for form fields that affect
3026 items other than the template default item (see the cgi
3027 documentation on `special form variables`_). In particular, we add a
3028 field to capture a new timelog item's perdiod::
3030 <tr>
3031 <th>Time Log</th>
3032 <td colspan=3><input type="text" name="timelog-1@period" />
3033 <br />(enter as '3y 1m 4d 2:40:02' or parts thereof)
3034 </td>
3035 </tr>
3037 and another hidden field that links that new timelog item (new
3038 because it's marked as having id "-1") to the issue item. It looks
3039 like this::
3041 <input type="hidden" name="@link@times" value="timelog-1" />
3043 On submission, the "-1" timelog item will be created and assigned a
3044 real item id. The "times" property of the issue will have the new id
3045 added to it.
3047 4. We want to display a total of the time log times that have been
3048 accumulated for an issue. To do this, we'll need to actually write
3049 some Python code, since it's beyond the scope of PageTemplates to
3050 perform such calculations. We do this by adding a method to the
3051 TemplatingUtils class in our tracker ``interfaces.py`` module::
3053 class TemplatingUtils:
3054 ''' Methods implemented on this class will be available to HTML
3055 templates through the 'utils' variable.
3056 '''
3057 def totalTimeSpent(self, times):
3058 ''' Call me with a list of timelog items (which have an
3059 Interval "period" property)
3060 '''
3061 total = Interval('0d')
3062 for time in times:
3063 total += time.period._value
3064 return total
3066 Replace the ``pass`` line if one appears in your TemplatingUtils
3067 class. As indicated in the docstrings, we will be able to access the
3068 ``totalTimeSpent`` method via the ``utils`` variable in our templates.
3070 5. Display the time log for an issue::
3072 <table class="otherinfo" tal:condition="context/times">
3073 <tr><th colspan="3" class="header">Time Log
3074 <tal:block
3075 tal:replace="python:utils.totalTimeSpent(context.times)" />
3076 </th></tr>
3077 <tr><th>Date</th><th>Period</th><th>Logged By</th></tr>
3078 <tr tal:repeat="time context/times">
3079 <td tal:content="time/creation"></td>
3080 <td tal:content="time/period"></td>
3081 <td tal:content="time/creator"></td>
3082 </tr>
3083 </table>
3085 I put this just above the Messages log in my issue display. Note our
3086 use of the ``totalTimeSpent`` method which will total up the times
3087 for the issue and return a new Interval. That will be automatically
3088 displayed in the template as text like "+ 1y 2:40" (1 year, 2 hours
3089 and 40 minutes).
3091 8. If you're using a persistent web server - roundup-server or
3092 mod_python for example - then you'll need to restart that to pick up
3093 the code changes. When that's done, you'll be able to use the new
3094 time logging interface.
3096 Using a UN*X passwd file as the user database
3097 ---------------------------------------------
3099 On some systems the primary store of users is the UN*X passwd file. It
3100 holds information on users such as their username, real name, password
3101 and primary user group.
3103 Roundup can use this store as its primary source of user information,
3104 but it needs additional information too - email address(es), roundup
3105 Roles, vacation flags, roundup hyperdb item ids, etc. Also, "retired"
3106 users must still exist in the user database, unlike some passwd files in
3107 which the users are removed when they no longer have access to a system.
3109 To make use of the passwd file, we therefore synchronise between the two
3110 user stores. We also use the passwd file to validate the user logins, as
3111 described in the previous example, `using an external password
3112 validation source`_. We keep the users lists in sync using a fairly
3113 simple script that runs once a day, or several times an hour if more
3114 immediate access is needed. In short, it:
3116 1. parses the passwd file, finding usernames, passwords and real names,
3117 2. compares that list to the current roundup user list:
3119 a. entries no longer in the passwd file are *retired*
3120 b. entries with mismatching real names are *updated*
3121 c. entries only exist in the passwd file are *created*
3123 3. send an email to administrators to let them know what's been done.
3125 The retiring and updating are simple operations, requiring only a call
3126 to ``retire()`` or ``set()``. The creation operation requires more
3127 information though - the user's email address and their roundup Roles.
3128 We're going to assume that the user's email address is the same as their
3129 login name, so we just append the domain name to that. The Roles are
3130 determined using the passwd group identifier - mapping their UN*X group
3131 to an appropriate set of Roles.
3133 The script to perform all this, broken up into its main components, is
3134 as follows. Firstly, we import the necessary modules and open the
3135 tracker we're to work on::
3137 import sys, os, smtplib
3138 from roundup import instance, date
3140 # open the tracker
3141 tracker_home = sys.argv[1]
3142 tracker = instance.open(tracker_home)
3144 Next we read in the *passwd* file from the tracker home::
3146 # read in the users
3147 file = os.path.join(tracker_home, 'users.passwd')
3148 users = [x.strip().split(':') for x in open(file).readlines()]
3150 Handle special users (those to ignore in the file, and those who don't
3151 appear in the file)::
3153 # users to not keep ever, pre-load with the users I know aren't
3154 # "real" users
3155 ignore = ['ekmmon', 'bfast', 'csrmail']
3157 # users to keep - pre-load with the roundup-specific users
3158 keep = ['comment_pool', 'network_pool', 'admin', 'dev-team',
3159 'cs_pool', 'anonymous', 'system_pool', 'automated']
3161 Now we map the UN*X group numbers to the Roles that users should have::
3163 roles = {
3164 '501': 'User,Tech', # tech
3165 '502': 'User', # finance
3166 '503': 'User,CSR', # customer service reps
3167 '504': 'User', # sales
3168 '505': 'User', # marketing
3169 }
3171 Now we do all the work. Note that the body of the script (where we have
3172 the tracker database open) is wrapped in a ``try`` / ``finally`` clause,
3173 so that we always close the database cleanly when we're finished. So, we
3174 now do all the work::
3176 # open the database
3177 db = tracker.open('admin')
3178 try:
3179 # store away messages to send to the tracker admins
3180 msg = []
3182 # loop over the users list read in from the passwd file
3183 for user,passw,uid,gid,real,home,shell in users:
3184 if user in ignore:
3185 # this user shouldn't appear in our tracker
3186 continue
3187 keep.append(user)
3188 try:
3189 # see if the user exists in the tracker
3190 uid = db.user.lookup(user)
3192 # yes, they do - now check the real name for correctness
3193 if real != db.user.get(uid, 'realname'):
3194 db.user.set(uid, realname=real)
3195 msg.append('FIX %s - %s'%(user, real))
3196 except KeyError:
3197 # nope, the user doesn't exist
3198 db.user.create(username=user, realname=real,
3199 address='%s@ekit-inc.com'%user, roles=roles[gid])
3200 msg.append('ADD %s - %s (%s)'%(user, real, roles[gid]))
3202 # now check that all the users in the tracker are also in our
3203 # "keep" list - retire those who aren't
3204 for uid in db.user.list():
3205 user = db.user.get(uid, 'username')
3206 if user not in keep:
3207 db.user.retire(uid)
3208 msg.append('RET %s'%user)
3210 # if we did work, then send email to the tracker admins
3211 if msg:
3212 # create the email
3213 msg = '''Subject: %s user database maintenance
3215 %s
3216 '''%(db.config.TRACKER_NAME, '\n'.join(msg))
3218 # send the email
3219 smtp = smtplib.SMTP(db.config.MAILHOST)
3220 addr = db.config.ADMIN_EMAIL
3221 smtp.sendmail(addr, addr, msg)
3223 # now we're done - commit the changes
3224 db.commit()
3225 finally:
3226 # always close the database cleanly
3227 db.close()
3229 And that's it!
3232 Using an LDAP database for user information
3233 -------------------------------------------
3235 A script that reads users from an LDAP store using
3236 http://python-ldap.sf.net/ and then compares the list to the users in the
3237 roundup user database would be pretty easy to write. You'd then have it run
3238 once an hour / day (or on demand if you can work that into your LDAP store
3239 workflow). See the example `Using a UN*X passwd file as the user database`_
3240 for more information about doing this.
3242 To authenticate off the LDAP store (rather than using the passwords in the
3243 roundup user database) you'd use the same python-ldap module inside an
3244 extension to the cgi interface. You'd do this by overriding the method called
3245 "verifyPassword" on the LoginAction class in your tracker's interfaces.py
3246 module (see `using an external password validation source`_). The method is
3247 implemented by default as::
3249 def verifyPassword(self, userid, password):
3250 ''' Verify the password that the user has supplied
3251 '''
3252 stored = self.db.user.get(self.userid, 'password')
3253 if password == stored:
3254 return 1
3255 if not password and not stored:
3256 return 1
3257 return 0
3259 So you could reimplement this as something like::
3261 def verifyPassword(self, userid, password):
3262 ''' Verify the password that the user has supplied
3263 '''
3264 # look up some unique LDAP information about the user
3265 username = self.db.user.get(self.userid, 'username')
3266 # now verify the password supplied against the LDAP store
3269 Enabling display of either message summaries or the entire messages
3270 -------------------------------------------------------------------
3272 This is pretty simple - all we need to do is copy the code from the
3273 example `displaying only message summaries in the issue display`_ into
3274 our template alongside the summary display, and then introduce a switch
3275 that shows either one or the other. We'll use a new form variable,
3276 ``@whole_messages`` to achieve this::
3278 <table class="messages" tal:condition="context/messages">
3279 <tal:block tal:condition="not:request/form/@whole_messages/value | python:0">
3280 <tr><th colspan="3" class="header">Messages</th>
3281 <th colspan="2" class="header">
3282 <a href="?@whole_messages=yes">show entire messages</a>
3283 </th>
3284 </tr>
3285 <tr tal:repeat="msg context/messages">
3286 <td><a tal:attributes="href string:msg${msg/id}"
3287 tal:content="string:msg${msg/id}"></a></td>
3288 <td tal:content="msg/author">author</td>
3289 <td class="date" tal:content="msg/date/pretty">date</td>
3290 <td tal:content="msg/summary">summary</td>
3291 <td>
3292 <a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">remove</a>
3293 </td>
3294 </tr>
3295 </tal:block>
3297 <tal:block tal:condition="request/form/@whole_messages/value | python:0">
3298 <tr><th colspan="2" class="header">Messages</th>
3299 <th class="header">
3300 <a href="?@whole_messages=">show only summaries</a>
3301 </th>
3302 </tr>
3303 <tal:block tal:repeat="msg context/messages">
3304 <tr>
3305 <th tal:content="msg/author">author</th>
3306 <th class="date" tal:content="msg/date/pretty">date</th>
3307 <th style="text-align: right">
3308 (<a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">remove</a>)
3309 </th>
3310 </tr>
3311 <tr><td colspan="3" tal:content="msg/content"></td></tr>
3312 </tal:block>
3313 </tal:block>
3314 </table>
3317 Blocking issues that depend on other issues
3318 -------------------------------------------
3320 We needed the ability to mark certain issues as "blockers" - that is,
3321 they can't be resolved until another issue (the blocker) they rely on is
3322 resolved. To achieve this:
3324 1. Create a new property on the issue Class,
3325 ``blockers=Multilink("issue")``. Edit your tracker's dbinit.py file.
3326 Where the "issue" class is defined, something like::
3328 issue = IssueClass(db, "issue",
3329 assignedto=Link("user"), topic=Multilink("keyword"),
3330 priority=Link("priority"), status=Link("status"))
3332 add the blockers entry like so::
3334 issue = IssueClass(db, "issue",
3335 blockers=Multilink("issue"),
3336 assignedto=Link("user"), topic=Multilink("keyword"),
3337 priority=Link("priority"), status=Link("status"))
3339 2. Add the new "blockers" property to the issue.item edit page, using
3340 something like::
3342 <th>Waiting On</th>
3343 <td>
3344 <span tal:replace="structure python:context.blockers.field(showid=1,
3345 size=20)" />
3346 <span tal:replace="structure python:db.issue.classhelp('id,title')" />
3347 <span tal:condition="context/blockers"
3348 tal:repeat="blk context/blockers">
3349 <br>View: <a tal:attributes="href string:issue${blk/id}"
3350 tal:content="blk/id"></a>
3351 </span>
3353 You'll need to fiddle with your item page layout to find an
3354 appropriate place to put it - I'll leave that fun part up to you.
3355 Just make sure it appears in the first table, possibly somewhere near
3356 the "superseders" field.
3358 3. Create a new detector module (attached) which enforces the rules:
3360 - issues may not be resolved if they have blockers
3361 - when a blocker is resolved, it's removed from issues it blocks
3363 The contents of the detector should be something like this::
3365 def blockresolution(db, cl, nodeid, newvalues):
3366 ''' If the issue has blockers, don't allow it to be resolved.
3367 '''
3368 if nodeid is None:
3369 blockers = []
3370 else:
3371 blockers = cl.get(nodeid, 'blockers')
3372 blockers = newvalues.get('blockers', blockers)
3374 # don't do anything if there's no blockers or the status hasn't
3375 # changed
3376 if not blockers or not newvalues.has_key('status'):
3377 return
3379 # get the resolved state ID
3380 resolved_id = db.status.lookup('resolved')
3382 # format the info
3383 u = db.config.TRACKER_WEB
3384 s = ', '.join(['<a href="%sissue%s">%s</a>'%(
3385 u,id,id) for id in blockers])
3386 if len(blockers) == 1:
3387 s = 'issue %s is'%s
3388 else:
3389 s = 'issues %s are'%s
3391 # ok, see if we're trying to resolve
3392 if newvalues['status'] == resolved_id:
3393 raise ValueError, "This issue can't be resolved until %s resolved."%s
3395 def resolveblockers(db, cl, nodeid, newvalues):
3396 ''' When we resolve an issue that's a blocker, remove it from the
3397 blockers list of the issue(s) it blocks.
3398 '''
3399 if not newvalues.has_key('status'):
3400 return
3402 # get the resolved state ID
3403 resolved_id = db.status.lookup('resolved')
3405 # interesting?
3406 if newvalues['status'] != resolved_id:
3407 return
3409 # yes - find all the blocked issues, if any, and remove me from
3410 # their blockers list
3411 issues = cl.find(blockers=nodeid)
3412 for issueid in issues:
3413 blockers = cl.get(issueid, 'blockers')
3414 if nodeid in blockers:
3415 blockers.remove(nodeid)
3416 cl.set(issueid, blockers=blockers)
3419 def init(db):
3420 # might, in an obscure situation, happen in a create
3421 db.issue.audit('create', blockresolution)
3422 db.issue.audit('set', blockresolution)
3424 # can only happen on a set
3425 db.issue.react('set', resolveblockers)
3427 Put the above code in a file called "blockers.py" in your tracker's
3428 "detectors" directory.
3430 4. Finally, and this is an optional step, modify the tracker web page
3431 URLs so they filter out issues with any blockers. You do this by
3432 adding an additional filter on "blockers" for the value "-1". For
3433 example, the existing "Show All" link in the "page" template (in the
3434 tracker's "html" directory) looks like this::
3436 <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>
3438 modify it to add the "blockers" info to the URL (note, both the
3439 ":filter" *and* "blockers" values must be specified)::
3441 <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>
3443 That's it. You should now be able to set blockers on your issues. Note
3444 that if you want to know whether an issue has any other issues dependent
3445 on it (i.e. it's in their blockers list) you can look at the journal
3446 history at the bottom of the issue page - look for a "link" event to
3447 another issue's "blockers" property.
3449 Add users to the nosy list based on the topic
3450 ---------------------------------------------
3452 We need the ability to automatically add users to the nosy list based
3453 on the occurence of a topic. Every user should be allowed to edit his
3454 own list of topics for which he wants to be added to the nosy list.
3456 Below will be showed that such a change can be performed with only
3457 minimal understanding of the roundup system, but with clever use
3458 of Copy and Paste.
3460 This requires three changes to the tracker: a change in the database to
3461 allow per-user recording of the lists of topics for which he wants to
3462 be put on the nosy list, a change in the user view allowing to edit
3463 this list of topics, and addition of an auditor which updates the nosy
3464 list when a topic is set.
3466 Adding the nosy topic list
3467 ~~~~~~~~~~~~~~~~~~~~~~~~~~
3469 The change in the database to make is that for any user there should be
3470 a list of topics for which he wants to be put on the nosy list. Adding
3471 a ``Multilink`` of ``keyword`` seem to fullfill this (note that within
3472 the code topics are called ``keywords``.) As such, all what has to be
3473 done is to add a new field to the definition of ``user`` within the
3474 file ``dbinit.py``. We will call this new field ``nosy_keywords``, and
3475 the updated definition of user will be::
3477 user = Class(db, "user",
3478 username=String(), password=Password(),
3479 address=String(), realname=String(),
3480 phone=String(), organisation=String(),
3481 alternate_addresses=String(),
3482 queries=Multilink('query'), roles=String(),
3483 timezone=String(),
3484 nosy_keywords=Multilink('keyword'))
3486 Changing the user view to allow changing the nosy topic list
3487 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3489 We want any user to be able to change the list of topics for which
3490 he will by default be added to the nosy list. We choose to add this
3491 to the user view, as is generated by the file ``html/user.item.html``.
3492 We easily can
3493 see that the topic field in the issue view has very similar editting
3494 requirements as our nosy topics, both being a list of topics. As
3495 such, we search for Topics in ``issue.item.html``, and extract the
3496 associated parts from there. We add this to ``user.item.html`` at the
3497 bottom of the list of viewed items (i.e. just below the 'Alternate
3498 E-mail addresses' in the classic template)::
3500 <tr>
3501 <th>Nosy Topics</th>
3502 <td>
3503 <span tal:replace="structure context/nosy_keywords/field" />
3504 <span tal:replace="structure python:db.keyword.classhelp(property='nosy_keywords')" />
3505 </td>
3506 </tr>
3509 Addition of an auditor to update the nosy list
3510 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3512 The more difficult part is the addition of the logic to actually
3513 at the users to the nosy list when it is required.
3514 The choice is made to perform this action when the topics on an
3515 item are set, including when an item is created.
3516 Here we choose to start out with a copy of the
3517 ``detectors/nosyreaction.py`` detector, which we copy to the file
3518 ``detectors/nosy_keyword_reaction.py``.
3519 This looks like a good start as it also adds users
3520 to the nosy list. A look through the code reveals that the
3521 ``nosyreaction`` function actually is sending the e-mail, which
3522 we do not need. As such, we can change the init function to::
3524 def init(db):
3525 db.issue.audit('create', update_kw_nosy)
3526 db.issue.audit('set', update_kw_nosy)
3528 After that we rename the ``updatenosy`` function to ``update_kw_nosy``.
3529 The first two blocks of code in that function relate to settings
3530 ``current`` to a combination of the old and new nosy lists. This
3531 functionality is left in the new auditor. The following block of
3532 code, which in ``updatenosy`` handled adding the assignedto user(s)
3533 to the nosy list, should be replaced by a block of code to add the
3534 interested users to the nosy list. We choose here to loop over all
3535 new topics, than loop over all users,
3536 and assign the user to the nosy list when the topic in the user's
3537 nosy_keywords. The next part in ``updatenosy``, adding the author
3538 and/or recipients of a message to the nosy list, obviously is not
3539 relevant here and thus is deleted from the new auditor. The last
3540 part, copying the new nosy list to newvalues, does not have to be changed.
3541 This brings the following function::
3543 def update_kw_nosy(db, cl, nodeid, newvalues):
3544 '''Update the nosy list for changes to the topics
3545 '''
3546 # nodeid will be None if this is a new node
3547 current = {}
3548 if nodeid is None:
3549 ok = ('new', 'yes')
3550 else:
3551 ok = ('yes',)
3552 # old node, get the current values from the node if they haven't
3553 # changed
3554 if not newvalues.has_key('nosy'):
3555 nosy = cl.get(nodeid, 'nosy')
3556 for value in nosy:
3557 if not current.has_key(value):
3558 current[value] = 1
3560 # if the nosy list changed in this transaction, init from the new value
3561 if newvalues.has_key('nosy'):
3562 nosy = newvalues.get('nosy', [])
3563 for value in nosy:
3564 if not db.hasnode('user', value):
3565 continue
3566 if not current.has_key(value):
3567 current[value] = 1
3569 # add users with topic in nosy_keywords to the nosy list
3570 if newvalues.has_key('topic') and newvalues['topic'] is not None:
3571 topic_ids = newvalues['topic']
3572 for topic in topic_ids:
3573 # loop over all users,
3574 # and assign user to nosy when topic in nosy_keywords
3575 for user_id in db.user.list():
3576 nosy_kw = db.user.get(user_id, "nosy_keywords")
3577 found = 0
3578 for kw in nosy_kw:
3579 if kw == topic:
3580 found = 1
3581 if found:
3582 current[user_id] = 1
3584 # that's it, save off the new nosy list
3585 newvalues['nosy'] = current.keys()
3587 and these two function are the only ones needed in the file.
3589 TODO: update this example to use the find() Class method.
3591 Caveats
3592 ~~~~~~~
3594 A few problems with the design here can be noted:
3596 Multiple additions
3597 When a user, after automatic selection, is manually removed
3598 from the nosy list, he again is added to the nosy list when the
3599 topic list of the issue is updated. A better design might be
3600 to only check which topics are new compared to the old list
3601 of topics, and only add users when they have indicated
3602 interest on a new topic.
3604 The code could also be changed to only trigger on the create() event,
3605 rather than also on the set() event, thus only setting the nosy list
3606 when the issue is created.
3608 Scalability
3609 In the auditor there is a loop over all users. For a site with
3610 only few users this will pose no serious problem, however, with
3611 many users this will be a serious performance bottleneck.
3612 A way out will be to link from the topics to the users which
3613 selected these topics a nosy topics. This will eliminate the
3614 loop over all users.
3617 Adding action links to the index page
3618 -------------------------------------
3620 Add a column to the item.index.html template.
3622 Resolving the issue::
3624 <a tal:attributes="href
3625 string:issue${i/id}?:status=resolved&:action=edit">resolve</a>
3627 "Take" the issue::
3629 <a tal:attributes="href
3630 string:issue${i/id}?:assignedto=${request/user/id}&:action=edit">take</a>
3632 ... and so on
3634 Users may only edit their issues
3635 --------------------------------
3637 Users registering themselves are granted Provisional access - meaning they
3638 have access to edit the issues they submit, but not others. We create a new
3639 Role called "Provisional User" which is granted to newly-registered users,
3640 and has limited access. One of the Permissions they have is the new "Edit
3641 Own" on issues (regular users have "Edit".) We back up the permissions with
3642 an auditor.
3644 First up, we create the new Role and Permission structure in
3645 ``dbinit.py``::
3647 # New users not approved by the admin
3648 db.security.addRole(name='Provisional User',
3649 description='New user registered via web or email')
3650 p = db.security.addPermission(name='Edit Own', klass='issue',
3651 description='Can only edit own issues')
3652 db.security.addPermissionToRole('Provisional User', p)
3654 # Assign the access and edit Permissions for issue to new users now
3655 p = db.security.getPermission('View', 'issue')
3656 db.security.addPermissionToRole('Provisional User', p)
3657 p = db.security.getPermission('Edit', 'issue')
3658 db.security.addPermissionToRole('Provisional User', p)
3660 # and give the new users access to the web and email interface
3661 p = db.security.getPermission('Web Access')
3662 db.security.addPermissionToRole('Provisional User', p)
3663 p = db.security.getPermission('Email Access')
3664 db.security.addPermissionToRole('Provisional User', p)
3667 Then in the ``config.py`` we change the Role assigned to newly-registered
3668 users, replacing the existing ``'User'`` values::
3670 NEW_WEB_USER_ROLES = 'Provisional User'
3671 NEW_EMAIL_USER_ROLES = 'Provisional User'
3673 Finally we add a new *auditor* to the ``detectors`` directory called
3674 ``provisional_user_auditor.py``::
3676 def audit_provisionaluser(db, cl, nodeid, newvalues):
3677 ''' New users are only allowed to modify their own issues.
3678 '''
3679 if (db.getuid() != cl.get(nodeid, 'creator')
3680 and db.security.hasPermission('Edit Own', db.getuid(), cl.classname)):
3681 raise ValueError, ('You are only allowed to edit your own %s'
3682 % cl.classname)
3684 def init(db):
3685 # fire before changes are made
3686 db.issue.audit('set', audit_provisionaluser)
3687 db.issue.audit('retire', audit_provisionaluser)
3688 db.issue.audit('restore', audit_provisionaluser)
3690 Note that some older trackers might also want to change the ``page.html``
3691 template as follows::
3693 <p class="classblock"
3694 - tal:condition="python:request.user.username != 'anonymous'">
3695 + tal:condition="python:request.user.hasPermission('View', 'user')">
3696 <b>Administration</b><br>
3697 <tal:block tal:condition="python:request.user.hasPermission('Edit', None)">
3698 <a href="home?:template=classlist">Class List</a><br>
3700 (note that the "-" indicates a removed line, and the "+" indicates an added
3701 line).
3704 Colouring the rows in the issue index according to priority
3705 -----------------------------------------------------------
3707 A simple ``tal:attributes`` statement will do the bulk of the work here. In
3708 the ``issue.index.html`` template, add to the ``<tr>`` that displays the
3709 actual rows of data::
3711 <tr tal:attributes="class string:priority-${i/priority/plain}">
3713 and then in your stylesheet (``style.css``) specify the colouring for the
3714 different priorities, like::
3716 tr.priority-critical td {
3717 background-color: red;
3718 }
3720 tr.priority-urgent td {
3721 background-color: orange;
3722 }
3724 and so on, with far less offensive colours :)
3726 Editing multiple items in an index view
3727 ---------------------------------------
3729 To edit the status of all items in the item index view, edit the
3730 ``issue.item.html``:
3732 1. add a form around the listing table, so at the top it reads::
3734 <form method="POST" tal:attributes="action request/classname">
3735 <table class="list">
3737 and at the bottom of that table::
3739 </table>
3740 </form
3742 making sure you match the ``</table>`` from the list table, not the
3743 navigation table or the subsequent form table.
3745 2. in the display for the issue property, change::
3747 <td tal:condition="request/show/status"
3748 tal:content="python:i.status.plain() or default"> </td>
3750 to::
3752 <td tal:condition="request/show/status"
3753 tal:content="structure i/status/field"> </td>
3755 this will result in an edit field for the status property.
3757 3. after the ``tal:block`` which lists the actual index items (marked by
3758 ``tal:repeat="i batch"``) add a new table row::
3760 <tr>
3761 <td tal:attributes="colspan python:len(request.columns)">
3762 <input type="submit" value=" Save Changes ">
3763 <input type="hidden" name="@action" value="edit">
3764 <tal:block replace="structure request/indexargs_form" />
3765 </td>
3766 </tr>
3768 which gives us a submit button, indicates that we are performing an edit
3769 on any changed statuses and the final block will make sure that the
3770 current index view parameters (filtering, columns, etc) will be used in
3771 rendering the next page (the results of the editing).
3773 -------------------
3775 Back to `Table of Contents`_
3777 .. _`Table of Contents`: index.html
3778 .. _`design documentation`: design.html