Mercurial > p > roundup > code

comparison doc/customizing.txt @ 2910:5c0e5abcb5e3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc updates
author Richard Jones <richard@users.sourceforge.net>
date Sun, 14 Nov 2004 23:30:43 +0000
parents 21a0b049fed8
children ca6206cc74d9
comparison
equal deleted inserted replaced
2909:2fc6c508b537 2910:5c0e5abcb5e3
1 =================== 1 ===================
2 Customising Roundup 2 Customising Roundup
3 =================== 3 ===================
4 4
5 :Version: $Revision: 1.152 $ 5 :Version: $Revision: 1.153 $
6 6
7 .. This document borrows from the ZopeBook section on ZPT. The original is at: 7 .. This document borrows from the ZopeBook section on ZPT. The original is at:
8 http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx 8 http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
9 9
10 .. contents:: 10 .. contents::
50 =================== ======================================================== 50 =================== ========================================================
51 51
52 Tracker Configuration 52 Tracker Configuration
53 ===================== 53 =====================
54 54
55 The ``config.py`` located in your tracker home contains the basic 55 The ``config.ini`` located in your tracker home contains the basic
56 configuration for the web and e-mail components of roundup's interfaces. 56 configuration for the web and e-mail components of roundup's interfaces.
57 As the name suggests, this file is a Python module. This means that any 57
58 valid python expression may be used in the file. Mostly though, you'll 58 The followin taken from the `Python Library Reference`__ (May 20, 2004)
59 be setting the configuration variables to string values. Python string 59 section "ConfigParser -- Configuration file parser":
60 values must be quoted with either single or double quotes:: 60
61 61 The configuration file consists of sections, led by a "[section]" header
62 'this is a string' 62 and followed by "name = value" entries, with line continuations on a
63 "this is also a string - use it when the value has 'single quotes'" 63 newline with leading whitespace. Note that leading whitespace is removed
64 this is not a string - it's not quoted 64 from values. The optional values can contain format strings which
65 65 refer to other values in the same section. Lines beginning with "#" or ";"
66 Python strings may use formatting that's almost identical to C string 66 are ignored and may be used to provide comments.
67 formatting. The ``%`` operator is used to perform the formatting, like 67
68 so:: 68 For example::
69 69
70 'roundup-admin@%s'%MAIL_DOMAIN 70 [My Section]
71 71 foodir: %(dir)s/whatever
72 this will create a string ``'roundup-admin@tracker.domain.example'`` if 72 dir=frob
73 MAIL_DOMAIN is set to ``'tracker.domain.example'``. 73
74 74 would resolve the "%(dir)s" to the value of "dir" ("frob" in this case).
75 You'll also note some values are set to:: 75
76 76 __ http://docs.python.org/lib/module-ConfigParser.html
77 os.path.join(TRACKER_HOME, 'db')
78
79 or similar. This creates a new string which holds the path to the
80 ``'db'`` directory in the TRACKER_HOME directory. This is just a
81 convenience so if the TRACKER_HOME changes you don't have to edit
82 multiple valoues.
83 77
84 The configuration variables available are: 78 The configuration variables available are:
85 79
86 **TRACKER_HOME** - ``os.path.split(__file__)[0]`` 80 Section **main**
87 The tracker home directory. The above default code will automatically 81 database -- ``db``
88 determine the tracker home for you, so you can just leave it alone. 82 Database directory path. The path may be either absolute or relative
89 83 to the directory containig this config file.
90 **MAILHOST** - ``'localhost'`` 84
91 The SMTP mail host that roundup will use to send e-mail. 85 templates -- ``html``
92 86 Path to the HTML templates directory. The path may be either absolute
93 **MAILUSER** - ``()`` 87 or relative to the directory containig this config file.
94 If your SMTP mail host requires a username and password for access, then 88
95 specify them here. eg. ``MAILUSER = ('username', 'password')`` 89 admin_email -- ``roundup-admin``
96 90 Email address that roundup will complain to if it runs into trouble.
97 **MAILHOST_TLS** - ``'no'`` 91
98 If your SMTP mail host provides or requires TLS (Transport Layer 92 dispatcher_email -- ``roundup-admin``
99 Security) then set ``MAILHOST_TLS = 'yes'`` 93 The 'dispatcher' is a role that can get notified of new items to the
100 94 database. It is used by the ERROR_MESSAGES_TO config setting.
101 **MAILHOST_TLS_KEYFILE** - ``''`` 95
102 If you're using TLS, you may also set MAILHOST_TLS_KEYFILE to the name of 96 email_from_tag -- default *blank*
103 a PEM formatted file that contains your private key. 97 Additional text to include in the "name" part of the From: address used
104 98 in nosy messages. If the sending user is "Foo Bar", the From: line
105 **MAILHOST_TLS_CERTFILE** - ``''`` 99 is usually: ``"Foo Bar" <issue_tracker@tracker.example>``
106 If you're using TLS and have specified a MAILHOST_TLS_KEYFILE, you may 100 the EMAIL_FROM_TAG goes inside the "Foo Bar" quotes like so:
107 also set MAILHOST_TLS_CERTFILE to the name of a PEM formatted certificate 101 ``"Foo Bar EMAIL_FROM_TAG" <issue_tracker@tracker.example>``
108 chain file. 102
109 103 new_web_user_roles -- ``User``
110 **MAIL_DOMAIN** - ``'tracker.domain.example'`` 104 Roles that a user gets when they register with Web User Interface.
111 The domain name used for email addresses. 105 This is a comma-separated list of role names (e.g. ``Admin,User``).
112 106
113 **DATABASE** - ``os.path.join(TRACKER_HOME, 'db')`` 107 new_email_user_roles -- ``User``
114 This is the directory that the database is going to be stored in. By default 108 Roles that a user gets when they register with Email Gateway.
115 it is in the tracker home. 109 This is a comma-separated string of role names (e.g. ``Admin,User``).
116 110
117 **TEMPLATES** - ``os.path.join(TRACKER_HOME, 'html')`` 111 error_messages_to -- ``user``
118 This is the directory that the HTML templates reside in. By default they are 112 Send error message emails to the ``dispatcher``, ``user``, or ``both``?
119 in the tracker home. 113 The dispatcher is configured using the DISPATCHER_EMAIL setting.
120 114 Allowed values: ``dispatcher``, ``user``, or ``both``
121 **STATIC_FILES** - e.g. ``os.path.join(TRACKER_HOME, 'files')`` 115
122 This *optional* variable defines the directory that static files are served 116 html_version -- ``html4``
123 from (files with the URL ``/@@file/<filename>``). If this is not defined, 117 HTML version to generate. The templates are ``html4`` by default.
124 then static files are served from the TEMPLATES directory. 118 If you wish to make them xhtml, then you'll need to change this
125 119 var to ``xhtml`` too so all auto-generated HTML is compliant.
126 **TRACKER_NAME** - ``'Roundup issue tracker'`` 120 Allowed values: ``html4``, ``xhtml``
127 A descriptive name for your roundup tracker. This is sent out in e-mails and 121
128 appears in the heading of CGI pages. 122 timezone -- ``0``
129 123 Numeric timezone offset used when users do not choose their own
130 **TRACKER_EMAIL** - ``'issue_tracker@%s'%MAIL_DOMAIN`` 124 in their settings.
131 The email address that e-mail sent to roundup should go to. Think of it as the 125
132 tracker's personal e-mail address. 126 instant_registration -- ``yes``
133 127 Register new users instantly, or require confirmation via
134 **TRACKER_WEB** - ``'http://tracker.example/cgi-bin/roundup.cgi/bugs/'`` 128 email?
135 The web address that the tracker is viewable at. This will be included in 129 Allowed values: ``yes``, ``no``
136 information sent to users of the tracker. The URL **must** include the 130
137 cgi-bin part or anything else that is required to get to the home page of 131 Section **tracker**
138 the tracker. You **must** include a trailing '/' in the URL. 132 name -- ``Roundup issue tracker``
139 133 A descriptive name for your roundup instance.
140 **ADMIN_EMAIL** - ``'roundup-admin@%s'%MAIL_DOMAIN`` 134
141 The email address that roundup will complain to if it runs into trouble. 135 web -- ``http://host.example/demo/``
142 136 The web address that the tracker is viewable at.
143 **EMAIL_FROM_TAG** - ``''`` 137 This will be included in information sent to users of the tracker.
144 Additional text to include in the "name" part of the ``From:`` address used 138 The URL MUST include the cgi-bin part or anything else
145 in nosy messages. If the sending user is "Foo Bar", the ``From:`` line is 139 that is required to get to the home page of the tracker.
146 usually:: 140 You MUST include a trailing '/' in the URL.
147 141
148 "Foo Bar" <issue_tracker@tracker.example> 142 email -- ``issue_tracker``
149 143 Email address that mail to roundup should go to.
150 The EMAIL_FROM_TAG goes inside the "Foo Bar" quotes like so:: 144
151 145 Section **rdbms**
152 "Foo Bar EMAIL_FROM_TAG" <issue_tracker@tracker.example> 146 Settings in this section are used by Postgresql and MySQL backends only
153 147
154 **ERROR_MESSAGES_TO** - ``'user'``, ``'dispatcher'`` or ``'both'`` 148 name -- ``roundup``
155 Sends error messages to the dispatcher, user, or both. It will use the 149 Name of the database to use.
156 ``DISPATCHER_EMAIL`` address if set, otherwise it'll use the 150
157 ``ADMIN_EMAIL`` address. 151 host -- ``localhost``
158 152 Database server host.
159 **DISPATCHER_EMAIL** - ``''`` 153
160 The email address that Roundup will issue all error messages to. This is 154 port -- default *blank*
161 also useful if you want to switch your 'new message' notification to 155 TCP port number of the database server. Postgresql usually resides on
162 a central user. 156 port 5432 (if any), for MySQL default port number is 3306. Leave this
163 157 option empty to use backend default.
164 **LOGGGING_CONFIG** - ``os.path.join(TRACKER_HOME, 'logging.ini')`` 158
165 This variable activates logging of Roundup's internal messages using the 159 user -- ``roundup``
166 standard python ``logging`` module. The module is configured using the 160 Database user name that Roundup should use.
167 indicated configuration file. See the `admin guide`_ for more detail. 161
168 162 password -- ``roundup``
169 **LOGGING_FILENAME** - ``'/path/to/log file'`` 163 Database user password.
170 This variable activates logging of Roundup's internal messages using a 164
171 built-in minimal logging service which appends messages to the indicated 165 Section **logging**
172 file. See the `admin guide`_ for more detail. 166 config -- default *blank*
173 167 Path to configuration file for standard Python logging module. If this
174 **LOGGING_LEVEL** - ``'DEBUG'``, ``'INFO'``, ``'WARNING'`` or ``'ERROR'`` 168 option is set, logging configuration is loaded from specified file;
175 This variable determines the level of messages logged by the built-in 169 options 'filename' and 'level' in this section are ignored. The path may
176 logging service - messages of the level named and higher will be sent to 170 be either absolute or relative to the directory containig this config file.
177 the ``LOGGING_FILENAME`` file. Not used when the ``LOGGGING_CONFIG`` 171
178 variable is set. See the `admin guide`_ for more detail. 172 filename -- default *blank*
179 173 Log file name for minimal logging facility built into Roundup. If no file
180 **MESSAGES_TO_AUTHOR** - ``'new'``, ``'yes'`` or``'no'`` 174 name specified, log messages are written on stderr. If above 'config'
181 Send nosy messages to the author of the message? 175 option is set, this option has no effect. The path may be either absolute
182 If 'new' is used, then the author will only be sent the message when the 176 or relative to the directory containig this config file.
183 message creates a new issue. If 'yes' then the author will always be sent 177
184 a copy of the message they wrote. 178 level -- ``ERROR``
185 179 Minimal severity level of messages written to log file. If above 'config'
186 **ADD_AUTHOR_TO_NOSY** - ``'new'``, ``'yes'`` or ``'no'`` 180 option is set, this option has no effect.
187 Does the author of a message get placed on the nosy list automatically? 181 Allowed values: ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``
188 If ``'new'`` is used, then the author will only be added when a message 182
189 creates a new issue. If ``'yes'``, then the author will be added on followups 183 Section **mail**
190 too. If ``'no'``, they're never added to the nosy. 184 Outgoing email options. Used for nosy messages, password reset and
191 185 registration approval requests.
192 **ADD_RECIPIENTS_TO_NOSY** - ``'new'``, ``'yes'`` or ``'no'`` 186
193 Do the recipients (To:, Cc:) of a message get placed on the nosy list? 187 domain -- ``localhost``
194 If ``'new'`` is used, then the recipients will only be added when a message 188 Domain name used for email addresses.
195 creates a new issue. If ``'yes'``, then the recipients will be added on 189
196 followups too. If ``'no'``, they're never added to the nosy. 190 host -- default *blank*
197 191 SMTP mail host that roundup will use to send mail
198 **EMAIL_SIGNATURE_POSITION** - ``'top'``, ``'bottom'`` or ``'none'`` 192
199 Where to place the email signature in messages that Roundup generates. 193 username -- default *blank*
200 194 SMTP login name. Set this if your mail host requires authenticated access.
201 **EMAIL_KEEP_QUOTED_TEXT** - ``'yes'`` or ``'no'`` 195 If username is not empty, password (below) MUST be set!
202 Keep email citations. Citations are the part of e-mail which the sender has 196
203 quoted in their reply to previous e-mail with ``>`` or ``|`` characters at 197 password -- default *blank*
204 the start of the line. 198 SMTP login password.
205 199 Set this if your mail host requires authenticated access.
206 **EMAIL_LEAVE_BODY_UNCHANGED** - ``'no'`` 200
207 Preserve the email body as is. Enabiling this will cause the entire message 201 tls -- ``no``
208 body to be stored, including all citations, signatures and Outlook-quoted 202 If your SMTP mail host provides or requires TLS (Transport Layer Security)
209 sections (ie. "Original Message" blocks). It should be either ``'yes'`` 203 then you may set this option to 'yes'.
210 or ``'no'``. 204 Allowed values: ``yes``, ``no``
211 205
212 **MAIL_DEFAULT_CLASS** - ``'issue'`` or ``''`` 206 tls_keyfile -- default *blank*
213 Default class to use in the mailgw if one isn't supplied in email 207 If TLS is used, you may set this option to the name of a PEM formatted
214 subjects. To disable, comment out the variable below or leave it blank. 208 file that contains your private key. The path may be either absolute or
215 209 relative to the directory containig this config file.
216 **HTML_VERSION** - ``'html4'`` or ``'xhtml'`` 210
217 HTML version to generate. The templates are html4 by default. If you 211 tls_certfile -- default *blank*
218 wish to make them xhtml, then you'll need to change this var to 'xhtml' 212 If TLS is used, you may set this option to the name of a PEM formatted
219 too so all auto-generated HTML is compliant. 213 certificate chain file. The path may be either absolute or relative
220 214 to the directory containig this config file.
221 **EMAIL_CHARSET** - ``utf-8`` (or ``iso-8859-1`` for Eudora users) 215
222 Character set to encode email headers with. We use utf-8 by default, as 216 charset -- utf-8
223 it's the most flexible. Some mail readers (eg. Eudora) can't cope with 217 Character set to encode email headers with. We use utf-8 by default, as
224 that, so you might need to specify a more limited character set (eg. 218 it's the most flexible. Some mail readers (eg. Eudora) can't cope with
225 'iso-8859-1'. 219 that, so you might need to specify a more limited character set
226 220 (eg. iso-8859-1).
227 **DEFAULT_TIMEZONE** - ``0`` 221
228 Numeric hour timezone offest to be used when displaying local times. 222 debug -- default *blank*
229 The default timezone is used when users do not choose their own in 223 Setting this option makes Roundup to write all outgoing email messages
230 their settings. 224 to this file *instead* of sending them. This option has the same effect
231 225 as environment variable SENDMAILDEBUG. Environment variable takes
232 The default config.py is given below - as you 226 precedence. The path may be either absolute or relative to the directory
233 can see, the MAIL_DOMAIN must be edited before any interaction with the 227 containig this config file.
234 tracker is attempted.:: 228
235 229 Section **mailgw**
236 # roundup home is this package's directory 230 Roundup Mail Gateway options
237 TRACKER_HOME=os.path.split(__file__)[0] 231
238 232 keep_quoted_text -- ``yes``
239 # The SMTP mail host that roundup will use to send mail 233 Keep email citations when accepting messages. Setting this to ``no`` strips
240 MAILHOST = 'localhost' 234 out "quoted" text from the message. Signatures are also stripped.
241 235 Allowed values: ``yes``, ``no``
242 # The domain name used for email addresses. 236
243 MAIL_DOMAIN = 'your.tracker.email.domain.example' 237 leave_body_unchanged -- ``no``
244 238 Preserve the email body as is - that is, keep the citations *and*
245 # This is the directory that the database is going to be stored in 239 signatures.
246 DATABASE = os.path.join(TRACKER_HOME, 'db') 240 Allowed values: ``yes``, ``no``
247 241
248 # This is the directory that the HTML templates reside in 242 default_class -- ``issue``
249 TEMPLATES = os.path.join(TRACKER_HOME, 'html') 243 Default class to use in the mailgw if one isn't supplied in email subjects.
250 244 To disable, leave the value blank.
251 # Optional: the directory that static files are served from (files with 245
252 # the URL /@@file/<filename>). If this is not defined, then static files 246 Section **nosy**
253 # are served from the TEMPLATES directory. 247 Nosy messages sending
254 # STATIC_FILES = os.path.join(TRACKER_HOME, 'files') 248
255 249 messages_to_author -- ``no``
256 # A descriptive name for your roundup tracker 250 Send nosy messages to the author of the message.
257 TRACKER_NAME = 'Roundup issue tracker' 251 Allowed values: ``yes``, ``no``, ``new``
258 252
259 # The email address that mail to roundup should go to 253 signature_position -- ``bottom``
260 TRACKER_EMAIL = 'issue_tracker@%s'%MAIL_DOMAIN 254 Where to place the email signature.
261 255 Allowed values: ``top``, ``bottom``, ``none``
262 # The web address that the tracker is viewable at. This will be 256
263 # included in information sent to users of the tracker. The URL MUST 257 add_author -- ``new``
264 # include the cgi-bin part or anything else that is required to get 258 Does the author of a message get placed on the nosy list automatically?
265 # to the home page of the tracker. You MUST include a trailing '/' 259 If ``new`` is used, then the author will only be added when a message
266 # in the URL. 260 creates a new issue. If ``yes``, then the author will be added on
267 TRACKER_WEB = 'http://tracker.example/cgi-bin/roundup.cgi/bugs/' 261 followups too. If ``no``, they're never added to the nosy.
268 262 Allowed values: ``yes``, ``no``, ``new``
269 # The email address that roundup will complain to if it runs into 263
270 # trouble 264 add_recipients -- ``new``
271 ADMIN_EMAIL = 'roundup-admin@%s'%MAIL_DOMAIN 265 Do the recipients (``To:``, ``Cc:``) of a message get placed on the nosy
272 266 list? If ``new`` is used, then the recipients will only be added when a
273 # These variables define where to log Roundup's internal messages to. 267 message creates a new issue. If ``yes``, then the recipients will be added
274 # You have two choices - either using the standard Python logging module 268 on followups too. If ``no``, they're never added to the nosy.
275 # or a minimal logging facility built into Roundup. The former is activated 269 Allowed values: ``yes``, ``no``, ``new``
276 # when you provide a LOGGING_CONFIG variable below which contains the 270
277 # configuration of the logging module. The latter is activated when you 271 You may generate a new default config file using the ``roundup-admin
278 # provide the LOGGING_FILENAME and optionally LOGGING_LEVEL variables. If 272 genconfig`` command.
279 # none of these variables are defined then only errors will be logged, and 273
280 # they will go to stderr. See the Admin Guide for more detail.
281 # LOGGGING_CONFIG = os.path.join(TRACKER_HOME, 'logging.ini')
282 # or,
283 # LOGGING_FILENAME = '/path/to/log file'
284 # LOGGING_LEVEL = 'INFO' # one of 'DEBUG', 'INFO', 'WARNING', 'ERROR'
285
286 # Additional text to include in the "name" part of the From: address
287 # used in nosy messages. If the sending user is "Foo Bar", the From:
288 # line is usually: "Foo Bar" <issue_tracker@tracker.example>
289 # the EMAIL_FROM_TAG goes inside the "Foo Bar" quotes like so:
290 # "Foo Bar EMAIL_FROM_TAG" <issue_tracker@tracker.example>
291 EMAIL_FROM_TAG = ""
292
293 # Send nosy messages to the author of the message
294 MESSAGES_TO_AUTHOR = 'no' # either 'yes' or 'no'
295
296 # Does the author of a message get placed on the nosy list
297 # automatically? If 'new' is used, then the author will only be
298 # added when a message creates a new issue. If 'yes', then the
299 # author will be added on followups too. If 'no', they're never
300 # added to the nosy.
301 ADD_AUTHOR_TO_NOSY = 'new' # one of 'yes', 'no', 'new'
302
303 # Do the recipients (To:, Cc:) of a message get placed on the nosy
304 # list? If 'new' is used, then the recipients will only be added
305 # when a message creates a new issue. If 'yes', then the recipients
306 # will be added on followups too. If 'no', they're never added to
307 # the nosy.
308 ADD_RECIPIENTS_TO_NOSY = 'new' # either 'yes', 'no', 'new'
309
310 # Where to place the email signature
311 EMAIL_SIGNATURE_POSITION = 'bottom' # one of 'top', 'bottom', 'none'
312
313 # Keep email citations
314 EMAIL_KEEP_QUOTED_TEXT = 'no' # either 'yes' or 'no'
315
316 # Preserve the email body as is
317 EMAIL_LEAVE_BODY_UNCHANGED = 'no' # either 'yes' or 'no'
318
319 # Default class to use in the mailgw if one isn't supplied in email
320 # subjects. To disable, comment out the variable below or leave it
321 # blank. Examples:
322 MAIL_DEFAULT_CLASS = 'issue' # use "issue" class by default
323 #MAIL_DEFAULT_CLASS = '' # disable (or just comment the var out)
324
325 # HTML version to generate. The templates are html4 by default. If you
326 # wish to make them xhtml, then you'll need to change this var to 'xhtml'
327 # too so all auto-generated HTML is compliant.
328 HTML_VERSION = 'html4' # either 'html4' or 'xhtml'
329
330 # Character set to encode email headers with. We use utf-8 by default, as
331 # it's the most flexible. Some mail readers (eg. Eudora) can't cope with
332 # that, so you might need to specify a more limited character set (eg.
333 # 'iso-8859-1'.
334 EMAIL_CHARSET = 'utf-8'
335 #EMAIL_CHARSET = 'iso-8859-1' # use this instead for Eudora users
336
337 # You may specify a different default timezone, for use when users do not
338 # choose their own in their settings.
339 DEFAULT_TIMEZONE = 0 # specify as numeric hour offest
340
341 #
342 # SECURITY DEFINITIONS
343 #
344 # define the Roles that a user gets when they register with the
345 # tracker these are a comma-separated string of role names (e.g.
346 # 'Admin,User')
347 NEW_WEB_USER_ROLES = 'User'
348 NEW_EMAIL_USER_ROLES = 'User'
349 274
350 Tracker Schema 275 Tracker Schema
351 ============== 276 ==============
352 277
353 Note: if you modify the schema, you'll most likely need to edit the 278 Note: if you modify the schema, you'll most likely need to edit the
955 tracker ``interfaces.Client`` class - which uses the ``Client`` class 880 tracker ``interfaces.Client`` class - which uses the ``Client`` class
956 from ``roundup.cgi.client`` - which handles the rest of the access 881 from ``roundup.cgi.client`` - which handles the rest of the access
957 through its ``main()`` method. This means that you can do pretty much 882 through its ``main()`` method. This means that you can do pretty much
958 anything you want as a web interface to your tracker. 883 anything you want as a web interface to your tracker.
959 884
885
960 Repercussions of changing the tracker schema 886 Repercussions of changing the tracker schema
961 --------------------------------------------- 887 ---------------------------------------------
962 888
963 If you choose to change the `tracker schema`_ you will need to ensure 889 If you choose to change the `tracker schema`_ you will need to ensure
964 the web interface knows about it: 890 the web interface knows about it:
965 891
966 1. Index, item and search pages for the relevant classes may need to 892 1. Index, item and search pages for the relevant classes may need to
967 have properties added or removed, 893 have properties added or removed,
968 2. The "page" template may require links to be changed, as might the 894 2. The "page" template may require links to be changed, as might the
969 "home" page's content arguments. 895 "home" page's content arguments.
896
970 897
971 How requests are processed 898 How requests are processed
972 -------------------------- 899 --------------------------
973 900
974 The basic processing of a web request proceeds as follows: 901 The basic processing of a web request proceeds as follows:
991 message is displayed indicating that permission was not granted for 918 message is displayed indicating that permission was not granted for
992 the action to take place 919 the action to take place
993 - NotFound (raised wherever it needs to be) 920 - NotFound (raised wherever it needs to be)
994 this exception percolates up to the CGI interface that called the 921 this exception percolates up to the CGI interface that called the
995 client 922 client
923
996 924
997 Determining web context 925 Determining web context
998 ----------------------- 926 -----------------------
999 927
1000 To determine the "context" of a request, we look at the URL and the 928 To determine the "context" of a request, we look at the URL and the
1279 is also performed. 1207 is also performed.
1280 1208
1281 We also check that FileClass items have a "content" property with 1209 We also check that FileClass items have a "content" property with
1282 actual content, otherwise we remove them from all_props before 1210 actual content, otherwise we remove them from all_props before
1283 returning. 1211 returning.
1284
1285 1212
1286 1213
1287 Default templates 1214 Default templates
1288 ----------------- 1215 -----------------
1289 1216
1445 1372
1446 .. _TAL: 1373 .. _TAL:
1447 .. _Template Attribute Language: 1374 .. _Template Attribute Language:
1448 http://dev.zope.org/Wikis/DevSite/Projects/ZPT/TAL%20Specification%201.4 1375 http://dev.zope.org/Wikis/DevSite/Projects/ZPT/TAL%20Specification%201.4
1449 1376
1377
1450 Templating Expressions 1378 Templating Expressions
1451 ~~~~~~~~~~~~~~~~~~~~~~ 1379 ~~~~~~~~~~~~~~~~~~~~~~
1452 1380
1453 Templating Expressions are covered by `Template Attribute Language 1381 Templating Expressions are covered by `Template Attribute Language
1454 Expression Syntax`_, or TALES. The expressions you may use in the 1382 Expression Syntax`_, or TALES. The expressions you may use in the
1510 expression. 1438 expression.
1511 1439
1512 .. _TALES: 1440 .. _TALES:
1513 .. _Template Attribute Language Expression Syntax: 1441 .. _Template Attribute Language Expression Syntax:
1514 http://dev.zope.org/Wikis/DevSite/Projects/ZPT/TALES%20Specification%201.3 1442 http://dev.zope.org/Wikis/DevSite/Projects/ZPT/TALES%20Specification%201.3
1443
1515 1444
1516 Template Macros 1445 Template Macros
1517 ~~~~~~~~~~~~~~~ 1446 ~~~~~~~~~~~~~~~
1518 1447
1519 Macros are used in Roundup to save us from repeating the same common 1448 Macros are used in Roundup to save us from repeating the same common
2126 </table> 2055 </table>
2127 2056
2128 ... which will produce a table with four columns containing the items of 2057 ... which will produce a table with four columns containing the items of
2129 the "keyword" class (well, their "name" anyway). 2058 the "keyword" class (well, their "name" anyway).
2130 2059
2060
2131 Displaying Properties 2061 Displaying Properties
2132 --------------------- 2062 ---------------------
2133 2063
2134 Properties appear in the user interface in three contexts: in indices, 2064 Properties appear in the user interface in three contexts: in indices,
2135 in editors, and as search arguments. For each type of property, there 2065 in editors, and as search arguments. For each type of property, there
2178 and "ui" are displayed. The items are grouped by priority, arranged in 2108 and "ui" are displayed. The items are grouped by priority, arranged in
2179 ascending order; and within groups, sorted by activity, arranged in 2109 ascending order; and within groups, sorted by activity, arranged in
2180 descending order. The filter section shows filters for the "status" and 2110 descending order. The filter section shows filters for the "status" and
2181 "topic" properties, and the table includes columns for the "title", 2111 "topic" properties, and the table includes columns for the "title",
2182 "status", and "fixer" properties. 2112 "status", and "fixer" properties.
2113
2183 2114
2184 Searching Views 2115 Searching Views
2185 --------------- 2116 ---------------
2186 2117
2187 Note: if you add a new column to the ``:columns`` form variable 2118 Note: if you add a new column to the ``:columns`` form variable
2390 a journal entry 2321 a journal entry
2391 </tal:block> 2322 </tal:block>
2392 2323
2393 *where each journal entry is an HTMLJournalEntry.* 2324 *where each journal entry is an HTMLJournalEntry.*
2394 2325
2326
2395 Defining new web actions 2327 Defining new web actions
2396 ------------------------ 2328 ------------------------
2397 2329
2398 You may define new actions to be triggered by the ``@action`` form variable. 2330 You may define new actions to be triggered by the ``@action`` form variable.
2399 These are added to the tracker ``interfaces.py`` as ``Action`` classes that get 2331 These are added to the tracker ``interfaces.py`` as ``Action`` classes that get
2470 self.client.setHeader('Content-Type', 'text/csv') 2402 self.client.setHeader('Content-Type', 'text/csv')
2471 2403
2472 This example indicates that the value sent back to the user is actually 2404 This example indicates that the value sent back to the user is actually
2473 comma-separated value content (eg. something to be loaded into a 2405 comma-separated value content (eg. something to be loaded into a
2474 spreadsheet or database). 2406 spreadsheet or database).
2407
2408
2409 8-bit character set support in Web interface
2410 --------------------------------------------
2411
2412 The web interface uses UTF-8 default. It may be overridden in both forms
2413 and a browser cookie.
2414
2415 - In forms, use the ``@charset`` variable.
2416 - To use the cookie override, have the ``roundup_charset`` cookie set.
2417
2418 In both cases, the value is a valid charset name (eg. ``utf-8`` or
2419 ``kio8-r``).
2420
2421 Inside Roundup, all strings are stored and processed in utf-8.
2422 Unfortunately, some older browsers do not work properly with
2423 utf8-encoded pages (e.g. Netscape Navigator 4 displays wrong
2424 characters in form fields). This version allows to change
2425 the character set for http transfers. To do so, you may add
2426 the following code to your ``page.html`` template::
2427
2428 <tal:block define="uri string:${request/base}${request/env/PATH_INFO}">
2429 <a tal:attributes="href python:request.indexargs_href(uri,
2430 {'@charset':'utf-8'})">utf-8</a>
2431 <a tal:attributes="href python:request.indexargs_href(uri,
2432 {'@charset':'koi8-r'})">koi8-r</a>
2433 </tal:block>
2434
2435 (substitute ``koi8-r`` with appropriate charset for your language).
2436 Charset preference is kept in the browser cookie ``roundup_charset``.
2437
2438 Lines ``meta http-equiv`` added to the tracker templates in version 0.6.0
2439 should be changed to include actual character set name::
2440
2441 <meta http-equiv="Content-Type"
2442 tal:attributes="content string:text/html;; charset=${request/client/charset}"
2443 />
2444
2445 The charset is also sent in the http header.
2475 2446
2476 2447
2477 Examples 2448 Examples
2478 ======== 2449 ========
2479 2450
2960 accumulated for an issue. To do this, we'll need to actually write 2931 accumulated for an issue. To do this, we'll need to actually write
2961 some Python code, since it's beyond the scope of PageTemplates to 2932 some Python code, since it's beyond the scope of PageTemplates to
2962 perform such calculations. We do this by adding a method to the 2933 perform such calculations. We do this by adding a method to the
2963 TemplatingUtils class in our tracker ``interfaces.py`` module:: 2934 TemplatingUtils class in our tracker ``interfaces.py`` module::
2964 2935
2965 XXX update this example for TemplatingUtils -> extensions
2966
2967 class TemplatingUtils: 2936 class TemplatingUtils:
2968 ''' Methods implemented on this class will be available to HTML 2937 ''' Methods implemented on this class will be available to HTML
2969 templates through the 'utils' variable. 2938 templates through the 'utils' variable.
2970 ''' 2939 '''
2971 def totalTimeSpent(self, times): 2940 def totalTimeSpent(self, times):
2974 ''' 2943 '''
2975 total = Interval('0d') 2944 total = Interval('0d')
2976 for time in times: 2945 for time in times:
2977 total += time.period._value 2946 total += time.period._value
2978 return total 2947 return total
2948
2949 XXX update this example for TemplatingUtils -> extensions
2979 2950
2980 Replace the ``pass`` line if one appears in your TemplatingUtils 2951 Replace the ``pass`` line if one appears in your TemplatingUtils
2981 class. As indicated in the docstrings, we will be able to access the 2952 class. As indicated in the docstrings, we will be able to access the
2982 ``totalTimeSpent`` method via the ``utils`` variable in our templates. 2953 ``totalTimeSpent`` method via the ``utils`` variable in our templates.
2983 2954
Roundup Issue Tracker: http://roundup-tracker.org/