Metadata-Version: 1.1
Name: plone.batching
Version: 1.0.3
Summary: Batching facilities used in Plone.
Home-page: http://pypi.python.org/pypi/plone.batching
Author: Plone Foundation
Author-email: plone-developers@lists.sourceforge.net
License: GPL
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
        
        Navigation
        ----------
        
        Because the batch implementation is geared towards templates it also provides a
        few navigation related methods.
        
        The first thing we can check is whether our batch spans over multiple pages.
        
          >>> batch = Batch.fromPagenumber(
          ...          items=range(333), pagesize=10, navlistsize=5)
          >>> batch.multiple_pages
          True
        
          >>> other_batch = Batch.fromPagenumber(
          ...          items=range(3))
          >>> other_batch.multiple_pages
          False
        
        It will also do simple math for giving the next and previous page numbers.
        
          >>> batch.nextpage
          2
        
          >>> batch.pagenumber = 5
          >>> batch.previouspage
          4
        
        We can also ask if there are any next or previous pages.
        
          >>> batch.has_next
          True
        
          >>> batch.pagenumber = batch.lastpage
          >>> batch.has_next
          False
        
          >>> batch.has_previous
          True
        
          >>> batch.pagenumber = 1
          >>> batch.has_previous
          False
        
        You might want to display the next item count. This can be usefull in case the
        batch is not exactly divisible by the pagesize.
        
          >>> batch.pagenumber = batch.lastpage - 1
          >>> batch.next_item_count
          3
        
        The system maintains a navigation list as well. This is normally used to
        display numbers at the bottom of the screen for quick access to those pages.
        
          >>> batch.pagenumber = 1
          >>> batch.navlist
          [1, 2, 3, 4, 5]
        
        Keep in mind that the navlist centers around the current page when it can.
        
          >>> batch.pagenumber = 10
          >>> batch.navlist
          [8, 9, 10, 11, 12]
        
        You can specify the navlist size to be any size you want.
        
          >>> other_batch = Batch.fromPagenumber(items=range(333), pagesize=10, pagenumber=10,
          ...                     navlistsize=12)
          >>> other_batch.navlist
          [4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]
        
        We have already seen the `lastpage` property. There is also the equivalent
        `firstpage` property.
        
          >>> batch.firstpage
          1
        
        Normally you would want to provide your users with a quick way to jump the the
        first or last page from anywhere in the batch. To make sure you will not show
        the links twice (once in the navlist and once for quick access) you can use the
        special helpers.
        
          >>> batch.pagenumber = 1
          >>> batch.show_link_to_first
          False
        
          >>> batch.pagenumber = 15
          >>> batch.show_link_to_first
          True
        
          >>> batch.pagenumber = 1
          >>> batch.show_link_to_last
          True
        
          >>> batch.pagenumber = batch.lastpage
          >>> batch.show_link_to_last
          False
        
        For extra visual smoothness you might also want to display an elipses next to
        your quicklink to the first page.
        
          >>> batch.pagenumber = 15
          >>> batch.second_page_not_in_navlist
          True
        
        This should only be done in case the second page is not in the navigation list.
        
          >>> batch.pagenumber = 4
          >>> batch.navlist
          [2, 3, 4, 5, 6]
          >>> batch.second_page_not_in_navlist
          False
        
        The same goes for the showing an elipses before the last link.
        
          >>> batch.pagenumber = 15
          >>> batch.before_last_page_not_in_navlist
          True
        
          >>> batch.pagenumber = batch.lastpage - 2
          >>> batch.before_last_page_not_in_navlist
          False
        
        To make displaying the links to next and previous pages even easier you can
        also get two seperate navlist for both of them.
        
          >>> batch.pagenumber = 1
          >>> batch.next_pages
          [2, 3, 4, 5]
        
          >>> batch.pagenumber = batch.lastpage - 2
          >>> batch.next_pages
          [33, 34]
        
        
          >>> batch.pagenumber = batch.lastpage
          >>> batch.previous_pages
          [32, 33]
        
          >>> batch.pagenumber = batch.firstpage + 1
          >>> batch.previous_pages
          [1]
        
        A batch defined in plone.batching usually consists of two things:
        
         1. A batch object. This is usually a wrapper for a sequence, which
            provides slices of information
         #. A batch view. This is needed for display. It contains links to
            navigate to the slices defined in 1.
        
        Both elements can be defined and accessed in Python code AND pagetemplates.
        
        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
        
        
Keywords: Plone
Platform: UNKNOWN
Classifier: Framework :: Plone :: 4.3
Classifier: Framework :: Zope2
Classifier: Programming Language :: Python :: 2.6
