JavaScript Shogi Board Viewer
Life is like a hamburger on our gas station - never know what you gonna get.

blog counter

If you have any suggestions, comments or you spotted some error (bug, broken link, grammatical error), please drop me a note:

Sign my Guestbook from Bravenet.com

2008. 07.01

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:

  1. JavaScript program to generate the diagram
  2. CSS file containing style definitions for the diagram
  3. Images representing the board and the pieces

You can download them separately or in in one all in one pack.


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:

  1. Including the script on the page
  2. Creating <DIV> element(s) for the diagrams
  3. Using the script to populate the diagrams.

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(s) 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

The javascript source has has been included and one or more board placeholders has been created. The only thing to do is to make the script generate the board for as. To do this, first we create the ShogiBoardViewer object:


<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.

Now, we are almost there. The only thing to do 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 a javascript object. Feels 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. 


Shogi position data format

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 piece 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"}
    };



Complete HTML file for our Tsume would look like this (html tag intentionally removed -- googlepages didn't like it):


<!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 7 or 8, before including ShogiBoardViewer.js, you have to include js_fixes.js: 

 

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

 

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

20081214 -- placeholder element's id is now a constructor parameter.

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