![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/customizing.txt b/doc/customizing.txt
index 2662f62945040cf7be84d72c932336095b420b27..0136601910ec8a56f34d249378bd9c36dd0a9db6 100644 (file)
--- a/doc/customizing.txt
+++ b/doc/customizing.txt
Customising Roundup
===================
-:Version: $Revision: 1.100 $
+:Version: $Revision: 1.105 $
.. This document borrows from the ZopeBook section on ZPT. The original is at:
http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
Before you get too far, it's probably worth having a quick read of the Roundup
`design documentation`_.
-Customisation of Roundup can take one of five forms:
+Customisation of Roundup can take one of six forms:
1. `tracker configuration`_ file changes
2. database, or `tracker schema`_ changes
priority=Link("priority"))
issue.setkey('title')
+
+What you can't do to the schema
+-------------------------------
+
+You must never:
+
+**Remove the users class**
+ This class is the only *required* class in Roundup. Similarly, its
+ username, password and address properties must never be removed.
+
+**Change the type of a property**
+ Property types must *never* be changed - the database simply doesn't take
+ this kind of action into account. Note that you can't just remove a
+ property and re-add it as a new type either. If you wanted to make the
+ assignedto property a Multilink, you'd need to create a new property
+ assignedto_list and remove the old assignedto property.
+
+
+What you can do to the schema
+-----------------------------
+
+Your schema may be changed at any time before or after the tracker has been
+initialised (or used). You may:
+
+**Add new properties to classes, or add whole new classes**
+ This is painless and easy to do - there are generally no repurcussions
+ from adding new information to a tracker's schema.
+
+**Remove properties**
+ Removing properties is a little more tricky - you need to make sure that
+ the property is no longer used in the `web interface`_ *or* by the
+ detectors_.
+
+
+
Classes and Properties - creating a new information store
---------------------------------------------------------
This is equivalent to::
@link@messages=msg-1
- @msg-1@content=value
+ msg-1@content=value
except that in addition, the "author" and "date" properties of
"msg-1" are set to the userid of the submitter, and the current
This is equivalent to::
@link@files=file-1
- @file-1@content=value
+ file-1@content=value
The String content value is handled as described above for file
uploads.
<table class="form">
<tr>
- <th nowrap>Title</th>
+ <th>Title</th>
<td colspan="3" tal:content="structure python:context.title.field(size=60)">title</td>
</tr>
<tr>
- <th nowrap>Priority</th>
+ <th>Priority</th>
<td tal:content="structure context/priority/menu">priority</td>
- <th nowrap>Status</th>
+ <th>Status</th>
<td tal:content="structure context/status/menu">status</td>
</tr>
<tr>
- <th nowrap>Superseder</th>
+ <th>Superseder</th>
<td>
<span tal:replace="structure python:context.superseder.field(showid=1, size=20)" />
<span tal:replace="structure python:db.issue.classhelp('id,title')" />
<br>View: <span tal:replace="structure python:context.superseder.link(showid=1)" />
</span>
</td>
- <th nowrap>Nosy List</th>
+ <th>Nosy List</th>
<td>
<span tal:replace="structure context/nosy/field" />
<span tal:replace="structure python:db.user.classhelp('username,realname,address,phone')" />
</tr>
<tr>
- <th nowrap>Assigned To</th>
+ <th>Assigned To</th>
<td tal:content="structure context/assignedto/menu">
assignedto menu
</td>
</tr>
<tr>
- <th nowrap>Change Note</th>
+ <th>Change Note</th>
<td colspan="3">
<textarea name=":note" wrap="hard" rows="5" cols="60"></textarea>
</td>
</tr>
<tr>
- <th nowrap>File</th>
+ <th>File</th>
<td colspan="3"><input type="file" name=":file" size="40"></td>
</tr>
to the form, a new category will be created with that name::
<tr>
- <th nowrap>Name</th>
+ <th>Name</th>
<td tal:content="structure python:context.name.field(size=60)">
name</td>
</tr>
<form method="POST" onSubmit="return submit_once()"
enctype="multipart/form-data">
- <input type="hidden" name="@required" value="name">
-
<table class="form">
<tr><th class="header" colspan="2">Category</th></tr>
<tr>
- <th nowrap>Name</th>
+ <th>Name</th>
<td tal:content="structure python:context.name.field(size=60)">
name</td>
</tr>
<tr>
- <td> </td>
+ <td>
+
+ <input type="hidden" name="@required" value="name">
+ </td>
<td colspan="3" tal:content="structure context/submit">
submit button will go here
</td>
table to lay things out. It doesn't matter where in the table we add new
stuff, it is entirely up to your sense of aesthetics::
- <th nowrap>Category</th>
+ <th>Category</th>
<td><span tal:replace="structure context/category/field" />
<span tal:replace="structure db/category/classhelp" />
</td>
4. in the ``issue.item.html`` template, change the status editing bit
from::
- <th nowrap>Status</th>
+ <th>Status</th>
<td tal:content="structure context/status/menu">status</td>
to::
- <th nowrap>Status</th>
+ <th>Status</th>
<td>
<select tal:condition="context/id" name="status">
<tal:block tal:define="ok context/status/transitions"
<td><a tal:attributes="href string:msg${msg/id}"
tal:content="string:msg${msg/id}"></a></td>
<td tal:content="msg/author">author</td>
- <td nowrap tal:content="msg/date/pretty">date</td>
+ <td class="date" tal:content="msg/date/pretty">date</td>
<td tal:content="msg/summary">summary</td>
<td>
<a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">
<tal:block tal:condition="python:cat in '6 10 13 14 15 16 17'.split()">
<tr>
- <th nowrap>Operating System</th>
+ <th>Operating System</th>
<td tal:content="structure context/os/field"></td>
</tr>
<tr>
- <th nowrap>Web Browser</th>
+ <th>Web Browser</th>
<td tal:content="structure context/browser/field"></td>
</tr>
</tal:block>
field to capture a new timelog item's perdiod::
<tr>
- <th nowrap>Time Log</th>
+ <th>Time Log</th>
<td colspan=3><input type="text" name="timelog-1@period" />
<br />(enter as '3y 1m 4d 2:40:02' or parts thereof)
</td>
<td><a tal:attributes="href string:msg${msg/id}"
tal:content="string:msg${msg/id}"></a></td>
<td tal:content="msg/author">author</td>
- <td nowrap tal:content="msg/date/pretty">date</td>
+ <td class="date" tal:content="msg/date/pretty">date</td>
<td tal:content="msg/summary">summary</td>
<td>
<a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">remove</a>
<tal:block tal:repeat="msg context/messages">
<tr>
<th tal:content="msg/author">author</th>
- <th nowrap tal:content="msg/date/pretty">date</th>
+ <th class="date" tal:content="msg/date/pretty">date</th>
<th style="text-align: right">
(<a tal:attributes="href string:?@remove@messages=${msg/id}&@action=edit">remove</a>)
</th>
2. Add the new "blockers" property to the issue.item edit page, using
something like::
- <th nowrap>Waiting On</th>
+ <th>Waiting On</th>
<td>
<span tal:replace="structure python:context.blockers.field(showid=1,
size=20)" />