Plans for a D7 'League Management' Module

You are viewing a wiki page. You are welcome to join the group and then edit it. Be bold!

As I've had a lot of thoughts regarding potential improvements to my ULT module, I'm creating this page to start discussing/documenting information regarding an improved D7 'League Management' module.

To all 'League' Module Maintainers

In order to help address the 'Module Duplication' concern within the Drupal community, I'm proposing this as a collaborative effort between all of the maintainers of 'league-related' modules ... if we can come to a consensus on a common data model, then feature integration and interoperability between our various components will be much easier - think a 'common league API' for league module developers.

To that end, I'll be generating a few pages here over the next couple days, and invite your comments, suggestions, and feedback ...


I believe a combination of the ULT and LeagueSite feature sets is a great place to start, with enhancements to scheduling and tournament support thrown in as well. Ideally, given the number of 'fantasy' league queries I've received on ULT, a 'combined' league management module should be able to provide functionality to support both 'amateur' and 'fantasy' style leagues.

Data Model

I'd propose fully leveraging the new 'Entity' concept within Drupal to represent each of the components required in a league management module.

Object Entity Bundles Comments
Sport Sport Team Sport
Individual Sport
League League League
Conferences and Divisions would have a 'parent league' reference field
Season Season Season
Facilities Facility Site
Fields have a 'site' reference (support for 'multi-field' sites)
Team Team Team Container
Team Instance
Team 'Instance' represents team in a season
Roster Roster Roster
Roster 'Instance' represents roster in a season, 'Lineup' in a game
Player Player Player
"User" players have uid, Admin for non-players (such as coach)
Position Position Position Represents sport-specific 'positions' as well as admin (coach, etc)
Match Match Match
Exhibition Match (by sport)
May include 'parent' relationships for Game/Set/Match setups
Result Result Game/Set/Match Results types (by sport)
Summary Summary Game Scoring Summary (by sport)
Stats Player Stats Per sport Player Statistics bundles

Thus, the data model should be flexible enough to support:
- Multiple sports
- League/Conference/Division seperations (and inter-division/conference games if desired)
- Facilities tracking/assignment
- Maintaining 'Team' objects across seasons
- Flexible 'Roster' tracking, and per-game lineups
- both the 'players as users' model used in ULT, as well as the 'players as objects' model used in LeagueSite
- Tracking of team 'admin' in addition to players (and flexibility to support 'player-coaches')
- Per-sport 'positions'
- Both single game and game/set/match structures
- Tracking of both 'exhibition' and 'league' games/results
- Scoring summaries by sport
- Player Statistics by sport


I envision this as a central 'infrastructure' or 'API' module, with the actual league functionality being supported via additional supplementary modules (pick and choose only those which provide the functionality you require).

As such, I'd like to leverage the 'league_' prefix as the namespace for the central module ... with any supporting modules adopting the 'league__' prefix. As far as I can recall, I believe this namespace is still available and doesn't conflict with any existing modules already in contrib - if you find a module with a conflicting namespace, please let me know.

Integration with Other Modules

Where reasonable, the act of creating new players, leagues, teams, games, etc should be defined as actions; to allow for integration with the 'Rules' engine, and expose greater flexibility in how users may implement the project.

... more to come ...


Really glad to see this

spencerfromsc's picture

I'm glad to see you're looking at this from this perspective. One of the problems I've come up against is that I'm working with some teams that would still like to have their own website, so I'm running up against the need to set up the leagues centrally, but display the data (schedules, scores) on remote sites. I expect to require some form of node synchronization with Pubsubhubbub and Feeds to accomplish. Conversely, each team needs to manage their own player rosters and dues through their own site, so I am probably going to using CiviCRM to manage this, although I've been watching the Red Hen project with a lot of interest. I suppose the synchronization could work in reverse to consolidate player data from the remote sites into the hub if there was a need for it.

Anyway, I'll add some more comments as I have time.

What about Domain Access for "external sites?"

wrburgess's picture

@pomaking - Have you explored the use of the Domain Access module? It can support multiple sites using unique domains, but all on the same Drupal install. It's actually a bit different from a multi-site installment because there's only one install of Drupal...but it renders a unique menu, content, and users to each domain you add.

Randy Burgess
Chicago, IL

Domain Access

spencerfromsc's picture

