Sorting/grouping by multiple properties.

- Implement sorting/grouping by multiple properties for the web
  interface. I'm now using @sort0/@sortdir0,@sort1/@sortdir1,... and
  @group0/@groupdir0,... when generating URLs from a search template.
  These are converted to a list internally. When saving URLs (e.g. when
  storing queries) I'm using @sort=prop1,prop2,... and @group=... with
  optional '-' prepended to individual props.
  This means saved URLs are backward compatible with existing trackers
  (and yes, this was a design goal).
  I need the clumsy version with @sort0,@Sort1 etc, because I'm
  currently using several selectors and checkboxes (as the classic
  template does, too). I don't think there is a way around that in HTML?
- Updated (hopefully all) documentation to reflect the new URL format
  and the consequences in the web-interface.
- I've set the number of sort/group properties in the classic template
  to two -- this can easily be reverted by changing n_sort to 1.

Richard, would you look over these changes? I've set a tag before and
(will set) after commit, so that it would be easy to merge out.
Don't be too scared about the size of the change, most is documentation,
the guts are in cgi/templating.py and small changes in the classic
template.

Author: Ralf Schlatterbeck

CHANGES.txt

@@ -17,7 +17,7 @@ Feature:
 - new "exporttables" command in roundup-admin (sf bug 1533791)
 - roundup-admin "export" may specify classes to exclude (sf bug 1533791)
 - sorting and grouping by multiple properties is now supported by the
-  backends
+  backends *and* the classic template.
 - sorting, grouping, and searching by transitive properties (e.g.,
   messages.author.supervisor) is now supported in all backends
 - added filter_sql to SQL backends which takes an arbitrary SQL statement

doc/customizing.txt

@@ -2,7 +2,7 @@
 Customising Roundup
 ===================
 
-:Version: $Revision: 1.205 $
+:Version: $Revision: 1.206 $
 
 .. This document borrows from the ZopeBook section on ZPT. The original is at:
    http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
@@ -1865,7 +1865,8 @@ filter      lists of items from this class, filtered and sorted. Two
             1. by the current *request* filterspec/filter/sort/group args
             2. by the "filterspec", "sort" and "group" keyword args.
                "filterspec" is ``{propname: value(s)}``. "sort" and
-               "group" are ``(dir, prop)`` where dir is '+', '-' or None
+               "group" are an optionally empty list ``[(dir, prop)]``
+               where dir is '+', '-' or None
                and prop is a prop name or None.
 
             eg. ``issue.filter(filterspec={"priority": "1"},
@@ -2195,8 +2196,8 @@ Variable    Holds
 columns     dictionary of the columns to display in an index page
 show        a convenience access to columns - request/show/colname will
             be true if the columns should be displayed, false otherwise
-sort        index sort column (direction, column name)
-group       index grouping property (direction, column name)
+sort        index sort columns [(direction, column name)]
+group       index grouping properties [(direction, column name)]
 filter      properties to filter the index on
 filterspec  values to filter the index on
 search_text text to perform a full-text search on for an index
@@ -2432,7 +2433,7 @@ been added for clarity)::
 
     /issue?status=unread,in-progress,resolved&
         topic=security,ui&
-        @group=priority&
+        @group=priority,-status&
         @sort=-activity&
         @filters=status,topic&
         @columns=title,status,fixer
@@ -2454,19 +2455,30 @@ 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"
-and "ui" are displayed. The items are grouped by priority, arranged in
-ascending order; and within groups, sorted by activity, arranged in
-descending order. The filter section shows filters for the "status" and
-"topic" properties, and the table includes columns for the "title",
-"status", and "fixer" properties.
+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
+table includes columns for the "title", "status", and "fixer"
+properties.
 
 ============ =============================================================
 Argument     Description
 ============ =============================================================
 @sort        sort by prop name, optionally preceeded with '-' to give
-             descending or nothing for ascending sorting.
+             descending or nothing for ascending sorting. Several
+             properties can be specified delimited with comma.
+             Internally a search-page using several sort properties may
+             use @sort0, @sort1 etc. with option @sortdir0, @sortdir1
+             etc. for the direction of sorting (a non-empty value of
+             sortdir0 specifies reverse order).
 @group       group by prop name, optionally preceeded with '-' or to sort
