Batching facilities used in Plone.
Project description
Welcome to Plone batching’s documentation!
This package includes facilities for creating a batched sequence.
It originated from the the PloneBatch module written for Plone which in itself has been based on Zope2’s ZTUtils.Batch.
Changelog
1.0.4 (2015-04-28)
Fix lastpage computation with orphaning [gbastien]
1.0.3 (2015-02-20)
Fix issue with orphaning [do3cc]
1.0.2 (2014-04-13)
Fix issue where a start >= end will always return last item. https://dev.plone.org/ticket/13880[thepjot]
Fix multiple_pages if the length of the sequence is exactly the page length. [gaudenz]
1.0.1 (2014-01-27)
Fix issue with sequences when the reported length was different than len() iteration would return the full unbatched sequence. [alecm]
1.0 (2013-05-23)
Use index instead of template attribute in BatchView to be able to customize only the template. [vincentfretin, thomasdesvenain]
Fixed wrong msgid for ‘First item’. [vincentfretin]
1.0b1 (2013-01-17)
Nothing changed yet.
1.0a1 (2012-04-25)
Factored out Plone batching implementation to seperate egg (PLIP #12235) [tom_gross]
Batching
Batching is the mechanism with which you split up a large dataset over multiple pages. The batching implementation discussed here has many features to help with constructing templates.
A basic batch is created using a few paramenters.
>>> from plone.batching.batch import Batch >>> batch = Batch.fromPagenumber( ... items=range(333), pagesize=10, pagenumber=1, navlistsize=5)
Items on page
The batch is iterable. It will only return the items for the current page.
>>> list(batch) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
If we change to a different page it will change the result set to that page.
>>> batch.pagenumber = 3 >>> list(batch) [20, 21, 22, 23, 24, 25, 26, 27, 28, 29]
Batch size
We can ask a batch for its size using two different methods. The first is to use the normal Python style.
>>> len(batch) 333
The other is more convenient for use with template.
>>> batch.sequence_length 333
It is also possible to ask for the items on the current page.
>>> batch.items_on_page 10
We can get the number of pages in a batch. This is actually the same as requesting the number of the last page.
>>> batch.lastpage 34
If we switch to this page the items_on_page attribute should be different (because our items are indivisible by ten).
>>> batch.pagenumber = batch.lastpage >>> batch.items_on_page 3
Usage in Python code
A batch is instantiated like this:
>>> from plone.batching import Batch >>> batch = Batch(range(100), size=15, orphan=10)
This generates 5 subbatches with 15 items from the sequence [0, 1, …, 99] and one subbatch with the last 25 items (including 10 orphaned items). For a detailed description of available parameters for a batch look at the API of the BaseBatch class.
Another way to instaniate a batch is like this:
>>> batch = Batch.fromPagenumber(range(100), pagesize=15, pagenumber=1)
This results in 6 batches with 15 items and one batch with the last 10 items. This way of creating a batch is meant as a short cut and does not support all the options the canonical constructor supports.
For big sequences there is another base class provided by the package: QuantumBatch. This batch generates quantum leaps for quicker navigation.
>>> from plone.batching.batch import QuantumBatch >>> qb = QuantumBatch(range(1000), 10, start=500, quantumleap=1) >>> qb.leapforward [69, 84] >>> qb.leapback [18, 33]
It is possible to navigate the batch stored in the two attributes leapback and leapforward with 5 clicks.
Usage in Views
Plone.batching comes with a customizable batch View batchnavigation with the view class BatchView. The view comes with a template. All you have to do, if you want to customize it, is to override the make_link-method. This method should return a string with the link to the given pagenumber. Here is an example from the folder_contents implementation in plone.app.content:
>>> from plone.batching.browser import BatchView >>> from ZTUtils import make_query >>> class MyBatchView(BatchView): ... def make_link(self, pagenumber): ... batchlinkparams = self.request.form.copy() ... return '%s?%s' % (self.request.ACTUAL_URL, ... make_query(batchlinkparams, {'pagenumber': pagenumber}))
One thing you have to keep in mind is to call the batch view with a batch as the first argument.
>>> class MyContentView(BrowserView): ... def batch(self): ... " " # see above how a batch is defined ... ... def batching(self): ... return MyBatchView(self.context, self.request)(self.batch)
Now you can use this in the template of your view.
<div tal:replace="structure view/batching" />
Incompatibilities
XXX __len__ method
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.