skip to navigation
skip to content

plone.batching 1.0.5

Batching facilities used in Plone.

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.


1.0.5 (2015-07-18)

  • Make sure pagenumber value is not bigger that numpages or it fails in previous_pages when using orphan [gbastien]
  • Allow orphan size to be equal to batch size. This allows the edge case of batch size 0 with default orphan size 0. [do3cc]

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.[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 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)

The other is more convenient for use with template.

>>> batch.sequence_length

It is also possible to ask for the items on the current page.

>>> batch.items_on_page

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

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

Batch navigation in templates

For the use of batching features in Page Templates plone.batching the first thing you have to do is to create a sequence batch and put it in a template variable named batch. You should do this in a view class if possible

<div tal:define="batch view/batchresults;">

or you can do it in the template itself if necessary

<div tal:define="Batch python:modules['plone.batching'].Batch;
                 b_size python:30;b_start python:0;b_start request/b_start | b_start;
                 batch python:Batch(results, b_size, int(b_start), orphan=1);">

For the navigation you add the following snippet to your template

    define="batchnavigation nocall:context/@@batchnavigation"
    replace="structure python:batchnavigation(batch)" />

For backwards compatibility plone.batching provides a drop in metal macro navigation in the batch_macros template. Add it to the template like this:

<div metal:use-macro="context/batch_macros/macros/navigation" />

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

>>> 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" />


XXX __len__ method

File Type Py Version Uploaded on Size
plone.batching-1.0.5.tar.gz (md5) Source 2015-07-16 15KB
  • Downloads (All Versions):
  • 106 downloads in the last day
  • 717 downloads in the last week
  • 2875 downloads in the last month