Paginated Lists - A library for plugin developers!

Plugins Resources
1

How it all started
So I released a concept video for better list pagination. The idea was to make a better user experience when dealing with /list commands. The response was better than I expected, and I want to thank everyone along the way!

Make it re-usable
I’ve cleaned up the code considerably, and made it easy to use wherever a list should be shown to a player. I also took some extra time to make sure other plugin developers can customize it to their liking, without the need to hack the library.

How to use - Basics

First, create a list of Text objects:

List<Text> items = new ArrayList<Text>();
items.add(Texts.of(TextColors.GOLD, "I am an item"));
items.add(Texts.of(TextColors.GOLD, "I am another item"));
items.add(Texts.of(TextColors.GOLD, "I am a third item"));

You get the picture.
Now you can create a new PaginatedList, and add your items:

PagnatedList pList = new PaginatedList("/listhomes");
pList.addAll(items);

Be sure to include the command that calls the list when making a new PaginatedList().
Now send that list to the player:

player.sendMessage(pList.getPage(1));

That’s it, now you list looks much better!

Customization

Better list items
Since the list items are Text objects, you can make them much cooler than just Strings with colors:

List<String> homes = storage.getHomeList(player);
PaginatedList pList = new PaginatedList("/listhomes");

for (String name: homes) {
     Text item = Texts.builder(name)
        .onClick(TextActions.runCommand("/home " + name))
        .onHover(TextActions.showText(Texts.of(TextColors.WHITE, "Teleport to ", TextColors.GOLD, name)))
        .color(TextColors.DARK_AQUA)
        .style(TextStyles.UNDERLINE)
        .build();

    pList.add(item);
}

Items per page
Change how many items show on each page:

pList.setItemsPerPage(10);

Headers and footers
Adding headers and footers is as easy as adding items:

TextBuilder header = Texts.builder();
header.append(Texts.of(TextColors.GREEN, "------------"));
header.append(Texts.of(TextColors.GREEN, " Showing homes page " + currentPage + " of " + paginatedList.getTotalPages() + " "));
header.append(Texts.of(TextColors.GREEN, "------------"));

pList.setHeader(header.build());

Do the same thing for footers, just send your PaginatedList a Text object:

pList.setFooter(Texts.of("Additional information below the pagination links."));

Line numbers
Change line number color:

pList.setLineNumberColor(TextColors.BLUE);

Change line number appearance

// 01 - List Item
pList.setLineNumberType(PaginatedListUtil.LINE_NUMBER_TYPE_DASH);

// 01) List Item
pList.setLineNumberType(PaginatedListUtil.LINE_NUMBER_TYPE_PARENTHESIS);

// 01. List Item
pList.setLineNumberType(PaginatedListUtil.LINE_NUMBER_TYPE_PERIOD);

Don’t show line numbers:

pList.displayLineNumbers(false);

Pagination Links
Change the pagination style:

// --------- links ----------
pList.setPaginationType(PaginatedListUtil.PAGINATION_TYPE_DASH);

// _________ links ________
pList.setPaginationType(PaginatedListUtil.PAGINATION_TYPE_UNDERSCORE);

// ~~~~~~~~~ links ~~~~~~~~~
pList.setPaginationType(PaginatedListUtil.PAGINATION_TYPE_TILDA);

// *********** links ************
pList.setPaginationType(PaginatedListUtil.PAGINATION_TYPE_STAR);

// ########## links ##########
pList.setPaginationType(PaginatedListUtil.PAGINATION_TYPE_HASH);

// ========== links ==========
pList.setPaginationType(PaginatedListUtil.PAGINATION_TYPE_DOUBLELINE);

// +++++++++++ links +++++++++++
pList.setPaginationType(PaginatedListUtil.PAGINATION_TYPE_PLUS);

//             links
pList.setPaginationType(PaginatedListUtil.PAGINATION_TYPE_NONE);

Change pagination colors:

pList.setClickableLinkColor(TextColors.AQUA);
pList.setNonClickableLinkColor(TextColors.DARK_GREY);
pList.setPageNumberColor(TextColors.GOLD);
pList.setPaginationColor(TextColors.GREEN);

The Code

I just want the code:
Just copy the PaginatedList Class and the PaginatedListUtil Class into your project.

I want to look at another example:
See an example of implementation.

Try it out
If you have a development server and want to try it in Minecraft, you can find that here.

Comments / Suggestions

I would love to hear what you think about it. Leave a comment or suggestion below! Also, if you end up using this library, let me know, and I will link it in this post!

Thanks,
mmonkey

13 Likes
2

I like the navigation through the pages very much! I hope a lot of plugins include this because it would be so comfortable to only click through the pages! Thank you for sharing this with us. When we keep on not being selfish and sharing our cool things and make them available for every Sponge developer, Sponge plugins will be the best for Minecraft servers. :+1:

4 Likes
3

This is awesome! Will Definetely use this next time I get the chance!

4

@mmonkey
You might consider adapting your library a little bit (possibly turning it into a service) and making a PR to bring it into the SpongeAPI. There is an open issue here concerning a possible Pagination API.

6 Likes
5

Varargs text adding would be nice too. Is there a particular reason to use an ArrayList and wrap it with PaginatedList later? I’d like to get rid of the ArrayList instantiation completely and add it directly to the PaginatedList.

6

@amparch1980s there’s no reason you couldn’t just add list items directly to the PaginatedList. I should probably update the example.

What where you thinking for Varargs text adding? <- adding arguments instead of a command string?

7

For example, instead of doing this:

items.add(Texts.of(TextColors.GOLD, "I am an item"));
items.add(Texts.of(TextColors.GOLD, "I am another item"));
items.add(Texts.of(TextColors.GOLD, "I am a third item"));

You could add it like this:

items.addAll(Texts.of(TextColors.GOLD, "I am an item"), 
             Texts.of(TextColors.GOLD, "I am another item"), 
             Texts.of(TextColors.GOLD, "I am a third item"));
8

Yeah that is possible already. :slight_smile: I really need to make better documentation. :stuck_out_tongue:

1 Like
9

Ah that’s great! Looks pulls on sunglasses… swag.

2 Likes
10

What a fantastic library! Thank you so much.

2 Likes
11

Moderator, please move this to resources.

12

Pure Genius! Thanks for creating this! It made it so much easier to implement lists in my plugin!

2 Likes
13

Looks like this will be my go to list pagination for sponge. :smile:

2 Likes
14

This is awesome, thank you! @mmonkey

1 Like
15

Afaik this library is obsolete. Mmonkey implemented this directly in sponge :smile:

1 Like
16

Docs or it didn’t happen! xD

17

@Tzk I can’t take credit for implementing this into the API. But yes there is an official pagination API now.

2 Likes
18

https://docs.spongepowered.org/en/plugin/basics/text/pagination.html

3 Likes
19

I misunderstood something then.
I thought you were the one implementing this into sponge :frowning:

Nevertheless your Plugin and your library are both by far more than awesome!

1 Like