doc/customizing.txt

   1 Customising Roundup
   2 ===================
   3
   4 :Version: $Revision: 1.4 $
   5
   6 .. contents::
   7
   8
   9 Instances have the following structure:
  10
  11 +-------------------+--------------------------------------------------------+
  12 |instance_config.py |Holds the basic instance_configuration                  |
  13 +-------------------+--------------------------------------------------------+
  14 |dbinit.py          |Holds the instance_schema                               |
  15 +-------------------+--------------------------------------------------------+
  16 |interfaces.py      |Defines the Web and E-Mail interfaces for the instance  |
  17 +-------------------+--------------------------------------------------------+
  18 |select_db.py       |Selects the database back-end for the instance          |
  19 +-------------------+--------------------------------------------------------+
  20 |db/                |Holds the instance's database                           |
  21 +-------------------+--------------------------------------------------------+
  22 |db/files/          |Holds the instance's upload files and messages          |
  23 +-------------------+--------------------------------------------------------+
  24 |detectors/         |Auditors and reactors for this instance                 |
  25 +-------------------+--------------------------------------------------------+
  26 |html/              |Web interface templates, images and style sheets        |
  27 +-------------------+--------------------------------------------------------+
  28
  29 Instance Configuration
  30 ----------------------
  31
  32 The instance_config.py located in your instance home contains the basic
  33 configuration for the web and e-mail components of roundup's interfaces. This
  34 file is a Python module. The default instance_config.py is given below - as you
  35 can see, the MAIL_DOMAIN must be edited before any interaction with the
  36 instance is attempted.::
  37
  38   MAIL_DOMAIN=MAILHOST=HTTP_HOST=None
  39   HTTP_PORT=0
  40
  41   # roundup home is this package's directory
  42   INSTANCE_HOME=os.path.split(__file__)[0]
  43
  44   # The SMTP mail host that roundup will use to send mail
  45   if not MAILHOST:
  46       MAILHOST = 'localhost'
  47
  48   # The domain name used for email addresses.
  49   if not MAIL_DOMAIN:
  50       MAIL_DOMAIN = 'fill.me.in.'
  51
  52   # the next two are only used for the standalone HTTP server.
  53   if not HTTP_HOST:
  54       HTTP_HOST = ''
  55   if not HTTP_PORT:
  56       HTTP_PORT = 9080
  57
  58   # This is the directory that the database is going to be stored in
  59   DATABASE = os.path.join(INSTANCE_HOME, 'db')
  60
  61   # This is the directory that the HTML templates reside in
  62   TEMPLATES = os.path.join(INSTANCE_HOME, 'html')
  63
  64   # The email address that mail to roundup should go to
  65   ISSUE_TRACKER_EMAIL = 'issue_tracker@%s'%MAIL_DOMAIN
  66
  67   # The web address that the instance is viewable at
  68   ISSUE_TRACKER_WEB = 'http://some.useful.url/'
  69
  70   # The email address that roundup will complain to if it runs into trouble
  71   ADMIN_EMAIL = 'roundup-admin@%s'%MAIL_DOMAIN
  72
  73   # Somewhere for roundup to log stuff internally sent to stdout or stderr
  74   LOG = os.path.join(INSTANCE_HOME, 'roundup.log')
  75
  76   # Where to place the web filtering HTML on the index page
  77   FILTER_POSITION = 'bottom'      # one of 'top', 'bottom', 'top and bottom'
  78
  79   # Deny or allow anonymous access to the web interface
  80   ANONYMOUS_ACCESS = 'deny'
  81
  82   # Deny or allow anonymous users to register through the web interface
  83   ANONYMOUS_REGISTER = 'deny'
  84
  85   # Send nosy messages to the author of the message
  86   MESSAGES_TO_AUTHOR = 'no'       # either 'yes' or 'no'
  87
  88
  89 Instance Schema
  90 ---------------
  91
  92 Note: if you modify the schema, you'll most likely need to edit the
  93       `web interface`_ HTML template files to reflect your changes.
  94
  95 An instance schema defines what data is stored in the instance's database. The
  96 two schemas shipped with Roundup turn it into a typical software bug tracker
  97 (the extended schema allowing for support issues as well as bugs). Schemas are
  98 defined using Python code. The "classic" schema looks like this::
  99
 100     pri = Class(db, "priority", name=String(), order=String())
 101     pri.setkey("name")
 102     pri.create(name="critical", order="1")
 103     pri.create(name="urgent", order="2")
 104     pri.create(name="bug", order="3")
 105     pri.create(name="feature", order="4")
 106     pri.create(name="wish", order="5")
 107
 108     stat = Class(db, "status", name=String(), order=String())
 109     stat.setkey("name")
 110     stat.create(name="unread", order="1")
 111     stat.create(name="deferred", order="2")
 112     stat.create(name="chatting", order="3")
 113     stat.create(name="need-eg", order="4")
 114     stat.create(name="in-progress", order="5")
 115     stat.create(name="testing", order="6")
 116     stat.create(name="done-cbb", order="7")
 117     stat.create(name="resolved", order="8")
 118
 119     keyword = Class(db, "keyword", name=String())
 120     keyword.setkey("name")
 121
 122     user = Class(db, "user", username=String(), password=String(),
 123         address=String(), realname=String(), phone=String(),
 124         organisation=String())
 125     user.setkey("username")
 126     user.create(username="admin", password=adminpw,
 127         address=instance_config.ADMIN_EMAIL)
 128
 129     msg = FileClass(db, "msg", author=Link("user"), recipients=Multilink
 130         ("user"), date=Date(), summary=String(), files=Multilink("file"))
 131
 132     file = FileClass(db, "file", name=String(), type=String())
 133
 134     issue = IssueClass(db, "issue", assignedto=Link("user"),
 135         topic=Multilink("keyword"), priority=Link("priority"), status=Link
 136         ("status"))
 137     issue.setkey('title')
 138
 139 Classes and Properties - creating a new information store
 140 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 141
 142 In the instance above, we've defined 7 classes of information:
 143
 144   priority
 145       Defines the possible levels of urgency for issues.
 146
 147   status
 148       Defines the possible states of processing the issue may be in.
 149
 150   keyword
 151       Initially empty, will hold keywords useful for searching issues.
 152
 153   user
 154       Initially holding the "admin" user, will eventually have an entry for all
 155       users using roundup.
 156
 157   msg
 158       Initially empty, will all e-mail messages sent to or generated by
 159       roundup.
 160
 161   file
 162       Initially empty, will all files attached to issues.
 163
 164   issue
 165       Initially emtyp, this is where the issue information is stored.
 166
 167 We define the "priority" and "status" classes to allow two things: reduction in
 168 the amount of information stored on the issue and more powerful, accurate
 169 searching of issues by priority and status. By only requiring a link on the
 170 issue (which is stored as a single number) we reduce the chance that someone
 171 mis-types a priority or status - or simply makes a new one up.
 172
 173 Class and Nodes
 174 :::::::::::::::
 175
 176 A Class defines a particular class (or type) of data that will be stored in the
 177 database. A class comprises one or more properties, which given the information
 178 about the class nodes.
 179 The actual data entered into the database, using class.create() are called
 180 nodes. They have a special immutable property called id. We sometimes refer to
 181 this as the nodeid.
 182
 183 Properties
 184 ::::::::::
 185
 186 A Class is comprised of one or more properties of the following types:
 187     * String properties are for storing arbitrary-length strings.
 188     * Password properties are for storing encoded arbitrary-length strings. The
 189       default encoding is defined on the roundup.password.Password class.
 190     * Date properties store date-and-time stamps. Their values are Timestamp
 191       objects.
 192     * A Link property refers to a single other node selected from a specified
 193       class. The class is part of the property; the value is an integer, the id
 194       of the chosen node.
 195     * A Multilink property refers to possibly many nodes in a specified class.
 196       The value is a list of integers.
 197
 198 FileClass
 199 :::::::::
 200
 201 FileClasses save their "content" attribute off in a separate file from the rest
 202 of the database. This reduces the number of large entries in the database,
 203 which generally makes databases more efficient, and also allows us to use
 204 command-line tools to operate on the files. They are stored in the files sub-
 205 directory of the db directory in your instance.
 206
 207 IssueClass
 208 ::::::::::
 209
 210 IssueClasses automatically include the "messages", "files", "nosy", and
 211 "superseder" properties.
 212 The messages and files properties list the links to the messages and files
 213 related to the issue. The nosy property is a list of links to users who wish to
 214 be informed of changes to the issue - they get "CC'ed" e-mails when messages
 215 are sent to or generated by the issue. The nosy reactor (in the detectors
 216 directory) handles this action. The superceder link indicates an issue which
 217 has superceded this one.
 218 They also have the dynamically generated "creation", "activity" and "creator"
 219 properties.
 220 The value of the "creation" property is the date when a node was created, and
 221 the value of the "activity" property is the date when any property on the node
 222 was last edited (equivalently, these are the dates on the first and last
 223 records in the node's journal). The "creator" property holds a link to the user
 224 that created the issue.
 225
 226 setkey(property)
 227 ::::::::::::::::
 228
 229 Select a String property of the class to be the key property. The key property
 230 muse be unique, and allows references to the nodes in the class by the content
 231 of the key property. That is, we can refer to users by their username, e.g.
 232 let's say that there's an issue in roundup, issue 23. There's also a user,
 233 richard who happens to be user 2. To assign an issue to him, we could do either
 234 of::
 235
 236      roundup-admin set issue assignedto=2
 237
 238 or::
 239
 240      roundup-admin set issue assignedto=richard
 241
 242 Note, the same thing can be done in the web and e-mail interfaces.
 243
 244 create(information)
 245 :::::::::::::::::::
 246
 247 Create a node in the database. This is generally used to create nodes in the
 248 "definitional" classes like "priority" and "status".
 249
 250
 251 Detectors - adding behaviour to your tracker
 252 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 253
 254 Sample additional detectors that have been found useful will appear in the
 255 ``detectors`` directory of the Roundup distribution:
 256
 257 newissuecopy.py
 258   This detector sends an email to a team address whenever a new issue is
 259   created. The address is hard-coded into the detector, so edit it before you
 260   use it (look for the text 'team@team.host') or you'll get email errors!
 261
 262
 263 Web Interface
 264 -------------
 265
 266 The web interface works behind the cgi-bin/roundup.cgi or roundup-server
 267 scripts. In both cases, the scripts determine which instance is being accessed
 268 (the first part of the URL path inside the scope of the CGI handler) and pass
 269 control on to the instance interfaces.Client class which handles the rest of
 270 the access through its main() method. This means that you can do pretty much
 271 anything you want as a web interface to your instance.
 272 Most customisation of the web view can be done by modifying the templates in
 273 the instance html directory. These are divided into index, item and newitem
 274 views. The newitem view is optional - the item view will be used if the newitem
 275 view doesn't exist.
 276
 277 Repurcussions of changing the instance schema
 278 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 279
 280 If you choose to change_the_instance_schema you will need to ensure the web
 281 interface knows about it:
 282
 283    1. Index, item and filter pages for the relevant classes may need to have
 284       properties added or removed,
 285    2. The default page header relies on the existence of, and some values of
 286       the priority, status, assignedto and activity classes. If you change any
 287       of these (specifically if you remove any of the classes or their default
 288       values) you will need to implement your own pagehead() method in your
 289       instance's interfaces.py module.
 290
 291 Displaying Properties
 292 ~~~~~~~~~~~~~~~~~~~~~
 293
 294 Properties appear in the user interface in three contexts: in indices, in
 295 editors, and as filters. For each type of property, there are several display
 296 possibilities. For example, in an index view, a string property may just be
 297 printed as a plain string, but in an editor view, that property should be
 298 displayed in an editable field.
 299
 300 The display of a property is handled by functions in the htmltemplate module.
 301 Displayer functions are triggered by <display> tags in templates. The call
 302 attribute of the tag provides a Python expression for calling the displayer
 303 function. The three standard arguments are inserted in front of the arguments
 304 given. For example, the occurrence of::
 305
 306          <display call="plain('status')">
 307
 308 in a template triggers a call the "plain" function. The displayer functions can
 309 accept extra arguments to further specify details about the widgets that should
 310 be generated. By defining new displayer functions, the user interface can be
 311 highly customized.
 312
 313 +-----------------------------------------------------------------------------+
 314 |The displayer functions are                                                  |
 315 +---------+-------------------------------------------------------------------+
 316 |plain    |Display a String property directly.                                |
 317 |         |Display a Date property in a specified time zone with an option to |
 318 |         |omit the time from the date stamp.                                 |
 319 |         |For a Link or Multilink property, display the key strings of the   |
 320 |         |linked nodes (or the ids if the linked class has no key property). |
 321 |         |Options:                                                           |
 322 |         |escape (boolean) - HTML-escape the resulting text.                 |
 323 +---------+-------------------------------------------------------------------+
 324 |field    |Display a property like the plain displayer above, but in a form   |
 325 |         |field to be edited. Strings, Dates and Intervals use TEXT fields,  |
 326 |         |Links use SELECT fields and Multilinks use SELECT MULTIPLE fields. |
 327 |         |Options:                                                           |
 328 |         |size (number) - width of TEXT fields.                              |
 329 |         |height (number) - number of nows in SELECT MULTIPLE tags.          |
 330 |         |showid (boolean) - true includes the id of linked nodes in the     |
 331 |         |SELECT MULTIPLE fields.                                            |
 332 +---------+-------------------------------------------------------------------+
 333 |menu     |For a Links and Multilinks, display the same field as would be     |
 334 |         |generated using field.                                             |
 335 +---------+-------------------------------------------------------------------+
 336 |link     |For a Link or Multilink property, display the names of the linked  |
 337 |         |nodes, hyperlinked to the item views on those nodes.               |
 338 |         |For other properties, link to this node with the property as the   |
 339 |         |text.                                                              |
 340 |         |Options:                                                           |
 341 |         |property (property name) - the property to use in the second case. |
 342 |         |showid - use the linked node id as the link text (linked node      |
 343 |         |         "value" will be set as a tooltip)                         |
 344 +---------+-------------------------------------------------------------------+
 345 |count    |For a Multilink property, display a count of the number of links in|
 346 |         |the list.                                                          |
 347 |         |Arguments:                                                         |
 348 |         |property (property name) - the property to use.                    |
 349 +---------+-------------------------------------------------------------------+
 350 |reldate  |Display a Date property in terms of an interval relative to the    |
 351 |         |current date (e.g. "+ 3w", "- 2d").                                |
 352 |         |Arguments:                                                         |
 353 |         |property (property name) - the property to use.                    |
 354 |         |Options:                                                           |
 355 |         |pretty (boolean) - display the relative date in an English form.   |
 356 +---------+-------------------------------------------------------------------+
 357 |download |For a Link or Multilink property, display the names of the linked  |
 358 |         |nodes, hyperlinked to the item views on those nodes.               |
 359 |         |For other properties, link to this node with the property as the   |
 360 |         |text.                                                              |
 361 |         |In all cases, append the name (key property) of the item to the    |
 362 |         |path so it is the name of the file being downloaded.               |
 363 |         |Arguments:                                                         |
 364 |         |property (property name) - the property to use.                    |
 365 +---------+-------------------------------------------------------------------+
 366 |checklist|For a Link or Multilink property, display checkboxes for the       |
 367 |         |available choices to permit filtering.                             |
 368 |         |Arguments:                                                         |
 369 |         |property (property name) - the property to use.                    |
 370 +---------+-------------------------------------------------------------------+
 371 |note     |Display the special notes field, which is a text area for entering |
 372 |         |a note to go along with a change.                                  |
 373 +---------+-------------------------------------------------------------------+
 374 |list     |List the nodes specified by property using the standard index for  |
 375 |         |the class.                                                         |
 376 |         |Arguments:                                                         |
 377 |         |property (property name) - the property to use.                    |
 378 +---------+-------------------------------------------------------------------+
 379 |history  |List the history of the item.                                      |
 380 +---------+-------------------------------------------------------------------+
 381 |submit   |Add a submit button for the item.                                  |
 382 +---------+-------------------------------------------------------------------+
 383
 384
 385 Index Views
 386 ~~~~~~~~~~~
 387
 388 An index view contains two sections: a filter section and an index section. The
 389 filter section provides some widgets for selecting which items appear in the
 390 index. The index section is a table of items.
 391
 392 Index View Specifiers
 393 :::::::::::::::::::::
 394
 395 An index view specifier (URL fragment) looks like this (whitespace has been
 396 added for clarity)::
 397
 398      /issue?status=unread,in-progress,resolved&
 399              topic=security,ui&
 400              :group=+priority&
 401              :sort=-activity&
 402              :filters=status,topic&
 403              :columns=title,status,fixer
 404
 405 The index view is determined by two parts of the specifier: the layout part and
 406 the filter part. The layout part consists of the query parameters that begin
 407 with colons, and it determines the way that the properties of selected nodes
 408 are displayed. The filter part consists of all the other query parameters, and
 409 it determines the criteria by which nodes are selected for display.
 410 The filter part is interactively manipulated with the form widgets displayed in
 411 the filter section. The layout part is interactively manipulated by clicking on
 412 the column headings in the table.
 413
 414 The filter part selects the union of the sets of items with values matching any
 415 specified Link properties and the intersection of the sets of items with values
 416 matching any specified Multilink properties.
 417
 418 The example specifies an index of "issue" nodes. Only items with a "status" of
 419 either "unread" or "in-progres" or "resolved" are displayed, and only items
 420 with "topic" values including both "security" and "ui" are displayed. The items
 421 are grouped by priority, arranged in ascending order; and within groups, sorted
 422 by activity, arranged in descending order. The filter section shows filters for
 423 the "status" and "topic" properties, and the table includes columns for the
 424 "title", "status", and "fixer" properties.
 425
 426 Associated with each item class is a default layout specifier. The layout
 427 specifier in the above example is the default layout to be provided with the
 428 default bug-tracker schema described above in section 4.4.
 429
 430 Filter Section
 431 ::::::::::::::
 432
 433 The template for a filter section provides the filtering widgets at the top of
 434 the index view. Fragments enclosed in <property>...</property> tags are
 435 included or omitted depending on whether the view specifier requests a filter
 436 for a particular property.
 437
 438 A property must appear in the filter template for it to be available as a
 439 filter.
 440
 441 Here's a simple example of a filter template.::
 442
 443      <property name=status>
 444          <display call="checklist('status')">
 445      </property>
 446      <br>
 447      <property name=priority>
 448          <display call="checklist('priority')">
 449      </property>
 450      <br>
 451      <property name=fixer>
 452          <display call="menu('fixer')">
 453      </property>
 454
 455 The standard index generation code appends a section to the index pages which
 456 allows selection of the filters - from those which are defined in the filter
 457 template.
 458
 459 Index Section
 460 :::::::::::::
 461
 462 The template for an index section describes one row of the index table.
 463 Fragments enclosed in <property>...</property> tags are included or omitted
 464 depending on whether the view specifier requests a column for a particular
 465 property. The table cells should contain <display> tags to display the values
 466 of the item's properties.
 467
 468 Here's a simple example of an index template.::
 469
 470      <tr>
 471          <property name=title>
 472              <td><display call="plain('title', max=50)"></td>
 473          </property>
 474          <property name=status>
 475              <td><display call="plain('status')"></td>
 476          </property>
 477          <property name=fixer>
 478              <td><display call="plain('fixer')"></td>
 479          </property>
 480      </tr>
 481
 482 Sorting
 483 :::::::
 484
 485 String and Date values are sorted in the natural way. Link properties are
 486 sorted according to the value of the "order" property on the linked nodes if it
 487 is present; or otherwise on the key string of the linked nodes; or finally on
 488 the node ids. Multilink properties are sorted according to how many links are
 489 present.
 490
 491 Item Views
 492 ~~~~~~~~~~
 493
 494 An item view contains an editor section and a spool section. At the top of an
 495 item view, links to superseding and superseded items are always displayed.
 496
 497 Editor Section
 498 ::::::::::::::
 499
 500 The editor section is generated from a template containing <display> tags to
 501 insert the appropriate widgets for editing properties.
 502
 503 Here's an example of a basic editor template.::
 504
 505      <table>
 506      <tr>
 507          <td colspan=2>
 508              <display call="field('title', size=60)">
 509          </td>
 510      </tr>
 511      <tr>
 512          <td>
 513              <display call="field('fixer', size=30)">
 514          </td>
 515          <td>
 516              <display call="menu('status')>
 517          </td>
 518      </tr>
 519      <tr>
 520          <td>
 521              <display call="field('nosy', size=30)">
 522          </td>
 523          <td>
 524              <display call="menu('priority')>
 525          </td>
 526      </tr>
 527      <tr>
 528          <td colspan=2>
 529              <display call="note()">
 530          </td>
 531      </tr>
 532      </table>
 533
 534 As shown in the example, the editor template can also request the display of a
 535 "note" field, which is a text area for entering a note to go along with a
 536 change.
 537
 538 The <property> tag used in the index may also be used here - it checks to see
 539 if the nominated Multilink property has any entries. This can be used to
 540 eliminate sections of the editor section if the property has no entries::
 541
 542   <td class="form-text">
 543     <display call="field('superseder', size=40, showid=1)">
 544     <display call="classhelp('issue', 'id,title', label='list', width=500)">
 545     <property name="superseder">
 546       <br>View: <display call="link('superseder', showid=1)">
 547     </property>
 548   </td>
 549
 550 The "View: " part with the links will only display if the superseder property
 551 has values.
 552
 553 When a change is submitted, the system automatically generates a message
 554 describing the changed properties.
 555
 556 If a note is given in the "note" field, the note is appended to the
 557 description. The message is then added to the item's message spool (thus
 558 triggering the standard detector to react by sending out this message to the
 559 nosy list).
 560
 561 The message also displays all of the property values on the item and indicates
 562 which ones have changed. An example of such a message might be this::
 563
 564      Polly's taken a turn for the worse - this is now really important!
 565      -----
 566      title: Polly Parrot is dead
 567      priority: critical
 568      status: unread -> in-progress
 569      fixer: terry
 570      keywords: parrot,plumage,perch,nailed,dead
 571
 572 Spool Section
 573 :::::::::::::
 574
 575 The spool section lists messages in the item's "messages" property. The index
 576 of messages displays the "date", "author", and "summary" properties on the
 577 message nodes, and selecting a message takes you to its content.
 578
 579 The <property> tag used in the index may also be used here - it checks to see
 580 if the nominated Multilink property has any entries. This can be used to
 581 eliminate sections of the spool section if the property has no entries::
 582
 583      <property name="files">
 584       <tr class="strong-header">
 585        <td><b>Files</b></td>
 586       </tr>
 587
 588       <tr>
 589        <td><display call="list('files')"></td>
 590       </tr>
 591      </property>
 592
 593 -----------------
 594
 595 Back to `Table of Contents`_
 596
 597 .. _`Table of Contents`: index.html
 598