merge trunk 115488-115818

CHANGES.txt

@@ -2,9 +2,23 @@
 CHANGES
 =======
 
-0.9.0 (unreleased)
+0.9.1 (unreleased)
 ------------------
 
+- Nothing changed yet.
+
+
+0.9.0 (2010-08-09)
+------------------
+
+- Added ``EMailColumn`` which can be used to display mailto links.
+
+- Fixed the default BatchProvider not to lose table sorting query arguments
+  from the generated links; now batching and sorting play with each other
+  nicely.
+
+- Split single doctest file (README.txt) into different files
+>>>>>>> .merge-right.r115818
 
 - ``IValues`` conform to ``len`` protocol. ``table.Table`` has new
   ``allRowsCount`` attribute that surfaces the total number of rows.

COPYRIGHT.txt

@@ -0,0 +1 @@
+Zope Foundation and Contributors

LICENSE.txt

@@ -1,54 +1,44 @@
 Zope Public License (ZPL) Version 2.1
--------------------------------------
 
-A copyright notice accompanies this license document that
-identifies the copyright holders.
+A copyright notice accompanies this license document that identifies the
+copyright holders.
 
-This license has been certified as open source. It has also
-been designated as GPL compatible by the Free Software
-Foundation (FSF).
+This license has been certified as open source. It has also been designated as
+GPL compatible by the Free Software Foundation (FSF).
 
-Redistribution and use in source and binary forms, with or
-without modification, are permitted provided that the
-following conditions are met:
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
 
-1. Redistributions in source code must retain the
-   accompanying copyright notice, this list of conditions,
-   and the following disclaimer.
+1. Redistributions in source code must retain the accompanying copyright
+notice, this list of conditions, and the following disclaimer.
 
-2. Redistributions in binary form must reproduce the accompanying
-   copyright notice, this list of conditions, and the
-   following disclaimer in the documentation and/or other
-   materials provided with the distribution.
+2. Redistributions in binary form must reproduce the accompanying copyright
+notice, this list of conditions, and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
 
-3. Names of the copyright holders must not be used to
-   endorse or promote products derived from this software
-   without prior written permission from the copyright
-   holders.
+3. Names of the copyright holders must not be used to endorse or promote
+products derived from this software without prior written permission from the
+copyright holders.
 
-4. The right to distribute this software or to use it for
-   any purpose does not give you the right to use
-   Servicemarks (sm) or Trademarks (tm) of the copyright
-   holders. Use of them is covered by separate agreement
-   with the copyright holders.
+4. The right to distribute this software or to use it for any purpose does not
+give you the right to use Servicemarks (sm) or Trademarks (tm) of the
+copyright
+holders. Use of them is covered by separate agreement with the copyright
+holders.
 
-5. If any files are modified, you must cause the modified
-   files to carry prominent notices stating that you changed
-   the files and the date of any change.
+5. If any files are modified, you must cause the modified files to carry
+prominent notices stating that you changed the files and the date of any
+change.
 
 Disclaimer
 
-  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS''
-  AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
-  NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
-  AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN
-  NO EVENT SHALL THE COPYRIGHT HOLDERS BE
-  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
-  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
-  OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
-  DAMAGE.
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS'' AND ANY EXPRESSED
+OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
+EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

bootstrap.py

@@ -1,6 +1,6 @@
 ##############################################################################
 #
-# Copyright (c) 2008 Zope Corporation and Contributors.
+# Copyright (c) 2008 Zope Foundation and Contributors.
 # All Rights Reserved.
 #
 # This software is subject to the provisions of the Zope Public License,

setup.py

@@ -23,7 +23,7 @@ def read(*rnames):
 
 setup(
     name='z3c.table',
-    version='0.8.2dev',
+    version='0.9.1dev',
     author = "Stephan Richter, Roger Ineichen and the Zope Community",
     author_email = "zope-dev@zope.org",
     description = "Modular table rendering implementation for Zope3",

src/z3c/table/README.txt

@@ -599,7 +599,7 @@ sorting header implementation:
   ...     provides=interfaces.IColumnHeader)
 
 Now we can render the table and we shall see a link in the header. Note that it
-is set to switch to descending as the the table initially will display the first
+is set to switch to descending as the table initially will display the first
 column as ascending:
 
   >>> myTable.update()

src/z3c/table/batch.py

