[DEV] Lists v0.2.0 - Persistent Player Lists [803]

Discussion in 'Inactive/Unsupported Plugins' started by DThielke, Apr 18, 2011.

  1. Offline

    DThielke

    Lists Persistent Player Lists (v 0.1.0)
    Download Lists
    Source Code on GitHub

    What is Lists? Lists provides a convenient way for users to create lists of players that other plugins can and should take advantage of. Having multiple plugins use a central method of list storage, as this plugin provides, allows users to control the behavior of many plugins at a time.

    Tired of having to use commands from Towny, LWC and Regions every time a new citizen joins your town? Lists provides a simple solution: add the player to your town's list and voilĂ , the player is now an official citizen of your town, has access to your town's chests and can build in your town's regions. Lists doesn't stop here though; any plugin that controls groups of players can take advantage of this plugin.

    This is, at least, the goal of Lists. Getting to this point, however, will require participation and support of the developers of this community. Because of the inter-plugin nature of Lists, I will try to be very open to suggestions and pull requests submitted by you, the community. When making suggestions, however, keep in mind that the goal of this plugin is simple: to provide a central player list framework that all plugins can have access to. Feature requests should be less focused on "flair" and more concentrated on effectiveness and efficiency.

    Plugins using Lists:
    How does it work? Players in a list each have an associated privilege level, which defines what the player can do to the list. There are four privilege levels:
    1. NONE (n) - No privileges. If the list is restricted, such a user cannot see the list.
    2. VIEWER (v) - Basic viewing privileges, even if the list is restricted.
    3. MODIFIER (m) - The user can add, modify and remove players. Can promote others up to VIEWER.
    4. OWNER (o) - The user can delete the list. Can promote others up to OWNER.
    Each privilege level inherits from the one before it. When a player creates a new list, they default to OWNER and therefore have full control over the list. Every list is identified by a unique, case-sensitive name and is one of two types:
    1. RESTRICTED - Only members of the list with VIEWER or above can see the list and its members.
    2. UNRESTRICTED - Anyone can see the list and its members.
    How are lists stored? Lists are stored in either a SQLite or MySQL database (others might work too, but these are the only two I have tested and confirmed working). When you first run Lists, a config file will be created that holds your database information. By default, a SQLite database is created called plugins/Lists/lists.db.

    Default Configuration:
    Code:
    database:
        driver: 'org.sqlite.JDBC'
        URL: 'jdbc:sqlite:plugins/Lists/lists.db'
        user:
        password:
    
    If you would instead like to use a MySQL database, change the fields to match:
    Code:
    database:
        driver: 'com.mysql.jdbc.Driver'
        URL: 'jdbc:mysql://your_database_url:3306/database_name'
        user:
        password:
    
    Using the above configuration requires filling in your database URL, port and name, as well as a valid username and password.

    Important
    Before using lists, you must make sure that you have the appropriate JDBC driver defined in your configuration in the <server-root>/lib/ folder. The name of these drivers does not matter.

    You can find the two available drivers here:
    SQLite: http://www.zentus.com/sqlitejdbc/
    MySQL: http://dev.mysql.com/downloads/connector/j/

    Commands
    Code:
    -----[ HeroList Help <1/1> ]-----
      /ls list [page#]
      /ls view <list>
      /ls put <list> <player> -[n|v|m|o]
      /ls add <list> [player1] [player2] ... [playerN]
      /ls rem(ove) <list> <player>
      /ls create <list> [-r]
      /ls del(ete) <list>
      /ls help [page#]
    For more info on a particular command, type '/<command> ?'
    
    Permissions
    If Permissions is detected, all of Lists' commands will be restricted to users with the appropriate permissions.
    Code:
    Command             Permission
    -------------------------------------
    /ls list            lists.user.list
    /ls create          lists.user.create
    /ls delete          lists.user.delete
    /ls put             lists.user.put
    /ls view            lists.user.view
    /ls remove          lists.user.remove
    /ls add             lists.user.add
    
    In addition to these general user permissions, there are special admin permissions that allow a user to bypass any privilege level or membership checks.
    Code:
    Command             Permission                  Description
    ----------------------------------------------------------------------------
    /ls list            lists.admin.list            See all lists
    /ls delete          lists.admin.delete          Delete any list
    /ls put             lists.admin.put             Add/modify users in any list
    /ls view            lists.admin.view            View users in any list
    /ls add             lists.admin.add             Add users to any list
    

    For Developers

    Just as Lists strives to be a simple plugin, so does the API. I will outline the basics here, but if you have any questions, please don't hesitate to ask. Documentation is likely to improve as the plugin matures. I apologize if something is unclear.

    Connecting to Lists
    Code:
    public void loadListsPlugin() {
        Plugin plugin = this.getServer().getPluginManager().getPlugin("Lists");
            if (plugin != null) {
                if (plugin.isEnabled()) {
                    this.lists = (Lists) plugin;
                    System.out.println("Lists" + lists.getDescription().getVersion() + " found.");
                }
            }
    }
    
    There are two classes, Lists and PrivilegedList, and one enum, PrivilegeLevel, that you will use to interface with this plugin. The first class, Lists, contains methods for retrieving, saving and deleting existing lists. The second class, PrivilegedList, represents an actual list; it is essentially a wrapper for a mapping of player names to privilege levels (enumerated by PrivilegeLevel). Whenever you create a new list or modify an existing one, make sure to call lists.save(PrivilegedList list) to store the changes and make them accessible to both users and other plugins.

    Useful methods in Lists
    Code:
    public final PrivilegedList[] getLists()
    public PrivilegedList getList(String name)
    public void saveList(PrivilegedList list)
    public void deleteList(PrivilegedList list)
    
    Useful methods in PrivilegedList
    Code:
    public PrivilegedList(String name)
    public PrivilegedList(String name, boolean restricted)
    public boolean contains(String name)
    public void put(String name, PrivilegeLevel level
    public PrivilegeLevel get(String name)
    public Map<String, PrivilegeLevel> getUsers()
    public void setUsers(Map<String, PrivilegeLevel> users)
    public void remove(String name)
    public void setName(String name)
    public String getName()
    public void setRestricted(boolean restricted)
    public boolean isRestricted()
    
    If you have questions about any of these methods, there are two resources available to you:
    1. Javadocs
    2. Source code
    If neither of these sources answer your question, you can always contact me here or on IRC.

    Again, I would like to emphasize how important you developers are to this plugin. Your participation and support will make Lists a very useful tool for you, server admins, and general users.

    Feedback is always appreciated!

    Change Log
    Code:
    v 0.2.0 - List names are now case-insensitive while preserving the original case
    v 0.1.0 - Added getLists(String playerName) method
    v 0.0.1 - Initial public release.
    
     
  2. Offline

    oggedogge

    Very useful for Plugin Developers.
     
  3. Offline

    DThielke

    Hopefully others think so too!
     
  4. Offline

    Archelaus

    Gonna use this for my up and coming plugin ;D


    Thanks man, great API and extremely useful.
     
  5. Offline

    Kainzo

    We will continually update this and support it - Hidendra and Sk89q have stated they will support it for Regions / LWC. The more plugins that use the API will increase the awesome of having a Lists plugin.

    Note: this plugin ONLY creates/manages the lists. What you do with the lists is completely up to YOUR plugin and YOUR users.
     
  6. Offline

    aPunch

    This is just what I needed. Thanks a lot DThielke and whoever maintains it!
     
  7. Offline

    DThielke

    Happy to hear - promote it where you can! :)
     
  8. Offline

    Kainzo

    We need more devs to catch on and implement it in their plugins. This is the #1 solution to the problems with medium to larger servers having massive additions to protections / regions. Now you only need to create ONE list and use it for ALL other protections/regions!
     
  9. Offline

    netslug

    You rock man! Will probably most likely definitely use this in the future :D
     
  10. Offline

    Scorpia

    Thanks dude ! I'll use it in my plugin
     
  11. Offline

    DThielke

    To anyone who does decide to interface with Lists, please provide feedback! You're the pioneers of this plugin and I'm curious to know how development goes and what you're using it for.
     
  12. Offline

    Kainzo

    We want to get together a compiled list of what plugins are adopting - so if you are a plugin developer and you have added it - please reply with the plugin name so we can keep track (on this post)
     
  13. Offline

    DThielke

    Added a (hopefully soon to be populated) list of plugins that take advantage of this API.
     
  14. Offline

    contex

    Seems useful, will try to add it for the next versions of my plugins :)
     
  15. Offline

    Kainzo

    I would like to point out that this shouldn't have any issues - however if you find a flaw in design or a bug - please report it so we can patch it up as soon as possible.
     
  16. Offline

    DThielke

    Would anyone appreciate some actual usage examples, or are the existing docs enough?
     
  17. Offline

    Kainzo

    LWC will be adopting this soon - a test is in the works now. I believe the command will be; /cprivate list:name or /cprivate l:listnames
     
  18. Offline

    Hidendra

    Yes :)

    The development version of LWC is compatible with Lists right now.
     
  19. Offline

    DThielke

    This should provide an excellent example of how Lists can be useful :) - thanks for the support.
     
  20. Offline

    Kainzo

    Works on rb733
     
  21. Offline

    jblaske

    I'll gladly implement this in EpicZones. All I request is a method to get a list of lists a given player belongs to.
     
  22. Offline

    DThielke

    I'll add it ASAP.
     
    jblaske likes this.
  23. Offline

    Kainzo

    That's a good feature request.
     
  24. Offline

    DThielke

    Done. Sorry for the delay - finals suck.

    Code:
    /***
     * Returns an array of all lists containing the provided player name.
     *
     * @param playerName
     *            the name of a player
     * @return an array containing all <code>PrivilegedList</code>s the player is a member of
     */
    public final PrivilegedList[] getLists(String playerName)
    Change log
    v 0.1.0 - Added getLists(String playerName) method
     
  25. Offline

    jblaske

    No problem man, thanks a ton!
     
  26. Offline

    Kainzo

    Still trying to get Region/WorldGuard on board.
     
  27. Offline

    Sevenos

    Not sure if this goes too far, but it would be cool to store and get the date/time where players were added to a list or a list was created. Its probably an information alot of plugins could need.
     
  28. Offline

    DThielke

    Interesting idea - I'll add it soon.
     
  29. Offline

    Sevenos

    Just finished WG support for Lists - now my pull request just has to get accepted.
     
    DThielke likes this.
  30. Offline

    Kainzo

    Awesome :) I informed WG team about it.
     

Share This Page