-             in descending or nothing for ascending order.
+             in descending or nothing for ascending order. Several
+             properties can be specified delimited with comma.
+             Internally a search-page using several grouping properties may
+             use @group0, @group1 etc. with option @groupdir0, @groupdir1
+             etc. for the direction of grouping (a non-empty value of
+             groupdir0 specifies reverse order).
 @columns     selects the columns that should be displayed. Default is
              all.                     
 @filter      indicates which properties are being used in filtering.
@@ -3248,8 +3260,8 @@ The category search code above would expand to the following::
       </select>
     </td>
     <td><input type="checkbox" name=":columns" value="category"></td>
-    <td><input type="radio" name=":sort" value="category"></td>
-    <td><input type="radio" name=":group" value="category"></td>
+    <td><input type="radio" name=":sort0" value="category"></td>
+    <td><input type="radio" name=":group0" value="category"></td>
   </tr>
 
 Adding category to the default view

doc/design.txt

@@ -1251,7 +1251,7 @@ clarity)::
 
     /issue?status=unread,in-progress,resolved&
         topic=security,ui&
-        :group=priority&
+        :group=priority,-status&
         :sort=-activity&
         :filters=status,topic&
         :columns=title,status,fixer
@@ -1275,11 +1275,11 @@ of issues with values matching any specified Multilink properties.
 The example specifies an index of "issue" items. Only issues with a
 "status" of either "unread" or "in-progres" or "resolved" are displayed,
 and only issues with "topic" values including both "security" and "ui"
-are displayed.  The issues are grouped by priority, arranged in
-ascending order; and within groups, sorted by activity, arranged in
-descending order.  The filter section shows filters for the "status" and
-"topic" properties, and the table includes columns for the "title",
-"status", and "fixer" properties.
+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 table includes
+columns for the "title", "status", and "fixer" properties.
 
 Associated with each issue class is a default layout specifier.  The
 layout specifier in the above example is the default layout to be

doc/upgrading.txt

@@ -13,6 +13,37 @@ steps.
 
 .. contents::
 
+Migrating from 1.1.2 to 1.X.X
+=============================
+
+1.X.X Sorting and grouping by multiple properties
+-------------------------------------------------
+
+Starting with this version, sorting and grouping by multiple properties
+is possible. This means that request.sort and request.group are now
+lists. This is reflected in several places:
+
+ * ``renderWith`` now has list attributes for ``sort`` and ``group``,
+   where you previously wrote::
+   
+    renderWith(... sort=('-', 'activity'), group=('+', 'priority')
+
+   you write now::
+
+    renderWith(... sort=[('-', 'activity')], group=[('+', 'priority')]
+
+ * In templates that permit to edit sorting/grouping, request.sort and
+   request.group are (possibly empty) lists. You can now sort and group
+   by multiple attributes. For an example, see the classic template. You
+   may want search for the variable ``n_sort`` which can be set to the
+   number of sort/group properties.
+
+ * Templates that diplay new headlines for each group of items with
+   equal group properties can now use the modified ``batch.propchanged``
+   method that can take several properties which are checked for
+   changes. See the example in the classic template which makes use of
+   ``batch.propchanged``.
+
 Migrating from 1.1.0 to 1.1.1
 =============================
 

doc/user_guide.txt

@@ -2,7 +2,7 @@
 User Guide
 ==========
 
-:Version: $Revision: 1.33 $
+:Version: $Revision: 1.34 $
 
 .. contents::
 
@@ -338,9 +338,11 @@ arguments:
 Argument     Description
 ============ =============================================================
 @sort        sort by prop name, optionally preceeded with '-' to give
-             descending or nothing for ascending sorting.
+             descending or nothing for ascending sorting. The sort
+             argument can have several props separated with comma.
 @group       group by prop name, optionally preceeded with '-' or to sort
-             in descending or nothing for ascending order.
+             in descending or nothing for ascending order. The group
+             argument can have several props separated with comma.
 @columns     selects the columns that should be displayed. Default is
              all.                     
 @filter      indicates which properties are being used in filtering.
@@ -356,7 +358,7 @@ You may manually write URLS that contain these arguments, like so
 
     /issue?status=unread,in-progress,resolved&
         topic=security,ui&
-        @group=priority&
+        @group=priority,-status&
         @sort=-activity&
         @filters=status,topic&
         @columns=title,status,fixer