JavaScript Shogi Board Viewer

JS Shogi Board Viewer is a JavaScript component that makes it possible to generate Shogi position diagram on your Web page.

Here is a description of how to use it.

Using the viewer

Downloading files

The viewer consists of 3 elements:

You can download them separately or all in one pack (available also as an attachment to this page).

The viewer files ca be also seen on ShogiTools pages (http://code.google.com/p/shogitools/source/browse/#svn/trunk/jsfenparser)

Embedding on the page

Making the script work on your page is fairly simple. The procedure boils down to:

Including the script on the page
Creating <DIV> element(s) for the diagrams
Initializing the viewer
Using a script to populate the diagrams.

I describe the steps in details below.

Include ShogiBoardViewer

First we include the script on your page, by placing the following in the <HEAD> section:

<script type="text/javascript" src="js/ShogiBoardViewer.js"></script>

Create the HTML for the boards

Next, we put <DIV> HTML tag where we want the board to be inserted.

For a single board it would look like this:

<div id="board"></div>

Important thing to remember is the id attribute. We will later use it's value to tell the script to generate the diagram for us.

Initialize ShogiBoardViewer object

Now, the javascript source has has been included and a placeholder have been created. The next thing to do is to initialize the viewer.

To do this we create new ShogiBoardView instance and give the placeholder's id to it. For our example the code would look like this:

<script type="text/javascript">
var sbv = new ShogiBoardView('board');
</script>

Please note, that you could customize the viewer's behavior by supplying the constructor with init parameters. For clarity, I leave it for later and describe it in "Customization" section.

Preparing Shogi position data

Now, we are almost there. The only thing left is to "feed" the viewer with proper Shogi position. But how to do this?

Well, I wanted my viewer to be "generic" (independent of the position data source) and possibly small. Therefore I decided that the position is provided with the help of a javascript object. Sounds like real pain, doesn't it? But fortunately, JSON notation comes to the rescue. Thanks to it we can build JavaScript objects that are understood both by computers and humans.

Besides, JSON is quite popular data exchange format, so there could be converters (i.e. from Shogi FEN or others) easily plugged in to the viewer.

The good thing about JSON is that it's very self-descriptive format. Here is how I designed the format.

The description consists of 4 elements:

side on move
white pieces in hand
black pieces in hand
pieces on the board

and could be expressed as JSON like this:

{
   "sideOnMove":"black",
   "blackHand":[],
   "whiteHand":[],
   "pieces":{}
}

Side on move is simple: it can be either "black" or white".

Pieces in hand data is an array of numbers. Each number represent the count of pieces for a given rank. The rank is indicated by position in the array. Pieces info is stored in a given order:

Pawn (index 0)
Lance
Knight
Silver
Gold
Bishop
Rook

So, for a Silver and 2 Pawns in hand the data would look like this:

[2,0,0,1,0,0,0]

I am not particularly happy with the format. I don't like the fact that a human has to remember position of piece ranks in the array. The format could be therefore change in the matter.

[[Maybe better would be to have pairs rank:count?]]

Pieces on board are given by field:rank pairs. A field is described by 2 chars: column number and row char in the standard Shogi coordinate system. Leftmost column is named '9', rightmost is '1'. Uppermost row is 'a', lowermost is 'i'.

A rank symbol is "borrowed" from Shogi Ladder notation (http://www.shogi.net/ladder/shogiboard.html). The 'w' and 'b' in front of the piece symbol's abbreviations indicate white and black respectively. When a piece is promoted, it will be given with a preceding "+", as in "+bL" or "+wP".

Summing up, here is an example Tsume Shogi position and it's JSON object represention:

tsumeJson = {
        "sideOnMove":"black",
        "blackHand":[0,0,0,0,1,0,0],
        "whiteHand":[0,0,0,0,0,0,0],
        "pieces":{"2a":"wK","1a":"wL","3c":"+wR","1c":"+bB","3d":"+bB"}
    };

The ShogiBoardView object gives us the following method to display the position:

chessObj.drawBoard(<<position data>>);

or:

chessObj.drawBoard(<<ShogiBoardModel object>>);

Using the second alternative will be explained while explaining Shogi FEN parser. For now, let's focus on the first option.

The complete HTML file for our Tsume would look like this:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<head>
    <title>Tsume Shogi diagram</title>
    <script type="text/javascript" src="js/ShogiBoardView.js"></script>
</head>
<body>
    <p>Board 1</p>
    <div id="board"></div>

    <script type="text/javascript">
        var chessObj = new ShogiBoardView('board');

        tsumeJson = {
            "sideOnMove":"black",
            "blackHand":[0,0,0,0,1,0,0],
            "whiteHand":[0,0,0,0,0,0,0],
            "pieces":{"2a":"wK","1a":"wL","3c":"+wR","1c":"+bB","3d":"+bB"}
        };

        chessObj.drawBoard(tsumeJson);
    </script>
</body>
</html>

One important thing to note. If you are using Internet Explorer, before including ShogiBoardViewer.js, you have to include js_fixes.js:

This file contains javascript definitions that fix Internet Explorer incompatibilities.

That's all. You can check the resulting page here. Similar example can be seen live here

Customizing the viewer

TBD (for now, see the example: http://shogitools.appspot.com/html/shogiview.html).

Change log

20080701 -- created the page

20080703 -- added js "patch" for IE7/8

20080917 -- fixed bugs reported by Bernhard Maerz

20081206 -- moved example to appspot.com

20081214 -- changed the way to initailize the viewer (now it takes a placeholder's id in the constructor -- see description)

20090609 -- changes in ShogiBoard. Fields are direct attributes of 'pieces' field (not an array of objects anymore)

20090628 -- better positioning of hand pieces

v.2

jssfen.zip

(1547k)

fat bold cyclop,

Jun 28, 2009 7:09 AM

Fat Bold Cyclop's Place

Navigation

Recent site activity