Planet Kubb:Creating a scoring application

A number of people have expressed interest in creating applications that help people score Kubb games and then saving those games into the Planet Kubb Wiki. While the wiki itself allows you to create a game using user friendly forms, an application that is specifically designed to facilitate scoring could provide a quicker experience as well as a more mobile-friendly option.

This document is intendended to explain how one would go about creating such an application. It focuses on what the Planet Kubb Wiki needs, not on any specifics of making an application in whatever environment you choose.

Approach
There are two distinctly seperate components to making an application that would allow scoring. The first is simply reading and writing information from the MediaWiki and Semantic MediaWiki API's. These problems are completely generic and have nothing specific to Planet Kubb. Familiarity with the MediaWiki API will be useful and access to any existing frameworks that facilitate communication with the MediaWiki API will make development simpler. There is a list of MediaWiki clients that would be good to start with.

To make this documentation simpler we are only looking at the use case of creating a new game and saving it. You could also support loading an existing game, editing and then re-saving it. However, that adds further flow complexity that is beyond the scope of this document.

MediaWiki Access
Let's first deal with just getting to the wiki. Your application will need to talk to the MediaWiki API for Planet Kubb which is at

http://wiki.planetkubb.com/w/api.php

You will need to get and store the users username and password. It will be necessary for the user to already have a registered account on the wiki. I would suggest that you not attempt to handle registration in your application, but instead direct the user to do that on their own.

Once you are able to get and securely store the users username and password you can then communicate with the API. You will need an edit token to make changes the wiki, and that is a good place to test that your logging in properly. Most client frameworks will handle authenticating the user using some method call. This API call will return an edit token after you have authenticated and logged in via the API:

http://wiki.planetkubb.com/w/api.php?action=query&titles=Foo&prop=info&intoken=edit&format=json

At this point you should try to just write a change to your userpage or some other safe place in the Planet Kubb Wiki to make sure that basic editing is working. If you are able to do that your half-way there.

Getting Planet Kubb Data
Fill in with information on the Ask queries.

List of events
Fill in with information on the Ask queries.

List of players
Fill in with information on the Ask queries.

List of teams
You can request the list of teams from the Planet Kubb Wiki via the MediaWiki API. You do not need to be logged in to make these queries, any request with the correct URL will work.

To get the list of all teams make the following query:

http://wiki.planetkubb.com/w/api.php?action=ask&query=%5B%5BCategory%3ATeam%5D%5D%7Csort%3DHas%20name%7Corder%3Dasc%7Climit%3D50%7Coffset%3D0&format=json

If you URL decode the "query" parameter you can see the query is straightforward Semantic MediaWiki query syntax.

|sort=Has name|order=asc|limit=50|offset=0

You can set limit higher. It has a maximum value of 500. You can use limit and offset to page through all of the teams in the wiki.

Searching for a team
You may want to just show teams matching a certain string. In that case, you just need to add another parameter to the query being submitted. This query shows all teams that have "Kubbchucks" in their name. You can change the location of the asterisks to get different wildcards. Note the tilde is required to execute a wildcard match.

http://wiki.planetkubb.com/w/api.php?action=ask&query=%5B%5BCategory%3ATeam%5D%5D%5B%5BHas%20name%3A%3A%7E%2AKubbchucks%2A%5D%5D%7Csort%3DHas%20name%7Corder%3Dasc%7Climit%3D50%7Coffset%3D0&format=json

Query:

Has name::~*Kubbchucks*|sort=Has name|order=asc|limit=50|offset=0

You can add other parameters to this easily enough. You can query by any of the properties that a team has (see http://wiki.planetkubb.com/wiki/Special:Browse/Team:Kubbchucks for full list). If you want location in the list, add that to the output parameters. You could even get the team logo, country, club, Kubb Power Index, anything that is in the wiki.

Getting team Roster
A similar query will allow you to retrieve the roster for a team.

http://wiki.planetkubb.com/w/api.php?action=ask&query=%5B%5BHas%20object%20type%3A%3ARoster%5D%5D%5B%5BHas%20team%3A%3ATeam%3AKubbchucks%5D%5D%7Csort%3DHas%20player%7Corder%3Dasc%7Climit%3D50%7Coffset%3D0&format=json

Query:

Has object type::RosterHas team::Team:Kubbchucks|sort=Has player|order=asc|limit=50|offset=0

This example query shows the roster for Team:Kubbchucks. You could also add an output for their position into the query:

Has object type::RosterHas team::Team:Kubbchucks|?Has player position|sort=Has player|order=asc|limit=50|offset=0

Which would be

http://wiki.planetkubb.com/w/api.php?action=ask&query=%5B%5BHas%20object%20type%3A%3ARoster%5D%5D%5B%5BHas%20team%3A%3ATeam%3AKubbchucks%5D%5D%7C%3FHas%20player%20position%7Csort%3DHas%20player%7Corder%3Dasc%7Climit%3D50%7Coffset%3D0&format=json

List of matches
Fill in with information on the Ask queries.

Assembling a Game
It is up to the developers infinite creativity to figure out how you want to present the scoring interface to the user. It is worth noting that a regular expression pattern is already identified that you can use to validate scoring notation. Please reuse this.

Once the user has added some information to the scoring interface you can start writing that information to the wiki for archival and analysis, as well as potentially reloading it. All the information in the wiki for a game is stored in MediaWiki template calls using four seperate templates:


 * Game
 * Game player
 * Game initialize
 * Game turn
 * Game statistics


 * Game
 * This template defines the game metadata. What teams are palying, where is it, etc.


 * Game player
 * This template attaches a player to the game. Some of this information can be inherited from the Match that the game is part of.


 * Game initialize
 * You don't do anything with this other than place it before any calls to Game turn. It sets up state variables for analyzing the game.


 * Game turn
 * This is the workhorse of the game system. It holds the notation about what happened in the turn.


 * Game statistics
 * This also is just placed at the end and has no parameters.

So, if you think of your application you need to collect the information from the user and then build a Game template and as many Game turn templates as you need. Inser the placeholder Game initialize and Game statistics templates in as well. Please add newlines as shown here to increase readability.

Game turn
The game turn template accepts Notation for each turn. If you are using player identifiers you should follow the notation guideline using a colon. So,  would attach that throw to player. Player notation is not required and can be mixed with some turns having it and others not. The wiki will report an error on display if a player is referenced but not defined in an instance of a  template, but the game will still be saved.

Saving a game
After you have created this series of templates you then call the MediaWiki API and issue an edit call to the page with all of the data. Note that you can and should feel free to save many times. You could issue a save after each turn is added. You could do that by either submitting a full edit with the entire game, or alternatively, you could even just issue an edit and specify  for the turn that is being added.

The wiki will take over from here, and your work is done.

Other capabilities
The method described here for adding information to the Planet Kubb Wiki could be extended in many other ways. Adding Teams, Players, Matches all follow the exact same cycle described above they just require different templates. You could extend your application to support adding matches and players and even attaching photos from the pitch of a player. All are imminently feasible and supported by the core API's that MediaWiki and Planet Kubb Wiki have available today.

Complete Game
Here is two examples of a complete game for reference. The first doesn't have player information, only team activity.

Here is an example that includes player by player information.