Premiere version : mise en route du suivi.
[auf_roundup.git] / doc / .svn / text-base / customizing.txt.svn-base
1 :tocdepth: 2
2
3 ===================
4 Customising Roundup
5 ===================
6
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
9
10 .. contents::
11    :depth: 1
12
13 What You Can Do
14 ===============
15
16 Before you get too far, it's probably worth having a quick read of the Roundup
17 `design documentation`_.
18
19 Customisation of Roundup can take one of six forms:
20
21 1. `tracker configuration`_ 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`_
27
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.
32
33
34 Trackers in a Nutshell
35 ======================
36
37 Trackers have the following structure:
38
39 =================== ========================================================
40 Tracker File        Description
41 =================== ========================================================
42 config.ini          Holds the basic `tracker configuration`_                 
43 schema.py           Holds the `tracker schema`_                              
44 initial_data.py     Holds any data to be entered into the database when the
45                     tracker is initialised.
46 db/                 Holds the tracker's database                             
47 db/files/           Holds the tracker's upload files and messages            
48 db/backend_name     Names the database back-end for the tracker            
49 detectors/          Auditors and reactors for this tracker                   
50 extensions/         Additional web actions and templating utilities.
51 html/               Web interface templates, images and style sheets         
52 lib/                optional common imports for detectors and extensions
53 =================== ======================================================== 
54
55
56 Tracker Configuration
57 =====================
58
59 The ``config.ini`` located in your tracker home contains the basic
60 configuration for the web and e-mail components of roundup's interfaces.
61
62 Changes to the data captured by your tracker is controlled by the `tracker
63 schema`_.  Some configuration is also performed using permissions - see the 
64 `security / access controls`_ section. For example, to allow users to
65 automatically register through the email interface, you must grant the
66 "Anonymous" Role the "Email Access" Permission.
67
68 The following is taken from the `Python Library Reference`__ (May 20, 2004)
69 section "ConfigParser -- Configuration file parser":
70
71  The configuration file consists of sections, led by a "[section]" header
72  and followed by "name = value" entries, with line continuations on a
73  newline with leading whitespace. Note that leading whitespace is removed
74  from values. The optional values can contain format strings which
75  refer to other values in the same section. Lines beginning with "#" or ";"
76  are ignored and may be used to provide comments. 
77
78  For example::
79
80    [My Section]
81    foodir = %(dir)s/whatever
82    dir = frob
83
84  would resolve the "%(dir)s" to the value of "dir" ("frob" in this case)
85  resulting in "foodir" being "frob/whatever".
86
87 __ http://docs.python.org/lib/module-ConfigParser.html
88
89 Section **main**
90  database -- ``db``
91   Database directory path. The path may be either absolute or relative
92   to the directory containig this config file.
93
94  templates -- ``html``
95   Path to the HTML templates directory. The path may be either absolute
96   or relative to the directory containig this config file.
97
98  static_files -- default *blank*
99   Path to directory holding additional static files available via Web
100   UI.  This directory may contain sitewide images, CSS stylesheets etc.
101   and is searched for these files prior to the TEMPLATES directory
102   specified above.  If this option is not set, all static files are
103   taken from the TEMPLATES directory The path may be either absolute or
104   relative to the directory containig this config file.
105
106  admin_email -- ``roundup-admin``
107   Email address that roundup will complain to if it runs into trouble. If
108   the email address doesn't contain an ``@`` part, the MAIL_DOMAIN defined
109   below is used.
110
111  dispatcher_email -- ``roundup-admin``
112   The 'dispatcher' is a role that can get notified of new items to the
113   database. It is used by the ERROR_MESSAGES_TO config setting. If the
114   email address doesn't contain an ``@`` part, the MAIL_DOMAIN defined
115   below is used.
116
117  email_from_tag -- default *blank*
118   Additional text to include in the "name" part of the From: address used
119   in nosy messages. If the sending user is "Foo Bar", the From: line
120   is usually: ``"Foo Bar" <issue_tracker@tracker.example>``
121   the EMAIL_FROM_TAG goes inside the "Foo Bar" quotes like so:
122   ``"Foo Bar EMAIL_FROM_TAG" <issue_tracker@tracker.example>``
123
124  new_web_user_roles -- ``User``
125   Roles that a user gets when they register with Web User Interface.
126   This is a comma-separated list of role names (e.g. ``Admin,User``).
127
128  new_email_user_roles -- ``User``
129   Roles that a user gets when they register with Email Gateway.
130   This is a comma-separated string of role names (e.g. ``Admin,User``).
131
132  error_messages_to -- ``user``
133   Send error message emails to the ``dispatcher``, ``user``, or ``both``?
134   The dispatcher is configured using the DISPATCHER_EMAIL setting.
135   Allowed values: ``dispatcher``, ``user``, or ``both``
136
137  html_version -- ``html4``
138   HTML version to generate. The templates are ``html4`` by default.
139   If you wish to make them xhtml, then you'll need to change this
140   var to ``xhtml`` too so all auto-generated HTML is compliant.
141   Allowed values: ``html4``, ``xhtml``
142
143  timezone -- ``0``
144   Numeric timezone offset used when users do not choose their own
145   in their settings.
146
147  instant_registration -- ``yes``
148   Register new users instantly, or require confirmation via
149   email?
150   Allowed values: ``yes``, ``no``
151
152  email_registration_confirmation -- ``yes``
153   Offer registration confirmation by email or only through the web?
154   Allowed values: ``yes``, ``no``
155
156  indexer_stopwords -- default *blank*
157   Additional stop-words for the full-text indexer specific to
158   your tracker. See the indexer source for the default list of
159   stop-words (e.g. ``A,AND,ARE,AS,AT,BE,BUT,BY, ...``).
160
161  umask -- ``02``
162   Defines the file creation mode mask.
163
164 Section **tracker**
165  name -- ``Roundup issue tracker``
166   A descriptive name for your roundup instance.
167
168  web -- ``http://host.example/demo/``
169   The web address that the tracker is viewable at.
170   This will be included in information sent to users of the tracker.
171   The URL MUST include the cgi-bin part or anything else
172   that is required to get to the home page of the tracker.
173   You MUST include a trailing '/' in the URL.
174
175  email -- ``issue_tracker``
176   Email address that mail to roundup should go to.
177
178  language -- default *blank*
179   Default locale name for this tracker. If this option is not set, the
180   language is determined by the environment variable LANGUAGE, LC_ALL,
181   LC_MESSAGES, or LANG, in that order of preference.
182
183 Section **web**
184  allow_html_file -- ``no``
185   Setting this option enables Roundup to serve uploaded HTML
186   file content *as HTML*. This is a potential security risk
187   and is therefore disabled by default. Set to 'yes' if you
188   trust *all* users uploading content to your tracker.
189
190  http_auth -- ``yes``
191   Whether to use HTTP Basic Authentication, if present.
192   Roundup will use either the REMOTE_USER or HTTP_AUTHORIZATION
193   variables supplied by your web server (in that order).
194   Set this option to 'no' if you do not wish to use HTTP Basic
195   Authentication in your web interface.
196
197  use_browser_language -- ``yes``
198   Whether to use HTTP Accept-Language, if present.
199   Browsers send a language-region preference list.
200   It's usually set in the client's browser or in their
201   Operating System.
202   Set this option to 'no' if you want to ignore it.
203
204  debug -- ``no``
205   Setting this option makes Roundup display error tracebacks
206   in the user's browser rather than emailing them to the
207   tracker admin."),
208
209 Section **rdbms**
210  Settings in this section are used by Postgresql and MySQL backends only
211
212  name -- ``roundup``
213   Name of the database to use.
214
215  host -- ``localhost``
216   Database server host.
217
218  port -- default *blank*
219   TCP port number of the database server. Postgresql usually resides on
220   port 5432 (if any), for MySQL default port number is 3306. Leave this
221   option empty to use backend default.
222
223  user -- ``roundup``
224   Database user name that Roundup should use.
225
226  password -- ``roundup``
227   Database user password.
228
229  read_default_file -- ``~/.my.cnf``
230   Name of the MySQL defaults file. Only used in MySQL connections.
231
232  read_default_group -- ``roundup``
233   Name of the group to use in the MySQL defaults file. Only used in
234   MySQL connections.
235
236 Section **logging**
237  config -- default *blank*
238   Path to configuration file for standard Python logging module. If this
239   option is set, logging configuration is loaded from specified file;
240   options 'filename' and 'level' in this section are ignored. The path may
241   be either absolute or relative to the directory containig this config file.
242
243  filename -- default *blank*
244   Log file name for minimal logging facility built into Roundup.  If no file
245   name specified, log messages are written on stderr. If above 'config'
246   option is set, this option has no effect. The path may be either absolute
247   or relative to the directory containig this config file.
248
249  level -- ``ERROR``
250   Minimal severity level of messages written to log file. If above 'config'
251   option is set, this option has no effect.
252   Allowed values: ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``
253
254 Section **mail**
255  Outgoing email options. Used for nosy messages, password reset and
256  registration approval requests.
257
258  domain -- ``localhost``
259   Domain name used for email addresses.
260
261  host -- default *blank*
262   SMTP mail host that roundup will use to send mail
263
264  username -- default *blank*
265   SMTP login name. Set this if your mail host requires authenticated access.
266   If username is not empty, password (below) MUST be set!
267
268  password -- default *blank*
269   SMTP login password.
270   Set this if your mail host requires authenticated access.
271
272  port -- default *25*
273   SMTP port on mail host.
274   Set this if your mail host runs on a different port.
275
276  local_hostname -- default *blank*
277   The fully qualified domain name (FQDN) to use during SMTP sessions. If left
278   blank, the underlying SMTP library will attempt to detect your FQDN. If your
279   mail host requires something specific, specify the FQDN to use.
280
281  tls -- ``no``
282   If your SMTP mail host provides or requires TLS (Transport Layer Security)
283   then you may set this option to 'yes'.
284   Allowed values: ``yes``, ``no``
285
286  tls_keyfile -- default *blank*
287   If TLS is used, you may set this option to the name of a PEM formatted
288   file that contains your private key. The path may be either absolute or
289   relative to the directory containig this config file.
290
291  tls_certfile -- default *blank*
292   If TLS is used, you may set this option to the name of a PEM formatted
293   certificate chain file. The path may be either absolute or relative
294   to the directory containig this config file.
295
296  charset -- utf-8
297   Character set to encode email headers with. We use utf-8 by default, as
298   it's the most flexible. Some mail readers (eg. Eudora) can't cope with
299   that, so you might need to specify a more limited character set
300   (eg. iso-8859-1).
301
302  debug -- default *blank*
303   Setting this option makes Roundup to write all outgoing email messages
304   to this file *instead* of sending them. This option has the same effect
305   as environment variable SENDMAILDEBUG. Environment variable takes
306   precedence. The path may be either absolute or relative to the directory
307   containig this config file.
308
309  add_authorinfo -- ``yes``
310   Add a line with author information at top of all messages send by
311   roundup.
312
313  add_authoremail -- ``yes``
314   Add the mail address of the author to the author information at the
315   top of all messages.  If this is false but add_authorinfo is true,
316   only the name of the actor is added which protects the mail address
317   of the actor from being exposed at mail archives, etc.
318
319 Section **mailgw**
320  Roundup Mail Gateway options
321
322  keep_quoted_text -- ``yes``
323   Keep email citations when accepting messages. Setting this to ``no`` strips
324   out "quoted" text from the message. Signatures are also stripped.
325   Allowed values: ``yes``, ``no``
326
327  leave_body_unchanged -- ``no``
328   Preserve the email body as is - that is, keep the citations *and*
329   signatures.
330   Allowed values: ``yes``, ``no``
331
332  default_class -- ``issue``
333   Default class to use in the mailgw if one isn't supplied in email subjects.
334   To disable, leave the value blank.
335
336  language -- default *blank*
337   Default locale name for the tracker mail gateway.  If this option is
338   not set, mail gateway will use the language of the tracker instance.
339
340  subject_prefix_parsing -- ``strict``
341   Controls the parsing of the [prefix] on subject lines in incoming emails.
342   ``strict`` will return an error to the sender if the [prefix] is not
343   recognised. ``loose`` will attempt to parse the [prefix] but just
344   pass it through as part of the issue title if not recognised. ``none``
345   will always pass any [prefix] through as part of the issue title.
346
347  subject_suffix_parsing -- ``strict``
348   Controls the parsing of the [suffix] on subject lines in incoming emails.
349   ``strict`` will return an error to the sender if the [suffix] is not
350   recognised. ``loose`` will attempt to parse the [suffix] but just
351   pass it through as part of the issue title if not recognised. ``none``
352   will always pass any [suffix] through as part of the issue title.
353
354  subject_suffix_delimiters -- ``[]``
355   Defines the brackets used for delimiting the commands suffix in a subject
356   line.
357
358  subject_content_match -- ``always``
359   Controls matching of the incoming email subject line against issue titles
360   in the case where there is no designator [prefix]. ``never`` turns off
361   matching. ``creation + interval`` or ``activity + interval`` will match
362   an issue for the interval after the issue's creation or last activity.
363   The interval is a standard Roundup interval.
364
365  refwd_re -- ``(\s*\W?\s*(fw|fwd|re|aw|sv|ang)\W)+``
366   Regular expression matching a single reply or forward prefix
367   prepended by the mailer. This is explicitly stripped from the
368   subject during parsing.  Value is Python Regular Expression
369   (UTF8-encoded).
370
371  origmsg_re -- `` ^[>|\s]*-----\s?Original Message\s?-----$``
372   Regular expression matching start of an original message if quoted
373   the in body.  Value is Python Regular Expression (UTF8-encoded).
374
375  sign_re -- ``^[>|\s]*-- ?$``
376   Regular expression matching the start of a signature in the message
377   body.  Value is Python Regular Expression (UTF8-encoded).
378
379  eol_re -- ``[\r\n]+``
380   Regular expression matching end of line.  Value is Python Regular
381   Expression (UTF8-encoded).
382
383  blankline_re -- ``[\r\n]+\s*[\r\n]+``
384   Regular expression matching a blank line.  Value is Python Regular
385   Expression (UTF8-encoded).
386
387 Section **pgp**
388  OpenPGP mail processing options
389
390  enable -- ``no``
391   Enable PGP processing. Requires pyme.
392
393  roles -- default *blank*
394   If specified, a comma-separated list of roles to perform PGP
395   processing on. If not specified, it happens for all users.
396
397  homedir -- default *blank*
398   Location of PGP directory. Defaults to $HOME/.gnupg if not
399   specified.
400
401 Section **nosy**
402  Nosy messages sending
403
404  messages_to_author -- ``no``
405   Send nosy messages to the author of the message.
406   Allowed values: ``yes``, ``no``, ``new``
407
408  signature_position -- ``bottom``
409   Where to place the email signature.
410   Allowed values: ``top``, ``bottom``, ``none``
411
412  add_author -- ``new``
413   Does the author of a message get placed on the nosy list automatically?
414   If ``new`` is used, then the author will only be added when a message
415   creates a new issue. If ``yes``, then the author will be added on
416   followups too. If ``no``, they're never added to the nosy.
417   Allowed values: ``yes``, ``no``, ``new``
418   
419  add_recipients -- ``new``
420   Do the recipients (``To:``, ``Cc:``) of a message get placed on the nosy
421   list?  If ``new`` is used, then the recipients will only be added when a
422   message creates a new issue. If ``yes``, then the recipients will be added
423   on followups too. If ``no``, they're never added to the nosy.
424   Allowed values: ``yes``, ``no``, ``new``
425
426  email_sending -- ``single``
427   Controls the email sending from the nosy reactor. If ``multiple`` then
428   a separate email is sent to each recipient. If ``single`` then a single
429   email is sent with each recipient as a CC address.
430
431  max_attachment_size -- ``2147483647``
432   Attachments larger than the given number of bytes won't be attached
433   to nosy mails. They will be replaced by a link to the tracker's
434   download page for the file.
435
436
437 You may generate a new default config file using the ``roundup-admin
438 genconfig`` command.
439
440 Configuration variables may be referred to in lower or upper case. In code,
441 variables not in the "main" section are referred to using their section and
442 name, so "domain" in the section "mail" becomes MAIL_DOMAIN. The
443 configuration variables available are:
444
445 Extending the configuration file
446 --------------------------------
447
448 You can't add new variables to the config.ini file in the tracker home but
449 you can add two new config.ini files:
450
451 - a config.ini in the ``extensions`` directory will be loaded and attached
452   to the config variable as "ext".
453 - a config.ini in the ``detectors`` directory will be loaded and attached
454   to the config variable as "detectors".
455
456 For example, the following in ``detectors/config.ini``::
457
458     [main]
459     qa_recipients = email@example.com
460
461 is accessible as::
462
463     db.config.detectors['QA_RECIPIENTS']
464
465 Note that the name grouping applied to the main configuration file is
466 applied to the extension config files, so if you instead have::
467
468     [qa]
469     recipients = email@example.com
470
471 then the above ``db.config.detectors['QA_RECIPIENTS']`` will still work.
472
473
474 Tracker Schema
475 ==============
476
477 .. note::
478    if you modify the schema, you'll most likely need to edit the
479    `web interface`_ HTML template files and `detectors`_ to reflect
480    your changes.
481
482 A tracker schema defines what data is stored in the tracker's database.
483 Schemas are defined using Python code in the ``schema.py`` module of your
484 tracker.
485
486 The ``schema.py`` module
487 ------------------------
488
489 The ``schema.py`` module contains two functions:
490
491 **open**
492   This function defines what your tracker looks like on the inside, the
493   **schema** of the tracker. It defines the **Classes** and **properties**
494   on each class. It also defines the **security** for those Classes. The
495   next few sections describe how schemas work and what you can do with
496   them.
497 **init**
498   This function is responsible for setting up the initial state of your
499   tracker. It's called exactly once - but the ``roundup-admin initialise``
500   command.  See the start of the section on `database content`_ for more
501   info about how this works.
502
503
504 The "classic" schema
505 --------------------
506
507 The "classic" schema looks like this (see section `setkey(property)`_
508 below for the meaning of ``'setkey'`` -- you may also want to look into
509 the sections `setlabelprop(property)`_ and `setorderprop(property)`_ for
510 specifying (default) labelling and ordering of classes.)::
511
512     pri = Class(db, "priority", name=String(), order=String())
513     pri.setkey("name")
514
515     stat = Class(db, "status", name=String(), order=String())
516     stat.setkey("name")
517
518     keyword = Class(db, "keyword", name=String())
519     keyword.setkey("name")
520
521     user = Class(db, "user", username=String(), organisation=String(),
522         password=String(), address=String(), realname=String(),
523         phone=String(), alternate_addresses=String(),
524         queries=Multilink('query'), roles=String(), timezone=String())
525     user.setkey("username")
526
527     msg = FileClass(db, "msg", author=Link("user"), summary=String(),
528         date=Date(), recipients=Multilink("user"),
529         files=Multilink("file"), messageid=String(), inreplyto=String())
530
531     file = FileClass(db, "file", name=String())
532
533     issue = IssueClass(db, "issue", keyword=Multilink("keyword"),
534         status=Link("status"), assignedto=Link("user"),
535         priority=Link("priority"))
536     issue.setkey('title')
537
538
539 What you can't do to the schema
540 -------------------------------
541
542 You must never:
543
544 **Remove the users class**
545   This class is the only *required* class in Roundup.
546
547 **Remove the "username", "address", "password" or "realname" user properties**
548   Various parts of Roundup require these properties. Don't remove them.
549
550 **Change the type of a property**
551   Property types must *never* be changed - the database simply doesn't take
552   this kind of action into account. Note that you can't just remove a
553   property and re-add it as a new type either. If you wanted to make the
554   assignedto property a Multilink, you'd need to create a new property
555   assignedto_list and remove the old assignedto property.
556
557
558 What you can do to the schema
559 -----------------------------
560
561 Your schema may be changed at any time before or after the tracker has been
562 initialised (or used). You may:
563
564 **Add new properties to classes, or add whole new classes**
565   This is painless and easy to do - there are generally no repurcussions
566   from adding new information to a tracker's schema.
567
568 **Remove properties**
569   Removing properties is a little more tricky - you need to make sure that
570   the property is no longer used in the `web interface`_ *or* by the
571   detectors_.
572
573
574
575 Classes and Properties - creating a new information store
576 ---------------------------------------------------------
577
578 In the tracker above, we've defined 7 classes of information:
579
580   priority
581       Defines the possible levels of urgency for issues.
582
583   status
584       Defines the possible states of processing the issue may be in.
585
586   keyword
587       Initially empty, will hold keywords useful for searching issues.
588
589   user
590       Initially holding the "admin" user, will eventually have an entry
591       for all users using roundup.
592
593   msg
594       Initially empty, will hold all e-mail messages sent to or
595       generated by roundup.
596
597   file
598       Initially empty, will hold all files attached to issues.
599
600   issue
601       Initially empty, this is where the issue information is stored.
602
603 We define the "priority" and "status" classes to allow two things:
604 reduction in the amount of information stored on the issue and more
605 powerful, accurate searching of issues by priority and status. By only
606 requiring a link on the issue (which is stored as a single number) we
607 reduce the chance that someone mis-types a priority or status - or
608 simply makes a new one up.
609
610
611 Class and Items
612 ~~~~~~~~~~~~~~~
613
614 A Class defines a particular class (or type) of data that will be stored
615 in the database. A class comprises one or more properties, which gives
616 the information about the class items.
617
618 The actual data entered into the database, using ``class.create()``, are
619 called items. They have a special immutable property called ``'id'``. We
620 sometimes refer to this as the *itemid*.
621
622
623 Properties
624 ~~~~~~~~~~
625
626 A Class is comprised of one or more properties of the following types:
627
628 * String properties are for storing arbitrary-length strings.
629 * Password properties are for storing encoded arbitrary-length strings.
630   The default encoding is defined on the ``roundup.password.Password``
631   class.
632 * Date properties store date-and-time stamps. Their values are Timestamp
633   objects.
634 * Number properties store numeric values.
635 * Boolean properties store on/off, yes/no, true/false values.
636 * A Link property refers to a single other item selected from a
637   specified class. The class is part of the property; the value is an
638   integer, the id of the chosen item.
639 * A Multilink property refers to possibly many items in a specified
640   class. The value is a list of integers.
641
642 All Classes automatically have a number of properties by default:
643
644 *creator*
645   Link to the user that created the item.
646 *creation*
647   Date the item was created.
648 *actor*
649   Link to the user that last modified the item.
650 *activity*
651   Date the item was last modified.
652
653
654 FileClass
655 ~~~~~~~~~
656
657 FileClasses save their "content" attribute off in a separate file from
658 the rest of the database. This reduces the number of large entries in
659 the database, which generally makes databases more efficient, and also
660 allows us to use command-line tools to operate on the files. They are
661 stored in the files sub-directory of the ``'db'`` directory in your
662 tracker. FileClasses also have a "type" attribute to store the MIME
663 type of the file.
664
665
666 IssueClass
667 ~~~~~~~~~~
668
669 IssueClasses automatically include the "messages", "files", "nosy", and
670 "superseder" properties.
671
672 The messages and files properties list the links to the messages and
673 files related to the issue. The nosy property is a list of links to
674 users who wish to be informed of changes to the issue - they get "CC'ed"
675 e-mails when messages are sent to or generated by the issue. The nosy
676 reactor (in the ``'detectors'`` directory) handles this action. The
677 superseder link indicates an issue which has superseded this one.
678
679 They also have the dynamically generated "creation", "activity" and
680 "creator" properties.
681
682 The value of the "creation" property is the date when an item was
683 created, and the value of the "activity" property is the date when any
684 property on the item was last edited (equivalently, these are the dates
685 on the first and last records in the item's journal). The "creator"
686 property holds a link to the user that created the issue.
687
688
689 setkey(property)
690 ~~~~~~~~~~~~~~~~
691
692 Select a String property of the class to be the key property. The key
693 property must be unique, and allows references to the items in the class
694 by the content of the key property. That is, we can refer to users by
695 their username: for example, let's say that there's an issue in roundup,
696 issue 23. There's also a user, richard, who happens to be user 2. To
697 assign an issue to him, we could do either of::
698
699      roundup-admin set issue23 assignedto=2
700
701 or::
702
703      roundup-admin set issue23 assignedto=richard
704
705 Note, the same thing can be done in the web and e-mail interfaces. 
706
707 setlabelprop(property)
708 ~~~~~~~~~~~~~~~~~~~~~~
709
710 Select a property of the class to be the label property. The label
711 property is used whereever an item should be uniquely identified, e.g.,
712 when displaying a link to an item. If setlabelprop is not specified for
713 a class, the following values are tried for the label: 
714
715  * the key of the class (see the `setkey(property)`_ section above)
716  * the "name" property
717  * the "title" property
718  * the first property from the sorted property name list
719
720 So in most cases you can get away without specifying setlabelprop
721 explicitly.
722
723 setorderprop(property)
724 ~~~~~~~~~~~~~~~~~~~~~~
725
726 Select a property of the class to be the order property. The order
727 property is used whenever using a default sort order for the class,
728 e.g., when grouping or sorting class A by a link to class B in the user
729 interface, the order property of class B is used for sorting.  If
730 setorderprop is not specified for a class, the following values are tried
731 for the order property:
732
733  * the property named "order"
734  * the label property (see `setlabelprop(property)`_ above)
735
736 So in most cases you can get away without specifying setorderprop
737 explicitly.
738
739 create(information)
740 ~~~~~~~~~~~~~~~~~~~
741
742 Create an item in the database. This is generally used to create items
743 in the "definitional" classes like "priority" and "status".
744
745
746 A note about ordering
747 ~~~~~~~~~~~~~~~~~~~~~
748
749 When we sort items in the hyperdb, we use one of a number of methods,
750 depending on the properties being sorted on:
751
752 1. If it's a String, Number, Date or Interval property, we just sort the
753    scalar value of the property. Strings are sorted case-sensitively.
754 2. If it's a Link property, we sort by either the linked item's "order"
755    property (if it has one) or the linked item's "id".
756 3. Mulitlinks sort similar to #2, but we start with the first Multilink
757    list item, and if they're the same, we sort by the second item, and
758    so on.
759
760 Note that if an "order" property is defined on a Class that is used for
761 sorting, all items of that Class *must* have a value against the "order"
762 property, or sorting will result in random ordering.
763
764
765 Examples of adding to your schema
766 ---------------------------------
767
768 The Roundup wiki has examples of how schemas can be customised to add
769 new functionality.
770
771
772 Detectors - adding behaviour to your tracker
773 ============================================
774 .. _detectors:
775
776 Detectors are initialised every time you open your tracker database, so
777 you're free to add and remove them any time, even after the database is
778 initialised via the ``roundup-admin initialise`` command.
779
780 The detectors in your tracker fire *before* (**auditors**) and *after*
781 (**reactors**) changes to the contents of your database. They are Python
782 modules that sit in your tracker's ``detectors`` directory. You will
783 have some installed by default - have a look. You can write new
784 detectors or modify the existing ones. The existing detectors installed
785 for you are:
786
787 **nosyreaction.py**
788   This provides the automatic nosy list maintenance and email sending.
789   The nosy reactor (``nosyreaction``) fires when new messages are added
790   to issues. The nosy auditor (``updatenosy``) fires when issues are
791   changed, and figures out what changes need to be made to the nosy list
792   (such as adding new authors, etc.)
793 **statusauditor.py**
794   This provides the ``chatty`` auditor which changes the issue status
795   from ``unread`` or ``closed`` to ``chatting`` if new messages appear.
796   It also provides the ``presetunread`` auditor which pre-sets the
797   status to ``unread`` on new items if the status isn't explicitly
798   defined.
799 **messagesummary.py**
800   Generates the ``summary`` property for new messages based on the message
801   content.
802 **userauditor.py**
803   Verifies the content of some of the user fields (email addresses and
804   roles lists).
805
806 If you don't want this default behaviour, you're completely free to change
807 or remove these detectors.
808
809 See the detectors section in the `design document`__ for details of the
810 interface for detectors.
811
812 __ design.html
813
814
815 Detector API
816 ------------
817
818 Auditors are called with the arguments::
819
820     audit(db, cl, itemid, newdata)
821
822 where ``db`` is the database, ``cl`` is an instance of Class or
823 IssueClass within the database, and ``newdata`` is a dictionary mapping
824 property names to values.
825
826 For a ``create()`` operation, the ``itemid`` argument is None and
827 newdata contains all of the initial property values with which the item
828 is about to be created.
829
830 For a ``set()`` operation, newdata contains only the names and values of
831 properties that are about to be changed.
832
833 For a ``retire()`` or ``restore()`` operation, newdata is None.
834
835 Reactors are called with the arguments::
836
837     react(db, cl, itemid, olddata)
838
839 where ``db`` is the database, ``cl`` is an instance of Class or
840 IssueClass within the database, and ``olddata`` is a dictionary mapping
841 property names to values.
842
843 For a ``create()`` operation, the ``itemid`` argument is the id of the
844 newly-created item and ``olddata`` is None.
845
846 For a ``set()`` operation, ``olddata`` contains the names and previous
847 values of properties that were changed.
848
849 For a ``retire()`` or ``restore()`` operation, ``itemid`` is the id of
850 the retired or restored item and ``olddata`` is None.
851
852
853 Additional Detectors Ready For Use
854 ----------------------------------
855
856 Sample additional detectors that have been found useful will appear in
857 the ``'detectors'`` directory of the Roundup distribution. If you want
858 to use one, copy it to the ``'detectors'`` of your tracker instance:
859
860 **newissuecopy.py**
861   This detector sends an email to a team address whenever a new issue is
862   created. The address is hard-coded into the detector, so edit it
863   before you use it (look for the text 'team@team.host') or you'll get
864   email errors!
865 **creator_resolution.py**
866   Catch attempts to set the status to "resolved" - if the assignedto
867   user isn't the creator, then set the status to "confirm-done". Note that
868   "classic" Roundup doesn't have that status, so you'll have to add it. If
869   you don't want to though, it'll just use "in-progress" instead.
870 **email_auditor.py**
871   If a file added to an issue is of type message/rfc822, we tack on the
872   extension .eml.
873   The reason for this is that Microsoft Internet Explorer will not open
874   things with a .eml attachment, as they deem it 'unsafe'. Worse yet,
875   they'll just give you an incomprehensible error message. For more 
876   information, see the detector code - it has a length explanation.
877
878
879 Auditor or Reactor?
880 -------------------
881
882 Generally speaking, the following rules should be observed:
883
884 **Auditors**
885   Are used for `vetoing creation of or changes to items`_. They might
886   also make automatic changes to item properties.
887 **Reactors**
888   Detect changes in the database and react accordingly. They should avoid
889   making changes to the database where possible, as this could create
890   detector loops.
891
892
893 Vetoing creation of or changes to items
894 ---------------------------------------
895
896 Auditors may raise the ``Reject`` exception to prevent the creation of
897 or changes to items in the database.  The mail gateway, for example, will
898 not attach files or messages to issues when the creation of those files or
899 messages are prevented through the ``Reject`` exception. It'll also not create
900 users if that creation is ``Reject``'ed too.
901
902 To use, simply add at the top of your auditor::
903
904    from roundup.exceptions import Reject
905
906 And then when your rejection criteria have been detected, simply::
907
908    raise Reject
909
910
911 Generating email from Roundup
912 -----------------------------
913
914 The module ``roundup.mailer`` contains most of the nuts-n-bolts required
915 to generate email messages from Roundup.
916
917 In addition, the ``IssueClass`` methods ``nosymessage()`` and
918 ``send_message()`` are used to generate nosy messages, and may generate
919 messages which only consist of a change note (ie. the message id parameter
920 is not required - this is referred to as a "System Message" because it
921 comes from "the system" and not a user).
922
923
924 Database Content
925 ================
926
927 .. note::
928    If you modify the content of definitional classes, you'll most
929    likely need to edit the tracker `detectors`_ to reflect your changes.
930
931 Customisation of the special "definitional" classes (eg. status,
932 priority, resolution, ...) may be done either before or after the
933 tracker is initialised. The actual method of doing so is completely
934 different in each case though, so be careful to use the right one.
935
936 **Changing content before tracker initialisation**
937     Edit the initial_data.py module in your tracker to alter the items
938     created using the ``create( ... )`` methods.
939
940 **Changing content after tracker initialisation**
941     As the "admin" user, click on the "class list" link in the web
942     interface to bring up a list of all database classes. Click on the
943     name of the class you wish to change the content of.
944
945     You may also use the ``roundup-admin`` interface's create, set and
946     retire methods to add, alter or remove items from the classes in
947     question.
948
949 See "`adding a new field to the classic schema`_" for an example that
950 requires database content changes.
951
952
953 Security / Access Controls
954 ==========================
955
956 A set of Permissions is built into the security module by default:
957
958 - Create (everything)
959 - Edit (everything)
960 - View (everything)
961 - Register (User class only)
962
963 These are assigned to the "Admin" Role by default, and allow a user to do
964 anything. Every Class you define in your `tracker schema`_ also gets an
965 Create, Edit and View Permission of its own. The web and email interfaces
966 also define:
967
968 *Email Access*
969   If defined, the user may use the email interface. Used by default to deny
970   Anonymous users access to the email interface. When granted to the
971   Anonymous user, they will be automatically registered by the email
972   interface (see also the ``new_email_user_roles`` configuration option).
973 *Web Access*
974   If defined, the user may use the web interface. All users are able to see
975   the login form, regardless of this setting (thus enabling logging in).
976 *Web Roles*
977   Controls user access to editing the "roles" property of the "user" class.
978   TODO: deprecate in favour of a property-based control.
979
980 These are hooked into the default Roles:
981
982 - Admin (Create, Edit, View and everything; Web Roles)
983 - User (Web Access; Email Access)
984 - Anonymous (Web Access)
985
986 And finally, the "admin" user gets the "Admin" Role, and the "anonymous"
987 user gets "Anonymous" assigned when the tracker is installed.
988
989 For the "User" Role, the "classic" tracker defines:
990
991 - Create, Edit and View issue, file, msg, query, keyword 
992 - View priority, status
993 - View user
994 - Edit their own user record
995
996 And the "Anonymous" Role is defined as:
997
998 - Web interface access
999 - Register user (for registration)
1000 - View issue, file, msg, query, keyword, priority, status
1001
1002 Put together, these settings appear in the tracker's ``schema.py`` file::
1003
1004     #
1005     # TRACKER SECURITY SETTINGS
1006     #
1007     # See the configuration and customisation document for information
1008     # about security setup.
1009
1010     #
1011     # REGULAR USERS
1012     #
1013     # Give the regular users access to the web and email interface
1014     db.security.addPermissionToRole('User', 'Web Access')
1015     db.security.addPermissionToRole('User', 'Email Access')
1016
1017     # Assign the access and edit Permissions for issue, file and message
1018     # to regular users now
1019     for cl in 'issue', 'file', 'msg', 'query', 'keyword':
1020         db.security.addPermissionToRole('User', 'View', cl)
1021         db.security.addPermissionToRole('User', 'Edit', cl)
1022         db.security.addPermissionToRole('User', 'Create', cl)
1023     for cl in 'priority', 'status':
1024         db.security.addPermissionToRole('User', 'View', cl)
1025
1026     # May users view other user information? Comment these lines out
1027     # if you don't want them to
1028     db.security.addPermissionToRole('User', 'View', 'user')
1029
1030     # Users should be able to edit their own details -- this permission
1031     # is limited to only the situation where the Viewed or Edited item
1032     # is their own.
1033     def own_record(db, userid, itemid):
1034         '''Determine whether the userid matches the item being accessed.'''
1035         return userid == itemid
1036     p = db.security.addPermission(name='View', klass='user', check=own_record,
1037         description="User is allowed to view their own user details")
1038     db.security.addPermissionToRole('User', p)
1039     p = db.security.addPermission(name='Edit', klass='user', check=own_record,
1040         description="User is allowed to edit their own user details")
1041     db.security.addPermissionToRole('User', p)
1042
1043     #
1044     # ANONYMOUS USER PERMISSIONS
1045     #
1046     # Let anonymous users access the web interface. Note that almost all
1047     # trackers will need this Permission. The only situation where it's not
1048     # required is in a tracker that uses an HTTP Basic Authenticated front-end.
1049     db.security.addPermissionToRole('Anonymous', 'Web Access')
1050
1051     # Let anonymous users access the email interface (note that this implies
1052     # that they will be registered automatically, hence they will need the
1053     # "Create" user Permission below)
1054     # This is disabled by default to stop spam from auto-registering users on
1055     # public trackers.
1056     #db.security.addPermissionToRole('Anonymous', 'Email Access')
1057
1058     # Assign the appropriate permissions to the anonymous user's Anonymous
1059     # Role. Choices here are:
1060     # - Allow anonymous users to register
1061     db.security.addPermissionToRole('Anonymous', 'Create', 'user')
1062
1063     # Allow anonymous users access to view issues (and the related, linked
1064     # information)
1065     for cl in 'issue', 'file', 'msg', 'keyword', 'priority', 'status':
1066         db.security.addPermissionToRole('Anonymous', 'View', cl)
1067
1068     # [OPTIONAL]
1069     # Allow anonymous users access to create or edit "issue" items (and the
1070     # related file and message items)
1071     #for cl in 'issue', 'file', 'msg':
1072     #   db.security.addPermissionToRole('Anonymous', 'Create', cl)
1073     #   db.security.addPermissionToRole('Anonymous', 'Edit', cl)
1074
1075
1076 Automatic Permission Checks
1077 ---------------------------
1078
1079 Permissions are automatically checked when information is rendered
1080 through the web. This includes:
1081
1082 1. View checks for properties when being rendered via the ``plain()`` or
1083    similar methods. If the check fails, the text "[hidden]" will be
1084    displayed.
1085 2. Edit checks for properties when the edit field is being rendered via
1086    the ``field()`` or similar methods. If the check fails, the property
1087    will be rendered via the ``plain()`` method (see point 1. for subsequent
1088    checking performed)
1089 3. View checks are performed in index pages for each item being displayed
1090    such that if the user does not have permission, the row is not rendered.
1091 4. View checks are performed at the top of item pages for the Item being
1092    displayed. If the user does not have permission, the text "You are not
1093    allowed to view this page." will be displayed.
1094 5. View checks are performed at the top of index pages for the Class being
1095    displayed. If the user does not have permission, the text "You are not
1096    allowed to view this page." will be displayed.
1097
1098
1099 New User Roles
1100 --------------
1101
1102 New users are assigned the Roles defined in the config file as:
1103
1104 - NEW_WEB_USER_ROLES
1105 - NEW_EMAIL_USER_ROLES
1106
1107 The `users may only edit their issues`_ example shows customisation of
1108 these parameters.
1109
1110
1111 Changing Access Controls
1112 ------------------------
1113
1114 You may alter the configuration variables to change the Role that new
1115 web or email users get, for example to not give them access to the web
1116 interface if they register through email. 
1117
1118 You may use the ``roundup-admin`` "``security``" command to display the
1119 current Role and Permission configuration in your tracker.
1120
1121
1122 Adding a new Permission
1123 ~~~~~~~~~~~~~~~~~~~~~~~
1124
1125 When adding a new Permission, you will need to:
1126
1127 1. add it to your tracker's ``schema.py`` so it is created, using
1128    ``security.addPermission``, for example::
1129
1130     self.security.addPermission(name="View", klass='frozzle',
1131         description="User is allowed to access frozzles")
1132
1133    will set up a new "View" permission on the Class "frozzle".
1134 2. enable it for the Roles that should have it (verify with
1135    "``roundup-admin security``")
1136 3. add it to the relevant HTML interface templates
1137 4. add it to the appropriate xxxPermission methods on in your tracker
1138    interfaces module
1139
1140 The ``addPermission`` method takes a couple of optional parameters:
1141
1142 **properties**
1143   A sequence of property names that are the only properties to apply the
1144   new Permission to (eg. ``... klass='user', properties=('name',
1145   'email') ...``)
1146 **check**
1147   A function to be execute which returns boolean determining whether the
1148   Permission is allowed. The function has the signature ``check(db, userid,
1149   itemid)`` where ``db`` is a handle on the open database, ``userid`` is
1150   the user attempting access and ``itemid`` is the specific item being
1151   accessed.
1152
1153 Example Scenarios
1154 ~~~~~~~~~~~~~~~~~
1155
1156 See the `examples`_ section for longer examples of customisation.
1157
1158 **anonymous access through the e-mail gateway**
1159  Give the "anonymous" user the "Email Access", ("Edit", "issue") and
1160  ("Create", "msg") Permissions but do not not give them the ("Create",
1161  "user") Permission. This means that when an unknown user sends email
1162  into the tracker, they're automatically logged in as "anonymous".
1163  Since they don't have the ("Create", "user") Permission, they won't
1164  be automatically registered, but since "anonymous" has permission to
1165  use the gateway, they'll still be able to submit issues. Note that
1166  the Sender information - their email address - will not be available
1167  - they're *anonymous*.
1168
1169 **automatic registration of users in the e-mail gateway**
1170  By giving the "anonymous" user the ("Register", "user") Permission, any
1171  unidentified user will automatically be registered with the tracker
1172  (with no password, so they won't be able to log in through
1173  the web until an admin sets their password). By default new Roundup
1174  trackers don't allow this as it opens them up to spam. It may be enabled
1175  by uncommenting the appropriate addPermissionToRole in your tracker's
1176  ``schema.py`` file. The new user is given the Roles list defined in the
1177  "new_email_user_roles" config variable. 
1178
1179 **only developers may be assigned issues**
1180  Create a new Permission called "Fixer" for the "issue" class. Create a
1181  new Role "Developer" which has that Permission, and assign that to the
1182  appropriate users. Filter the list of users available in the assignedto
1183  list to include only those users. Enforce the Permission with an
1184  auditor. See the example 
1185  `restricting the list of users that are assignable to a task`_.
1186
1187 **only managers may sign off issues as complete**
1188  Create a new Permission called "Closer" for the "issue" class. Create a
1189  new Role "Manager" which has that Permission, and assign that to the
1190  appropriate users. In your web interface, only display the "resolved"
1191  issue state option when the user has the "Closer" Permissions. Enforce
1192  the Permission with an auditor. This is very similar to the previous
1193  example, except that the web interface check would look like::
1194
1195    <option tal:condition="python:request.user.hasPermission('Closer')"
1196            value="resolved">Resolved</option>
1197  
1198 **don't give web access to users who register through email**
1199  Create a new Role called "Email User" which has all the Permissions of
1200  the normal "User" Role minus the "Web Access" Permission. This will
1201  allow users to send in emails to the tracker, but not access the web
1202  interface.
1203
1204 **let some users edit the details of all users**
1205  Create a new Role called "User Admin" which has the Permission for
1206  editing users::
1207
1208     db.security.addRole(name='User Admin', description='Managing users')
1209     p = db.security.getPermission('Edit', 'user')
1210     db.security.addPermissionToRole('User Admin', p)
1211
1212  and assign the Role to the users who need the permission.
1213
1214
1215 Web Interface
1216 =============
1217
1218 .. contents::
1219    :local:
1220
1221 The web interface is provided by the ``roundup.cgi.client`` module and
1222 is used by ``roundup.cgi``, ``roundup-server`` and ``ZRoundup``
1223 (``ZRoundup``  is broken, until further notice). In all cases, we
1224 determine which tracker is being accessed (the first part of the URL
1225 path inside the scope of the CGI handler) and pass control on to the
1226 ``roundup.cgi.client.Client`` class - which handles the rest of the
1227 access through its ``main()`` method. This means that you can do pretty
1228 much anything you want as a web interface to your tracker.
1229
1230
1231
1232 Repercussions of changing the tracker schema
1233 ---------------------------------------------
1234
1235 If you choose to change the `tracker schema`_ you will need to ensure
1236 the web interface knows about it:
1237
1238 1. Index, item and search pages for the relevant classes may need to
1239    have properties added or removed,
1240 2. The "page" template may require links to be changed, as might the
1241    "home" page's content arguments.
1242
1243
1244 How requests are processed
1245 --------------------------
1246
1247 The basic processing of a web request proceeds as follows:
1248
1249 1. figure out who we are, defaulting to the "anonymous" user
1250 2. figure out what the request is for - we call this the "context"
1251 3. handle any requested action (item edit, search, ...)
1252 4. render the template requested by the context, resulting in HTML
1253    output
1254
1255 In some situations, exceptions occur:
1256
1257 - HTTP Redirect  (generally raised by an action)
1258 - SendFile       (generally raised by ``determine_context``)
1259     here we serve up a FileClass "content" property
1260 - SendStaticFile (generally raised by ``determine_context``)
1261     here we serve up a file from the tracker "html" directory
1262 - Unauthorised   (generally raised by an action)
1263     here the action is cancelled, the request is rendered and an error
1264     message is displayed indicating that permission was not granted for
1265     the action to take place
1266 - NotFound       (raised wherever it needs to be)
1267     this exception percolates up to the CGI interface that called the
1268     client
1269
1270
1271 Determining web context
1272 -----------------------
1273
1274 To determine the "context" of a request, we look at the URL and the
1275 special request variable ``@template``. The URL path after the tracker
1276 identifier is examined. Typical URL paths look like:
1277
1278 1.  ``/tracker/issue``
1279 2.  ``/tracker/issue1``
1280 3.  ``/tracker/@@file/style.css``
1281 4.  ``/cgi-bin/roundup.cgi/tracker/file1``
1282 5.  ``/cgi-bin/roundup.cgi/tracker/file1/kitten.png``
1283
1284 where the "tracker identifier" is "tracker" in the above cases. That means
1285 we're looking at "issue", "issue1", "@@file/style.css", "file1" and
1286 "file1/kitten.png" in the cases above. The path is generally only one
1287 entry long - longer paths are handled differently.
1288
1289 a. if there is no path, then we are in the "home" context. See `the "home"
1290    context`_ below for more information about how it may be used.
1291 b. if the path starts with "@@file" (as in example 3,
1292    "/tracker/@@file/style.css"), then the additional path entry,
1293    "style.css" specifies the filename of a static file we're to serve up
1294    from the tracker TEMPLATES (or STATIC_FILES, if configured) directory.
1295    This is usually the tracker's "html" directory. Raises a SendStaticFile
1296    exception.
1297 c. if there is something in the path (as in example 1, "issue"), it
1298    identifies the tracker class we're to display.
1299 d. if the path is an item designator (as in examples 2 and 4, "issue1"
1300    and "file1"), then we're to display a specific item.
1301 e. if the path starts with an item designator and is longer than one
1302    entry (as in example 5, "file1/kitten.png"), then we're assumed to be
1303    handling an item of a ``FileClass``, and the extra path information
1304    gives the filename that the client is going to label the download
1305    with (i.e. "file1/kitten.png" is nicer to download than "file1").
1306    This raises a ``SendFile`` exception.
1307
1308 Both b. and e. stop before we bother to determine the template we're
1309 going to use. That's because they don't actually use templates.
1310
1311 The template used is specified by the ``@template`` CGI variable, which
1312 defaults to:
1313
1314 - only classname suplied:        "index"
1315 - full item designator supplied: "item"
1316
1317
1318 The "home" Context
1319 ------------------
1320
1321 The "home" context is special because it allows you to add templated
1322 pages to your tracker that don't rely on a class or item (ie. an issues
1323 list or specific issue).
1324
1325 Let's say you wish to add frames to control the layout of your tracker's
1326 interface. You'd probably have:
1327
1328 - A top-level frameset page. This page probably wouldn't be templated, so
1329   it could be served as a static file (see `serving static content`_)
1330 - A sidebar frame that is templated. Let's call this page
1331   "home.navigation.html" in your tracker's "html" directory. To load that
1332   page up, you use the URL:
1333
1334     <tracker url>/home?@template=navigation
1335
1336
1337 Serving static content
1338 ----------------------
1339
1340 See the previous section `determining web context`_ where it describes
1341 ``@@file`` paths.
1342
1343
1344 Performing actions in web requests
1345 ----------------------------------
1346
1347 When a user requests a web page, they may optionally also request for an
1348 action to take place. As described in `how requests are processed`_, the
1349 action is performed before the requested page is generated. Actions are
1350 triggered by using a ``@action`` CGI variable, where the value is one
1351 of:
1352
1353 **login**
1354  Attempt to log a user in.
1355
1356 **logout**
1357  Log the user out - make them "anonymous".
1358
1359 **register**
1360  Attempt to create a new user based on the contents of the form and then
1361  log them in.
1362
1363 **edit**
1364  Perform an edit of an item in the database. There are some `special form
1365  variables`_ you may use.
1366
1367 **new**
1368  Add a new item to the database. You may use the same `special form
1369  variables`_ as in the "edit" action.
1370
1371 **retire**
1372  Retire the item in the database.
1373
1374 **editCSV**
1375  Performs an edit of all of a class' items in one go. See also the
1376  *class*.csv templating method which generates the CSV data to be
1377  edited, and the ``'_generic.index'`` template which uses both of these
1378  features.
1379
1380 **search**
1381  Mangle some of the form variables:
1382
1383  - Set the form ":filter" variable based on the values of the filter
1384    variables - if they're set to anything other than "dontcare" then add
1385    them to :filter.
1386
1387  - Also handle the ":queryname" variable and save off the query to the
1388    user's query list.
1389
1390 Each of the actions is implemented by a corresponding ``*XxxAction*`` (where
1391 "Xxx" is the name of the action) class in the ``roundup.cgi.actions`` module.
1392 These classes are registered with ``roundup.cgi.client.Client``. If you need
1393 to define new actions, you may add them there (see `defining new
1394 web actions`_).
1395
1396 Each action class also has a ``*permission*`` method which determines whether
1397 the action is permissible given the current user. The base permission checks
1398 for each action are:
1399
1400 **login**
1401  Determine whether the user has the "Web Access" Permission.
1402 **logout**
1403  No permission checks are made.
1404 **register**
1405  Determine whether the user has the ("Create", "user") Permission.
1406 **edit**
1407  Determine whether the user has permission to edit this item. If we're
1408  editing the "user" class, users are allowed to edit their own details -
1409  unless they try to edit the "roles" property, which requires the
1410  special Permission "Web Roles".
1411 **new**
1412  Determine whether the user has permission to create this item. No
1413  additional property checks are made. Additionally, new user items may
1414  be created if the user has the ("Create", "user") Permission.
1415 **editCSV**
1416  Determine whether the user has permission to edit this class.
1417 **search**
1418  Determine whether the user has permission to view this class.
1419
1420
1421 Special form variables
1422 ----------------------
1423
1424 Item properties and their values are edited with html FORM
1425 variables and their values. You can:
1426
1427 - Change the value of some property of the current item.
1428 - Create a new item of any class, and edit the new item's
1429   properties,
1430 - Attach newly created items to a multilink property of the
1431   current item.
1432 - Remove items from a multilink property of the current item.
1433 - Specify that some properties are required for the edit
1434   operation to be successful.
1435 - Set up user interface locale.
1436
1437 These operations will only take place if the form action (the
1438 ``@action`` variable) is "edit" or "new".
1439
1440 In the following, <bracketed> values are variable, "@" may be
1441 either ":" or "@", and other text "required" is fixed.
1442
1443 Two special form variables are used to specify user language preferences:
1444
1445 ``@language``
1446   value may be locale name or ``none``. If this variable is set to
1447   locale name, web interface language is changed to given value
1448   (provided that appropriate translation is available), the value
1449   is stored in the browser cookie and will be used for all following
1450   requests.  If value is ``none`` the cookie is removed and the
1451   language is changed to the tracker default, set up in the tracker
1452   configuration or OS environment.
1453
1454 ``@charset``
1455   value may be character set name or ``none``.  Character set name
1456   is stored in the browser cookie and sets output encoding for all
1457   HTML pages generated by Roundup.  If value is ``none`` the cookie
1458   is removed and HTML output is reset to Roundup internal encoding
1459   (UTF-8).
1460
1461 Most properties are specified as form variables:
1462
1463 ``<propname>``
1464   property on the current context item
1465
1466 ``<designator>"@"<propname>``
1467   property on the indicated item (for editing related information)
1468
1469 Designators name a specific item of a class.
1470
1471 ``<classname><N>``
1472     Name an existing item of class <classname>.
1473
1474 ``<classname>"-"<N>``
1475     Name the <N>th new item of class <classname>. If the form
1476     submission is successful, a new item of <classname> is
1477     created. Within the submitted form, a particular
1478     designator of this form always refers to the same new
1479     item.
1480
1481 Once we have determined the "propname", we look at it to see
1482 if it's special:
1483
1484 ``@required``
1485     The associated form value is a comma-separated list of
1486     property names that must be specified when the form is
1487     submitted for the edit operation to succeed.  
1488
1489     When the <designator> is missing, the properties are
1490     for the current context item.  When <designator> is
1491     present, they are for the item specified by
1492     <designator>.
1493
1494     The "@required" specifier must come before any of the
1495     properties it refers to are assigned in the form.
1496
1497 ``@remove@<propname>=id(s)`` or ``@add@<propname>=id(s)``
1498     The "@add@" and "@remove@" edit actions apply only to
1499     Multilink properties.  The form value must be a
1500     comma-separate list of keys for the class specified by
1501     the simple form variable.  The listed items are added
1502     to (respectively, removed from) the specified
1503     property.
1504
1505 ``@link@<propname>=<designator>``
1506     If the edit action is "@link@", the simple form
1507     variable must specify a Link or Multilink property.
1508     The form value is a comma-separated list of
1509     designators.  The item corresponding to each
1510     designator is linked to the property given by simple
1511     form variable.
1512
1513 None of the above (ie. just a simple form value)
1514     The value of the form variable is converted
1515     appropriately, depending on the type of the property.
1516
1517     For a Link('klass') property, the form value is a
1518     single key for 'klass', where the key field is
1519     specified in schema.py.  
1520
1521     For a Multilink('klass') property, the form value is a
1522     comma-separated list of keys for 'klass', where the
1523     key field is specified in schema.py.  
1524
1525     Note that for simple-form-variables specifiying Link
1526     and Multilink properties, the linked-to class must
1527     have a key field.
1528
1529     For a String() property specifying a filename, the
1530     file named by the form value is uploaded. This means we
1531     try to set additional properties "filename" and "type" (if
1532     they are valid for the class).  Otherwise, the property
1533     is set to the form value.
1534
1535     For Date(), Interval(), Boolean(), and Number()
1536     properties, the form value is converted to the
1537     appropriate
1538
1539 Any of the form variables may be prefixed with a classname or
1540 designator.
1541
1542 Two special form values are supported for backwards compatibility:
1543
1544 @note
1545     This is equivalent to::
1546
1547         @link@messages=msg-1
1548         msg-1@content=value
1549
1550     except that in addition, the "author" and "date" properties of
1551     "msg-1" are set to the userid of the submitter, and the current
1552     time, respectively.
1553
1554 @file
1555     This is equivalent to::
1556
1557         @link@files=file-1
1558         file-1@content=value
1559
1560     The String content value is handled as described above for file
1561     uploads.
1562
1563 If both the "@note" and "@file" form variables are
1564 specified, the action::
1565
1566         @link@msg-1@files=file-1
1567
1568 is also performed.
1569
1570 We also check that FileClass items have a "content" property with
1571 actual content, otherwise we remove them from all_props before
1572 returning.
1573
1574
1575 Default templates
1576 -----------------
1577
1578 The default templates are html4 compliant. If you wish to change them to be
1579 xhtml compliant, you'll need to change the ``html_version`` configuration
1580 variable in ``config.ini`` to ``'xhtml'`` instead of ``'html4'``.
1581
1582 Most customisation of the web view can be done by modifying the
1583 templates in the tracker ``'html'`` directory. There are several types
1584 of files in there. The *minimal* template includes:
1585
1586 **page.html**
1587   This template usually defines the overall look of your tracker. When
1588   you view an issue, it appears inside this template. When you view an
1589   index, it also appears inside this template. This template defines a
1590   macro called "icing" which is used by almost all other templates as a
1591   coating for their content, using its "content" slot. It also defines
1592   the "head_title" and "body_title" slots to allow setting of the page
1593   title.
1594 **home.html**
1595   the default page displayed when no other page is indicated by the user
1596 **home.classlist.html**
1597   a special version of the default page that lists the classes in the
1598   tracker
1599 **classname.item.html**
1600   displays an item of the *classname* class
1601 **classname.index.html**
1602   displays a list of *classname* items
1603 **classname.search.html**
1604   displays a search page for *classname* items
1605 **_generic.index.html**
1606   used to display a list of items where there is no
1607   ``*classname*.index`` available
1608 **_generic.help.html**
1609   used to display a "class help" page where there is no
1610   ``*classname*.help``
1611 **user.register.html**
1612   a special page just for the user class, that renders the registration
1613   page
1614 **style.css.html**
1615   a static file that is served up as-is
1616
1617 The *classic* template has a number of additional templates.
1618
1619 Remember that you can create any template extension you want to,
1620 so if you just want to play around with the templating for new issues,
1621 you can copy the current "issue.item" template to "issue.test", and then
1622 access the test template using the "@template" URL argument::
1623
1624    http://your.tracker.example/tracker/issue?@template=test
1625
1626 and it won't affect your users using the "issue.item" template.
1627
1628
1629 How the templates work
1630 ----------------------
1631
1632
1633 Basic Templating Actions
1634 ~~~~~~~~~~~~~~~~~~~~~~~~
1635
1636 Roundup's templates consist of special attributes on the HTML tags.
1637 These attributes form the `Template Attribute Language`_, or TAL.
1638 The basic TAL commands are:
1639
1640 **tal:define="variable expression; variable expression; ..."**
1641    Define a new variable that is local to this tag and its contents. For
1642    example::
1643
1644       <html tal:define="title request/description">
1645        <head><title tal:content="title"></title></head>
1646       </html>
1647
1648    In this example, the variable "title" is defined as the result of the
1649    expression "request/description". The "tal:content" command inside the
1650    <html> tag may then use the "title" variable.
1651
1652 **tal:condition="expression"**
1653    Only keep this tag and its contents if the expression is true. For
1654    example::
1655
1656      <p tal:condition="python:request.user.hasPermission('View', 'issue')">
1657       Display some issue information.
1658      </p>
1659
1660    In the example, the <p> tag and its contents are only displayed if
1661    the user has the "View" permission for issues. We consider the number
1662    zero, a blank string, an empty list, and the built-in variable
1663    nothing to be false values. Nearly every other value is true,
1664    including non-zero numbers, and strings with anything in them (even
1665    spaces!).
1666
1667 **tal:repeat="variable expression"**
1668    Repeat this tag and its contents for each element of the sequence
1669    that the expression returns, defining a new local variable and a
1670    special "repeat" variable for each element. For example::
1671
1672      <tr tal:repeat="u user/list">
1673       <td tal:content="u/id"></td>
1674       <td tal:content="u/username"></td>
1675       <td tal:content="u/realname"></td>
1676      </tr>
1677
1678    The example would iterate over the sequence of users returned by
1679    "user/list" and define the local variable "u" for each entry. Using
1680    the repeat command creates a new variable called "repeat" which you
1681    may access to gather information about the iteration. See the section
1682    below on `the repeat variable`_.
1683
1684 **tal:replace="expression"**
1685    Replace this tag with the result of the expression. For example::
1686
1687     <span tal:replace="request/user/realname" />
1688
1689    The example would replace the <span> tag and its contents with the
1690    user's realname. If the user's realname was "Bruce", then the
1691    resultant output would be "Bruce".
1692
1693 **tal:content="expression"**
1694    Replace the contents of this tag with the result of the expression.
1695    For example::
1696
1697     <span tal:content="request/user/realname">user's name appears here
1698     </span>
1699
1700    The example would replace the contents of the <span> tag with the
1701    user's realname. If the user's realname was "Bruce" then the
1702    resultant output would be "<span>Bruce</span>".
1703
1704 **tal:attributes="attribute expression; attribute expression; ..."**
1705    Set attributes on this tag to the results of expressions. For
1706    example::
1707
1708      <a tal:attributes="href string:user${request/user/id}">My Details</a>
1709
1710    In the example, the "href" attribute of the <a> tag is set to the
1711    value of the "string:user${request/user/id}" expression, which will
1712    be something like "user123".
1713
1714 **tal:omit-tag="expression"**
1715    Remove this tag (but not its contents) if the expression is true. For
1716    example::
1717
1718       <span tal:omit-tag="python:1">Hello, world!</span>
1719
1720    would result in output of::
1721
1722       Hello, world!
1723
1724 Note that the commands on a given tag are evaulated in the order above,
1725 so *define* comes before *condition*, and so on.
1726
1727 Additionally, you may include tags such as <tal:block>, which are
1728 removed from output. Its content is kept, but the tag itself is not (so
1729 don't go using any "tal:attributes" commands on it). This is useful for
1730 making arbitrary blocks of HTML conditional or repeatable (very handy
1731 for repeating multiple table rows, which would othewise require an
1732 illegal tag placement to effect the repeat).
1733
1734 .. _TAL:
1735 .. _Template Attribute Language:
1736    http://dev.zope.org/Wikis/DevSite/Projects/ZPT/TAL%20Specification%201.4
1737
1738
1739 Templating Expressions
1740 ~~~~~~~~~~~~~~~~~~~~~~
1741
1742 Templating Expressions are covered by `Template Attribute Language
1743 Expression Syntax`_, or TALES. The expressions you may use in the
1744 attribute values may be one of the following forms:
1745
1746 **Path Expressions** - eg. ``item/status/checklist``
1747    These are object attribute / item accesses. Roughly speaking, the
1748    path ``item/status/checklist`` is broken into parts ``item``,
1749    ``status`` and ``checklist``. The ``item`` part is the root of the
1750    expression. We then look for a ``status`` attribute on ``item``, or
1751    failing that, a ``status`` item (as in ``item['status']``). If that
1752    fails, the path expression fails. When we get to the end, the object
1753    we're left with is evaluated to get a string - if it is a method, it
1754    is called; if it is an object, it is stringified. Path expressions
1755    may have an optional ``path:`` prefix, but they are the default
1756    expression type, so it's not necessary.
1757
1758    If an expression evaluates to ``default``, then the expression is
1759    "cancelled" - whatever HTML already exists in the template will
1760    remain (tag content in the case of ``tal:content``, attributes in the
1761    case of ``tal:attributes``).
1762
1763    If an expression evaluates to ``nothing`` then the target of the
1764    expression is removed (tag content in the case of ``tal:content``,
1765    attributes in the case of ``tal:attributes`` and the tag itself in
1766    the case of ``tal:replace``).
1767
1768    If an element in the path may not exist, then you can use the ``|``
1769    operator in the expression to provide an alternative. So, the
1770    expression ``request/form/foo/value | default`` would simply leave
1771    the current HTML in place if the "foo" form variable doesn't exist.
1772
1773    You may use the python function ``path``, as in
1774    ``path("item/status")``, to embed path expressions in Python
1775    expressions.
1776
1777 **String Expressions** - eg. ``string:hello ${user/name}`` 
1778    These expressions are simple string interpolations - though they can
1779    be just plain strings with no interpolation if you want. The
1780    expression in the ``${ ... }`` is just a path expression as above.
1781
1782 **Python Expressions** - eg. ``python: 1+1`` 
1783    These expressions give the full power of Python. All the "root level"
1784    variables are available, so ``python:item.status.checklist()`` would
1785    be equivalent to ``item/status/checklist``, assuming that
1786    ``checklist`` is a method.
1787
1788 Modifiers:
1789
1790 **structure** - eg. ``structure python:msg.content.plain(hyperlink=1)``
1791    The result of expressions are normally *escaped* to be safe for HTML
1792    display (all "<", ">" and "&" are turned into special entities). The
1793    ``structure`` expression modifier turns off this escaping - the
1794    result of the expression is now assumed to be HTML, which is passed
1795    to the web browser for rendering.
1796
1797 **not:** - eg. ``not:python:1=1``
1798    This simply inverts the logical true/false value of another
1799    expression.
1800
1801 .. _TALES:
1802 .. _Template Attribute Language Expression Syntax:
1803    http://dev.zope.org/Wikis/DevSite/Projects/ZPT/TALES%20Specification%201.3
1804
1805
1806 Template Macros
1807 ~~~~~~~~~~~~~~~
1808
1809 Macros are used in Roundup to save us from repeating the same common
1810 page stuctures over and over. The most common (and probably only) macro
1811 you'll use is the "icing" macro defined in the "page" template.
1812
1813 Macros are generated and used inside your templates using special
1814 attributes similar to the `basic templating actions`_. In this case,
1815 though, the attributes belong to the `Macro Expansion Template
1816 Attribute Language`_, or METAL. The macro commands are:
1817
1818 **metal:define-macro="macro name"**
1819   Define that the tag and its contents are now a macro that may be
1820   inserted into other templates using the *use-macro* command. For
1821   example::
1822
1823     <html metal:define-macro="page">
1824      ...
1825     </html>
1826
1827   defines a macro called "page" using the ``<html>`` tag and its
1828   contents. Once defined, macros are stored on the template they're
1829   defined on in the ``macros`` attribute. You can access them later on
1830   through the ``templates`` variable, eg. the most common
1831   ``templates/page/macros/icing`` to access the "page" macro of the
1832   "page" template.
1833
1834 **metal:use-macro="path expression"**
1835   Use a macro, which is identified by the path expression (see above).
1836   This will replace the current tag with the identified macro contents.
1837   For example::
1838
1839    <tal:block metal:use-macro="templates/page/macros/icing">
1840     ...
1841    </tal:block>
1842
1843    will replace the tag and its contents with the "page" macro of the
1844    "page" template.
1845
1846 **metal:define-slot="slot name"** and **metal:fill-slot="slot name"**
1847   To define *dynamic* parts of the macro, you define "slots" which may
1848   be filled when the macro is used with a *use-macro* command. For
1849   example, the ``templates/page/macros/icing`` macro defines a slot like
1850   so::
1851
1852     <title metal:define-slot="head_title">title goes here</title>
1853
1854   In your *use-macro* command, you may now use a *fill-slot* command
1855   like this::
1856
1857     <title metal:fill-slot="head_title">My Title</title>
1858
1859   where the tag that fills the slot completely replaces the one defined
1860   as the slot in the macro.
1861
1862 Note that you may not mix `METAL`_ and `TAL`_ commands on the same tag, but
1863 TAL commands may be used freely inside METAL-using tags (so your
1864 *fill-slots* tags may have all manner of TAL inside them).
1865
1866 .. _METAL:
1867 .. _Macro Expansion Template Attribute Language:
1868    http://dev.zope.org/Wikis/DevSite/Projects/ZPT/METAL%20Specification%201.0
1869
1870 Information available to templates
1871 ----------------------------------
1872
1873 This is implemented by ``roundup.cgi.templating.RoundupPageTemplate``
1874
1875 The following variables are available to templates.
1876
1877 **context**
1878   The current context. This is either None, a `hyperdb class wrapper`_
1879   or a `hyperdb item wrapper`_
1880 **request**
1881   Includes information about the current request, including:
1882    - the current index information (``filterspec``, ``filter`` args,
1883      ``properties``, etc) parsed out of the form. 
1884    - methods for easy filterspec link generation
1885    - "form"
1886      The current CGI form information as a mapping of form argument name
1887      to value (specifically a cgi.FieldStorage)
1888    - "env" the CGI environment variables
1889    - "base" the base URL for this instance
1890    - "user" a HTMLItem instance for the current user
1891    - "language" as determined by the browser or config
1892    - "classname" the current classname (possibly None)
1893    - "template" the current template (suffix, also possibly None)
1894 **config**
1895   This variable holds all the values defined in the tracker config.ini
1896   file (eg. TRACKER_NAME, etc.)
1897 **db**
1898   The current database, used to access arbitrary database items.
1899 **templates**
1900   Access to all the tracker templates by name. Used mainly in
1901   *use-macro* commands.
1902 **utils**
1903   This variable makes available some utility functions like batching.
1904 **nothing**
1905   This is a special variable - if an expression evaluates to this, then
1906   the tag (in the case of a ``tal:replace``), its contents (in the case
1907   of ``tal:content``) or some attributes (in the case of
1908   ``tal:attributes``) will not appear in the the output. So, for
1909   example::
1910
1911     <span tal:attributes="class nothing">Hello, World!</span>
1912
1913   would result in::
1914
1915     <span>Hello, World!</span>
1916
1917 **default**
1918   Also a special variable - if an expression evaluates to this, then the
1919   existing HTML in the template will not be replaced or removed, it will
1920   remain. So::
1921
1922     <span tal:replace="default">Hello, World!</span>
1923
1924   would result in::
1925
1926     <span>Hello, World!</span>
1927
1928 **true**, **false**
1929   Boolean constants that may be used in `templating expressions`_
1930   instead of ``python:1`` and ``python:0``.
1931 **i18n**
1932   Internationalization service, providing two string translation methods:
1933
1934   **gettext** (*message*)
1935     Return the localized translation of message
1936   **ngettext** (*singular*, *plural*, *number*)
1937     Like ``gettext()``, but consider plural forms. If a translation
1938     is found, apply the plural formula to *number*, and return the
1939     resulting message (some languages have more than two plural forms).
1940     If no translation is found, return singular if *number* is 1;
1941     return plural otherwise.
1942
1943     This function requires python2.3; in earlier python versions
1944     may not work as expected.
1945
1946 The context variable
1947 ~~~~~~~~~~~~~~~~~~~~
1948
1949 The *context* variable is one of three things based on the current
1950 context (see `determining web context`_ for how we figure this out):
1951
1952 1. if we're looking at a "home" page, then it's None
1953 2. if we're looking at a specific hyperdb class, it's a
1954    `hyperdb class wrapper`_.
1955 3. if we're looking at a specific hyperdb item, it's a
1956    `hyperdb item wrapper`_.
1957
1958 If the context is not None, we can access the properties of the class or
1959 item. The only real difference between cases 2 and 3 above are:
1960
1961 1. the properties may have a real value behind them, and this will
1962    appear if the property is displayed through ``context/property`` or
1963    ``context/property/field``.
1964 2. the context's "id" property will be a false value in the second case,
1965    but a real, or true value in the third. Thus we can determine whether
1966    we're looking at a real item from the hyperdb by testing
1967    "context/id".
1968
1969 Hyperdb class wrapper
1970 :::::::::::::::::::::
1971
1972 This is implemented by the ``roundup.cgi.templating.HTMLClass``
1973 class.
1974
1975 This wrapper object provides access to a hyperb class. It is used
1976 primarily in both index view and new item views, but it's also usable
1977 anywhere else that you wish to access information about a class, or the
1978 items of a class, when you don't have a specific item of that class in
1979 mind.
1980
1981 We allow access to properties. There will be no "id" property. The value
1982 accessed through the property will be the current value of the same name
1983 from the CGI form.
1984
1985 There are several methods available on these wrapper objects:
1986
1987 =========== =============================================================
1988 Method      Description
1989 =========== =============================================================
1990 properties  return a `hyperdb property wrapper`_ for all of this class's
1991             properties.
1992 list        lists all of the active (not retired) items in the class.
1993 csv         return the items of this class as a chunk of CSV text.
1994 propnames   lists the names of the properties of this class.
1995 filter      lists of items from this class, filtered and sorted. Two
1996             options are avaible for sorting:
1997
1998             1. by the current *request* filterspec/filter/sort/group args
1999             2. by the "filterspec", "sort" and "group" keyword args.
2000                "filterspec" is ``{propname: value(s)}``. "sort" and
2001                "group" are an optionally empty list ``[(dir, prop)]``
2002                where dir is '+', '-' or None
2003                and prop is a prop name or None.
2004
2005                The propname in filterspec and prop in a sort/group spec
2006                may be transitive, i.e., it may contain properties of
2007                the form link.link.link.name.
2008
2009             eg. All issues with a priority of "1" with messages added in
2010             the last week, sorted by activity date:
2011             ``issue.filter(filterspec={"priority": "1",
2012             'messages.creation' : '.-1w;'}, sort=[('activity', '+')])``
2013
2014 filter_sql  **Only in SQL backends**
2015
2016             Lists the items that match the SQL provided. The SQL is a
2017             complete "select" statement.
2018
2019             The SQL select must include the item id as the first column.
2020
2021             This function **does not** filter out retired items, add
2022             on a where clause "__retired__ <> 1" if you don't want
2023             retired nodes.
2024
2025 classhelp   display a link to a javascript popup containing this class'
2026             "help" template.
2027
2028             This generates a link to a popup window which displays the
2029             properties indicated by "properties" of the class named by
2030             "classname". The "properties" should be a comma-separated list
2031             (eg. 'id,name,description'). Properties defaults to all the
2032             properties of a class (excluding id, creator, created and
2033             activity).
2034
2035             You may optionally override the "label" displayed, the "width",
2036             the "height", the number of items per page ("pagesize") and
2037             the field on which the list is sorted ("sort").
2038
2039             With the "filter" arg it is possible to specify a filter for
2040             which items are supposed to be displayed. It has to be of
2041             the format "<field>=<values>;<field>=<values>;...".
2042
2043             The popup window will be resizable and scrollable.
2044
2045             If the "property" arg is given, it's passed through to the
2046             javascript help_window function. This allows updating of a
2047             property in the calling HTML page.
2048
2049             If the "form" arg is given, it's passed through to the
2050             javascript help_window function - it's the name of the form
2051             the "property" belongs to.
2052
2053 submit      generate a submit button (and action hidden element)
2054 renderWith  render this class with the given template.
2055 history     returns 'New node - no history' :)
2056 is_edit_ok  is the user allowed to Edit the current class?
2057 is_view_ok  is the user allowed to View the current class?
2058 =========== =============================================================
2059
2060 Note that if you have a property of the same name as one of the above
2061 methods, you'll need to access it using a python "item access"
2062 expression. For example::
2063
2064    python:context['list']
2065
2066 will access the "list" property, rather than the list method.
2067
2068
2069 Hyperdb item wrapper
2070 ::::::::::::::::::::
2071
2072 This is implemented by the ``roundup.cgi.templating.HTMLItem``
2073 class.
2074
2075 This wrapper object provides access to a hyperb item.
2076
2077 We allow access to properties. There will be no "id" property. The value
2078 accessed through the property will be the current value of the same name
2079 from the CGI form.
2080
2081 There are several methods available on these wrapper objects:
2082
2083 =============== ========================================================
2084 Method          Description
2085 =============== ========================================================
2086 submit          generate a submit button (and action hidden element)
2087 journal         return the journal of the current item (**not
2088                 implemented**)
2089 history         render the journal of the current item as HTML
2090 renderQueryForm specific to the "query" class - render the search form
2091                 for the query
2092 hasPermission   specific to the "user" class - determine whether the
2093                 user has a Permission. The signature is::
2094
2095                     hasPermission(self, permission, [classname=],
2096                         [property=], [itemid=])
2097
2098                 where the classname defaults to the current context.
2099 hasRole         specific to the "user" class - determine whether the
2100                 user has a Role. The signature is::
2101
2102                     hasRole(self, rolename)
2103
2104 is_edit_ok      is the user allowed to Edit the current item?
2105 is_view_ok      is the user allowed to View the current item?
2106 is_retired      is the item retired?
2107 download_url    generate a url-quoted link for download of FileClass
2108                 item contents (ie. file<id>/<name>)
2109 copy_url        generate a url-quoted link for creating a copy
2110                 of this item.  By default, the copy will acquire
2111                 all properties of the current item except for
2112                 ``messages`` and ``files``.  This can be overridden
2113                 by passing ``exclude`` argument which contains a list
2114                 (or any iterable) of property names that shall not be
2115                 copied.  Database-driven properties like ``id`` or
2116                 ``activity`` cannot be copied.
2117 =============== ========================================================
2118
2119 Note that if you have a property of the same name as one of the above
2120 methods, you'll need to access it using a python "item access"
2121 expression. For example::
2122
2123    python:context['journal']
2124
2125 will access the "journal" property, rather than the journal method.
2126
2127
2128 Hyperdb property wrapper
2129 ::::::::::::::::::::::::
2130
2131 This is implemented by subclasses of the
2132 ``roundup.cgi.templating.HTMLProperty`` class (``HTMLStringProperty``,
2133 ``HTMLNumberProperty``, and so on).
2134
2135 This wrapper object provides access to a single property of a class. Its
2136 value may be either:
2137
2138 1. if accessed through a `hyperdb item wrapper`_, then it's a value from
2139    the hyperdb
2140 2. if access through a `hyperdb class wrapper`_, then it's a value from
2141    the CGI form
2142
2143
2144 The property wrapper has some useful attributes:
2145
2146 =============== ========================================================
2147 Attribute       Description
2148 =============== ========================================================
2149 _name           the name of the property
2150 _value          the value of the property if any - this is the actual
2151                 value retrieved from the hyperdb for this property
2152 =============== ========================================================
2153
2154 There are several methods available on these wrapper objects:
2155
2156 =========== ================================================================
2157 Method      Description
2158 =========== ================================================================
2159 plain       render a "plain" representation of the property. This method
2160             may take two arguments:
2161
2162             escape
2163              If true, escape the text so it is HTML safe (default: no). The
2164              reason this defaults to off is that text is usually escaped
2165              at a later stage by the TAL commands, unless the "structure"
2166              option is used in the template. The following ``tal:content``
2167              expressions are all equivalent::
2168  
2169               "structure python:msg.content.plain(escape=1)"
2170               "python:msg.content.plain()"
2171               "msg/content/plain"
2172               "msg/content"
2173
2174              Usually you'll only want to use the escape option in a
2175              complex expression.
2176
2177             hyperlink
2178              If true, turn URLs, email addresses and hyperdb item
2179              designators in the text into hyperlinks (default: no). Note
2180              that you'll need to use the "structure" TAL option if you
2181              want to use this ``tal:content`` expression::
2182   
2183               "structure python:msg.content.plain(hyperlink=1)"
2184
2185              The text is automatically HTML-escaped before the hyperlinking
2186              transformation done in the plain() method.
2187
2188 hyperlinked The same as msg.content.plain(hyperlink=1), but nicer::
2189
2190               "structure msg/content/hyperlinked"
2191
2192 field       render an appropriate form edit field for the property - for
2193             most types this is a text entry box, but for Booleans it's a
2194             tri-state yes/no/neither selection. This method may take some
2195             arguments:
2196
2197             size
2198               Sets the width in characters of the edit field
2199
2200             format (Date properties only)
2201               Sets the format of the date in the field - uses the same
2202               format string argument as supplied to the ``pretty`` method
2203               below.
2204
2205             popcal (Date properties only)
2206               Include the Javascript-based popup calendar for date
2207               selection. Defaults to on.
2208
2209 stext       only on String properties - render the value of the property
2210             as StructuredText (requires the StructureText module to be
2211             installed separately)
2212 multiline   only on String properties - render a multiline form edit
2213             field for the property
2214 email       only on String properties - render the value of the property
2215             as an obscured email address
2216 confirm     only on Password properties - render a second form edit field
2217             for the property, used for confirmation that the user typed
2218             the password correctly. Generates a field with name
2219             "name:confirm".
2220 now         only on Date properties - return the current date as a new
2221             property
2222 reldate     only on Date properties - render the interval between the date
2223             and now
2224 local       only on Date properties - return this date as a new property
2225             with some timezone offset, for example::
2226             
2227                 python:context.creation.local(10)
2228
2229             will render the date with a +10 hour offset.
2230 pretty      Date properties - render the date as "dd Mon YYYY" (eg. "19
2231             Mar 2004"). Takes an optional format argument, for example::
2232
2233                 python:context.activity.pretty('%Y-%m-%d')
2234
2235             Will format as "2004-03-19" instead.
2236
2237             Interval properties - render the interval in a pretty
2238             format (eg. "yesterday"). The format arguments are those used
2239             in the standard ``strftime`` call (see the `Python Library
2240             Reference: time module`__)
2241 popcal      Generate a link to a popup calendar which may be used to
2242             edit the date field, for example::
2243
2244               <span tal:replace="structure context/due/popcal" />
2245
2246             you still need to include the ``field`` for the property, so
2247             typically you'd have::
2248
2249               <span tal:replace="structure context/due/field" />
2250               <span tal:replace="structure context/due/popcal" />
2251
2252 menu        only on Link and Multilink properties - render a form select
2253             list for this property. Takes a number of optional arguments
2254
2255             size
2256                is used to limit the length of the list labels
2257             height
2258                is used to set the <select> tag's "size" attribute
2259             showid
2260                includes the item ids in the list labels
2261             additional
2262                lists properties which should be included in the label
2263             sort_on
2264                 indicates the property to sort the list on as (direction,
2265                 (direction, property) where direction is '+' or '-'. A
2266                 single string with the direction prepended may be used.
2267                 For example: ('-', 'order'), '+name'.
2268             value
2269                 gives a default value to preselect in the menu
2270
2271             The remaining keyword arguments are used as conditions for
2272             filtering the items in the list - they're passed as the
2273             "filterspec" argument to a Class.filter() call. For example::
2274
2275              <span tal:replace="structure context/status/menu" />
2276
2277              <span tal:replace="python:context.status.menu(order='+name",
2278                                    value='chatting', 
2279                                    filterspec={'status': '1,2,3,4'}" />
2280
2281 sorted      only on Multilink properties - produce a list of the linked
2282             items sorted by some property, for example::
2283             
2284                 python:context.files.sorted('creation')
2285
2286             Will list the files by upload date.
2287 reverse     only on Multilink properties - produce a list of the linked
2288             items in reverse order
2289 isset       returns True if the property has been set to a value
2290 =========== ================================================================
2291
2292 __ http://docs.python.org/lib/module-time.html
2293
2294 All of the above functions perform checks for permissions required to
2295 display or edit the data they are manipulating. The simplest case is
2296 editing an issue title. Including the expression::
2297
2298    context/title/field
2299
2300 Will present the user with an edit field, if they have edit permission. If
2301 not, then they will be presented with a static display if they have view
2302 permission. If they don't even have view permission, then an error message
2303 is raised, preventing the display of the page, indicating that they don't
2304 have permission to view the information.
2305
2306
2307 The request variable
2308 ~~~~~~~~~~~~~~~~~~~~
2309
2310 This is implemented by the ``roundup.cgi.templating.HTMLRequest``
2311 class.
2312
2313 The request variable is packed with information about the current
2314 request.
2315
2316 .. taken from ``roundup.cgi.templating.HTMLRequest`` docstring
2317
2318 =========== ============================================================
2319 Variable    Holds
2320 =========== ============================================================
2321 form        the CGI form as a cgi.FieldStorage
2322 env         the CGI environment variables
2323 base        the base URL for this tracker
2324 user        a HTMLUser instance for this user
2325 classname   the current classname (possibly None)
2326 template    the current template (suffix, also possibly None)
2327 form        the current CGI form variables in a FieldStorage
2328 =========== ============================================================
2329
2330 **Index page specific variables (indexing arguments)**
2331
2332 =========== ============================================================
2333 Variable    Holds
2334 =========== ============================================================
2335 columns     dictionary of the columns to display in an index page
2336 show        a convenience access to columns - request/show/colname will
2337             be true if the columns should be displayed, false otherwise
2338 sort        index sort columns [(direction, column name)]
2339 group       index grouping properties [(direction, column name)]
2340 filter      properties to filter the index on
2341 filterspec  values to filter the index on (property=value, eg
2342             ``priority=1`` or ``messages.author=42``
2343 search_text text to perform a full-text search on for an index
2344 =========== ============================================================
2345
2346 There are several methods available on the request variable:
2347
2348 =============== ========================================================
2349 Method          Description
2350 =============== ========================================================
2351 description     render a description of the request - handle for the
2352                 page title
2353 indexargs_form  render the current index args as form elements
2354 indexargs_url   render the current index args as a URL
2355 base_javascript render some javascript that is used by other components
2356                 of the templating
2357 batch           run the current index args through a filter and return a
2358                 list of items (see `hyperdb item wrapper`_, and
2359                 `batching`_)
2360 =============== ========================================================
2361
2362 The form variable
2363 :::::::::::::::::
2364
2365 The form variable is a bit special because it's actually a python
2366 FieldStorage object. That means that you have two ways to access its
2367 contents. For example, to look up the CGI form value for the variable
2368 "name", use the path expression::
2369
2370    request/form/name/value
2371
2372 or the python expression::
2373
2374    python:request.form['name'].value
2375
2376 Note the "item" access used in the python case, and also note the
2377 explicit "value" attribute we have to access. That's because the form
2378 variables are stored as MiniFieldStorages. If there's more than one
2379 "name" value in the form, then the above will break since
2380 ``request/form/name`` is actually a *list* of MiniFieldStorages. So it's
2381 best to know beforehand what you're dealing with.
2382
2383
2384 The db variable
2385 ~~~~~~~~~~~~~~~
2386
2387 This is implemented by the ``roundup.cgi.templating.HTMLDatabase``
2388 class.
2389
2390 Allows access to all hyperdb classes as attributes of this variable. If
2391 you want access to the "user" class, for example, you would use::
2392
2393   db/user
2394   python:db.user
2395
2396 Also, the current id of the current user is available as
2397 ``db.getuid()``. This isn't so useful in templates (where you have
2398 ``request/user``), but it can be useful in detectors or interfaces.
2399
2400 The access results in a `hyperdb class wrapper`_.
2401
2402
2403 The templates variable
2404 ~~~~~~~~~~~~~~~~~~~~~~
2405
2406 This is implemented by the ``roundup.cgi.templating.Templates``
2407 class.
2408
2409 This variable doesn't have any useful methods defined. It supports being
2410 used in expressions to access the templates, and consequently the
2411 template macros. You may access the templates using the following path
2412 expression::
2413
2414    templates/name
2415
2416 or the python expression::
2417
2418    templates[name]
2419
2420 where "name" is the name of the template you wish to access. The
2421 template has one useful attribute, namely "macros". To access a specific
2422 macro (called "macro_name"), use the path expression::
2423
2424    templates/name/macros/macro_name
2425
2426 or the python expression::
2427
2428    templates[name].macros[macro_name]
2429
2430 The repeat variable
2431 ~~~~~~~~~~~~~~~~~~~
2432
2433 The repeat variable holds an entry for each active iteration. That is, if
2434 you have a ``tal:repeat="user db/users"`` command, then there will be a
2435 repeat variable entry called "user". This may be accessed as either::
2436
2437     repeat/user
2438     python:repeat['user']
2439
2440 The "user" entry has a number of methods available for information:
2441
2442 =============== =========================================================
2443 Method          Description
2444 =============== =========================================================
2445 first           True if the current item is the first in the sequence.
2446 last            True if the current item is the last in the sequence.
2447 even            True if the current item is an even item in the sequence.
2448 odd             True if the current item is an odd item in the sequence.
2449 number          Current position in the sequence, starting from 1.
2450 letter          Current position in the sequence as a letter, a through
2451                 z, then aa through zz, and so on.
2452 Letter          Same as letter(), except uppercase.
2453 roman           Current position in the sequence as lowercase roman
2454                 numerals.
2455 Roman           Same as roman(), except uppercase.
2456 =============== =========================================================
2457
2458
2459 The utils variable
2460 ~~~~~~~~~~~~~~~~~~
2461
2462 This is implemented by the
2463 ``roundup.cgi.templating.TemplatingUtils`` class, but it may be extended
2464 as described below.
2465
2466 =============== ========================================================
2467 Method          Description
2468 =============== ========================================================
2469 Batch           return a batch object using the supplied list
2470 url_quote       quote some text as safe for a URL (ie. space, %, ...)
2471 html_quote      quote some text as safe in HTML (ie. <, >, ...)
2472 html_calendar   renders an HTML calendar used by the
2473                 ``_generic.calendar.html`` template (itself invoked by
2474                 the popupCalendar DateHTMLProperty method
2475 =============== ========================================================
2476
2477 You may add additional utility methods by writing them in your tracker
2478 ``extensions`` directory and registering them with the templating system
2479 using ``instance.registerUtil`` (see `adding a time log to your issues`_ for
2480 an example of this).
2481
2482
2483 Batching
2484 ::::::::
2485
2486 Use Batch to turn a list of items, or item ids of a given class, into a
2487 series of batches. Its usage is::
2488
2489     python:utils.Batch(sequence, size, start, end=0, orphan=0,
2490     overlap=0)
2491
2492 or, to get the current index batch::
2493
2494     request/batch
2495
2496 The parameters are:
2497
2498 ========= ==============================================================
2499 Parameter  Usage
2500 ========= ==============================================================
2501 sequence  a list of HTMLItems
2502 size      how big to make the sequence.
2503 start     where to start (0-indexed) in the sequence.
2504 end       where to end (0-indexed) in the sequence.
2505 orphan    if the next batch would contain less items than this value,
2506           then it is combined with this batch
2507 overlap   the number of items shared between adjacent batches
2508 ========= ==============================================================
2509
2510 All of the parameters are assigned as attributes on the batch object. In
2511 addition, it has several more attributes:
2512
2513 =============== ========================================================
2514 Attribute       Description
2515 =============== ========================================================
2516 start           indicates the start index of the batch. *Unlike
2517                 the argument, is a 1-based index (I know, lame)*
2518 first           indicates the start index of the batch *as a 0-based
2519                 index*
2520 length          the actual number of elements in the batch
2521 sequence_length the length of the original, unbatched, sequence.
2522 =============== ========================================================
2523
2524 And several methods:
2525
2526 =============== ========================================================
2527 Method          Description
2528 =============== ========================================================
2529 previous        returns a new Batch with the previous batch settings
2530 next            returns a new Batch with the next batch settings
2531 propchanged     detect if the named property changed on the current item
2532                 when compared to the last item
2533 =============== ========================================================
2534
2535 An example of batching::
2536
2537  <table class="otherinfo">
2538   <tr><th colspan="4" class="header">Existing Keywords</th></tr>
2539   <tr tal:define="keywords db/keyword/list"
2540       tal:repeat="start python:range(0, len(keywords), 4)">
2541    <td tal:define="batch python:utils.Batch(keywords, 4, start)"
2542        tal:repeat="keyword batch" tal:content="keyword/name">
2543        keyword here</td>
2544   </tr>
2545  </table>
2546
2547 ... which will produce a table with four columns containing the items of
2548 the "keyword" class (well, their "name" anyway).
2549
2550
2551 Translations
2552 ~~~~~~~~~~~~
2553
2554 Should you wish to enable multiple languages in template content that you
2555 create you'll need to add new locale files in the tracker home under a
2556 ``locale`` directory. Use the instructions in the ``developer's guide`` to
2557 create the locale files.
2558
2559
2560 Displaying Properties
2561 ---------------------
2562
2563 Properties appear in the user interface in three contexts: in indices,
2564 in editors, and as search arguments. For each type of property, there
2565 are several display possibilities. For example, in an index view, a
2566 string property may just be printed as a plain string, but in an editor
2567 view, that property may be displayed in an editable field.
2568
2569
2570 Index Views
2571 -----------
2572
2573 This is one of the class context views. It is also the default view for
2574 classes. The template used is "*classname*.index".
2575
2576
2577 Index View Specifiers
2578 ~~~~~~~~~~~~~~~~~~~~~
2579
2580 An index view specifier (URL fragment) looks like this (whitespace has
2581 been added for clarity)::
2582
2583     /issue?status=unread,in-progress,resolved&
2584         keyword=security,ui&
2585         @group=priority,-status&
2586         @sort=-activity&
2587         @filters=status,keyword&
2588         @columns=title,status,fixer
2589
2590 The index view is determined by two parts of the specifier: the layout
2591 part and the filter part. The layout part consists of the query
2592 parameters that begin with colons, and it determines the way that the
2593 properties of selected items are displayed. The filter part consists of
2594 all the other query parameters, and it determines the criteria by which
2595 items are selected for display. The filter part is interactively
2596 manipulated with the form widgets displayed in the filter section. The
2597 layout part is interactively manipulated by clicking on the column
2598 headings in the table.
2599
2600 The filter part selects the union of the sets of items with values
2601 matching any specified Link properties and the intersection of the sets
2602 of items with values matching any specified Multilink properties.
2603
2604 The example specifies an index of "issue" items. Only items with a
2605 "status" of either "unread" or "in-progress" or "resolved" are
2606 displayed, and only items with "keyword" values including both "security"
2607 and "ui" are displayed. The items are grouped by priority arranged in
2608 ascending order and in descending order by status; and within
2609 groups, sorted by activity, arranged in descending order. The filter
2610 section shows filters for the "status" and "keyword" properties, and the
2611 table includes columns for the "title", "status", and "fixer"
2612 properties.
2613
2614 ============ =============================================================
2615 Argument     Description
2616 ============ =============================================================
2617 @sort        sort by prop name, optionally preceeded with '-' to give
2618              descending or nothing for ascending sorting. Several
2619              properties can be specified delimited with comma.
2620              Internally a search-page using several sort properties may
2621              use @sort0, @sort1 etc. with option @sortdir0, @sortdir1
2622              etc. for the direction of sorting (a non-empty value of
2623              sortdir0 specifies reverse order).
2624 @group       group by prop name, optionally preceeded with '-' or to sort
2625              in descending or nothing for ascending order. Several
2626              properties can be specified delimited with comma.
2627              Internally a search-page using several grouping properties may
2628              use @group0, @group1 etc. with option @groupdir0, @groupdir1
2629              etc. for the direction of grouping (a non-empty value of
2630              groupdir0 specifies reverse order).
2631 @columns     selects the columns that should be displayed. Default is
2632              all.                     
2633 @filter      indicates which properties are being used in filtering.
2634              Default is none.
2635 propname     selects the values the item properties given by propname must
2636              have (very basic search/filter).
2637 @search_text if supplied, performs a full-text search (message bodies,
2638              issue titles, etc)
2639 ============ =============================================================
2640
2641
2642 Searching Views
2643 ---------------
2644
2645 .. note::
2646    if you add a new column to the ``@columns`` form variable potentials
2647    then you will need to add the column to the appropriate `index views`_
2648    template so that it is actually displayed.
2649
2650 This is one of the class context views. The template used is typically
2651 "*classname*.search". The form on this page should have "search" as its
2652 ``@action`` variable. The "search" action:
2653
2654 - sets up additional filtering, as well as performing indexed text
2655   searching
2656 - sets the ``@filter`` variable correctly
2657 - saves the query off if ``@query_name`` is set.
2658
2659 The search page should lay out any fields that you wish to allow the
2660 user to search on. If your schema contains a large number of properties,
2661 you should be wary of making all of those properties available for
2662 searching, as this can cause confusion. If the additional properties are
2663 Strings, consider having their value indexed, and then they will be
2664 searchable using the full text indexed search. This is both faster, and
2665 more useful for the end user.
2666
2667 If the search view does specify the "search" ``@action``, then it may also
2668 provide an additional argument:
2669
2670 ============ =============================================================
2671 Argument     Description
2672 ============ =============================================================
2673 @query_name  if supplied, the index parameters (including @search_text)
2674              will be saved off as a the query item and registered against
2675              the user's queries property. Note that the *classic* template
2676              schema has this ability, but the *minimal* template schema
2677              does not.
2678 ============ =============================================================
2679
2680
2681 Item Views
2682 ----------
2683
2684 The basic view of a hyperdb item is provided by the "*classname*.item"
2685 template. It generally has three sections; an "editor", a "spool" and a
2686 "history" section.
2687
2688
2689 Editor Section
2690 ~~~~~~~~~~~~~~
2691
2692 The editor section is used to manipulate the item - it may be a static
2693 display if the user doesn't have permission to edit the item.
2694
2695 Here's an example of a basic editor template (this is the default
2696 "classic" template issue item edit form - from the "issue.item.html"
2697 template)::
2698
2699  <table class="form">
2700  <tr>
2701   <th>Title</th>
2702   <td colspan="3" tal:content="structure python:context.title.field(size=60)">title</td>
2703  </tr>
2704  
2705  <tr>
2706   <th>Priority</th>
2707   <td tal:content="structure context/priority/menu">priority</td>
2708   <th>Status</th>
2709   <td tal:content="structure context/status/menu">status</td>
2710  </tr>
2711  
2712  <tr>
2713   <th>Superseder</th>
2714   <td>
2715    <span tal:replace="structure python:context.superseder.field(showid=1, size=20)" />
2716    <span tal:replace="structure python:db.issue.classhelp('id,title')" />
2717    <span tal:condition="context/superseder">
2718     <br>View: <span tal:replace="structure python:context.superseder.link(showid=1)" />
2719    </span>
2720   </td>
2721   <th>Nosy List</th>
2722   <td>
2723    <span tal:replace="structure context/nosy/field" />
2724    <span tal:replace="structure python:db.user.classhelp('username,realname,address,phone')" />
2725   </td>
2726  </tr>
2727  
2728  <tr>
2729   <th>Assigned To</th>
2730   <td tal:content="structure context/assignedto/menu">
2731    assignedto menu
2732   </td>
2733   <td>&nbsp;</td>
2734   <td>&nbsp;</td>
2735  </tr>
2736  
2737  <tr>
2738   <th>Change Note</th>
2739   <td colspan="3">
2740    <textarea name=":note" wrap="hard" rows="5" cols="60"></textarea>
2741   </td>
2742  </tr>
2743  
2744  <tr>
2745   <th>File</th>
2746   <td colspan="3"><input type="file" name=":file" size="40"></td>
2747  </tr>
2748  
2749  <tr>
2750   <td>&nbsp;</td>
2751   <td colspan="3" tal:content="structure context/submit">
2752    submit button will go here
2753   </td>
2754  </tr>
2755  </table>
2756
2757
2758 When a change is submitted, the system automatically generates a message
2759 describing the changed properties. As shown in the example, the editor
2760 template can use the ":note" and ":file" fields, which are added to the
2761 standard changenote message generated by Roundup.
2762
2763
2764 Form values
2765 :::::::::::
2766
2767 We have a number of ways to pull properties out of the form in order to
2768 meet the various needs of:
2769
2770 1. editing the current item (perhaps an issue item)
2771 2. editing information related to the current item (eg. messages or
2772    attached files)
2773 3. creating new information to be linked to the current item (eg. time
2774    spent on an issue)
2775
2776 In the following, ``<bracketed>`` values are variable, ":" may be one of
2777 ":" or "@", and other text ("required") is fixed.
2778
2779 Properties are specified as form variables:
2780
2781 ``<propname>``
2782   property on the current context item
2783
2784 ``<designator>:<propname>``
2785   property on the indicated item (for editing related information)
2786
2787 ``<classname>-<N>:<propname>``
2788   property on the Nth new item of classname (generally for creating new
2789   items to attach to the current item)
2790
2791 Once we have determined the "propname", we check to see if it is one of
2792 the special form values:
2793
2794 ``@required``
2795   The named property values must be supplied or a ValueError will be
2796   raised.
2797
2798 ``@remove@<propname>=id(s)``
2799   The ids will be removed from the multilink property.
2800
2801 ``:add:<propname>=id(s)``
2802   The ids will be added to the multilink property.
2803
2804 ``:link:<propname>=<designator>``
2805   Used to add a link to new items created during edit. These are
2806   collected and returned in ``all_links``. This will result in an
2807   additional linking operation (either Link set or Multilink append)
2808   after the edit/create is done using ``all_props`` in ``_editnodes``.
2809   The <propname> on the current item will be set/appended the id of the
2810   newly created item of class <designator> (where <designator> must be
2811   <classname>-<N>).
2812
2813 Any of the form variables may be prefixed with a classname or
2814 designator.
2815
2816 Two special form values are supported for backwards compatibility:
2817
2818 ``:note``
2819   create a message (with content, author and date), linked to the
2820   context item. This is ALWAYS designated "msg-1".
2821 ``:file``
2822   create a file, attached to the current item and any message created by
2823   :note. This is ALWAYS designated "file-1".
2824
2825
2826 Spool Section
2827 ~~~~~~~~~~~~~
2828
2829 The spool section lists related information like the messages and files
2830 of an issue.
2831
2832 TODO
2833
2834
2835 History Section
2836 ~~~~~~~~~~~~~~~
2837
2838 The final section displayed is the history of the item - its database
2839 journal. This is generally generated with the template::
2840
2841  <tal:block tal:replace="structure context/history" />
2842
2843 *To be done:*
2844
2845 *The actual history entries of the item may be accessed for manual
2846 templating through the "journal" method of the item*::
2847
2848  <tal:block tal:repeat="entry context/journal">
2849   a journal entry
2850  </tal:block>
2851
2852 *where each journal entry is an HTMLJournalEntry.*
2853
2854
2855 Defining new web actions
2856 ------------------------
2857
2858 You may define new actions to be triggered by the ``@action`` form variable.
2859 These are added to the tracker ``extensions`` directory and registered
2860 using ``instance.registerAction``.
2861
2862 All the existing Actions are defined in ``roundup.cgi.actions``.
2863
2864 Adding action classes takes three steps; first you `define the new
2865 action class`_, then you `register the action class`_ with the cgi
2866 interface so it may be triggered by the ``@action`` form variable.
2867 Finally you `use the new action`_ in your HTML form.
2868
2869 See "`setting up a "wizard" (or "druid") for controlled adding of
2870 issues`_" for an example.
2871
2872
2873 Define the new action class
2874 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2875
2876 Create a new action class in your tracker's ``extensions`` directory, for
2877 example ``myaction.py``::
2878
2879  from roundup.cgi.actions import Action
2880
2881  class MyAction(Action):
2882      def handle(self):
2883          ''' Perform some action. No return value is required.
2884          '''
2885
2886 The *self.client* attribute is an instance of ``roundup.cgi.client.Client``.
2887 See the docstring of that class for details of what it can do.
2888
2889 The method will typically check the ``self.form`` variable's contents.
2890 It may then:
2891
2892 - add information to ``self.client.ok_message`` or ``self.client.error_message``
2893 - change the ``self.client.template`` variable to alter what the user will see
2894   next
2895 - raise Unauthorised, SendStaticFile, SendFile, NotFound or Redirect
2896   exceptions (import them from roundup.cgi.exceptions)
2897
2898
2899 Register the action class
2900 ~~~~~~~~~~~~~~~~~~~~~~~~~~
2901
2902 The class is now written, but isn't available to the user until you register
2903 it with the following code appended to your ``myaction.py`` file::
2904
2905     def init(instance):
2906         instance.registerAction('myaction', myActionClass)
2907
2908 This maps the action name "myaction" to the action class we defined.
2909
2910
2911 Use the new action
2912 ~~~~~~~~~~~~~~~~~~
2913
2914 In your HTML form, add a hidden form element like so::
2915
2916   <input type="hidden" name="@action" value="myaction">
2917
2918 where "myaction" is the name you registered in the previous step.
2919
2920 Actions may return content to the user
2921 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2922
2923 Actions generally perform some database manipulation and then pass control
2924 on to the rendering of a template in the current context (see `Determining
2925 web context`_ for how that works.) Some actions will want to generate the
2926 actual content returned to the user. Action methods may return their own
2927 content string to be displayed to the user, overriding the templating step.
2928 In this situation, we assume that the content is HTML by default. You may
2929 override the content type indicated to the user by calling ``setHeader``::
2930
2931    self.client.setHeader('Content-Type', 'text/csv')
2932
2933 This example indicates that the value sent back to the user is actually
2934 comma-separated value content (eg. something to be loaded into a
2935 spreadsheet or database).
2936
2937
2938 8-bit character set support in Web interface
2939 --------------------------------------------
2940
2941 The web interface uses UTF-8 default. It may be overridden in both forms
2942 and a browser cookie.
2943
2944 - In forms, use the ``@charset`` variable.
2945 - To use the cookie override, have the ``roundup_charset`` cookie set.
2946
2947 In both cases, the value is a valid charset name (eg. ``utf-8`` or
2948 ``kio8-r``).
2949
2950 Inside Roundup, all strings are stored and processed in utf-8.
2951 Unfortunately, some older browsers do not work properly with
2952 utf-8-encoded pages (e.g. Netscape Navigator 4 displays wrong
2953 characters in form fields).  This version allows one to change
2954 the character set for http transfers.  To do so, you may add
2955 the following code to your ``page.html`` template::
2956
2957  <tal:block define="uri string:${request/base}${request/env/PATH_INFO}">
2958   <a tal:attributes="href python:request.indexargs_url(uri,
2959    {'@charset':'utf-8'})">utf-8</a>
2960   <a tal:attributes="href python:request.indexargs_url(uri,
2961    {'@charset':'koi8-r'})">koi8-r</a>
2962  </tal:block>
2963
2964 (substitute ``koi8-r`` with appropriate charset for your language).
2965 Charset preference is kept in the browser cookie ``roundup_charset``.
2966
2967 ``meta http-equiv`` lines added to the tracker templates in version 0.6.0
2968 should be changed to include actual character set name::
2969
2970  <meta http-equiv="Content-Type"
2971   tal:attributes="content string:text/html;; charset=${request/client/charset}"
2972  />
2973
2974 The charset is also sent in the http header.
2975
2976
2977 Examples
2978 ========
2979
2980 .. contents::
2981    :local:
2982    :depth: 2
2983
2984
2985 Changing what's stored in the database
2986 --------------------------------------
2987
2988 The following examples illustrate ways to change the information stored in
2989 the database.
2990
2991
2992 Adding a new field to the classic schema
2993 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2994
2995 This example shows how to add a simple field (a due date) to the default
2996 classic schema. It does not add any additional behaviour, such as enforcing
2997 the due date, or causing automatic actions to fire if the due date passes.
2998
2999 You add new fields by editing the ``schema.py`` file in you tracker's home.
3000 Schema changes are automatically applied to the database on the next
3001 tracker access (note that roundup-server would need to be restarted as it
3002 caches the schema).
3003
3004 1. Modify the ``schema.py``::
3005
3006     issue = IssueClass(db, "issue", 
3007                     assignedto=Link("user"), keyword=Multilink("keyword"),
3008                     priority=Link("priority"), status=Link("status"),
3009                     due_date=Date())
3010
3011 2. Add an edit field to the ``issue.item.html`` template::
3012
3013     <tr> 
3014      <th>Due Date</th> 
3015      <td tal:content="structure context/due_date/field" /> 
3016     </tr>
3017     
3018    If you want to show only the date part of due_date then do this instead::
3019    
3020     <tr> 
3021      <th>Due Date</th> 
3022      <td tal:content="structure python:context.due_date.field(format='%Y-%m-%d')" /> 
3023     </tr>
3024
3025 3. Add the property to the ``issue.index.html`` page::
3026
3027     (in the heading row)
3028       <th tal:condition="request/show/due_date">Due Date</th>
3029     (in the data row)
3030       <td tal:condition="request/show/due_date" 
3031           tal:content="i/due_date" />
3032           
3033    If you want format control of the display of the due date you can
3034    enter the following in the data row to show only the actual due date::
3035     
3036       <td tal:condition="request/show/due_date" 
3037           tal:content="python:i.due_date.pretty('%Y-%m-%d')">&nbsp;</td>
3038
3039 4. Add the property to the ``issue.search.html`` page::
3040
3041      <tr tal:define="name string:due_date">
3042        <th i18n:translate="">Due Date:</th>
3043        <td metal:use-macro="search_input"></td>
3044        <td metal:use-macro="column_input"></td>
3045        <td metal:use-macro="sort_input"></td>
3046        <td metal:use-macro="group_input"></td>
3047      </tr>
3048
3049 5. If you wish for the due date to appear in the standard views listed
3050    in the sidebar of the web interface then you'll need to add "due_date"
3051    to the columns and columns_showall lists in your ``page.html``::
3052     
3053     columns string:id,activity,due_date,title,creator,status;
3054     columns_showall string:id,activity,due_date,title,creator,assignedto,status;
3055
3056 Adding a new constrained field to the classic schema
3057 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3058
3059 This example shows how to add a new constrained property (i.e. a
3060 selection of distinct values) to your tracker.
3061
3062
3063 Introduction
3064 ::::::::::::
3065
3066 To make the classic schema of Roundup useful as a TODO tracking system
3067 for a group of systems administrators, it needs an extra data field per
3068 issue: a category.
3069
3070 This would let sysadmins quickly list all TODOs in their particular area
3071 of interest without having to do complex queries, and without relying on
3072 the spelling capabilities of other sysadmins (a losing proposition at
3073 best).
3074
3075
3076 Adding a field to the database
3077 ::::::::::::::::::::::::::::::
3078
3079 This is the easiest part of the change. The category would just be a
3080 plain string, nothing fancy. To change what is in the database you need
3081 to add some lines to the ``schema.py`` file of your tracker instance.
3082 Under the comment::
3083
3084     # add any additional database schema configuration here
3085
3086 add::
3087
3088     category = Class(db, "category", name=String())
3089     category.setkey("name")
3090
3091 Here we are setting up a chunk of the database which we are calling
3092 "category". It contains a string, which we are refering to as "name" for
3093 lack of a more imaginative title. (Since "name" is one of the properties
3094 that Roundup looks for on items if you do not set a key for them, it's
3095 probably a good idea to stick with it for new classes if at all
3096 appropriate.) Then we are setting the key of this chunk of the database
3097 to be that "name". This is equivalent to an index for database types.
3098 This also means that there can only be one category with a given name.
3099
3100 Adding the above lines allows us to create categories, but they're not
3101 tied to the issues that we are going to be creating. It's just a list of
3102 categories off on its own, which isn't much use. We need to link it in
3103 with the issues. To do that, find the lines 
3104 in ``schema.py`` which set up the "issue" class, and then add a link to
3105 the category::
3106
3107     issue = IssueClass(db, "issue", ... ,
3108         category=Multilink("category"), ... )
3109
3110 The ``Multilink()`` means that each issue can have many categories. If
3111 you were adding something with a one-to-one relationship to issues (such
3112 as the "assignedto" property), use ``Link()`` instead.
3113
3114 That is all you need to do to change the schema. The rest of the effort
3115 is fiddling around so you can actually use the new category.
3116
3117
3118 Populating the new category class
3119 :::::::::::::::::::::::::::::::::
3120
3121 If you haven't initialised the database with the ``roundup-admin``
3122 "initialise" command, then you can add the following to the tracker
3123 ``initial_data.py`` under the comment::
3124
3125     # add any additional database creation steps here - but only if you
3126     # haven't initialised the database with the admin "initialise" command
3127
3128 Add::
3129
3130      category = db.getclass('category')
3131      category.create(name="scipy")
3132      category.create(name="chaco")
3133      category.create(name="weave")
3134
3135 If the database has already been initalised, then you need to use the
3136 ``roundup-admin`` tool::
3137
3138      % roundup-admin -i <tracker home>
3139      Roundup <version> ready for input.
3140      Type "help" for help.
3141      roundup> create category name=scipy
3142      1
3143      roundup> create category name=chaco
3144      2
3145      roundup> create category name=weave
3146      3
3147      roundup> exit...
3148      There are unsaved changes. Commit them (y/N)? y
3149
3150
3151 Setting up security on the new objects
3152 ::::::::::::::::::::::::::::::::::::::
3153
3154 By default only the admin user can look at and change objects. This
3155 doesn't suit us, as we want any user to be able to create new categories
3156 as required, and obviously everyone needs to be able to view the
3157 categories of issues for it to be useful.
3158
3159 We therefore need to change the security of the category objects. This
3160 is also done in ``schema.py``.
3161
3162 There are currently two loops which set up permissions and then assign
3163 them to various roles. Simply add the new "category" to both lists::
3164
3165     # Assign the access and edit permissions for issue, file and message
3166     # to regular users now
3167     for cl in 'issue', 'file', 'msg', 'category':
3168         p = db.security.getPermission('View', cl)
3169         db.security.addPermissionToRole('User', 'View', cl)
3170         db.security.addPermissionToRole('User', 'Edit', cl)
3171         db.security.addPermissionToRole('User', 'Create', cl)
3172
3173 These lines assign the "View" and "Edit" Permissions to the "User" role,
3174 so that normal users can view and edit "category" objects.
3175
3176 This is all the work that needs to be done for the database. It will
3177 store categories, and let users view and edit them. Now on to the
3178 interface stuff.
3179
3180
3181 Changing the web left hand frame
3182 ::::::::::::::::::::::::::::::::
3183
3184 We need to give the users the ability to create new categories, and the
3185 place to put the link to this functionality is in the left hand function
3186 bar, under the "Issues" area. The file that defines how this area looks
3187 is ``html/page.html``, which is what we are going to be editing next.
3188
3189 If you look at this file you can see that it contains a lot of
3190 "classblock" sections which are chunks of HTML that will be included or
3191 excluded in the output depending on whether the condition in the
3192 classblock is met. We are going to add the category code at the end of
3193 the classblock for the *issue* class::
3194
3195   <p class="classblock"
3196      tal:condition="python:request.user.hasPermission('View', 'category')">
3197    <b>Categories</b><br>
3198    <a tal:condition="python:request.user.hasPermission('Edit', 'category')"
3199       href="category?@template=item">New Category<br></a>
3200   </p>
3201
3202 The first two lines is the classblock definition, which sets up a
3203 condition that only users who have "View" permission for the "category"
3204 object will have this section included in their output. Next comes a
3205 plain "Categories" header in bold. Everyone who can view categories will
3206 get that.
3207
3208 Next comes the link to the editing area of categories. This link will
3209 only appear if the condition - that the user has "Edit" permissions for
3210 the "category" objects - is matched. If they do have permission then
3211 they will get a link to another page which will let the user add new
3212 categories.
3213
3214 Note that if you have permission to *view* but not to *edit* categories,
3215 then all you will see is a "Categories" header with nothing underneath
3216 it. This is obviously not very good interface design, but will do for
3217 now. I just claim that it is so I can add more links in this section
3218 later on. However, to fix the problem you could change the condition in
3219 the classblock statement, so that only users with "Edit" permission
3220 would see the "Categories" stuff.
3221
3222
3223 Setting up a page to edit categories
3224 ::::::::::::::::::::::::::::::::::::
3225
3226 We defined code in the previous section which let users with the
3227 appropriate permissions see a link to a page which would let them edit
3228 conditions. Now we have to write that page.
3229
3230 The link was for the *item* template of the *category* object. This
3231 translates into Roundup looking for a file called ``category.item.html``
3232 in the ``html`` tracker directory. This is the file that we are going to
3233 write now.
3234
3235 First, we add an info tag in a comment which doesn't affect the outcome
3236 of the code at all, but is useful for debugging. If you load a page in a
3237 browser and look at the page source, you can see which sections come
3238 from which files by looking for these comments::
3239
3240     <!-- category.item -->
3241
3242 Next we need to add in the METAL macro stuff so we get the normal page
3243 trappings::
3244
3245  <tal:block metal:use-macro="templates/page/macros/icing">
3246   <title metal:fill-slot="head_title">Category editing</title>
3247   <td class="page-header-top" metal:fill-slot="body_title">
3248    <h2>Category editing</h2>
3249   </td>
3250   <td class="content" metal:fill-slot="content">
3251
3252 Next we need to setup up a standard HTML form, which is the whole
3253 purpose of this file. We link to some handy javascript which sends the
3254 form through only once. This is to stop users hitting the send button
3255 multiple times when they are impatient and thus having the form sent
3256 multiple times::
3257
3258     <form method="POST" onSubmit="return submit_once()"
3259           enctype="multipart/form-data">
3260
3261 Next we define some code which sets up the minimum list of fields that
3262 we require the user to enter. There will be only one field - "name" - so
3263 they better put something in it, otherwise the whole form is pointless::
3264
3265     <input type="hidden" name="@required" value="name">
3266
3267 To get everything to line up properly we will put everything in a table,
3268 and put a nice big header on it so the user has an idea what is
3269 happening::
3270
3271     <table class="form">
3272      <tr><th class="header" colspan="2">Category</th></tr>
3273
3274 Next, we need the field into which the user is going to enter the new
3275 category. The ``context.name.field(size=60)`` bit tells Roundup to
3276 generate a normal HTML field of size 60, and the contents of that field
3277 will be the "name" variable of the current context (namely "category").
3278 The upshot of this is that when the user types something in
3279 to the form, a new category will be created with that name::
3280
3281     <tr>
3282      <th>Name</th>
3283      <td tal:content="structure python:context.name.field(size=60)">
3284      name</td>
3285     </tr>
3286
3287 Then a submit button so that the user can submit the new category::
3288
3289     <tr>
3290      <td>&nbsp;</td>
3291      <td colspan="3" tal:content="structure context/submit">
3292       submit button will go here
3293      </td>
3294     </tr>
3295
3296 Finally we finish off the tags we used at the start to do the METAL
3297 stuff::
3298
3299   </td>
3300  </tal:block>
3301
3302 So putting it all together, and closing the table and form we get::
3303
3304  <!-- category.item -->
3305  <tal:block metal:use-macro="templates/page/macros/icing">
3306   <title metal:fill-slot="head_title">Category editing</title>
3307   <td class="page-header-top" metal:fill-slot="body_title">
3308    <h2>Category editing</h2>
3309   </td>
3310   <td class="content" metal:fill-slot="content">
3311    <form method="POST" onSubmit="return submit_once()"
3312          enctype="multipart/form-data">
3313
3314     <table class="form">
3315      <tr><th class="header" colspan="2">Category</th></tr>
3316
3317      <tr>
3318       <th>Name</th>
3319       <td tal:content="structure python:context.name.field(size=60)">
3320       name</td>
3321      </tr>
3322
3323      <tr>
3324       <td>
3325         &nbsp;
3326         <input type="hidden" name="@required" value="name"> 
3327       </td>
3328       <td colspan="3" tal:content="structure context/submit">
3329        submit button will go here
3330       </td>
3331      </tr>
3332     </table>
3333    </form>
3334   </td>
3335  </tal:block>
3336
3337 This is quite a lot to just ask the user one simple question, but there
3338 is a lot of setup for basically one line (the form line) to do its work.
3339 To add another field to "category" would involve one more line (well,
3340 maybe a few extra to get the formatting correct).
3341
3342
3343 Adding the category to the issue
3344 ::::::::::::::::::::::::::::::::
3345
3346 We now have the ability to create issues to our heart's content, but
3347 that is pointless unless we can assign categories to issues.  Just like
3348 the ``html/category.item.html`` file was used to define how to add a new
3349 category, the ``html/issue.item.html`` is used to define how a new issue
3350 is created.
3351
3352 Just like ``category.issue.html``, this file defines a form which has a
3353 table to lay things out. It doesn't matter where in the table we add new
3354 stuff, it is entirely up to your sense of aesthetics::
3355
3356    <th>Category</th>
3357    <td>
3358     <span tal:replace="structure context/category/field" />
3359     <span tal:replace="structure python:db.category.classhelp('name',
3360                 property='category', width='200')" />
3361    </td>
3362
3363 First, we define a nice header so that the user knows what the next
3364 section is, then the middle line does what we are most interested in.
3365 This ``context/category/field`` gets replaced by a field which contains
3366 the category in the current context (the current context being the new
3367 issue).
3368
3369 The classhelp lines generate a link (labelled "list") to a popup window
3370 which contains the list of currently known categories.
3371
3372
3373 Searching on categories
3374 :::::::::::::::::::::::
3375
3376 Now we can add categories, and create issues with categories. The next
3377 obvious thing that we would like to be able to do, would be to search
3378 for issues based on their category, so that, for example, anyone working
3379 on the web server could look at all issues in the category "Web".
3380
3381 If you look for "Search Issues" in the ``html/page.html`` file, you will
3382 find that it looks something like 
3383 ``<a href="issue?@template=search">Search Issues</a>``. This shows us
3384 that when you click on "Search Issues" it will be looking for a
3385 ``issue.search.html`` file to display. So that is the file that we will
3386 change.
3387
3388 If you look at this file it should begin to seem familiar, although it
3389 does use some new macros. You can add the new category search code anywhere you
3390 like within that form::
3391
3392   <tr tal:define="name string:category;
3393                   db_klass string:category;
3394                   db_content string:name;">
3395     <th>Priority:</th>
3396     <td metal:use-macro="search_select"></td>
3397     <td metal:use-macro="column_input"></td>
3398     <td metal:use-macro="sort_input"></td>
3399     <td metal:use-macro="group_input"></td>
3400   </tr>
3401
3402 The definitions in the ``<tr>`` opening tag are used by the macros:
3403
3404 - ``search_select`` expands to a drop-down box with all categories using
3405   ``db_klass`` and ``db_content``.
3406 - ``column_input`` expands to a checkbox for selecting what columns
3407   should be displayed.
3408 - ``sort_input`` expands to a radio button for selecting what property
3409   should be sorted on.
3410 - ``group_input`` expands to a radio button for selecting what property
3411   should be grouped on.
3412
3413 The category search code above would&nb