WGo.js javascript library for game of go

SGF Player

WGo.js Player is the most significant component of the library. It is an application for viewing and replaying go game records that can be embedded into any website. Basically it does the same job as Eidogo or GOswf but trying to be better.

Features

  • No needs of third party software like Flash Player or Java.
  • Works on mobile devices.
  • Easy theming through css.
  • Many possible layouts.
  • Responsive - player can have any dimensions, and they can be changed any time.
  • Replaying games using mouse wheel
  • Permanent links
  • Highlighting of coordinates mentioned in comments
  • Score mode
  • Extendable - you can add new functionality to a player.
  • Internationalization

Demo

Quick example

Working with the player is quite awesome. Download WGo.js files and link them into your document, then you will just need HTML to display player. 
<!DOCTYPE HTML>
<html>
  <head>
    <title>My page</title>
    <script type="text/javascript" src="wgo/wgo.min.js"></script>
    <script type="text/javascript" src="wgo/wgo.player.min.js"></script>
    <link type="text/css" href="wgo/wgo.player.css" rel="stylesheet" />
  </head>
  <body>
    <div data-wgo="game.sgf" style="width: 700px">
      Sorry, your browser doesn't support WGo.js. Download SGF <a href="game.sgf">directly</a>.
    </div>
  </body>
</html>

Getting started

Installation

Basic installation of WGo.js Player is shown in example above. Both files (wgo.min.js and wgo.player.min.js) must be included in that order. You can download them here. However these script tags can be placed anywhere in the document. You can also add language .js file to display the player in different language. In wgo.player.css is defined player's look.

Embedding a player

There are 2 options of inserting SGF player into a website. You can use pure HTML or javascript. Javascript is more convenient for advanced tasks. I will show you both ways.

HTML

Player will be triggered in an element when you specify attribute data-wgo. Then you can use other data-wgo-* attributes to configurate the player. Dimensions, margins etc. are set exclusively by CSS.

<!-- Activating a player using HTML -->
<div data-wgo="game.sgf" style="width: 700px">
  Sorry, your browser doesn't support WGo.js. Download SGF <a href="game.sgf">directly</a>.
</div>

To create a read-only diagram you can use the attribute data-wgo-diagram instead. This will disable all controls and renders only the board. This is a shortcut for specifying an empty layout and disable the wheel and key input and does not mark the last move made with a circle.

Javascript

Embedding a player directly with javascript is less elegant, but you can set any configuration freely, for example by javascript function. You can also save player's instance for further manipulation.

<!-- Activating a player using javascript -->
<div id="player" style="width: 700px"></div>
<script type="text/javascript">
var elem = document.getElementById("player");
var player = new WGo.BasicPlayer(elem, {
    sgfFile: "game.sgf"
});
</script>

View the example

Text inside <div> tag will appear, if user's browser doesn't support WGo.js. You can write any message here.

Configuration is slightly different for HTML and javascript. In HTML you simply use attributes, in javascript settings are passed in second argument of WGo.BasicPlayer constructor. In that case you will use JSON object. It is simple variable that can contain one or more values. Values have form key: value and they are split with comma. This table shows brief summary of all possible configurations:

Javascript HTML Description
sgf - SGF as a text string.
sgfFile - Path of SGF file to be viewed.
json - Kifu stored in JSON format.
- data-wgo SGF string or path of SGF file to be viewed.
- data-wgo-diagram Like data-wgo but disables all controls and renders a static diagram.
move data-wgo-move Move number, path object or function returning a path.
board data-wgo-board Configuration object of the board.
layout data-wgo-layout Layout of the player.
enableWheel data-wgo-enablewheel Enables mouse wheel to replay game.
lockScroll data-wgo-lockscroll Locks page scroll when replaying game with mouse wheel.
enableKeys data-wgo-enablekeys Enables arrow keys to replay game.
rememberPath data-wgo-rememberpath Remembers last selected variations.
formatNicks data-wgo-formatnicks Highlight nicknames in comments.
formatMoves data-wgo-formatmoves Highlight coordinates (like A1, A2 etc) in comments.
kifuLoaded data-wgo-onkifuload Callback, that is executed after kifu is loaded.
update data-wgo-onupdate Callback, that is executed after every game's update.
frozen data-wgo-onfrozen Callback, that is executed when player starts being frozen.
unfrozen data-wgo-onunfrozen Callback, that is executed when player ends being frozen.
markLastMove data-wgo-marklastmove Displays a circle in the last move made if true (default: true).