I've spent some time working with Domain Access and it is an extraordinary tool for sharing content between sites, but I don't think it's the best option for me. First of all, I'm going to working in Aegir, which doesn't play nicely with table sharing. I've heard you can get it to work, but I tried it once and it got me highly irregular. Second, I'm a little put off by the large number of contributed modules required to install basic Drupal modules...content management is already complex enough when you start talking about a large number of sites. Finally, if you're not really talking about sharing that much content (sites are mostly autonomous), then the node synchronization just seems like a much cleaner solution.


Off-site Synchronizing ...

jthorson's picture

This is one of the advantages of using Drupal 7's 'entity' concept for the core data model, as opposed to nodes ... and while under-appreciated, it provides a major leap forward in flexibility, once I finally got my head around the concept.

The core module will define the entities, API calls, and default implementations ... so as an example, the API will define a 'Add Player to Roster' function call which adds a player to an existing roster. With the default 'Entity Controller' that would be shipped with the module, this would result in that player being added to the 'Roster' entry within the database.

However, this doesn't mean that the roster has to be stored in the site database ... adding support for a 3rd party site roster would simply be a case of overriding the default 'Entity Controller' class called by the 'Add to Roster' function, and having that controller feed the information to a different database. It could even be written to supply the data to an HTTP REST-ful web service call ... the introduction of the entity concept allows for complete separation of the 'application' logic from the 'storage' logic!

This is part of the reason that I'm looking for other league module maintainers to chip in here ... I'd like to take advantage of the new power introduced in Drupal 7, but I want to make sure we're doing it in such a way that we don't paint ourselves into a corner, where someone has to build their own competing module because we can't meet their use case.

Just a message to encourage

MasterChief's picture

Just a message to encourage you and thanks again for your work (^_^)

A word of encouragement

bbross's picture

This would be great and invaluable to me :) Thank you very much for your time and efforts and thans for what you give to the community.

I am currently too much of a noob with Drupal, but when I get a little accustomed to it, I'll certainly try and help you.

Keep on going ! :-D

Glad to see this proposed.

joshtheradiodude's picture

