From 427495daead2bd1bc142eb65c9a147b5564bd23a Mon Sep 17 00:00:00 2001 From: richard Date: Sun, 30 Sep 2001 01:19:22 +0000 Subject: [PATCH] more doc git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@264 57a73879-2fb5-44c3-a270-3262357dd7e2 --- doc/index.html | 343 ++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 314 insertions(+), 29 deletions(-) diff --git a/doc/index.html b/doc/index.html index dd2b714..7e6cdf7 100644 --- a/doc/index.html +++ b/doc/index.html @@ -3,9 +3,9 @@

Roundup

An Issue-Tracking System for Knowledge Workers

Overview (Initial submission to SC Track) @@ -40,10 +40,10 @@

Installation

Prerequisites

Either: @@ -57,13 +57,13 @@ Download the latest version from - Getting Roundup + Getting Roundup Download the latest version from http://roundup.sf.net/. - Installing Roundup + Installing Roundup Run: @@ -79,14 +79,14 @@ Download the latest version from - Getting Started + Getting Started The following instructions assume that you have installed roundup. If you haven't, you may still proceed - just preface all commands with "./" ie. "./roundup-admin init". - The Instance + The Instance We'll be referring to the term instance a lot from now on. An instance is @@ -113,7 +113,7 @@ all reside there: Instances are created using the roundup-admin tool. - Command Line Tool + Command Line Tool To initiliase a new instance, run roundup-admin init. You will be asked a series of questions: @@ -153,7 +153,7 @@ We run the instance as group "issue_tracker" and add the mail and web user any admin people. - E-Mail Interface + E-Mail Interface Set up a mail alias called "issue_tracker" as: |/usr/bin/python /usr/local/bin/roundup-mailgw @@ -176,7 +176,7 @@ To test the mail gateway on unix systems, try: -Web Interface +Web Interface This software will work through apache or stand-alone. Stand-alone: @@ -212,7 +212,7 @@ RewriteRule ^/roundup/roundup.cgi(.*) /home/httpd/html/roundup/roundup.cgi$1 [e= -Users +Users To add users, use one of the following interfaces: @@ -230,7 +230,7 @@ To add users, use one of the following interfaces: -Issues +Issues To add issues, use one of the following interfaces: @@ -247,8 +247,8 @@ To add issues, use one of the following interfaces: -User Guide -Command Line Tool +User Guide +Command Line Tool Usage: roundup-admin [-i instance home] [-u login] [-c] <command> @@ -397,10 +397,10 @@ login may be specified as either "name" or "name:password". If either the name or password is not supplied, they are obtained from the command-line. -Web Interface +Web Interface T.B.D. -E-Mail Gateway +E-Mail Gateway Incoming messages are examined for multiple parts: @@ -413,14 +413,14 @@ Incoming messages are examined for multiple parts: subpart and ignore the other parts. -Summary +Summary The "summary" property on message nodes is taken from the first non-quoting section in the message body. The message body is divided into sections by blank lines. Sections where the second and all subsequent lines begin with a ">" or "|" character are considered "quoting sections". The first line of the first non-quoting section becomes the summary of the message. -Addresses +Addresses All of the addresses in the To: and Cc: headers of the incoming message are looked up among the user nodes, and the corresponding users are placed in the "recipients" property on the new "msg" node. The address in the From: @@ -432,7 +432,7 @@ passwords.) If we prefer to reject mail from outside sources, we can simply register an auditor on the "user" class that prevents the creation of user nodes with no passwords. -Actions +Actions The subject line of the incoming message is examined to determine whether the message is an attempt to create a new item or to discuss an existing item. A designator enclosed in square brackets is sought as the first thing @@ -447,7 +447,7 @@ of that class with its "messages" property initialized to contain the new "msg" node and its "files" property initialized to contain any new "file" nodes. -Triggers +Triggers Both cases may trigger detectors (in the first case we are calling the set() method to add the message to the item's spool; in the second case we are calling the create() method to create a new node). If an auditor raises @@ -455,7 +455,7 @@ an exception, the original message is bounced back to the sender with the explanatory message given in the exception. -Customising Roundup +Customising Roundup Instances have the following structure: @@ -477,7 +477,7 @@ Instances have the following structure: Web interface templates, images and style sheets -Instance Schema +Instance Schema An instance schema defines what data is stored in the instance's database. The two schemas shipped with Roundup turn it into a typical software bug tracker (the extended schema allowing for support issues as well as bugs). @@ -522,7 +522,7 @@ this: issue.setkey('title') -Class, FileClass, IssueClass - creating a new information store +Class, FileClass, IssueClass - creating a new information store A Class defines a particular class (or type) of data that will be stored in the database. In the instance above, we've defined 7 classes of information: @@ -589,7 +589,7 @@ the item was last edited (equivalently, these are the dates on the first and last records in the item's journal). The "creator" property holds a link to the user that created the issue. -setkey(property) +setkey(property) Select a String property of the class to be the key property. The key property muse be unique, and allows references to the items in the class by the content of the key property. That is, we can refer to users by their @@ -606,21 +606,306 @@ or Note, the same thing can be done in the web and e-mail interfaces. - create(information) +create(information) Create an item in the database. This is generally used to create items in the "definitional" classes like "priority" and "status". -Web Interface +Web Interface + +The web interface works behind the cgi-bin/roundup.cgi or roundup-server +scripts. In both cases, the scripts determine which instance is being +accessed (the first part of the URL path inside the scope of the CGI +handler) and pass control on to the instance interfaces.Client class which +handles the rest of the access through its main() method. This means that +you can do pretty much anything you want as a web interface to your +instance. + +Most customisation of the web view can be done by modifying the templates +in the instance html directory. These are divided into index, item and +newitem views. The newitem view is optional - the item view will be used if +the newitem view doesn't exist. + + +Next bit cut straight from the implementation guide + + + 8.2. Displaying Properties + +Properties appear in the user interface in three contexts: +in indices, in editors, and as filters. For each type of +property, there are several display possibilities. For example, +in an index view, a string property may just be printed as +a plain string, but in an editor view, that property should +be displayed in an editable field. + + The display of a property is handled by functions in +a displayers module. Each function accepts at +least three standard arguments -- the database, class name, +and node id -- and returns a chunk of HTML. + + Displayer functions are triggered by <display> +tags in templates. The call attribute of the tag +provides a Python expression for calling the displayer +function. The three standard arguments are inserted in +front of the arguments given. For example, the occurrence of + + <display call="plain('status', max=30)"> + + +in a template triggers a call to + + plain(db, "issue", 13, "status", max=30) + + +when displaying item 13 in the "issue" class. The displayer +functions can accept extra arguments to further specify +details about the widgets that should be generated. By defining new +displayer functions, the user interface can be highly customized. + +Some of the standard displayer functions include: + + +plain: display a String property directly; +display a Date property in a specified time zone with an option +to omit the time from the date stamp; for a Link or Multilink +property, display the key strings of the linked nodes (or the +ids if the linked class has no key property) + + field: display a property like the +plain displayer above, but in a text field +to be edited + + menu: for a Link property, display +a menu of the available choices + + link: for a Link or Multilink property, +display the names of the linked nodes, hyperlinked to the +item views on those nodes + + count: for a Multilink property, display +a count of the number of links in the list + + reldate: display a Date property in terms +of an interval relative to the current date (e.g. "+ 3w", "- 2d"). + + download: show a Link("file") or Multilink("file") +property using links that allow you to download files + + checklist: for a Link or Multilink property, +display checkboxes for the available choices to permit filtering + + +8.3. Index Views + +An index view contains two sections: a filter section +and an index section. +The filter section provides some widgets for selecting +which items appear in the index. The index section is +a table of items. + + 8.3.1. Index View Specifiers + +An index view specifier looks like this (whitespace +has been added for clarity): + + /issue?status=unread,in-progress,resolved& + topic=security,ui& + :group=+priority& + :sort=-activity& + :filters=status,topic& + :columns=title,status,fixer + + +The index view is determined by two parts of the +specifier: the layout part and the filter part. +The layout part consists of the query parameters that +begin with colons, and it determines the way that the +properties of selected nodes are displayed. +The filter part consists of all the other query parameters, +and it determines the criteria by which nodes +are selected for display. + + The filter part is interactively manipulated with +the form widgets displayed in the filter section. The +layout part is interactively manipulated by clicking +on the column headings in the table. + + The filter part selects the union of the +sets of items with values matching any specified Link +properties and the intersection of the sets +of items with values matching any specified Multilink +properties. + + The example specifies an index of "issue" nodes. +Only items with a "status" of either +"unread" or "in-progres" or "resolved" are displayed, +and only items with "topic" values including both +"security" and "ui" are displayed. The items +are grouped by priority, arranged in ascending order; +and within groups, sorted by activity, arranged in +descending order. The filter section shows filters +for the "status" and "topic" properties, and the +table includes columns for the "title", "status", and +"fixer" properties. + + Associated with each item class is a default +layout specifier. The layout specifier in the above +example is the default layout to be provided with +the default bug-tracker schema described above in +section 4.4. + + 8.3.2. Filter Section + +The template for a filter section provides the +filtering widgets at the top of the index view. +Fragments enclosed in <property>...</property> +tags are included or omitted depending on whether the +view specifier requests a filter for a particular property. + + Here's a simple example of a filter template. + + <property name=status> + <display call="checklist('status')"> +</property> +<br> +<property name=priority> + <display call="checklist('priority')"> +</property> +<br> +<property name=fixer> + <display call="menu('fixer')"> +</property> + +8.3.3. Index Section + +The template for an index section describes one row of +the index table. +Fragments enclosed in <property>...</property> +tags are included or omitted depending on whether the +view specifier requests a column for a particular property. +The table cells should contain <display> tags +to display the values of the item's properties. + + Here's a simple example of an index template. + + <tr> + <property name=title> + <td><display call="plain('title', max=50)"></td> + </property> + <property name=status> + <td><display call="plain('status')"></td> + </property> + <property name=fixer> + <td><display call="plain('fixer')"></td> + </property> +</tr> + +8.3.4. Sorting + +String and Date values are sorted in the natural way. +Link properties are sorted according to the value of the +"order" property on the linked nodes if it is present; or +otherwise on the key string of the linked nodes; or +finally on the node ids. Multilink properties are +sorted according to how many links are present. + + 8.4. Item Views + +An item view contains an editor section and a spool section. +At the top of an item view, links to superseding and superseded +items are always displayed. + + 8.4.1. Item View Specifiers + +An item view specifier is simply the item's designator: + + /patch23 + + +8.4.2. Editor Section + +The editor section is generated from a template +containing <display> tags to insert +the appropriate widgets for editing properties. + + Here's an example of a basic editor template. + + <table> +<tr> + <td colspan=2> + <display call="field('title', size=60)"> + </td> +</tr> +<tr> + <td> + <display call="field('fixer', size=30)"> + </td> + <td> + <display call="menu('status')> + </td> +</tr> +<tr> + <td> + <display call="field('nosy', size=30)"> + </td> + <td> + <display call="menu('priority')> + </td> +</tr> +<tr> + <td colspan=2> + <display call="note()"> + </td> +</tr> +</table> + + +As shown in the example, the editor template can also +request the display of a "note" field, which is a +text area for entering a note to go along with a change. + + When a change is submitted, the system automatically +generates a message describing the changed properties. +The message displays all of the property values on the +item and indicates which ones have changed. +An example of such a message might be this: + + title: Polly Parrot is dead +priority: critical +status: unread -> in-progress +fixer: (none) +keywords: parrot,plumage,perch,nailed,dead + + +If a note is given in the "note" field, the note is +appended to the description. The message is then added +to the item's message spool (thus triggering the standard +detector to react by sending out this message to the nosy list). + + 8.4.3. Spool Section + +The spool section lists messages in the item's "messages" +property. The index of messages displays the "date", "author", +and "summary" properties on the message nodes, and selecting a +message takes you to its content. -Acknowledgements +Acknowledgements Go Ping, you rock! Also, go Bizar Software for letting me implement this system on their time. -$Id: index.html,v 1.4 2001-09-29 23:48:06 richard Exp $ +$Id: index.html,v 1.5 2001-09-30 01:19:22 richard Exp $ -- 2.30.2

Roundup

An Issue-Tracking System for Knowledge Workers

An Issue-Tracking System for Knowledge Workers

Contents

Contents

Summary

Summary

Addresses

Addresses

Actions

Actions

Triggers

Triggers

Class, FileClass, IssueClass - creating a new information store

Class, FileClass, IssueClass - creating a new information store

setkey(property)

setkey(property)

create(information)

create(information)

8.2. Displaying Properties

8.3. Index Views

8.3.1. Index View Specifiers

8.3.2. Filter Section

8.3.3. Index Section

8.3.4. Sorting

8.4. Item Views

8.4.1. Item View Specifiers

8.4.2. Editor Section

8.4.3. Spool Section