Configure your player

In this section we will discuss all settings in detail.

Loading a SGF

As I mentioned earlier for loading a kifu there are configurations sgfFile and sgf or attribute data-wgo. Example of opening SGF file you can see above. If you want to replay SGF from string you will use this syntax:

HTML

<div data-wgo="(;PB[Black]PW[White]RE[B+R];B[qd];W[dd];B[pq];W[dq];B[fc])"></div>

Javascript

var player = new WGo.BasicPlayer(elem, {
    sgf: "(;PB[Black]PW[White]RE[B+R];B[qd];W[dd];B[pq];W[dq];B[fc])"
});

View the example

Javascript doesn't allow accessing files from other hosts. It means if your site is on domain www.example.com, SGF files also must be on this domain. However it is possible to use PHP script which makes a bridge between your host and foreign host. You can find it in download section. Then you must refer on this bridge: data-wgo="bridge.php?url=http://www.example.com/game.sgf"
JSON game record format is still experimetal and its structure can be changed, so I won't describe it yet.

Loading kifu at specified position

You can open SGF game with other than initial position, so board won't be empty, but there will be also first n moves. For this behaviour just set configuration move.

HTML

<!-- This example opens game.sgf at position 50. -->
<div data-wgo="game.sgf" data-wgo-move="50"></div>

Javascript

var player = new WGo.BasicPlayer(elem, {
    sgf: "game.sgf",
    move: 50
});

View the example

However in special cases, when there is more variantions, it may be necessary to use path object. It has property m with final move number and one property for each fork, which says what variantion to choose. It can look like this: {m: 100, 50: 0, 75: 1} - this will show first 100 moves, in move 50 the first variantion is chosen in move 75 second variation. Usage in HTML:

<div data-wgo="game.sgf" data-wgo-move="m: 100, 50: 0, 75: 1"></div>
In default WGo Player checks URL fragment (part of URL after #). If there is a path object, the kifu will be loaded at given position. This allows to create permanent links. If you want fragment to be ignored, just set data-wgo-move="0".

Customizing the board

Player's board can be customized via attribute board. Its value is passed as a configuration object of WGo.Board constructor. Look at board object for all possible settings. Don't set parameters width, height and size, they are automatically computed so your values would be ignored. Some examples of board's customizing:

HTML

<!-- Board with special stones and thicker lines. -->
<div data-wgo="game.sgf" data-wgo-board="stoneHandler: WGo.Board.drawHandlers.MONO, lineWidth: 2"></div>

Javascript

var player = new WGo.BasicPlayer(elem, {
    sgf: "game.sgf",
    board: {
        stoneHandler: WGo.Board.drawHandlers.MONO, 
        lineWidth: 2
    }
});

View the example

Layout of the player

WGo Player is composed from components. The main and required component is the board. Other components are optional and you can place them wherever around the board. In basic player there are these components available:

  • InfoBox - box with basic information about players.
  • CommentBox - box for comments and information about the game.
  • Control - panel with control buttons.

Although theming of player is accomplished with CSS, you need to specify placement of components in HTML (or javascript). For that there are four regions: top, right, bottom and left. There is illustration of regions:

left top right
board
bottom

Layout is set by JSON object. However there are 2 kinds of layout objects - static layout object and dynamic layout object.

Static layout object

This object specifies unchanging layout. It has simple structure: {top: array, right: array, bottom: array, left: array}. Each region array contains names of components which should be in that region. You can ommit any region.

Example
// These are predefined static layouts
WGo.BasicPlayer.layouts.one_column = {
    top: ["InfoBox", "Control"],
    bottom: ["CommentBox"]
};
WGo.BasicPlayer.layouts.no_comment = {
    top: ["InfoBox"],
    bottom: ["Control"]
};
WGo.BasicPlayer.layouts.right_top = {
    top: ["Control"],
    right: ["InfoBox", "CommentBox"]
};
WGo.BasicPlayer.layouts.right = {
    right: ["InfoBox", "Control", "CommentBox"]
};
WGo.BasicPlayer.minimal = {
    bottom: ["Control"]
};

Dynamic layout object

Basically it contains more static layouts which are triggered, when given conditions are matching. Dynamic layout object is an array of objects with this structure: {conditions: list_of_conditions, layout: static_layout, className: string}. Parameter list_of_conditions is an array with conditions. First static layout with matching conditions is applied. Possible conditions are:

  • minWidth number matches if width of the player in px is bigger or equal.
  • maxWidth number matches if width of the player in px is smaller.
  • minHeight number matches if height of the player in px is bigger or equal.
  • maxHeight number matches if height of the player in px is smaller.
  • custom function matches if given function returns true. It is called in player's context.

All conditions have to match for application of given layout. If you ommit conditions, layout will be also applied. You can also specify additional class names for the player in className parameter.

Example
// This is default layout of WGo Player
BasicPlayer.dynamicLayout = [{
  conditions: {
    minWidth: 650,
  },
  layout: BasicPlayer.layouts["right_top"], 
  className: "wgo-twocols wgo-large",
}, {
  conditions: {
    minWidth: 550,
    minHeight: 600,
  },
  layout: BasicPlayer.layouts["one_column"],
  className: "wgo-medium"
}, {
  conditions: {
    minWidth: 350,
  },
  layout: BasicPlayer.layouts["no_comment"],
  className: "wgo-small"
}, {
  layout: BasicPlayer.layouts["no_comment"],
  className: "wgo-xsmall",
}];
Dynamic layouts are necessary for responsiveness. If your player has static dimensions it is useless to use dynamic layout.

Setting the layout

In HTML you can only set static layout with data-wgo-layout attribute. If you want to customize dynamic layout you need to use javascript and property layout.

HTML

<!-- Different layout of the player. -->
<div data-wgo="game.sgf" data-wgo-layout="left: ['InfoBox', 'CommentBox'], bottom: ['Control']"></div>

Javascript

var player = new WGo.BasicPlayer(elem, {
    sgf: "game.sgf",
    layout: { // you can use static or dynamic layout
        left: ['InfoBox', 'CommentBox'], 
        bottom: ['Control']
    }
});

View the example

Dimensions of regions or components are not handled automatically, you will probably need to set widths of regions and heights of components in CSS for each layout.

Mouse and keyboard input

WGo Player can be controlled by arrow keys and mouse wheel in default. However you can turn off this behaviour if you set attributes data-wgo-enablewheel and data-wgo-enablekeys or properties enableWheel and enableKeys to false. Of course you can disable only wheel or only keys.

HTML

<!-- Player with disabled mouse wheel and arrow keys. -->
<div data-wgo="game.sgf" data-wgo-enablewheel="false" data-wgo-enablekeys="false"></div>

Javascript

var player = new WGo.BasicPlayer(elem, {
    sgf: "game.sgf",
    enableWheel: false,
    enableKeys: false 
});

View the example

Normally when you control player with mouse wheel, window scrolling is locked. You can suppress this if you set attribute data-wgo-lockscroll or property lockScroll to false. In that case the window will be scrolled no matter what.

Formatting of comments

WGo Player has ability to format comment text. It can highlight nicknames (string at the beginnig of a line followed by a colon) and coordinates (strings like A1). Moreover when you hover coordinates, mark will be displayed on the board at corresponding position. If you dislike these features set attributes data-wgo-formatnicks and data-wgo-formatmoves or properties formatNicks and formatMoves to false. If you don't know how, look at example above.

For your information all HTML tags in comments are stripped for security reasons.

Player's events

WGo Player dispatches several types of events and you can attach listeneres to them. Listener is a function which is called when given event occures. Function is an executable javascript code, so if you don't know javascript, this section won't be much useful for you. You can listen any of these events:

  • kifuLoaded - dispatched when new kifu is fully loaded and ready for replaying. Function is called with one argument, event object with these properties:
    • type - name of event.
    • target - current player object.
    • kifu - kifu object.
  • update - dispatched after every change of game's position. Function is called with one argument, event object with these properties:
    • type - name of event.
    • target - current player object.
    • op - operation which triggered the event ("next", "previous", etc...).
    • node - current node object.
    • position - current position object.
    • path - current path object.
    • change - object containg last changes.
  • frozen - dispatched when the player freezes. In frozen state you can't replay kifu. Function is called with one argument, event object with these properties:
    • type - name of event.
    • target - current player object.
  • unfrozen - dispatched when the player stops being frozen. Function is called with one argument, event object with these properties:
    • type - name of event.
    • target - current player object.
At this point I won't discuss particular properties of event objects in detail. However you can use console.log() or something to discover their structure.

If you are using javascript to embed the player, set properties of configuration object with same names as events. In HTML there are attributes: data-wgo-onkifuload, data-wgo-onupdate, data-wgo-onfrozen and data-wgo-onunfrozen.

HTML

<!-- Player reacting on events. -->
<div data-wgo="game.sgf"  data-wgo-onkifuload="document.getElementById('info').innerHTML += '&gt; Loaded kifu: '+arguments[0].kifu.info.black.name+' vs. '+arguments[0].kifu.info.white.name+'\n'" data-wgo-onupdate="if(arguments[0].node.move) document.getElementById('info').innerHTML += '&gt; '+(arguments[0].node.move.c == WGo.B ? 'Black' : 'White')+'\'s move at: '+arguments[0].node.move.x+'x'+arguments[0].node.move.y+'\n'" data-wgo-onfrozen="document.getElementById('info').innerHTML += '&gt; Player is now frozen.\n'"  data-wgo-onunfrozen="document.getElementById('info').innerHTML += '&gt; Player is no longer frozen.\n'"></div>
<pre id="info"></pre>

Javascript

var player = new WGo.BasicPlayer(elem, {
    sgf: "game.sgf",
    kifuLoaded: function(e) {
        elem2.innerHTML += '> Loaded kifu: '+e.kifu.info.black.name+' vs. '+e.kifu.info.white.name+'\n';
    },
    update: function(e) {
        if(e.node.move) elem2.innerHTML += '> '+(e.node.move.c == WGo.B ? 'Black' : 'White')+'\'s move at: '+e.node.move.x+'x'+e.node.move.y+'\n';
    },
    frozen: function(e) {
        elem2.innerHTML += '> Player is now frozen.\n';
    },
    unfrozen: function(e) {
        elem2.innerHTML += '> Player is no longer frozen.\n';
    }
});

View the example

Theming

All theming is done with CSS. You can set dimensions of the player and any component. You can also change colors, icons and almost anything else. Just create your own CSS file, altering the basic look, and include it after other WGo files.

You can also find some alternative themes in download section. For example look at Dark theme.

Internationalization

WGo Player can be translated into any language. If translation already exists, you just include language file after other WGo javascript files.

Example of player in czech

<!DOCTYPE HTML>
<html>
  <head>
    <title>My page<title>
    <script type="text/javascript" src="wgo/wgo.min.js"></script>
    <script type="text/javascript" src="wgo/wgo.player.min.js"></script>
    <script type="text/javascript" src="wgo/i18n.cs.js"></script>
    <link type="text/css" href="wgo/wgo.player.css" rel="stylesheet" />
  </head>
  <body>
    <div data-wgo="game.sgf" style="width: 700px">
      Váš prohlížeč není podporován.
    </div>
  </body>
</html>

In download section you can find all translations. If translation into your language doesn't exist, you can create it. You must copy english language file (i18n.en.js) and replace all english strings with your strings. Then include this new file into your document. You can also send this file to me (thebestgoplayergmail.com) and I will publish it.

API Reference

API documentation hasn't been written yet. If you are interested in WGo Player you can explore source codes. They are fairly commented.