Mercurial > p > roundup > code

annotate doc/customizing.txt @ 1057:8b9feca82090

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
some progress
author Richard Jones <richard@users.sourceforge.net>
date Fri, 06 Sep 2002 03:08:35 +0000
parents f89b8d32291b
children a55ef5a98fd3
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
688
b38f4f95bffd More doc tweaks
Richard Jones <richard@users.sourceforge.net>
parents: 686
diff changeset
1 ===================
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2 Customising Roundup
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3 ===================
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
4
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
5 :Version: $Revision: 1.17 $
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 684
diff changeset
6
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 684
diff changeset
7 .. contents::
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 684
diff changeset
8
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 684
diff changeset
9
898
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
10 What You Can Do
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
11 ---------------
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
12
935
2abb6b2697b6 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 910
diff changeset
13 Customisation of Roundup can take one of five forms:
898
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
14
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
15 1. `instance configuration`_ file changes
909
ef9c759c243e Fix to hasPermission, thanks Stefan Seefeld.
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
16 2. database, or `instance schema`_ changes
898
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
17 3. "definition" class `database content`_ changes
909
ef9c759c243e Fix to hasPermission, thanks Stefan Seefeld.
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
18 4. behavioural changes, through detectors_
935
2abb6b2697b6 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 910
diff changeset
19 5. `access controls`_
898
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
20
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
21 The third case is special because it takes two distinctly different forms
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
22 depending upon whether the instance has been initialised or not. The other two
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
23 may be done at any time, before or after instance initialisation. Yes, this
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
24 includes adding or removing properties from classes.
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
25
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
26
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
27 Instances in a Nutshell
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
28 -----------------------
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
29
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
30 Instances have the following structure:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
31
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
32 +-------------------+--------------------------------------------------------+
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
33 |instance_config.py |Holds the basic instance_configuration |
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
34 +-------------------+--------------------------------------------------------+
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
35 |dbinit.py |Holds the instance_schema |
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
36 +-------------------+--------------------------------------------------------+
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
37 |interfaces.py |Defines the Web and E-Mail interfaces for the instance |
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
38 +-------------------+--------------------------------------------------------+
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
39 |select_db.py |Selects the database back-end for the instance |
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
40 +-------------------+--------------------------------------------------------+
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
41 |db/ |Holds the instance's database |
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
42 +-------------------+--------------------------------------------------------+
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
43 |db/files/ |Holds the instance's upload files and messages |
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
44 +-------------------+--------------------------------------------------------+
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
45 |detectors/ |Auditors and reactors for this instance |
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
46 +-------------------+--------------------------------------------------------+
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
47 |html/ |Web interface templates, images and style sheets |
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
48 +-------------------+--------------------------------------------------------+
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
49
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
50 Instance Configuration
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
51 ----------------------
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
52
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
53 The instance_config.py located in your instance home contains the basic
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
54 configuration for the web and e-mail components of roundup's interfaces. This
794
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
55 file is a Python module. The configuration variables available are:
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
56
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
57 **INSTANCE_HOME** - ``os.path.split(__file__)[0]``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
58 The instance home directory. The above default code will automatically
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
59 determine the instance home for you.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
60
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
61 **MAILHOST** - ``'localhost'``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
62 The SMTP mail host that roundup will use to send e-mail.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
63
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
64 **MAIL_DOMAIN** - ``'your.tracker.email.domain.example'``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
65 The domain name used for email addresses.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
66
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
67 **DATABASE** - ``os.path.join(INSTANCE_HOME, 'db')``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
68 This is the directory that the database is going to be stored in. By default
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
69 it is in the instance home.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
70
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
71 **TEMPLATES** - ``os.path.join(INSTANCE_HOME, 'html')``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
72 This is the directory that the HTML templates reside in. By default they are
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
73 in the instance home.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
74
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
75 **INSTANCE_NAME** - ``'Roundup issue tracker'``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
76 A descriptive name for your roundup instance. This is sent out in e-mails and
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
77 appears in the heading of CGI pages.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
78
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
79 **ISSUE_TRACKER_EMAIL** - ``'issue_tracker@%s'%MAIL_DOMAIN``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
80 The email address that e-mail sent to roundup should go to. Think of it as the
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
81 instance's personal e-mail address.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
82
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
83 **ISSUE_TRACKER_WEB** - ``'http://your.tracker.url.example/'``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
84 The web address that the instance is viewable at. This will be included in
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
85 information sent to users of the tracker.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
86
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
87 **ADMIN_EMAIL** - ``'roundup-admin@%s'%MAIL_DOMAIN``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
88 The email address that roundup will complain to if it runs into trouble.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
89
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
90 **FILTER_POSITION** - ``'top'``, ``'bottom'`` or ``'top and bottom'``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
91 Where to place the web filtering HTML on the index page.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
92
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
93 **ANONYMOUS_ACCESS** - ``'deny'`` or ``'allow'``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
94 Deny or allow anonymous access to the web interface.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
95
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
96 **ANONYMOUS_REGISTER** - ``'deny'`` or ``'allow'``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
97 Deny or allow anonymous users to register through the web interface.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
98
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
99 **ANONYMOUS_REGISTER_MAIL** - ``'deny'`` or ``'allow'``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
100 Deny or allow anonymous users to register through the mail interface.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
101
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
102 **MESSAGES_TO_AUTHOR** - ``'yes'`` or``'no'``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
103 Send nosy messages to the author of the message.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
104
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
105 **ADD_AUTHOR_TO_NOSY** - ``'new'``, ``'yes'`` or ``'no'``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
106 Does the author of a message get placed on the nosy list automatically?
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
107 If ``'new'`` is used, then the author will only be added when a message
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
108 creates a new issue. If ``'yes'``, then the author will be added on followups
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
109 too. If ``'no'``, they're never added to the nosy.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
110
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
111 **ADD_RECIPIENTS_TO_NOSY** - ``'new'``, ``'yes'`` or ``'no'``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
112 Do the recipients (To:, Cc:) of a message get placed on the nosy list?
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
113 If ``'new'`` is used, then the recipients will only be added when a message
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
114 creates a new issue. If ``'yes'``, then the recipients will be added on
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
115 followups too. If ``'no'``, they're never added to the nosy.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
116
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
117 **EMAIL_SIGNATURE_POSITION** - ``'top'``, ``'bottom'`` or ``'none'``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
118 Where to place the email signature in messages that Roundup generates.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
119
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
120 **EMAIL_KEEP_QUOTED_TEXT** - ``'yes'`` or ``'no'``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
121 Keep email citations. Citations are the part of e-mail which the sender has
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
122 quoted in their reply to previous e-mail.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
123
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
124 **EMAIL_LEAVE_BODY_UNCHANGED** - ``'no'``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
125 Preserve the email body as is. Enabiling this will cause the entire message
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
126 body to be stored, including all citations and signatures. It should be
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
127 either ``'yes'`` or ``'no'``.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
128
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
129 **MAIL_DEFAULT_CLASS** - ``'issue'`` or ``''``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
130 Default class to use in the mailgw if one isn't supplied in email
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
131 subjects. To disable, comment out the variable below or leave it blank.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
132
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
133 **HEADER_INDEX_LINKS** - ``['DEFAULT', 'UNASSIGNED', 'USER']``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
134 Define what index links are available in the header, and what their
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
135 labels are. Each key is used to look up one of the index specifications
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
136 below - so ``'DEFAULT'`` will use ``'DEFAULT_INDEX'``.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
137
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
138 Example ``DEFAULT_INDEX``::
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
139
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
140 {
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
141 'LABEL': 'All Issues',
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
142 'CLASS': 'issue',
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
143 'SORT': ['-activity'],
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
144 'GROUP': ['priority'],
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
145 'FILTER': ['status'],
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
146 'COLUMNS': ['id','activity','title','creator','assignedto'],
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
147 'FILTERSPEC': {
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
148 'status': ['-1', '1', '2', '3', '4', '5', '6', '7'],
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
149 },
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
150 }
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
151
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
152 This defines one of the index links that appears in the
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
153 ``HEADER_INDEX_LINKS`` list.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
154
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
155 **LABEL** - ``'All Issues'``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
156 The text that appears as the link label.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
157 **CLASS** - ``'issue'``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
158 The class to display the index for.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
159 **SORT** - ``['-activity']``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
160 Sort by prop name, optionally preceeded with '-' to give descending or
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
161 nothing for ascending sorting.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
162 **GROUP** - ``['priority']``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
163 Group by prop name, optionally preceeded with '-' or to sort in descending
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
164 or nothing for ascending order.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
165 **FILTER** - ``['status']``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
166 Selects which props should be displayed in the filter section.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
167 Default is all.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
168 **COLUMNS** - ``['id','activity','title','creator','assignedto']``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
169 Selects the columns that should be displayed. Default is all.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
170 **FILTERSPEC** - *a dictionary giving the filter specification*
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
171 The ``FILTERSPEC`` gives the filtering arguments. This selects the values
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
172 the node properties given by propname must have.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
173
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
174 Where the ``FILTERSPEC`` value is ``'CURRENT USER'``, it will be replaced
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
175 by the id of the logged-in user. For example::
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
176
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
177 'FILTERSPEC': {
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
178 'status': ['-1', '1', '2', '3', '4', '5', '6', '7'],
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
179 'assignedto': 'CURRENT USER',
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
180 },
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
181
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
182 **HEADER_ADD_LINKS** - ``['issue']``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
183 List the classes that users are able to add nodes to.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
184
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
185 **HEADER_SEARCH_LINKS** - ``['issue']``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
186 List the classes that users can search.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
187
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
188 **SEARCH_FILTERS** - ``['ISSUE_FILTER', 'SUPPORT_FILTER']``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
189 List search filters per class. Like the INDEX entries above, each key is
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
190 used to look up one of the filter specifications below - so ``'ISSUE'``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
191 will use ``'ISSUE_FILTER'``.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
192
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
193 Example ``ISSUE_FILTER``::
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
194
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
195 ISSUE_FILTER = {
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
196 'CLASS': 'issue',
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
197 'FILTER': ['status', 'priority', 'assignedto', 'creator']
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
198 }
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
199
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
200 **CLASS** - ``'issue'``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
201 The class that the search page is for.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
202 **FILTER** - ``['status', 'priority', 'assignedto', 'creator']``
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
203 Selects which props should be displayed on the filter page. Default is
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
204 all.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
205
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
206 The default instance_config.py is given below - as you
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
207 can see, the MAIL_DOMAIN must be edited before any interaction with the
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
208 instance is attempted.::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
209
794
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
210 # roundup home is this package's directory
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
211 INSTANCE_HOME=os.path.split(__file__)[0]
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
212
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
213 # The SMTP mail host that roundup will use to send mail
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
214 MAILHOST = 'localhost'
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
215
794
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
216 # The domain name used for email addresses.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
217 MAIL_DOMAIN = 'your.tracker.email.domain.example'
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
218
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
219 # the next two are only used for the standalone HTTP server.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
220 HTTP_HOST = ''
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
221 HTTP_PORT = 9080
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
222
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
223 # This is the directory that the database is going to be stored in
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
224 DATABASE = os.path.join(INSTANCE_HOME, 'db')
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
225
794
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
226 # This is the directory that the HTML templates reside in
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
227 TEMPLATES = os.path.join(INSTANCE_HOME, 'html')
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
228
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
229 # A descriptive name for your roundup instance
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
230 INSTANCE_NAME = 'Roundup issue tracker'
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
231
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
232 # The email address that mail to roundup should go to
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
233 ISSUE_TRACKER_EMAIL = 'issue_tracker@%s'%MAIL_DOMAIN
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
234
794
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
235 # The web address that the instance is viewable at
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
236 ISSUE_TRACKER_WEB = 'http://your.tracker.url.example/'
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
237
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
238 # The email address that roundup will complain to if it runs into trouble
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
239 ADMIN_EMAIL = 'roundup-admin@%s'%MAIL_DOMAIN
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
240
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
241 # Somewhere for roundup to log stuff internally sent to stdout or stderr
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
242 LOG = os.path.join(INSTANCE_HOME, 'roundup.log')
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
243
794
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
244 # Where to place the web filtering HTML on the index page
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
245 FILTER_POSITION = 'bottom' # one of 'top', 'bottom', 'top and bottom'
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
246
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
247 # Deny or allow anonymous access to the web interface
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
248 ANONYMOUS_ACCESS = 'deny' # either 'deny' or 'allow'
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
249
794
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
250 # Deny or allow anonymous users to register through the web interface
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
251 ANONYMOUS_REGISTER = 'deny' # either 'deny' or 'allow'
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
252
794
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
253 # Deny or allow anonymous users to register through the mail interface
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
254 ANONYMOUS_REGISTER_MAIL = 'deny' # either 'deny' or 'allow'
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
255
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
256 # Send nosy messages to the author of the message
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
257 MESSAGES_TO_AUTHOR = 'no' # either 'yes' or 'no'
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
258
794
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
259 # Does the author of a message get placed on the nosy list automatically?
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
260 # If 'new' is used, then the author will only be added when a message
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
261 # creates a new issue. If 'yes', then the author will be added on followups
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
262 # too. If 'no', they're never added to the nosy.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
263 ADD_AUTHOR_TO_NOSY = 'new' # one of 'yes', 'no', 'new'
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
264
794
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
265 # Do the recipients (To:, Cc:) of a message get placed on the nosy list?
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
266 # If 'new' is used, then the recipients will only be added when a message
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
267 # creates a new issue. If 'yes', then the recipients will be added on followups
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
268 # too. If 'no', they're never added to the nosy.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
269 ADD_RECIPIENTS_TO_NOSY = 'new' # either 'yes', 'no', 'new'
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
270
794
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
271 # Where to place the email signature
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
272 EMAIL_SIGNATURE_POSITION = 'bottom' # one of 'top', 'bottom', 'none'
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
273
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
274 # Keep email citations
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
275 EMAIL_KEEP_QUOTED_TEXT = 'no' # either 'yes' or 'no'
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
276
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
277 # Preserve the email body as is
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
278 EMAIL_LEAVE_BODY_UNCHANGED = 'no' # either 'yes' or 'no'
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
279
794
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
280 # Default class to use in the mailgw if one isn't supplied in email
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
281 # subjects. To disable, comment out the variable below or leave it blank.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
282 # Examples:
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
283 MAIL_DEFAULT_CLASS = 'issue' # use "issue" class by default
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
284 #MAIL_DEFAULT_CLASS = '' # disable (or just comment the var out)
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
285
794
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
286 # Define what index links are available in the header, and what their
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
287 # labels are. Each key is used to look up one of the index specifications
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
288 # below - so 'DEFAULT' will use 'DEFAULT_INDEX'.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
289 # Where the FILTERSPEC has 'assignedto' with a value of None, it will be
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
290 # replaced by the id of the logged-in user.
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
291 HEADER_INDEX_LINKS = ['DEFAULT', 'UNASSIGNED', 'USER']
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
292
794
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
293 # list the classes that users are able to add nodes to
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
294 HEADER_ADD_LINKS = ['issue']
700
4f9686134fef added missing documentation for a few of the config option values
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
295
794
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
296 # list the classes that users can search
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
297 HEADER_SEARCH_LINKS = ['issue']
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
298
794
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
299 # list search filters per class
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
300 SEARCH_FILTERS = ['ISSUE_FILTER', 'SUPPORT_FILTER']
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
301
794
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
302 # Now the DEFAULT display specification. TODO: describe format
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
303 DEFAULT_INDEX = {
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
304 'LABEL': 'All Issues',
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
305 'CLASS': 'issue',
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
306 'SORT': ['-activity'],
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
307 'GROUP': ['priority'],
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
308 'FILTER': ['status'],
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
309 'COLUMNS': ['id','activity','title','creator','assignedto'],
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
310 'FILTERSPEC': {
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
311 'status': ['-1', '1', '2', '3', '4', '5', '6', '7'],
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
312 },
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
313 }
700
4f9686134fef added missing documentation for a few of the config option values
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
314
794
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
315 # The "unsassigned issues" index
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
316 UNASSIGNED_INDEX = {
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
317 'LABEL': 'Unassigned Issues',
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
318 'CLASS': 'issue',
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
319 'SORT': ['-activity'],
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
320 'GROUP': ['priority'],
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
321 'FILTER': ['status', 'assignedto'],
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
322 'COLUMNS': ['id','activity','title','creator','status'],
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
323 'FILTERSPEC': {
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
324 'status': ['-1', '1', '2', '3', '4', '5', '6', '7'],
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
325 'assignedto': ['-1'],
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
326 },
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
327 }
700
4f9686134fef added missing documentation for a few of the config option values
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
328
794
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
329 # The "my issues" index -- note that the user's id will replace the
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
330 # 'CURRENT USER' value of the "assignedto" filterspec
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
331 USER_INDEX = {
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
332 'LABEL': 'My Issues',
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
333 'CLASS': 'issue',
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
334 'SORT': ['-activity'],
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
335 'GROUP': ['priority'],
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
336 'FILTER': ['status', 'assignedto'],
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
337 'COLUMNS': ['id','activity','title','creator','status'],
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
338 'FILTERSPEC': {
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
339 'status': ['-1', '1', '2', '3', '4', '5', '6', '7'],
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
340 'assignedto': 'CURRENT USER',
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
341 },
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
342 }
700
4f9686134fef added missing documentation for a few of the config option values
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
343
794
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
344 ISSUE_FILTER = {
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
345 'CLASS': 'issue',
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
346 'FILTER': ['status', 'priority', 'assignedto', 'creator']
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
347 }
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
348
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
349 SUPPORT_FILTER = {
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
350 'CLASS': 'issue',
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
351 'FILTER': ['status', 'priority', 'assignedto', 'creator']
8c6df3f14020 Added better explanation of the instance configuration.
Richard Jones <richard@users.sourceforge.net>
parents: 724
diff changeset
352 }
700
4f9686134fef added missing documentation for a few of the config option values
Richard Jones <richard@users.sourceforge.net>
parents: 688
diff changeset
353
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
354
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
355 Instance Schema
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
356 ---------------
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
357
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
358 Note: if you modify the schema, you'll most likely need to edit the
898
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
359 `web interface`_ HTML template files and `detectors`_ to reflect
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
360 your changes.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
361
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
362 An instance schema defines what data is stored in the instance's database. The
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
363 two schemas shipped with Roundup turn it into a typical software bug tracker
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
364 (the extended schema allowing for support issues as well as bugs). Schemas are
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
365 defined using Python code. The "classic" schema looks like this::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
366
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
367 pri = Class(db, "priority", name=String(), order=String())
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
368 pri.setkey("name")
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
369 pri.create(name="critical", order="1")
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
370 pri.create(name="urgent", order="2")
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
371 pri.create(name="bug", order="3")
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
372 pri.create(name="feature", order="4")
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
373 pri.create(name="wish", order="5")
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
374
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
375 stat = Class(db, "status", name=String(), order=String())
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
376 stat.setkey("name")
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
377 stat.create(name="unread", order="1")
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
378 stat.create(name="deferred", order="2")
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
379 stat.create(name="chatting", order="3")
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
380 stat.create(name="need-eg", order="4")
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
381 stat.create(name="in-progress", order="5")
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
382 stat.create(name="testing", order="6")
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
383 stat.create(name="done-cbb", order="7")
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
384 stat.create(name="resolved", order="8")
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
385
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
386 keyword = Class(db, "keyword", name=String())
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
387 keyword.setkey("name")
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
388
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
389 user = Class(db, "user", username=String(), password=String(),
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
390 address=String(), realname=String(), phone=String(),
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
391 organisation=String())
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
392 user.setkey("username")
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
393 user.create(username="admin", password=adminpw,
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
394 address=instance_config.ADMIN_EMAIL)
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
395
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
396 msg = FileClass(db, "msg", author=Link("user"), recipients=Multilink
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
397 ("user"), date=Date(), summary=String(), files=Multilink("file"))
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
398
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
399 file = FileClass(db, "file", name=String(), type=String())
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
400
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
401 issue = IssueClass(db, "issue", assignedto=Link("user"),
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
402 topic=Multilink("keyword"), priority=Link("priority"), status=Link
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
403 ("status"))
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
404 issue.setkey('title')
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
405
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
406 Classes and Properties - creating a new information store
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
407 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
408
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
409 In the instance above, we've defined 7 classes of information:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
410
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
411 priority
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
412 Defines the possible levels of urgency for issues.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
413
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
414 status
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
415 Defines the possible states of processing the issue may be in.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
416
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
417 keyword
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
418 Initially empty, will hold keywords useful for searching issues.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
419
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
420 user
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
421 Initially holding the "admin" user, will eventually have an entry for all
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
422 users using roundup.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
423
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
424 msg
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
425 Initially empty, will all e-mail messages sent to or generated by
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
426 roundup.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
427
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
428 file
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
429 Initially empty, will all files attached to issues.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
430
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
431 issue
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
432 Initially emtyp, this is where the issue information is stored.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
433
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
434 We define the "priority" and "status" classes to allow two things: reduction in
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
435 the amount of information stored on the issue and more powerful, accurate
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
436 searching of issues by priority and status. By only requiring a link on the
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
437 issue (which is stored as a single number) we reduce the chance that someone
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
438 mis-types a priority or status - or simply makes a new one up.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
439
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
440 Class and Nodes
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
441 :::::::::::::::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
442
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
443 A Class defines a particular class (or type) of data that will be stored in the
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
444 database. A class comprises one or more properties, which given the information
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
445 about the class nodes.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
446 The actual data entered into the database, using class.create() are called
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
447 nodes. They have a special immutable property called id. We sometimes refer to
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
448 this as the nodeid.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
449
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
450 Properties
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
451 ::::::::::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
452
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
453 A Class is comprised of one or more properties of the following types:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
454 * String properties are for storing arbitrary-length strings.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
455 * Password properties are for storing encoded arbitrary-length strings. The
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
456 default encoding is defined on the roundup.password.Password class.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
457 * Date properties store date-and-time stamps. Their values are Timestamp
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
458 objects.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
459 * A Link property refers to a single other node selected from a specified
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
460 class. The class is part of the property; the value is an integer, the id
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
461 of the chosen node.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
462 * A Multilink property refers to possibly many nodes in a specified class.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
463 The value is a list of integers.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
464
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
465 FileClass
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
466 :::::::::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
467
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
468 FileClasses save their "content" attribute off in a separate file from the rest
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
469 of the database. This reduces the number of large entries in the database,
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
470 which generally makes databases more efficient, and also allows us to use
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
471 command-line tools to operate on the files. They are stored in the files sub-
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
472 directory of the db directory in your instance.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
473
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
474 IssueClass
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
475 ::::::::::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
476
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
477 IssueClasses automatically include the "messages", "files", "nosy", and
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
478 "superseder" properties.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
479 The messages and files properties list the links to the messages and files
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
480 related to the issue. The nosy property is a list of links to users who wish to
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
481 be informed of changes to the issue - they get "CC'ed" e-mails when messages
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
482 are sent to or generated by the issue. The nosy reactor (in the detectors
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
483 directory) handles this action. The superceder link indicates an issue which
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
484 has superceded this one.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
485 They also have the dynamically generated "creation", "activity" and "creator"
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
486 properties.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
487 The value of the "creation" property is the date when a node was created, and
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
488 the value of the "activity" property is the date when any property on the node
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
489 was last edited (equivalently, these are the dates on the first and last
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
490 records in the node's journal). The "creator" property holds a link to the user
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
491 that created the issue.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
492
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
493 setkey(property)
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
494 ::::::::::::::::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
495
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
496 Select a String property of the class to be the key property. The key property
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
497 muse be unique, and allows references to the nodes in the class by the content
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
498 of the key property. That is, we can refer to users by their username, e.g.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
499 let's say that there's an issue in roundup, issue 23. There's also a user,
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
500 richard who happens to be user 2. To assign an issue to him, we could do either
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
501 of::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
502
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
503 roundup-admin set issue assignedto=2
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
504
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
505 or::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
506
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
507 roundup-admin set issue assignedto=richard
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
508
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
509 Note, the same thing can be done in the web and e-mail interfaces.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
510
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
511 create(information)
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
512 :::::::::::::::::::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
513
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
514 Create a node in the database. This is generally used to create nodes in the
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
515 "definitional" classes like "priority" and "status".
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
516
684
5b23ff865f3a added a "detectors" directory...
Richard Jones <richard@users.sourceforge.net>
parents: 673
diff changeset
517
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
518 Examples of adding to your schema
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
519 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
520
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
521 TODO
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
522
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
523
684
5b23ff865f3a added a "detectors" directory...
Richard Jones <richard@users.sourceforge.net>
parents: 673
diff changeset
524 Detectors - adding behaviour to your tracker
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
525 --------------------------------------------
909
ef9c759c243e Fix to hasPermission, thanks Stefan Seefeld.
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
526 .. _detectors:
684
5b23ff865f3a added a "detectors" directory...
Richard Jones <richard@users.sourceforge.net>
parents: 673
diff changeset
527
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
528 The detectors in your instance fire before (*auditors*) and after (*reactors*)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
529 changes to the contents of your database. They are Python modules that sit in
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
530 your instance's ``detectors`` directory. You will have some installed by
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
531 default - have a look. You can write new detectors or modify the existing
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
532 ones. The existing detectors installed for you are:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
533
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
534 **nosyreaction.py**
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
535 This provides the automatic nosy list maintenance and email sending. The nosy
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
536 reactor (``nosyreaction``) fires when new messages are added to issues.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
537 The nosy auditor (``updatenosy``) fires when issues are changed and figures
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
538 what changes need to be made to the nosy list (like adding new authors etc)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
539 **statusauditor.py**
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
540 This provides the ``chatty`` auditor which changes the issue status from
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
541 ``unread`` or ``closed`` to ``chatting`` if new messages appear. It also
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
542 provides the ``presetunread`` auditor which pre-sets the status to
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
543 ``unread`` on new nodes if the status isn't explicitly defined.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
544
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
545 See the detectors section in the `design document`__ for details of the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
546 interface for detectors.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
547
909
ef9c759c243e Fix to hasPermission, thanks Stefan Seefeld.
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
548 __ design.html
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
549
684
5b23ff865f3a added a "detectors" directory...
Richard Jones <richard@users.sourceforge.net>
parents: 673
diff changeset
550 Sample additional detectors that have been found useful will appear in the
5b23ff865f3a added a "detectors" directory...
Richard Jones <richard@users.sourceforge.net>
parents: 673
diff changeset
551 ``detectors`` directory of the Roundup distribution:
5b23ff865f3a added a "detectors" directory...
Richard Jones <richard@users.sourceforge.net>
parents: 673
diff changeset
552
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents: 899
diff changeset
553 **newissuecopy.py**
684
5b23ff865f3a added a "detectors" directory...
Richard Jones <richard@users.sourceforge.net>
parents: 673
diff changeset
554 This detector sends an email to a team address whenever a new issue is
5b23ff865f3a added a "detectors" directory...
Richard Jones <richard@users.sourceforge.net>
parents: 673
diff changeset
555 created. The address is hard-coded into the detector, so edit it before you
5b23ff865f3a added a "detectors" directory...
Richard Jones <richard@users.sourceforge.net>
parents: 673
diff changeset
556 use it (look for the text 'team@team.host') or you'll get email errors!
5b23ff865f3a added a "detectors" directory...
Richard Jones <richard@users.sourceforge.net>
parents: 673
diff changeset
557
5b23ff865f3a added a "detectors" directory...
Richard Jones <richard@users.sourceforge.net>
parents: 673
diff changeset
558
898
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
559 Database Content
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
560 ----------------
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
561
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
562 Note: if you modify the content of definitional classes, you'll most likely
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
563 need to edit the instance `detectors`_ to reflect your changes.
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
564
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
565 Customisation of the special "definitional" classes (eg. status, priority,
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
566 resolution, ...) may be done either before or after the instance is
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
567 initialised. The actual method of doing so is completely different in each
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
568 case though, so be careful to use the right one.
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
569
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
570 **Changing content before instance initialisation**
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
571 Edit the dbinit module in your instance to alter the nodes created in using
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
572 the create() methods.
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
573
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
574
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
575 **Changing content after instance initialisation**
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
576 Use the roundup-admin interface's create, set and retire methods to add,
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
577 alter or remove nodes from the classes in question.
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
578
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
579
5ffac75a7f2e clarification
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
580
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
581 Web Interface
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
582 -------------
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
583
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
584 The web interface works behind the cgi-bin/roundup.cgi or roundup-server
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
585 scripts. In both cases, the scripts determine which instance is being accessed
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
586 (the first part of the URL path inside the scope of the CGI handler) and pass
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
587 control on to the instance interfaces.Client class which handles the rest of
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
588 the access through its main() method. This means that you can do pretty much
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
589 anything you want as a web interface to your instance.
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
590
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
591 Most customisation of the web view can be done by modifying the templates in
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
592 the instance **html** directory. There are several types of files in there:
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
593
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
594 page
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
595 defines the overall look of your tracker. When you
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
596 view an issue, it appears inside this template. When you view an index, it
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
597 also appears inside this template.
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
598 home
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
599 the default page displayed when no other page is indicated by the user
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
600 home.classlist
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
601 a special version of the default page that lists the classes in the tracker
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
602 *classname*.item
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
603 displays an item of the *classname* class
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
604 *classname*.index
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
605 displays a list of *classname* items
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
606 *classname*.search
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
607 displays a search page for *classname* items
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
608 _generic.index
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
609 used to display a list of items where there is no *classname*.index available
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
610 user.register
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
611 a special page just for the user class that renders the registration page
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
612 style.css
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
613 a static file that is served up as-is
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
614
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
615 The basic processing of a web request proceeds as follows:
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
616
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
617 1. figure out who we are, defaulting to the "anonymous" user
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
618 2. figure out what the request is for - we call this the "context"
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
619 3. handle any requested action (item edit, search, ...)
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
620 4. render a template, resulting in HTML output
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
621
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
622 In some situations, exceptions occur:
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
623 - HTTP Redirect (generally raised by an action)
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
624 - SendFile (generally raised by determine_context)
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
625 here we serve up a FileClass "content" property
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
626 - SendStaticFile (generally raised by determine_context)
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
627 here we serve up a file from the tracker "html" directory
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
628 - Unauthorised (generally raised by an action)
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
629 here the action is cancelled, the request is rendered and an error
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
630 message is displayed indicating that permission was not
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
631 granted for the action to take place
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
632 - NotFound (raised wherever it needs to be)
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
633 this exception percolates up to the CGI interface that called the client
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
634
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
635 To determine the "context" of a request, we look at the URL and the special
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
636 request variable ``:template``. The URL path after the instance identifier
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
637 is examined. Typical URL paths look like:
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
638
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
639 1. ``/tracker/issue``
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
640 2. ``/tracker/issue1``
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
641 3. ``/tracker/_file/style.css``
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
642 4. ``/cgi-bin/roundup.cgi/tracker/file1``
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
643 5. ``/cgi-bin/roundup.cgi/tracker/file1/kitten.png``
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
644
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
645 where the "instance identifier" is "tracker" in the above cases. That means
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
646 we're looking at "issue", "issue1", "_file/style.css", "file1" and
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
647 "file1/kitten.png" in the cases above. The path is generally only one
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
648 entry long - longer paths are handled differently.
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
649
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
650 a. if there is no path, then we are in the "home" context.
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
651 b. if the path starts with "_file" (as in example 3,
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
652 "/tracker/_file/style.css"), then the additional path entry,
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
653 "style.css" specifies the filename of a static file we're to serve up
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
654 from the instance "html" directory. Raises a SendStaticFile
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
655 exception.
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
656 c. if there is something in the path (as in example 1, "issue"), it identifies
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
657 the tracker class we're to display.
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
658 d. if the path is an item designator (as in examples 2 and 4, "issue1" and
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
659 "file1"), then we're to display a specific item.
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
660 e. if the path starts with an item designator and is longer than
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
661 one entry (as in example 5, "file1/kitten.png"), then we're assumed
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
662 to be handling an item of a
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
663 FileClass, and the extra path information gives the filename
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
664 that the client is going to label the download with (ie
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
665 "file1/kitten.png" is nicer to download than "file1"). This
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
666 raises a SendFile exception.
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
667
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
668 Both b. and e. stop before we bother to
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
669 determine the template we're going to use. That's because they
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
670 don't actually use templates.
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
671
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
672 The template used is specified by the ``:template`` CGI variable,
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
673 which defaults to:
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
674
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
675 - only classname suplied: "index"
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
676 - full item designator supplied: "item"
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
677
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
678
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
679 Repurcussions of changing the instance schema
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
680 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
681
899
4f082e1242f7 more info
Richard Jones <richard@users.sourceforge.net>
parents: 898
diff changeset
682 If you choose to change the `instance schema`_ you will need to ensure the web
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
683 interface knows about it:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
684
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
685 1. Index, item and search pages for the relevant classes may need to have
798
faf164ab8ed9 Docco changes.
Richard Jones <richard@users.sourceforge.net>
parents: 794
diff changeset
686 properties added or removed,
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
687 2. The "page" template may require links to be changed, as might the "home"
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
688 page's content arguments.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
689
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
690 Overall Look - "page" template
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
691 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
899
4f082e1242f7 more info
Richard Jones <richard@users.sourceforge.net>
parents: 898
diff changeset
692
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
693 The "page" template in your instances
899
4f082e1242f7 more info
Richard Jones <richard@users.sourceforge.net>
parents: 898
diff changeset
694 roundup.cgi_client.Class. This class is mixed-in to your instance through the
4f082e1242f7 more info
Richard Jones <richard@users.sourceforge.net>
parents: 898
diff changeset
695 instance's interfaces module. This means you can override the header and
4f082e1242f7 more info
Richard Jones <richard@users.sourceforge.net>
parents: 898
diff changeset
696 footer with your own code. This allows you to use a sidebar navigation scheme,
4f082e1242f7 more info
Richard Jones <richard@users.sourceforge.net>
parents: 898
diff changeset
697 for example.
4f082e1242f7 more info
Richard Jones <richard@users.sourceforge.net>
parents: 898
diff changeset
698
4f082e1242f7 more info
Richard Jones <richard@users.sourceforge.net>
parents: 898
diff changeset
699
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
700 PageTemplates in a Nutshell
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
701 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
702
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
703 PageTemplates consist of two core technologies:
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
704
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
705 TAL - Template Attribute Language
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
706 This is the syntax which is woven into the HTML using the ``tal:`` tag
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
707 attributes. A TAL parser pulls out the TAL commands from the attributes
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
708 runs them using some expression engine. TAL gives:
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
709
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
710 tal:define
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
711 tal:replace
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
712 tal:content
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
713 tal:repeat
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
714 tal:attributes
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
715
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
716 Additionally, a tag is defined, tal:block, which is removed from output. Its
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
717 content is not, but the tag itself is (so don't go using any tal:attributes
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
718 commands on it). This is useful for making arbitrary blocks of HTML
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
719 conditional or repeatable (very handy for repeating multiple table rows,
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
720 which would othewise require an illegal tag placement to effect the repeat).
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
721
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
722 TALES - TAL Expression Syntax
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
723 The expression engine used in this case is TALES, which runs the expressions
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
724 that form the tag attribute values. TALES expressions come in three
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
725 flavours:
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
726
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
727 Path Expressions - eg. ``item/status/checklist``
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
728 These are object attribute / item accesses. Roughly speaking, the path
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
729 ``item/status/checklist`` is broken into parts ``item``, ``status``
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
730 and ``checklist``. The ``item`` part is the root of the expression.
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
731 We then look for a ``status`` attribute on ``item``, or failing that, a
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
732 ``status`` item (as in ``item['status']``). If that
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
733 fails, the path expression fails. When we get to the end, the object we're
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
734 left with is evaluated to get a string - methods are called, objects are
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
735 stringified. Path expressions may have an optional ``path:`` prefix, though
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
736 they are the default expression type, so it's not necessary.
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
737
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
738 String Expressions - eg. ``string:hello ${user/name}``
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
739 These expressions are simple string interpolations (though they can be just
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
740 plain strings with no interpolation if you want. The expression in the
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
741 ``${ ... }`` is just a path expression as above.
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
742
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
743 Python Expressions - eg. ``python: 1+1``
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
744 These expressions give the full power of Python. All the "root level"
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
745 variables are available, so ``python:item.status.checklist()`` would be
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
746 equivalent to ``item/status/checklist``, assuming that ``checklist`` is
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
747 a method.
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
748
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
749 Displaying Properties
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
750 ~~~~~~~~~~~~~~~~~~~~~
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
751
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
752 Properties appear in the user interface in three contexts: in indices, in
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
753 editors, and as search arguments.
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
754 For each type of property, there are several display possibilities.
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
755 For example, in an index view, a string property may just be
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
756 printed as a plain string, but in an editor view, that property may be
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
757 displayed in an editable field.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
758
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
759
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
760 Index Views
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
761 ~~~~~~~~~~~
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
762
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
763 Index View Specifiers
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
764 :::::::::::::::::::::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
765
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
766 An index view specifier (URL fragment) looks like this (whitespace has been
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
767 added for clarity)::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
768
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
769 /issue?status=unread,in-progress,resolved&
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
770 topic=security,ui&
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
771 :group=+priority&
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
772 :sort=-activity&
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
773 :filters=status,topic&
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
774 :columns=title,status,fixer
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
775
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
776 The index view is determined by two parts of the specifier: the layout part and
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
777 the filter part. The layout part consists of the query parameters that begin
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
778 with colons, and it determines the way that the properties of selected nodes
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
779 are displayed. The filter part consists of all the other query parameters, and
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
780 it determines the criteria by which nodes are selected for display.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
781 The filter part is interactively manipulated with the form widgets displayed in
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
782 the filter section. The layout part is interactively manipulated by clicking on
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
783 the column headings in the table.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
784
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
785 The filter part selects the union of the sets of items with values matching any
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
786 specified Link properties and the intersection of the sets of items with values
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
787 matching any specified Multilink properties.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
788
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
789 The example specifies an index of "issue" nodes. Only items with a "status" of
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
790 either "unread" or "in-progres" or "resolved" are displayed, and only items
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
791 with "topic" values including both "security" and "ui" are displayed. The items
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
792 are grouped by priority, arranged in ascending order; and within groups, sorted
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
793 by activity, arranged in descending order. The filter section shows filters for
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
794 the "status" and "topic" properties, and the table includes columns for the
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
795 "title", "status", and "fixer" properties.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
796
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
797 Associated with each item class is a default layout specifier. The layout
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
798 specifier in the above example is the default layout to be provided with the
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
799 default bug-tracker schema described above in section 4.4.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
800
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
801 Filtering of indexes
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
802 ::::::::::::::::::::
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
803
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
804 TODO
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
805
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
806 Searching Views
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
807 ~~~~~~~~~~~~~~~
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
808
1057
8b9feca82090 some progress
Richard Jones <richard@users.sourceforge.net>
parents: 1003
diff changeset
809 TODO
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
810
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
811 Item Views
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
812 ~~~~~~~~~~
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
813
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
814 An item view contains an editor section and a spool section. At the top of an
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
815 item view, links to superseding and superseded items are always displayed.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
816
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
817 Editor Section
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
818 ::::::::::::::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
819
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
820 The editor section is generated from a template containing <display> tags to
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
821 insert the appropriate widgets for editing properties.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
822
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
823 Here's an example of a basic editor template.::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
824
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
825 <table>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
826 <tr>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
827 <td colspan=2>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
828 <display call="field('title', size=60)">
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
829 </td>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
830 </tr>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
831 <tr>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
832 <td>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
833 <display call="field('fixer', size=30)">
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
834 </td>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
835 <td>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
836 <display call="menu('status')>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
837 </td>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
838 </tr>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
839 <tr>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
840 <td>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
841 <display call="field('nosy', size=30)">
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
842 </td>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
843 <td>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
844 <display call="menu('priority')>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
845 </td>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
846 </tr>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
847 <tr>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
848 <td colspan=2>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
849 <display call="note()">
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
850 </td>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
851 </tr>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
852 </table>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
853
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
854 As shown in the example, the editor template can also request the display of a
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
855 "note" field, which is a text area for entering a note to go along with a
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
856 change.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
857
673
604c84696461 link() htmltemplate function now has a "showid" option for links & multilinks.
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
858 The <property> tag used in the index may also be used here - it checks to see
604c84696461 link() htmltemplate function now has a "showid" option for links & multilinks.
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
859 if the nominated Multilink property has any entries. This can be used to
604c84696461 link() htmltemplate function now has a "showid" option for links & multilinks.
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
860 eliminate sections of the editor section if the property has no entries::
604c84696461 link() htmltemplate function now has a "showid" option for links & multilinks.
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
861
604c84696461 link() htmltemplate function now has a "showid" option for links & multilinks.
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
862 <td class="form-text">
604c84696461 link() htmltemplate function now has a "showid" option for links & multilinks.
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
863 <display call="field('superseder', size=40, showid=1)">
604c84696461 link() htmltemplate function now has a "showid" option for links & multilinks.
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
864 <display call="classhelp('issue', 'id,title', label='list', width=500)">
604c84696461 link() htmltemplate function now has a "showid" option for links & multilinks.
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
865 <property name="superseder">
604c84696461 link() htmltemplate function now has a "showid" option for links & multilinks.
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
866 <br>View: <display call="link('superseder', showid=1)">
604c84696461 link() htmltemplate function now has a "showid" option for links & multilinks.
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
867 </property>
604c84696461 link() htmltemplate function now has a "showid" option for links & multilinks.
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
868 </td>
604c84696461 link() htmltemplate function now has a "showid" option for links & multilinks.
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
869
604c84696461 link() htmltemplate function now has a "showid" option for links & multilinks.
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
870 The "View: " part with the links will only display if the superseder property
604c84696461 link() htmltemplate function now has a "showid" option for links & multilinks.
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
871 has values.
604c84696461 link() htmltemplate function now has a "showid" option for links & multilinks.
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
872
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
873 When a change is submitted, the system automatically generates a message
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
874 describing the changed properties.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
875
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
876 If a note is given in the "note" field, the note is appended to the
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
877 description. The message is then added to the item's message spool (thus
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
878 triggering the standard detector to react by sending out this message to the
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
879 nosy list).
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
880
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
881 The message also displays all of the property values on the item and indicates
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
882 which ones have changed. An example of such a message might be this::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
883
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
884 Polly's taken a turn for the worse - this is now really important!
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
885 -----
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
886 title: Polly Parrot is dead
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
887 priority: critical
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
888 status: unread -> in-progress
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
889 fixer: terry
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
890 keywords: parrot,plumage,perch,nailed,dead
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
891
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
892 Spool Section
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
893 :::::::::::::
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
894
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
895 The spool section lists messages in the item's "messages" property. The index
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
896 of messages displays the "date", "author", and "summary" properties on the
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
897 message nodes, and selecting a message takes you to its content.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
898
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
899 The <property> tag used in the index may also be used here - it checks to see
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
900 if the nominated Multilink property has any entries. This can be used to
673
604c84696461 link() htmltemplate function now has a "showid" option for links & multilinks.
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
901 eliminate sections of the spool section if the property has no entries::
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
902
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
903 <property name="files">
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
904 <tr class="strong-header">
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
905 <td><b>Files</b></td>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
906 </tr>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
907
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
908 <tr>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
909 <td><display call="list('files')"></td>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
910 </tr>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
911 </property>
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
912
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
913
935
2abb6b2697b6 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 910
diff changeset
914 Access Controls
2abb6b2697b6 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 910
diff changeset
915 ---------------
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
916
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
917 A set of Permissions are built in to the security module by default:
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
918
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
919 - Edit (everything)
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
920 - View (everything)
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
921
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
922 The default interfaces define:
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
923
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
924 - Web Registration
935
2abb6b2697b6 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 910
diff changeset
925 - Web Access
1003
f89b8d32291b Hack hack hack...
Richard Jones <richard@users.sourceforge.net>
parents: 935
diff changeset
926 - Web Roles
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
927 - Email Registration
935
2abb6b2697b6 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 910
diff changeset
928 - Email Access
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
929
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
930 These are hooked into the default Roles:
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
931
1003
f89b8d32291b Hack hack hack...
Richard Jones <richard@users.sourceforge.net>
parents: 935
diff changeset
932 - Admin (Edit everything, View everything, Web Roles)
935
2abb6b2697b6 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 910
diff changeset
933 - User (Web Access, Email Access)
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
934 - Anonymous (Web Registration, Email Registration)
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
935
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
936 And finally, the "admin" user gets the "Admin" Role, and the "anonymous" user
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
937 gets the "Anonymous" assigned when the database is initialised on installation.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
938 The two default schemas then define:
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
939
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
940 - Edit issue, View issue (both)
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
941 - Edit file, View file (both)
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
942 - Edit msg, View msg (both)
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
943 - Edit support, View support (extended only)
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
944
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
945 and assign those Permissions to the "User" Role. New users are assigned the
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
946 Roles defined in the config file as:
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
947
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
948 - NEW_WEB_USER_ROLES
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
949 - NEW_EMAIL_USER_ROLES
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
950
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
951 You may alter the configuration variables to change the Role that new web or
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
952 email users get, for example to not give them access to the web interface if
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
953 they register through email.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
954
935
2abb6b2697b6 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 910
diff changeset
955 You may use the ``roundup-admin`` "``security``" command to display the
2abb6b2697b6 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 910
diff changeset
956 current Role and Permission configuration in your instance.
2abb6b2697b6 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 910
diff changeset
957
1003
f89b8d32291b Hack hack hack...
Richard Jones <richard@users.sourceforge.net>
parents: 935
diff changeset
958 Adding a new Permission
f89b8d32291b Hack hack hack...
Richard Jones <richard@users.sourceforge.net>
parents: 935
diff changeset
959 ~~~~~~~~~~~~~~~~~~~~~~~
f89b8d32291b Hack hack hack...
Richard Jones <richard@users.sourceforge.net>
parents: 935
diff changeset
960
f89b8d32291b Hack hack hack...
Richard Jones <richard@users.sourceforge.net>
parents: 935
diff changeset
961 When adding a new Permission, you will need to:
f89b8d32291b Hack hack hack...
Richard Jones <richard@users.sourceforge.net>
parents: 935
diff changeset
962
f89b8d32291b Hack hack hack...
Richard Jones <richard@users.sourceforge.net>
parents: 935
diff changeset
963 1. add it to your instance's dbinit so it is created
f89b8d32291b Hack hack hack...
Richard Jones <richard@users.sourceforge.net>
parents: 935
diff changeset
964 2. enable it for the Roles that should have it (verify with
f89b8d32291b Hack hack hack...
Richard Jones <richard@users.sourceforge.net>
parents: 935
diff changeset
965 "``roundup-admin security``")
f89b8d32291b Hack hack hack...
Richard Jones <richard@users.sourceforge.net>
parents: 935
diff changeset
966 3. add it to the relevant HTML interface templates
f89b8d32291b Hack hack hack...
Richard Jones <richard@users.sourceforge.net>
parents: 935
diff changeset
967 4. add it to the appropriate xxxPermission methods on in your instance
f89b8d32291b Hack hack hack...
Richard Jones <richard@users.sourceforge.net>
parents: 935
diff changeset
968 interfaces module
f89b8d32291b Hack hack hack...
Richard Jones <richard@users.sourceforge.net>
parents: 935
diff changeset
969
f89b8d32291b Hack hack hack...
Richard Jones <richard@users.sourceforge.net>
parents: 935
diff changeset
970
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 909
diff changeset
971
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 684
diff changeset
972 -----------------
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
973
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 684
diff changeset
974 Back to `Table of Contents`_
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 684
diff changeset
975
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 684
diff changeset
976 .. _`Table of Contents`: index.html
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 684
diff changeset
977
Roundup Issue Tracker: http://roundup-tracker.org/