Add Text Paginator API

[zml2008]

API for formatted pagination of chat text
This allows long messages to be sent in a broken-up, user-friendly manner

Potential usage example:

API-side

public void sendPaginated(CommandSource source, Text... lines) {
    PaginationService service = game.getServicesManager().provideUnchecked(PaginationService.class);
    service.send(source, msgs);
}

User-side:

line 1
line2
line3
Previous Page        Next Page

Where previous and next page are clickable (for non-click supporting clients, commands will exist)
Commands:

• /paginator next and /paginator prev will send next or previous pages of a player's current pagination
• /paginator <uuid> next and /paginator <uuid> prev will send next or previous pages of a given paginaton -- this will mostly be used by quoted text

These commands will have no assigned permission because they only have meaning when triggered by other plugins, which are expected to do and appropriate permissions checking for data

[boformer]

I would name the command /page [int|next|prev]. Usually plugins will prefer their own paging commands (e.g. /mail read <page>).

Also, an optional header and footer Text would be nice.

There should be a send(CommandSource source, int page, Text... lines) method.

Edit:

Maybe it would be better to create an abstract CommandCallable implementation for it. This would allow the usage of /<plugincommand> <page> instead of /page. The class would have an abstract method List<Text> getPageContent(int page), int getPageCount() and maybe a method to get the header and footer of the page.

This also gives the the plugin the control how to handle caching. Some lists may have 10000 entries, so it would be a bad idea to store all of them in memory.

[ryantheleach]

Some lists may have 10000 entries.

Have an overload accepting an iterable or a stream?

[zml2008]

yeah, wouldn't be able to go back in pages with those though, but the best way to do it probably.

[TheE]

I have written a relative flexible paginator using fluent interfaces for my MyWarp project that could probably be used as a base for a Sponge version. It is basically a front-end for Guava's Lists.partition()method.

Usage is pretty straightforward:

// Iterable of objects to paginate
Iterable <Foo> foos = ...;

PaginatedResults <Foo> results = StringPaginator
    .of("Header text", foos)
        .withEntrysPerPage(8)
        .withNote("Note shown at the bottom of each page.")
        .withNote("Multiple notes can be registered.")
        .withMapping(new Function <Foo, String> () {
            @Override
            public String apply(Foo input) {
                //returns the string that is displayed for each entry
                return input.getName() + ", created by " + input.getCreator().getName();
            }
        })
    .paginate();

try {
    // get a page as list of entries...
    List <String> page = results.getPage(4);

    // ...or a page as one String,
    String pageString = results.getPageAsString(4);
} catch (NoResultsException e) {
    //thrown if the pagiantor is empty
} catch (UnknownPageException e) {
    //thrown if the page to display does not exist
}

// ...or directly send the page to somebody. Exception are handled internally in that case.
results.display(player, 4);

PaginatedResults can be reused to display several different pages. withEntrysPerPage(), withNote()and withMapping() are all optional.

Obviously, Text should be sued instead of Strings for Sponge but that is a relatively trivial change. Page changing can be implemented in top of PaginatedResults, similar to the display() method.

[Mumfrey]

This guy pretty much takes the cake on pagination systems.

@mmonkey wrote:
I set out to make /list commands better inside of sponge plugins, and this is what I have come up with so far: Video of pagination experiment

You are welcome to try it out download the Destinations plugin.
You may also steal the source code. (MIT License)
Or track the progress of development.

[FerusGrim]

I agree with @Mumfrey. He's also officially released a library for it. If we could somehow integrate this into Sponge, that would be pretty amazing.