Mercurial Repository: p/roundup/code: doc/customizing.txt comparison

comparison doc/customizing.txt @ 3904:91008ec8f9a0

retire "topic" usage "Topic" still appears in the locale files. I'm sure we need to support that for existing trackers. I *think* they don't care about any of the other changes that have been made. I also left Ka-Ping Yee's original design document unchanged. This takes care of sf feature request [SF#953161]

author	Justus Pendleton <jpend@users.sourceforge.net>
date	Sun, 16 Sep 2007 02:45:11 +0000
parents	e7050411a774
children	586679a314f7

comparison

equal deleted inserted replaced

-:a90fa2e08a0a
+:91008ec8f9a0
 ===================
 Customising Roundup
 ===================
-:Version: $Revision: 1.220 $
+:Version: $Revision: 1.221 $
 .. This document borrows from the ZopeBook section on ZPT. The original is at:
 http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
 .. contents::
 date=Date(), recipients=Multilink("user"),
 files=Multilink("file"), messageid=String(), inreplyto=String())
 file = FileClass(db, "file", name=String())
-issue = IssueClass(db, "issue", topic=Multilink("keyword"),
+issue = IssueClass(db, "issue", keyword=Multilink("keyword"),
 status=Link("status"), assignedto=Link("user"),
 priority=Link("priority"))
 issue.setkey('title')
 An index view specifier (URL fragment) looks like this (whitespace has
 been added for clarity)::
 /issue?status=unread,in-progress,resolved&
-topic=security,ui&
+keyword=security,ui&
 @group=priority,-status&
 @sort=-activity&
-@filters=status,topic&
+@filters=status,keyword&
 @columns=title,status,fixer
 The index view is determined by two parts of the specifier: the layout
 part and the filter part. The layout part consists of the query
 parameters that begin with colons, and it determines the way that the
 matching any specified Link properties and the intersection of the sets
 of items with values matching any specified Multilink properties.
 The example specifies an index of "issue" items. Only items with a
 "status" of either "unread" or "in-progress" or "resolved" are
-displayed, and only items with "topic" values including both "security"
+displayed, and only items with "keyword" values including both "security"
 and "ui" are displayed. The items are grouped by priority arranged in
 ascending order and in descending order by status; and within
 groups, sorted by activity, arranged in descending order. The filter
-section shows filters for the "status" and "topic" properties, and the
+section shows filters for the "status" and "keyword" properties, and the
 table includes columns for the "title", "status", and "fixer"
 properties.
 ============ =============================================================
 Argument     Description
 caches the schema).
 1. Modify the ``schema.py``::
 issue = IssueClass(db, "issue",
-assignedto=Link("user"), topic=Multilink("keyword"),
+assignedto=Link("user"), keyword=Multilink("keyword"),
 priority=Link("priority"), status=Link("status"),
 due_date=Date())
 2. Add an edit field to the ``issue.item.html`` template::
 2. Link to the new class from your issue class (again, in
 ``schema.py``)::
 issue = IssueClass(db, "issue",
-assignedto=Link("user"), topic=Multilink("keyword"),
+assignedto=Link("user"), keyword=Multilink("keyword"),
 priority=Link("priority"), status=Link("status"),
 times=Multilink("timelog"))
 the "times" property is the new link to the "timelog" class.
 system = Class(db, "system", name=String(), order=Number())
 system.setkey("name")
 # store issues related to those systems
 support = IssueClass(db, "support",
-assignedto=Link("user"), topic=Multilink("keyword"),
+assignedto=Link("user"), keyword=Multilink("keyword"),
 status=Link("status"), deadline=Date(),
 affects=Multilink("system"))
 3. Copy the existing ``issue.*`` (item, search and index) templates in the
 tracker's ``html`` to ``support.*``. Edit them so they use the properties
 1. Create a new property on the ``issue`` class:
 ``blockers=Multilink("issue")``. To do this, edit the definition of
 this class in your tracker's ``schema.py`` file. Change this::
 issue = IssueClass(db, "issue",
-assignedto=Link("user"), topic=Multilink("keyword"),
+assignedto=Link("user"), keyword=Multilink("keyword"),
 priority=Link("priority"), status=Link("status"))
 to this, adding the blockers entry::
 issue = IssueClass(db, "issue",
 blockers=Multilink("issue"),
-assignedto=Link("user"), topic=Multilink("keyword"),
+assignedto=Link("user"), keyword=Multilink("keyword"),
 priority=Link("priority"), status=Link("status"))
 2. Add the new ``blockers`` property to the ``issue.item.html`` edit
 page, using something like::
 that if you want to know whether an issue has any other issues dependent
 on it (i.e. it's in their blockers list) you can look at the journal
 history at the bottom of the issue page - look for a "link" event to
 another issue's "blockers" property.
-Add users to the nosy list based on the topic
+Add users to the nosy list based on the keyword
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Let's say we need the ability to automatically add users to the nosy
 list based
-on the occurance of a topic. Every user should be allowed to edit their
+on the occurance of a keyword. Every user should be allowed to edit their
-own list of topics for which they want to be added to the nosy list.
+own list of keywords for which they want to be added to the nosy list.
 Below, we'll show that this change can be done with minimal
 understanding of the Roundup system, using only copy and paste.
 This requires three changes to the tracker: a change in the database to
-allow per-user recording of the lists of topics for which he wants to
+allow per-user recording of the lists of keywords for which he wants to
 be put on the nosy list, a change in the user view allowing them to edit
-this list of topics, and addition of an auditor which updates the nosy
+this list of keywords, and addition of an auditor which updates the nosy
-list when a topic is set.
+list when a keyword is set.
-Adding the nosy topic list
+Adding the nosy keyword list
-::::::::::::::::::::::::::
+::::::::::::::::::::::::::::
-The change to make in the database, is that for any user there should be
+The change to make in the database, is that for any user there should be a list
-a list of topics for which he wants to be put on the nosy list. Adding
+of keywords for which he wants to be put on the nosy list. Adding a
-a ``Multilink`` of ``keyword`` seems to fullfill this (note that within
+``Multilink`` of ``keyword`` seems to fullfill this. As such, all that has to
-the code, topics are called ``keywords``.) As such, all that has to be
+be done is to add a new field to the definition of ``user`` within the file
-done is to add a new field to the definition of ``user`` within the
+``schema.py``.  We will call this new field ``nosy_keywords``, and the updated
-file ``schema.py``.  We will call this new field ``nosy_keywords``, and
+definition of user will be::
-the updated definition of user will be::
 user = Class(db, "user",
 username=String(),   password=Password(),
 address=String(),    realname=String(),
 phone=String(),      organisation=String(),
 alternate_addresses=String(),
 queries=Multilink('query'), roles=String(),
 timezone=String(),
 nosy_keywords=Multilink('keyword'))
-Changing the user view to allow changing the nosy topic list
+Changing the user view to allow changing the nosy keyword list
-::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
-We want any user to be able to change the list of topics for which
+We want any user to be able to change the list of keywords for which
 he will by default be added to the nosy list. We choose to add this
 to the user view, as is generated by the file ``html/user.item.html``.
 We can easily
-see that the topic field in the issue view has very similar editing
+see that the keyword field in the issue view has very similar editing
-requirements as our nosy topics, both being lists of topics. As
+requirements as our nosy keywords, both being lists of keywords. As
-such, we look for Topics in ``issue.item.html``, and extract the
+such, we look for Keywords in ``issue.item.html``, and extract the
 associated parts from there. We add this to ``user.item.html`` at the
 bottom of the list of viewed items (i.e. just below the 'Alternate
 E-mail addresses' in the classic template)::
 <tr>
-<th>Nosy Topics</th>
+<th>Nosy Keywords</th>
 <td>
 <span tal:replace="structure context/nosy_keywords/field" />
 <span tal:replace="structure python:db.keyword.classhelp(property='nosy_keywords')" />
 </td>
 </tr>
 Addition of an auditor to update the nosy list
 ::::::::::::::::::::::::::::::::::::::::::::::
 The more difficult part is the logic to add
 the users to the nosy list when required.
-We choose to perform this action whenever the topics on an
+We choose to perform this action whenever the keywords on an
 item are set (this includes the creation of items).
 Here we choose to start out with a copy of the
 ``detectors/nosyreaction.py`` detector, which we copy to the file
 ``detectors/nosy_keyword_reaction.py``.
 This looks like a good start as it also adds users
 ``current`` to a combination of the old and new nosy lists. This
 functionality is left in the new auditor. The following block of
 code, which handled adding the assignedto user(s) to the nosy list in
 ``updatenosy``, should be replaced by a block of code to add the
 interested users to the nosy list. We choose here to loop over all
-new topics, than looping over all users,
+new keywords, than looping over all users,
-and assign the user to the nosy list when the topic occurs in the user's
+and assign the user to the nosy list when the keyword occurs in the user's
 ``nosy_keywords``. The next part in ``updatenosy`` -- adding the author
 and/or recipients of a message to the nosy list -- is obviously not
 relevant here and is thus deleted from the new auditor. The last
 part, copying the new nosy list to ``newvalues``, can stay as is.
 This results in the following function::
 def update_kw_nosy(db, cl, nodeid, newvalues):
-'''Update the nosy list for changes to the topics
+'''Update the nosy list for changes to the keywords
 '''
 # nodeid will be None if this is a new node
 current = {}
 if nodeid is None:
 ok = ('new', 'yes')
 if not db.hasnode('user', value):
 continue
 if not current.has_key(value):
 current[value] = 1
-# add users with topic in nosy_keywords to the nosy list
+# add users with keyword in nosy_keywords to the nosy list
-if newvalues.has_key('topic') and newvalues['topic'] is not None:
+if newvalues.has_key('keyword') and newvalues['keyword'] is not None:
-topic_ids = newvalues['topic']
+keyword_ids = newvalues['keyword']
-for topic in topic_ids:
+for keyword in keyword_ids:
 # loop over all users,
-# and assign user to nosy when topic in nosy_keywords
+# and assign user to nosy when keyword in nosy_keywords
 for user_id in db.user.list():
 nosy_kw = db.user.get(user_id, "nosy_keywords")
 found = 0
 for kw in nosy_kw:
-if kw == topic:
+if kw == keyword:
 found = 1
 if found:
 current[user_id] = 1
 # that's it, save off the new nosy list
 A few problems with the design here can be noted:
 Multiple additions
 When a user, after automatic selection, is manually removed
 from the nosy list, he is added to the nosy list again when the
-topic list of the issue is updated. A better design might be
+keyword list of the issue is updated. A better design might be
-to only check which topics are new compared to the old list
+to only check which keywords are new compared to the old list
-of topics, and only add users when they have indicated
+of keywords, and only add users when they have indicated
-interest on a new topic.
+interest on a new keyword.
 The code could also be changed to only trigger on the ``create()``
 event, rather than also on the ``set()`` event, thus only setting
 the nosy list when the issue is created.
 Scalability
 In the auditor, there is a loop over all users. For a site with
 only few users this will pose no serious problem; however, with
 many users this will be a serious performance bottleneck.
-A way out would be to link from the topics to the users who
+A way out would be to link from the keywords to the users who
-selected these topics as nosy topics. This will eliminate the
+selected these keywords as nosy keywords. This will eliminate the
 loop over all users.
 Changes to Security and Permissions
 -----------------------------------

Mercurial > p > roundup > code

comparison doc/customizing.txt @ 3904:91008ec8f9a0