Skip to main content

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

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

<tal:batchnavigation
    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 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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

plone.batching-1.0.3.zip (26.5 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page