Review main Merged

62239[FEATURE] Introduce native pagination for lists

Alexander Schnitzler CR +2 V +2 Expert +1008 −0 updated 11/23/19, 13:39

Commit message

This patch introduces native support for pagination of
lists such as arrays or QueryResults of Extbase. The
main part of this feature is a new PaginatorInterface
that defines a basic set of methods a paginator needs
to implement.

To enable a quick creation of new paginators, an
AbstractPaginator class has been created which holds
the main pagination logic while the concrete paginator
only needs to take care of the concrete data type
handling.

The PaginatorInterface and the AbstractPaginator allow
the creation of futher paginators like one that supports
the doctrine/dbal query builder.

It's basically possible to create paginators for all
sets of items that are countable and which can be
transformed into an iterable sub set of given items.

The PaginationInterface will also be the foundation
for a new type agnostic pagination ViewHelper.

Review

  • Code review CR +2 Done
    • Daniel Goerz +2
    • Björn Jacob +1
    • Mathias Brodala +1
    • Susi Moog +1
  • Verified V +2 Done
    • Daniel Goerz +2
    • Björn Jacob +1
    • Mathias Brodala +1
    • Susi Moog +1
    • TYPO3com +1 CI

Issues 1

Files 10

Review log 3849

Show 1824 earlier messages
  1. Alexander Schnitzler uploaded patch set 1 11/07/19, 09:32

  2. TYPO3com voted on patch set 1 V +1 11/07/19, 09:41 Completed build in 09m 42s on Thu, 7 Nov, 09:41 AM Test Summary: 48196 passed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-38068

  3. Alexander Schnitzler uploaded patch set 2 11/07/19, 12:14

  4. TYPO3com voted on patch set 2 V +1 11/07/19, 12:24 Completed build in 09m 31s on Thu, 7 Nov, 12:24 PM Test Summary: 48196 passed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-38073

  5. Alexander Schnitzler commented on patch set 2 11/07/19, 12:27

    This change is ready for review.
  6. Sybille Peters commented on patch set 2 11/08/19, 14:33

    AbstractPaginator.php:57

    The descriptions for getAmountOfItems and getAmountOfPaginatedItems are a little redundant. They don't give information beyond the method name.

    AbstractPaginator.php:65

    By only looking at the description, it is not clear to me what getAmountOfPaginatedItems() is. "Number of items on current page" would be more intuitive to me.

    AbstractPaginator.php:123

    I don't understand why the object needs to get cloned. Why not change $this. I am assuming you only have one view open at a time, so it should not be necessary to clone.

    PaginatorInterface.php:69

    If I understood this correctly, the key and page number will start with 1 (and not 0). This is non-intuitive for me. (But, I understand that it makes sense to do it this way because that is what you would display as page number and item number). You might want to add this information to the method descriptions though.

    Feature-89603-IntroduceNativePaginationForLists.rst:33

    It might be helpful if you provide an example how to use the Paginator. It should be pretty intuitive to use, but a short code snippet won't hurt.
  7. Sybille Peters commented on patch set 2 11/08/19, 14:33

    AbstractPaginator.php:109

    I miss functions like next() { if (there is a next ....) { $this->withCurrentPageNumber($this->currentPageNumber+1); } } previous() { if (there is a prev) { $this->withCurrentPageNumber($this->currentPageNumber-1); } } first() last() hasNext() : bool
  8. Alexander Schnitzler commented on patch set 2 11/09/19, 09:32

    AbstractPaginator.php:57 Reply Unresolved

    You are right, I will remove the description(s).

    AbstractPaginator.php:65 Reply Unresolved

    Right, I will rename this method.

    AbstractPaginator.php:109 Reply Unresolved

    I think that you don't want what you proposed in your code example because the with-methods create new instances and update the internal state of the new objects. But those main properties that define the base of the pagination (number of items per page and current page) are those properties that you don't need to change to calculate next and previous page. In fact, changing those internal properties will alter the internal state in a way, that methods like next and previous would return different results. But I see what you mean here. I didn't add those methods because I first created a paginate view helper and when I split the patches that logic remained there. See https://review.typo3.org/c/Packages/TYPO3.CMS/+/62173/10/typo3/sysext/fluid/Classes/ViewHelpers/PaginateViewHelper.php#98. I understand that you would expect such methods but if we'd implement those here, we'd need to add them to the pagination interface because people should work with interfaces and not abstract classes. We have to decide if we want to add even more methods to the interface or if the interface just defines the very basic methods that enable a class to paginate items in contrast to displaying a pagination. To me that's two different functionalities and thus I would not extend the interface any further but maybe introduce a pagination helper instead that can use paginator instances and calculate the values needed for pagination navigations. Those can also be of a different complexity which makes it even harder. Example: One could decide to build a pagination where one does not have 100 page links but only a link to the first, previous, 2 pages around the current page, next and last. Or another example: Previous and next could be links the the last/first item. Usually we create paginations and disable the previous/next button if you reach the beginning/end. But one could also have some kind of corousel pagination where the previous link links to the last page when being on the first page. I don't want to restrict users here and rather come up with another interface for the pagination because to me paginator !== pagination.

    AbstractPaginator.php:123 Reply Unresolved

    This is done so you always have a paginator with a well defined state. There are two main properties that define the internal state, the current page number and the amount of items per page. Usually you define the amount of items per page once and then only update the current page number. In my first approach of this paginator, one could not update the amount of items per page after the object had been initialized. But then I realized that people need the chance to update the amount of items per page (for example in the viewhelper that will be introduced in the future). But still, the amount of items per page is fundamentally important for the internal logic that you don't want to mess around with that value. At least not when you built a pagination that relies on a sepcific state. So, I came up with the idea that each paginator has a fixed internal configuration state. And every time, you update a configuration value, you get a new instance whose methods are idempotent. Imagine what a chaos it would be if you create a paginator that updates it's internal state and people find a way to hook into processes and update the paginator. In the end you might get messed up results and have to search for the reason. Is it because the pagination logic itself is not working properly or because something changed the state and I didn't notice? You don't want that.

    PaginatorInterface.php:69 Reply Unresolved

    The interface does not define how you have to count. You can start with 0 or 1. The abstract paginator starts with 1 though at the moment. We can change this and let the pagination objects (which are yet to be invented) handle this then. It's the same with the keys of the paginated items. I am open to change the actual implementation. I think counting from 0 on is the more nerdy way to do it while counting from 1 is the more natural way to do it. What matters more in the end, is that your paginator is working correctly, no matter where you start counting.

    Feature-89603-IntroduceNativePaginationForLists.rst:33 Reply Unresolved

    Ack
  9. Alexander Schnitzler uploaded patch set 3 11/09/19, 10:49

  10. TYPO3com voted on patch set 3 V -1 11/09/19, 11:04 Completed build in 13m 47s on Sat, 9 Nov, 11:04 AM Test Summary: 4 of 48586 failed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-38153

  11. TYPO3com voted on patch set 3 V +1 11/09/19, 11:06 Completed build in 30m 07s on Sat, 9 Nov, 11:06 AM Test Summary: 48227 passed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-38153

  12. Alexander Schnitzler uploaded patch set 4 11/09/19, 11:50

  13. TYPO3com voted on patch set 4 V +1 11/09/19, 12:00 Completed build in 10m 19s on Sat, 9 Nov, 12:00 PM Test Summary: 48246 passed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-38158

  14. Alexander Schnitzler commented on patch set 4 11/18/19, 14:55

    ping
  15. Markus Klein commented on patch set 4 11/20/19, 14:08

    ArrayPaginator.php:65

    limit not used?
  16. Alexander Schnitzler commented on patch set 4 11/20/19, 18:51

    ArrayPaginator.php:65 Reply

    True, that's a bug. This method should use $limit instead of $this->itemsPerPage. I'll fix that.
  17. Markus Klein commented on patch set 4 11/20/19, 19:15

    ArrayPaginator.php:65 Reply

    So there is obviously no unit tests which covers whether limit is adhered. Maybe you can add one for this too. Thanks for your work.
  18. Alexander Schnitzler commented on patch set 4 11/20/19, 19:22

    ArrayPaginator.php:65 Reply Unresolved

    There is no test that checks if the exact argument is used but it's not necessary here as both $limit and $this->itemsPerPage hold the same value. Using $this->itemsPerPage here is a leftover from the refactoring. I am not into this patch right now but I guess $this->itemsPerPage should be private instead of protected and writable access should be implemented via setter. However, the abstract class is really not that important here. It should be flawless of course but the underlying interface is the actual api that matters.
  19. Alexander Schnitzler uploaded patch set 5 11/21/19, 07:32

  20. TYPO3com voted on patch set 5 V +1 11/21/19, 07:40 Completed build in 07m 25s on Thu, 21 Nov, 07:40 AM Test Summary: 48422 passed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-38512

  21. Mathias Brodala commented on patch set 5 11/22/19, 18:37

    AbstractPaginator.php:76

    Items per page should be normalized to be at least 1 IMO, it doesn't make sense otherwise.

    AbstractPaginator.php:86

    Since it is impossible to exceed PHP_INT_MAX anyways, wouldn't it be enough to have this: $this->numberOfPages = max(1, $this->numberOfPages); This way negative numbers and zero is forbidden, everything else is fine.

    AbstractPaginator.php:90

    Maybe rename to "currentPageHasItems"

    ArrayPaginator.php:48

    It would be great if we could provide an API in AbstractPaginator so that concrete paginators don't have to do this boilerplating anymore.

    PaginatorInterface.php:23

    Would it make sense to extend \Countable?

    PaginatorInterface.php:28

    This must be DEFAULT_ITEMS_PER_PAGE
  22. Benni Mack commented on patch set 5 11/22/19, 19:29

    how about we move it to "View" (namespace + folder) then?
  23. Alexander Schnitzler commented on patch set 5 11/23/19, 09:15

    > Patch Set 5: > > how about we move it to "View" (namespace + folder) then? What exactly is "it"? All the classes and interfaces?

    AbstractPaginator.php:76 Reply Unresolved

    I am fine with that. The concrete implementations we have right now make sure that itemsPerPage is > 0 already but we can also make this part of the api of this abstract class.

    AbstractPaginator.php:86 Reply Unresolved

    Ack

    AbstractPaginator.php:90 Reply Unresolved

    We can do so but we then loose the availability to get the exact number of items on the current page which can be useful to know. We could also implement both methods.

    ArrayPaginator.php:48 Reply

    Yes, what do you propose?

    PaginatorInterface.php:28 Reply

    I'm fine with that but I am still asking myself if this interface should define constants at all. Maybe it's a bad habit putting constants into interfaces because there is no reference between the minimum set of methods a paginator must implement and how paginators are configured. What do you think about moving those constants to the AbstractPaginator instead?
  24. Mathias Brodala commented on patch set 5 11/23/19, 09:22

    ArrayPaginator.php:48 Reply Unresolved

    Either separate "normalizeFoo()" or by providing default setters which perform these checks. Then the constructors could simply do this: $this->setItemsPerPage($itemsPerPage); $this->setCurrentPageNumber($currentPageNumber); If necessary, implementations could still overwrite these methods then for more custom logic.

    PaginatorInterface.php:23 Reply Unresolved

    What do you think?

    PaginatorInterface.php:28 Reply Unresolved

    True. It's not essential to have these defaults here and in fact the default limit highly depends on the implementation. So yes, if at all, this should be moved to the abstract class.
  1. Mathias Brodala commented on patch set 5 11/23/19, 09:33

    > Patch Set 5: > > how about we move it to "View" (namespace + folder) then? Hm, it's not really limited to a view. A pagination could also used completely internally without any output.
  2. Mathias Brodala uploaded patch set 6 11/23/19, 10:09

  3. TYPO3com voted on patch set 6 V -1 11/23/19, 10:10 Completed build in 25s on Sat, 23 Nov, 10:10 AM Test Summary: No tests found Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-38718

  4. Mathias Brodala uploaded patch set 7 11/23/19, 10:14

  5. TYPO3com voted on patch set 7 V -1 11/23/19, 10:19 Completed build in 04m 57s on Sat, 23 Nov, 10:19 AM Test Summary: 1449 of 42188 failed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-38720

  6. Mathias Brodala uploaded patch set 8 11/23/19, 10:21

  7. TYPO3com voted on patch set 8 V -1 11/23/19, 10:21 Completed build in 11s on Sat, 23 Nov, 10:21 AM Test Summary: No tests found Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-38721

  8. Mathias Brodala commented on patch set 8 11/23/19, 10:34

    AbstractPaginator.php:39 Unresolved

    Notice that these two are private now to enforce usage of the setters below.
  9. Mathias Brodala uploaded patch set 9 11/23/19, 10:34

  10. Mathias Brodala uploaded patch set 10 11/23/19, 10:34

  11. TYPO3com commented on patch set 9 11/23/19, 10:34 Completed build in 17s on Sat, 23 Nov, 10:34 AM Test Summary: No tests found Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-38723

  12. Mathias Brodala voted on patch set 10 V +1 CR +1 11/23/19, 10:37

  13. TYPO3com voted on patch set 10 V +1 11/23/19, 10:43 Completed build in 08m 33s on Sat, 23 Nov, 10:43 AM Test Summary: 48173 passed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-38724

  14. Björn Jacob voted on patch set 10 CR +1 11/23/19, 10:59

  15. Alexander Schnitzler commented on patch set 10 11/23/19, 11:11

    Thanks for taking care but please refrain from changing the order of methods while changing logic next time. It's really hard to review the diff between patch set 5 and everything beyond.
  16. Mathias Brodala commented on patch set 10 11/23/19, 11:17

    > Patch Set 10: > > Thanks for taking care but please refrain from changing the order of methods while changing logic next time. It's really hard to review the diff between patch set 5 and everything beyond. Yes sorry, I didn't think of this.
  17. Björn Jacob voted on patch set 10 V +1 11/23/19, 11:18

  18. Susi Moog voted on patch set 10 V +1 CR +1 11/23/19, 11:53

  19. Daniel Goerz voted on patch set 10 V +2 CR +2 11/23/19, 11:53

  20. Daniel Goerz merged patch set 11 11/23/19, 11:53

  21. Oliver Hader commented on patch set 11 11/23/19, 12:16

    Maybe it's just me, but "Pagination" and "Paginator" have great potential to be mixed... not sure what it should be... Provider, Processor, ...

    ArrayPaginator.php:19

    * Why `final`?
  22. Oliver Hader commented on patch set 11 11/23/19, 12:18

    Post -1

    SimplePagination.php:24

    Does not make sense - should be `private` then...
  23. Alexander Schnitzler commented on patch set 11 11/23/19, 12:53

    > Patch Set 11: > > (1 comment) > > Maybe it's just me, but "Pagination" and "Paginator" have great potential to be mixed... not sure what it should be... Provider, Processor, ... I am open for changes. We can still change the implementation. I tried my best to document the difference between a paginator and a pagination. btw: I often confuse DataHandler (core) and DataMapper (extbase) but because I know what those objects do, I can solve this in my head in a matter of milliseconds. So, what I want to say is things: - Naming is often confusing when you don't (yet) know exactly what something does. - Maybe the naming is quite alright once you know what the interfaces do. I found the names to be logical when I implemented them because I had a clear idea about what their intention was. The Paginator splits lists into chunks (pages). The Pagination prepares the visualisation of the UI element "pagination". - If there is a better naming, be my guest.
  24. Alexander Schnitzler commented on patch set 11 11/23/19, 13:23

    ArrayPaginator.php:33

    I forgot to adjust the order of arguments here. It makes more sense to have the current page number before the amount of items per page because the current page number needs to be overridden more often than the items per page.
  25. Mathias Brodala commented on patch set 11 11/23/19, 13:39

    ArrayPaginator.php:19 Reply Unresolved

    From my POV all new classes should be final: https://matthiasnoback.nl/2018/09/final-classes-by-default-why/

    ArrayPaginator.php:33 Reply

    Ack

    SimplePagination.php:24 Reply Unresolved

    Not necessary since the class is "final" already.