@@ -16,6 +16,8 @@
 """
 __docformat__ = "reStructuredText"
 
+from urllib import urlencode
+
 import zope.interface
 import zope.i18nmessageid
 from zope.traversing.browser import absoluteURL
@@ -70,6 +72,8 @@ class BatchProvider(object):
     nextBatchSize = 3
     batchSpacer = u'...'
 
+    _request_args = ['%(prefix)s-sortOn', '%(prefix)s-sortOrder']
+
     def __init__(self, context, request, table):
         self.__parent__ = context
         self.context = context
@@ -78,9 +82,24 @@ def __init__(self, context, request, table):
         self.batch = table.rows
         self.batches = table.rows.batches
 
+    def getQueryStringArgs(self):
+        """Collect additional terms from the request to include in links.
+
+        API borrowed from z3c.table.header.ColumnHeader.
+        """
+        args = {}
+        for key in self._request_args:
+            key = key % dict(prefix=self.table.prefix)
+            value = self.request.get(key, None)
+            if value:
+                args.update({key: value})
+        return args
+
     def renderBatchLink(self, batch, cssClass=None):
-        query = '%s=%s&%s=%s' % (self.table.prefix + '-batchStart',
-            batch.start, self.table.prefix + '-batchSize', batch.size)
+        args = self.getQueryStringArgs()
+        args[self.table.prefix +'-batchStart'] = batch.start
+        args[self.table.prefix +'-batchSize'] = batch.size
+        query = urlencode(sorted(args.items()))
         tableURL = absoluteURL(self.table, self.request)
         idx = batch.index + 1
         css = ' class="%s"' % cssClass

src/z3c/table/batch.txt

@@ -257,8 +257,8 @@ we have ``4`` batched row data available:
   4
 
 We can set such a batch as row values, then this batch data are used for
-rendering. But take care, if we update the table, our rows get overriden
-and reset to the previous values. this means you can set any bath as rows
+rendering. But take care, if we update the table, our rows get overridden
+and reset to the previous values. this means you can set any batch as rows
 data and only render them. This is possible since the update method sorted all
 items and all batch contain ready-to-use data. This concept could be important
 if you need to cache batches etc. :
@@ -332,8 +332,8 @@ reset:
     </tbody>
   </table>
 
-This means you can probably update all batches, cache them and use them alter.
-but this is not usefull for normal usage in a page without an enhanced concept
+This means you can probably update all batches, cache them and use them after.
+But this is not useful for normal usage in a page without an enhanced concept
 which is not a part of this implementation. This also means, there must be
 another way to set the batch index. Yes there is, there are two other ways how
 we can set the batch position. We can set a batch position by setting the
@@ -383,13 +383,13 @@ the sorting concept:
   ...                                     'table-sortOn': 'table-number-1'})
   >>> requestBatchingTable = SimpleTable(container, batchingRequest)
 
-We also need to give the table a location and a name like we normaly setup
+We also need to give the table a location and a name like we normally set up
 in traversing:
 
   >>> requestBatchingTable.__parent__ = container
   >>> requestBatchingTable.__name__ = u'requestBatchingTable.html'
 
-Note; our table needs to start batching at smaller amount of items than we
+Note: our table needs to start batching at smaller amount of items than we
 have by default otherwise we don't get a batch:
 
   >>> requestBatchingTable.startBatchingAt = 5
@@ -462,10 +462,10 @@ We use our previous batching table and render the batch with the built-in
 
   >>> requestBatchingTable.update()
   >>> print requestBatchingTable.renderBatch()
-  <a href="...html?table-batchStart=0&table-batchSize=5" class="first">1</a>
-  <a href="...html?table-batchStart=5&table-batchSize=5">2</a>
-  <a href="...html?table-batchStart=11&table-batchSize=5" class="current">3</a>
-  <a href="...html?table-batchStart=15&table-batchSize=5" class="last">4</a>
+  <a href="...html?table-batchSize=5&table-batchStart=0&..." class="first">1</a>
+  <a href="...html?table-batchSize=5&table-batchStart=5&...">2</a>
+  <a href="...html?table-batchSize=5&table-batchStart=11&..." class="current">3</a>
+  <a href="...html?table-batchSize=5&table-batchStart=15&..." class="last">4</a>
 
 Now let's add more items so that we can test the skipped links in large
 batches:
@@ -527,17 +527,17 @@ And test the batch. Note the three dots between the links are rendered by the
 batch provider and are not a part of the doctest:
 
   >>> print requestBatchingTable.renderBatch()
-  <a href="...html?table-batchStart=0&table-batchSize=5" class="first">1</a>
+  <a href="...html?table-batchSize=5&table-batchStart=0&table-sortOn=table-number-1" class="first">1</a>
   ...
-  <a href="...html?table-batchStart=85&table-batchSize=5">18</a>
-  <a href="...html?table-batchStart=90&table-batchSize=5">19</a>
-  <a href="...html?table-batchStart=95&table-batchSize=5">20</a>
-  <a href="...html?table-batchStart=100&table-batchSize=5" class="current">21</a>
-  <a href="...html?table-batchStart=105&table-batchSize=5">22</a>
-  <a href="...html?table-batchStart=110&table-batchSize=5">23</a>
-  <a href="...html?table-batchStart=115&table-batchSize=5">24</a>
+  <a href="...html?table-batchSize=5&table-batchStart=85&table-sortOn=table-number-1">18</a>
+  <a href="...html?table-batchSize=5&table-batchStart=90&table-sortOn=table-number-1">19</a>
+  <a href="...html?table-batchSize=5&table-batchStart=95&table-sortOn=table-number-1">20</a>
+  <a href="...html?table-batchSize=5&table-batchStart=100&table-sortOn=table-number-1" class="current">21</a>
+  <a href="...html?table-batchSize=5&table-batchStart=105&table-sortOn=table-number-1">22</a>
+  <a href="...html?table-batchSize=5&table-batchStart=110&table-sortOn=table-number-1">23</a>
+  <a href="...html?table-batchSize=5&table-batchStart=115&table-sortOn=table-number-1">24</a>
   ...
-  <a href="...html?table-batchStart=1015&table-batchSize=5" class="last">204</a>
+  <a href="...html?table-batchSize=5&table-batchStart=1015&table-sortOn=table-number-1" class="last">204</a>
 
 You can change the spacer in the batch provider if you set the ``batchSpacer``
 value:
@@ -567,17 +567,17 @@ As you can see the spacer get changed now:
   >>> requestBatchingTable.batchProvider
   <XBatchProvider object at ...>
   >>> print requestBatchingTable.renderBatch()
-  <a href="...html?table-batchStart=0&table-batchSize=5" class="first">1</a>
+  <a href="...html?table-batchSize=5&table-batchStart=0&table-sortOn=table-number-1" class="first">1</a>
   xxx
-  <a href="...html?table-batchStart=85&table-batchSize=5">18</a>
-  <a href="...html?table-batchStart=90&table-batchSize=5">19</a>
-  <a href="...html?table-batchStart=95&table-batchSize=5">20</a>
-  <a href="...html?table-batchStart=100&table-batchSize=5" class="current">21</a>
-  <a href="...html?table-batchStart=105&table-batchSize=5">22</a>
-  <a href="...html?table-batchStart=110&table-batchSize=5">23</a>
-  <a href="...html?table-batchStart=115&table-batchSize=5">24</a>
+  <a href="...html?table-batchSize=5&table-batchStart=85&table-sortOn=table-number-1">18</a>
+  <a href="...html?table-batchSize=5&table-batchStart=90&table-sortOn=table-number-1">19</a>
+  <a href="...html?table-batchSize=5&table-batchStart=95&table-sortOn=table-number-1">20</a>
+  <a href="...html?table-batchSize=5&table-batchStart=100&table-sortOn=table-number-1" class="current">21</a>
+  <a href="...html?table-batchSize=5&table-batchStart=105&table-sortOn=table-number-1">22</a>
+  <a href="...html?table-batchSize=5&table-batchStart=110&table-sortOn=table-number-1">23</a>
+  <a href="...html?table-batchSize=5&table-batchStart=115&table-sortOn=table-number-1">24</a>
   xxx
-  <a href="...html?table-batchStart=1015&table-batchSize=5" class="last">204</a>
+  <a href="...html?table-batchSize=5&table-batchStart=1015&table-sortOn=table-number-1" class="last">204</a>
 
 
 Now test the extremities, need to define a new batchingRequest:
@@ -591,14 +591,14 @@ Beginning by the left end point:
   >>> leftRequestBatchingTable.__name__ = u'leftRequestBatchingTable.html'
   >>> leftRequestBatchingTable.update()
   >>> print leftRequestBatchingTable.renderBatch()
-  <a href="http://...html?table-batchStart=0&table-batchSize=5" class="first">1</a>
-  <a href="http://...html?table-batchStart=5&table-batchSize=5">2</a>
-  <a href="http://...html?table-batchStart=10&table-batchSize=5" class="current">3</a>
-  <a href="http://...html?table-batchStart=15&table-batchSize=5">4</a>
-  <a href="http://...html?table-batchStart=20&table-batchSize=5">5</a>
-  <a href="http://...html?table-batchStart=25&table-batchSize=5">6</a>
+  <a href="http://...html?table-batchSize=5&table-batchStart=0&table-sortOn=table-number-1" class="first">1</a>
+  <a href="http://...html?table-batchSize=5&table-batchStart=5&table-sortOn=table-number-1">2</a>
+  <a href="http://...html?table-batchSize=5&table-batchStart=10&table-sortOn=table-number-1" class="current">3</a>
+  <a href="http://...html?table-batchSize=5&table-batchStart=15&table-sortOn=table-number-1">4</a>
+  <a href="http://...html?table-batchSize=5&table-batchStart=20&table-sortOn=table-number-1">5</a>
+  <a href="http://...html?table-batchSize=5&table-batchStart=25&table-sortOn=table-number-1">6</a>
   xxx
-  <a href="http://...html?table-batchStart=1015&table-batchSize=5" class="last">204</a>
+  <a href="http://...html?table-batchSize=5&table-batchStart=1015&table-sortOn=table-number-1" class="last">204</a>
 
 Go on with the right extremity:
 
@@ -610,14 +610,14 @@ Go on with the right extremity:
   >>> rightRequestBatchingTable.__name__ = u'rightRequestBatchingTable.html'
   >>> rightRequestBatchingTable.update()
   >>> print rightRequestBatchingTable.renderBatch()
-  <a href="http://...html?table-batchStart=0&table-batchSize=5" class="first">1</a>
+  <a href="http://...html?table-batchSize=5&table-batchStart=0&table-sortOn=table-number-1" class="first">1</a>
   xxx
-  <a href="http://...html?table-batchStart=990&table-batchSize=5">199</a>
-  <a href="http://...html?table-batchStart=995&table-batchSize=5">200</a>
-  <a href="http://...html?table-batchStart=1000&table-batchSize=5">201</a>
-  <a href="http://...html?table-batchStart=1005&table-batchSize=5" class="current">202</a>
-  <a href="http://...html?table-batchStart=1010&table-batchSize=5">203</a>
-  <a href="http://...html?table-batchStart=1015&table-batchSize=5" class="last">204</a>
+  <a href="http://...html?table-batchSize=5&table-batchStart=990&table-sortOn=table-number-1">199</a>
+  <a href="http://...html?table-batchSize=5&table-batchStart=995&table-sortOn=table-number-1">200</a>
+  <a href="http://...html?table-batchSize=5&table-batchStart=1000&table-sortOn=table-number-1">201</a>
+  <a href="http://...html?table-batchSize=5&table-batchStart=1005&table-sortOn=table-number-1" class="current">202</a>
+  <a href="http://...html?table-batchSize=5&table-batchStart=1010&table-sortOn=table-number-1">203</a>
+  <a href="http://...html?table-batchSize=5&table-batchStart=1015&table-sortOn=table-number-1" class="last">204</a>
 
 
 None previous and next batch size. Probably it doesn't make sense but let's
@@ -642,8 +642,9 @@ Update the table and render the batch:
 
   >>> requestBatchingTable.update()
   >>> print requestBatchingTable.renderBatch()
-  <a href="...html?table-batchStart=0&table-batchSize=5" class="first">1</a>
+  <a href="...html?table-batchSize=5&table-batchStart=0&table-sortOn=table-number-1" class="first">1</a>
   xxx
-  <a href="...html?table-batchStart=100&table-batchSize=5" class="current">21</a>
+  <a href="...html?table-batchSize=5&table-batchStart=100&table-sortOn=table-number-1" class="current">21</a>
   xxx
-  <a href="...html?table-batchStart=1015&table-batchSize=5" class="last">204</a>
+  <a href="...html?table-batchSize=5&table-batchStart=1015&table-sortOn=table-number-1" class="last">204</a>
+

src/z3c/table/column.py

@@ -355,6 +355,28 @@ def renderCell(self, item):
             self.getLinkContent(item))
 
 
+class EMailColumn(LinkColumn, GetAttrColumn):
+    "Column to display mailto links."
+
+    header = _(u'E-Mail')
+    attrName = None # attribute name which contains the mail address
+    defaultValue = u'' # value which is rendered when no value is found
+    linkContent = None
+
+    def getLinkURL(self, item):
+        return 'mailto:%s' % self.getValue(item)
+
+    def getLinkContent(self, item):
+        if self.linkContent:
+            return zope.i18n.translate(self.linkContent, context=self.request)
+        return self.getValue(item)
+
+    def renderCell(self, item):
+        value = self.getValue(item)
+        if value is self.defaultValue or value is None:
+            return self.defaultValue
+        return super(EMailColumn, self).renderCell(item)
+
 class SelectedItemColumn(LinkColumn):
     """Link which can set an item."""