Glad to see this proposed. I'm potentially going to be in charge of a high school sports league's web site (I'll find out this week) and having a module to cover everything instead of having to enter it all manually would be nice. The contributed modules I've seen so far don't look promising. This, however, does.

I am developing the new

fenda's picture

I am developing the new Tournament module:

I think this will meet most requirements here and more.

It's encouraging to see

jthorson's picture

It's encouraging to see additional development happening in this space ...

... that said, what I'm proposing here is collaboration with other developers working on similar projects, so that we end up with one rock-solid solution for sports/tournaments/leagues/etc ... instead of multiple individual modules that don't necessarily work with each other. Having one solution would be preferable to (for example) having both Tournament and the existing 'Tournament Bracket' project competing for the same user space.

The aim of Tournament is to

fenda's picture

The aim of Tournament is to do just that. In fact, I am in talks with the Bracket module maintainer about merging it into Tournament.
I'd love to get more people collaborating with Tournament. The initial dev release should pop up on the project page at some point today. Install it and check it out, you might be surprised. It's taking full advantage of new D7 features with entities/fields/db API and simple to extend.

Forgive my speculation here,

jthorson's picture

Forgive my speculation here, but it does come across as if you're using this thread to pitch your own project, rather than to show interest in participating in a wider community initiative ...

I'm not trying to discount your project or efforts in developing it - I'm just somewhat curious about your choice to position Tournament as the solution to my proposal, without so much as a friendly email notification that you were working on a related project.

The whole point of this proposal is to coordinate our efforts and avoid duplication of effort on competing projects; and to work on defining a common foundation and data structures in order to maximize interoperability between D7 sports modules ... jumping in with a finished module doesn't really align with the strategy being proposed here, even if it shares some of the same end functions.

It's possible that I'm simply misinterpreting your posts (and I hope that's true), in which case I apologize ... if you happen to be attending DrupalCon in Denver next month, I will be hosting a BoF on this topic; and would love to have you (and any other sports-related module developers) join for the discussion.

I do apologize if I've given

fenda's picture

I do apologize if I've given a bad impression. I'll give you some background on the Tournament module! (Here comes a long post..)

I work in Japan for the leading video games tournament website:
We run our current site on Drupal 6 with a tonne of custom modules to provide a platform to play video games in tournaments online for prizes.
It's been somewhat of a success so far and we have 20,000 active users playing in our tournaments.

We are currently undergoing re-development of our site and upgrading to D7. We've learnt a lot from our first site as we had the opportunity to stress test tournaments under huge pressure.
As we are a non-profit organization, we don't have many resources. We looked around for any D7 modules we could use on our upgraded site but we didn't find anything remotely like what was required. (Bracket being the closest). In fact, we didn't even know this group existed until yesterday! We decided to go open source and give back to the d.o community.

The idea for our module is somewhat similar to yours. We wanted to build something that would allow anyone to host competition on their website.

I mean no offence at all but I'd like to give my thoughts on your project plans:

Too many entities
I know, entities are amazing. But in reality, I think you don't need entities for all of the features. For example, why can't a league be a node? Node is an entity that gives a great foundation for content. A league will have a title, a body and comments right?

Too fine-grained
The purpose of this module is to make a 'common league API' but the model doesn't seem to give enough freedom. For example, you are creating bundles for Team sports and Individual sports. But what if you want tournaments with Cities or Countries for example? I suppose in theory they could be Teams. Facilities don't even exist for some sports (especially online video games, right?). Do we really need 3 bundles for Rosters? And a separate entity for match results? That could just be a field in Match entities, no? What I am trying to say is that 'competition' cannot be defined. It can be anything from rock-scissor-paper to NFL.

I picked the module name Tournament based on it's definition on Wikipedia and some other sources. I felt it best represented structured competition content. During the development of Tournament we tried to be as open-minded as we could. However, I am sure there are still many areas we need to relax further.

The details for the tournament module can be found on its project page. But in short:

Tournament is a node type. - We wanted comments, title, body, status.
Match is a node type. - Same as tournament.
Participants in tournaments can be any entity. (e.g. user/node/taxonomy etc) - This allows for easy expansion
Team entity. - We felt this was an entity type many people would request. Teams are groups of user entities.
Statistics. - For now we keep only some basic statistics for participants. (tournaments played, matches played etc)
Tournament types. - Each tournament type is actually a node but uses 'base' => 'tournament' to expand. By default 3 types will be packaged together with Tournament (bracket/round_robin/ladder)

With those elements, a web developer can use the package as-is for simple tournaments or extend to meet their requirements with custom participant entities and/or tournament types.
All that's left is some more stress and bug testing, implementation of brackets/ladders and then we can release 7.x-1.0. After that comes the REST API!

Of course the main motivation for building the module was to use on our own website. But that is the case with a lot of contributed modules when they start. In no way am I trying to 'pitch' the module! That would make no sense. I did come across this group way too late but I think we can agree that it's better to not re-invent the wheel.

I don't want to stump your development or anything like that. I hope we can work together on pushing Drupal to be the best CMS for running competition on websites!

Different approaches

semidone2's picture

I'm not too sure about the idea of too many entities. . .

Granted some things aren't always necessary -- facilities don't exist for online games (perhaps server 1?) but there are plenty of things that DO.

I think that a tournament is only a small part of things...IMHO, it should be only a small part of the larger project. A common language that informs and works for tournaments but also works for regular season or works for management for players.

I like the fact that we are thinking BEYOND the needs of a singular need -- they are all related so having them speak the same language NATIVELY is important to rapid development and ease of implementation by those of us on THAT side of the biz.

Now we're talking!

jthorson's picture

Thanks, Joe. This is EXACTLY the type of discussion and critical analysis that I was hoping to spark within these threads, so thank you for your response ... and apologies if I came across as accusatory.

I wanted to respond to your comment about the model not providing enough freedom to module developers, as this was the number one issue I encountered with my first attempt at a League Management module (ULT). I initially built each of the object types directly into my module, which worked very well as long as you stayed within the functionality and capabilities of that module. Where it fell apart was when I would attempt to integrate it with functionality from other modules on the same site (for example, leveraging components of ULT and LeagueSite or ULT and Bracket within the same Drupal instance). Because each module had their own representation of a 'team', it became impossible to integrate them without tons of custom 'bridging' code and duplication of data across multiple tables in the database ... along with the underlying challenge of keeping it all synchronized.

My intent with this initiative is not to bundle the objects/entities into a single project; rather, I envision site builders picking and choosing from a number of different core sport/league objects based on the needs of their particular site. You are entirely correct that there is no reason to include a roster entity on a site dedicated to singles tennis, or a facility object for online/virtual events ... this illustrates the second issue with modules which internally define their own data types and structures (i.e. inherent inflexibility). The entities and bundles I propose will not be relevant to every site; but I'd like for site builders to be able to choose and implement only those which are relevant to their application ... and know that other related modules will be able to work with those same objects.

I also struggled with the "node or entity" question early in the planning stages for this initiative ... and in the end, choose to follow the lead set by the 'product' implementation within Drupal Commerce. In Drupal Commerce, each product is an individual entity ... but display of those products is done via a 'product reference' content type. This does introduce a bit more work on the implementation side, but keeps the underlying foundation flexible. (For example, not every site will need/want to expose a separate page/node for each match, but those that do can easily build those nodes out with an entity-reference node.)

You specifically mention match results, which was another area of learning I took from my experience with ULT ... initially I set this up as a field directly on the underlying match node. Where the problem arose is when two teams did not agree on the final score for a game (or submitted two different scores) ... in which case the solution became to store both results separately, and flag the discrepancy so that a league administrator could step in and adjudicate.

Now I'm not so ignorant as to suggest that developers of existing sports/league modules now need to go back and re-code their projects in order to align with whatever implementation comes out of this initiative ... but I would encourage them to participate and contribute to the discussion. From an integration perspective, consistently adding the ability to define via configuration what entity type/bundle/name represents a 'team' on a given site, rather than assuming a specific implementation, would be a big step forward compared to the situation we had in Drupal 6; and does not preclude developers from including their existing implementations in code as the 'default'. Granted, this is adding a layer of abstraction that isn't strictly required within the limited scope of any one project ... but considering that nodes and content types are entities in and of themselves, I don't think it is strictly incompatible with any pre-existing implementations either; and simplifying integration between our individual projects can only help to fuel the adoption of all.

I'm very happy to contribute

fenda's picture

I'm very happy to contribute to this group and I keep my fingers crossed we can all come to an agreement one day!

Entities are still a very new concept, and we'll be seeing big changes in their API again in D8. In theory everything can be an entity but we shouldn't go crazy with it.
For example, you have Player entities for users/admins etc. Could we not just use the core user entity and add a field to them if required?

I think I'm struggling to see the benefits behind the large amount of separation in your model. Perhaps you have some sandbox code which we can all go over at some point?

Also, could you put Tournament under Drupal 7 League Modules on the group page? (active/active)

Hehe ... take into account

jthorson's picture

Hehe ... take into account that you're viewing the result of some 'spitballing' ... there's no guarantee that the bundles I've suggested are the right ones. And in this case, they're probably misleading.

With regards to the Player entity, I envision a 'user-reference' player entity for situations where the players also must register with the site in order to participate (such as was the case with ULT). I also envision a need for non-user 'player' entities, for situations such as a fantasy league site, where the players may be actual pro atheletes, but certainly not end users of the site.

In the former case, the 'Player' entity could be a simple wrapper which returns the user object ... in the latter, we obviously need a new object to represent the athelete. The purpose in setting it up this way is so that another sport module (player statistics, as an example) doesn't need to know or care whether the atheletes and site users are the same ... it can simply request the 'player' object, and leave it up to the specific player bundle installed on that site to return the correct object. In most cases, you probably only need one type or the other, though I've already had a need on the site to mix players with user accounts and players without user accounts; and group them on the same rosters.

Unrelated to the above, I also saw a potential seperation between 'players' who are actually competing, and non-playing members of a team (coaches, trainers, etc) ... in other words, the 'admin' represents a team's 'non-players' (who may require different fields than an actual competitor); and thus bear no relation to the site 'administrator' role.

Users / Players / Families

igwebdev's picture

I am a noob to Drupal, but have a need for exactly this type of application. I started a design with functional specs and database structure when someone suggested I look into a content management system and I found all this. I'm excited and would greatly appreciate lending a hand where I can. Forgive if I'm off-base here, or describe some base function of Drupal as I'm not that familiar yet.

Our current website for our league management (youth baseball/softball) forces the players to be users in the system. This causes all kinds of headaches as the parents usually end up using the "players" account to register and don't have access to all the 'parent' functions. In my new design I want the players to be a non-user, an entity, and the "users" (i.e. parents) are also the team managers, volunteers, board members, etc...

Another concept from our current website I would like to see implemented is "Families". In that a family consists of at least one parent/guardian and a player. Adding parent/guardians to the "Family" would give them access to edit any of the player information and to register them. This is important as we have split/blended families where one year ParentA may pay for registration and ParentB the next. Players could exist in more than one family. Not sure how this might fit with what you've started.

Great feedback ... I'm

jthorson's picture

Great feedback ... I'm familiar with the 'user/non-user' concern, but the whole 'Family' angle is one I hadn't considered. Excellent suggestion!

I think the 'family' concept could be fairly easily modelled with the 'Relation' module ... the more I look into it as a possible piece of the puzzle, the more impressed I grow with the sheer flexibility of Relation module and how it can simplify the development process. (In fact, with Views, Relation, Commerce, and Rules ... there's not much you can't do on a Drupal site anymore!)


spencerfromsc's picture

A lot of the concepts you are talking about overlap with the core elements of a lightweight CRM system. I'm not sure if any of you are familiar with the Party project (, but it is a lightweight D7 CRM that already will handle a lot of these user and organizational components (user/non-user, Commerce integration, teams, families or households, etc.) almost right out of the box. I haven't tried to do it yet, but I think it's got a pretty solid API as long as new components are built as Entities.

I just wanted to throw this out there. This would provide an extremely flexible model for users and organizations, which would seem to overcome one of the more problematic limitations of these systems in the past. It would also provide a pretty aggressive base for development of the D7 system.

Nice discussion.

I see what you're trying to

fenda's picture

I see what you're trying to achieve.

In regards to your model, would it not be better to have a single Participant entity that encompasses all different possible participant types as bundles? player/user/admin/team/family etc
Do we really need to split up team/individual?

team/individual split

jthorson's picture

That's certainly an option ... though I see a team entity being significantly different than an individual participant from a field/structure perspective; and cases where a site may only care about loading up the 'team' and 'roster' entities; but not actually track 'matches'; at which point using a 'participant' entity becomes non-intuitive.

Where it could work is having matches contain 'participants', and the participant entity be a wrapper or reference to other potential entity types ... while I was originally thinking that the match entity would be able to support multiple potential entity types as endpoints ... I'll have to ponder this for a day or two.

To throw another curveball into the mix, I have also been toying with the idea of a match being a fielded 'Relation' entity ... i.e. "hometeam" hosts "awayteam". This model could fairly easily support any combination of 'entity' versus 'entity', even of different types ... though one would probably want to set some sort of constraints on which entity types would be allowed as relationship endpoints, so that we don't end up with matches pitching 'node/234' versus 'taxonomy term/142'. :D

Personally I think matches

fenda's picture

Personally I think matches should be nodes because I would want comments and node fields out of the box.

That's where the 'match

jthorson's picture

That's where the 'match reference' content type would come in ... and it would be a node.

The sandbox (posted on d.o

jthorson's picture

The sandbox (posted on d.o under my account) currently contains only the basic (i.e. empty) entity definitions ... I'll work on putting some of the 'league structure' relationships into place this weekend, and post a direct link once there's something there worth looking at.


bdrichard's picture

I am trying to put a site together which needs this kind of functionality. I am new to drupal but I would like to contribute.

What drupal version are you

atin81's picture

What drupal version are you planing to use?

Planning on Drupal 7

bdrichard's picture

Planning on Drupal 7. I realize there are more Drupal 6 options for league managment , but I have a Drupal 7 site under my belt and would like to stick with that version if at all possible.

For Drupal 7 you can go and

atin81's picture

For Drupal 7 you can go and use this modules: they are making a nice work, in fact I'm thinking on merge my modules (, that at this momment are just for Drupal 6 with them.


jthorson's picture

I can confirm that tournament lines up very nicely with the architecture I had in mind, and given that we're probably a long way off from full implementation of this initiative, it's a good choice if your looking for something immediate (and should still be relatively compatible with what I would envision the final Sports API product to be).

I was hoping to avoid

bdrichard's picture

I was hoping to avoid having to migrate a large user base when league management is available. I was hoping to make "a long way off" a little shorter. I'd rather spend my time constructively rather than fixing things after the fact ...almost like the difference between constructive and destructive debt.

Ooops ... Wrong module

jthorson's picture

I was actually thinking of the 'tourney' module, which may only be in a sandbox right now.

iScore Module

gr8britton's picture

ESPN has a very nice app for Android/iOS for entering the stats and a gamecast (that is really sweet.) They have an API that returns XML for your team's stats. It might be good to include this with this module as a great way to enter the stats.

When the toast has burned, and the milk has turned,
And Captain Crunch is waving farewell.
When the "Big One" finds you, may this song remind you,
That they don't serve breakfast in hell.