Mercurial > p > roundup > code

annotate doc/customizing.stx @ 639:2f3e82a69eb5

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