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.

Simple & Customized Demos

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:

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!