The KGS Go Server is pretty much the bee’s knees in all respects. KGS provides an excellent web interface for viewing one’s archived games, but no API (that I know about) for grabbing that data. This plugin uses php + curl to scrape content from KGS’s archives, generate a list of one’s most recent games, and automatically generate a link to load the game in EidoGo, an awesome web-based SGF viewer/editor.
The KGS Games plugin uses a PHP file to scrape the KGS archive and create a static file with your game results. It also uses a PHP api called phpQuery used to parse the HTML from KGS’s archive.
Place both kgscurl.php and the lib directory somewhere they’ll be safe and content. I recommend a folder called KGS.
You can put the jquery.kgsgames.js plugin script anywhere you want. I keep all my scripts in a /scripts folder off of the root of my site and then I minify them and combine them all for production. You’ll need to include the script in a tag on any webpage using the script.
<script type="text/javascript" src="/scripts/jquery.kgsgames.js"></script>
The plugin should be activated on the container you want to populate with your list of games.
$('#go-games1').kgsgames({
url: '/go/kgs/kgscurl.php',
username: 'nate451'
});
The url should be the path to wherever you’ve placed the kgscurl.php file. The username variable should be your KGS username.
An important note about caching: Since this plugin makes HTTP requests to KGS’s server, I was very concerned about being a burden – even a minor one – on KGS’s server load. To help minimize any impact this plugin has on KGS, by default, it writes the results of its operation to a file in the same directory as kgscurl.php. On subsequent requests, it checks to see whether the cache file is over 24 hours old or not. If it’s not, it uses that data rather than fetching fresh data from KGS. I suspect that updating every day will be quite frequent enough for most users. If you need to change this, you can send a different integer for the “hoursFresh” variable, or you can set noCache to true to fetch data from KGS every time.
This option is to assist when initially setting up the widget, as any change in options (such as changing the number of games) may not be reflected right away if the cached file isn’t updated. Please turn noCache off when you’re ready for deployment so that we’re good stewards of the tool KGS has provided.
KGS Games is highly customizable. You can customize your implementations by passing options when you initialize your widget. Options are passed using this form:
$('#myKGSGamesWidget').kgsGames({
option: value,
option2: value2,
option3: value3
});
Here’s a list of available options:
Option | Type | Default | Explanation |
---|---|---|---|
archivesTag |
string | ‘<ul />’ | Tag used for the container of all the individual games. |
fullArchiveLink |
string | ‘<p />’ | Tag used for the link to one’s full archives at the end of the KGS Games widget. |
fullArchiveLinkText |
string | ‘Full Archive’ | Default text for the link to one’s full archives at the end of the KGS Games widget. |
dateFormat |
string | ‘F jS’ | Date format for game dates. Uses PHP date syntax |
hoursFresh |
number | 24 | Number of hours to consider a cached file fresh – not in need of an update from KGS. |
noCache |
boolean | false | If set to true, never uses the cached archive file. Useful when changing settings. Do not use for production. |
numGames |
number | 20 | Number of games to display, beginning with the most recent. |
output |
string | listed below | Controls the output for each game – default and available variables are listed after this. |
ranked |
boolean | true | By default, only retrieves ranked games. If set to false, will retreive all games except reviews. |
tags |
string | null | Set to “t” to retrieve only games with tags |
url |
string | null | The path to kgscurl.php |
username |
string | null | Your KGS username |
widgetName |
string | null | If, for whatever reason, you want two instances of the widget on the same site for the same username, you’ll need to add a widgetName so that it uses a different cache file |
Default:
<li><a href="http://eidogo.com/#url:@GAMESGF"><span class="date">@DATE:</span> <span class="black @BLACKRESULT">@BLACK</span> vs. <span class="white @WHITERESULT">@WHITE</span>: @RESULT</a>
bc.. @GAMESGF: a link to a game's SGF file @DATE: date of the game -- alter formatting via dateFormat option @BLACK: username & rank of person playing black @BLACKURL: link to black's archives on KGS @BLACKRESULT: either 'winner' or 'loser', depending on who won @WHITE: username & rank of person playing white @WHITEURL: link to white's archives on KGS @WHITERESULT: either 'winner' or 'loser', depending on who won @RESULT: game outcome, ie: 'B+7.5' or 'W+Res.'
Let me know if you have any feedback about how I can improve this plugin or its documentation. Onegaishimasu!