ChessPlayer v2.2 - by brothercake

This guide describes all query string and source-defined variables, with notes on implementation, how values are interpreted and how they affect each other.

Important note: The fault-tolerance of query string data within this program is basically zero; syntax errors could render the board unuseable. For this reason, I would discourage you from generating them manually, but rather encourage you to consider this documentation a framework for automated process.


top | query string game variables | query string style variables | page variables | query string examples | performance



Query string game variables

These values send game data and metadata to the chessboard. The most important ones are:

pos rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1

Send the board a single position; or

 
game e2e4,e7e5,g1f3,g8f6,f3e5,d7d6,e5f3,f6e4,d2d4,d6d5,f1d3,f8e7,e1g1,b8c6, f1e1,c8g4,c2c3,f7f5,d1b3,e8g8,b1d2,g8h8,b3b7,f8f6,b7b3,f6g6,d3f1

Send the board a comma-delimited sequence of moves.

You can send either a single position using pos, or a series of moves using game. It is not possible to use both in the same query string. With either, you can optionally use:

last d6c5

The presence of this named pair tells the board to indicate the last move that was made, using two red borders. The script is literal about what you define here, and doesn't check whether it's consistent with that position; it simply highlights the two squares you specify.

However using last with an input game tells the script to load and display from a position other than the start. The end position is probably most useful for showing a game in progress, but you can equally use it to specify any one move in the game, and the board will load and display from that position.

The next group of variables are used for sending PGN annotation information.

Event Good Side v Dark Side

The PGN [Event ] tag. This is displayed in the title bar, is user-editable, and is throughput to the export logs.

Site Death Star

The PGN [Site ] tag. This is user-editable, and is throughput to the export logs.

Date 2002.03.24

The PGN [Date ] tag. This is user-editable, and is throughput to the export logs.

Round 3

The PGN [Round ] tag. This is user-editable, and is throughput to the export logs.

White Obi Wan Kenobi

The PGN [White ] player name tag. This is user-editable, displayed at the top of the chessboard, and throughput to the export logs.

Black Darth Vader

The PGN [Black ] player name tag. This is user-editable, displayed at the top of the chessboard, and throughput to the export logs.

Result *

The PGN [Result ] tag. This is user-editable, and is throughput to the export logs.

WhiteElo 3

An optional PGN tag to indicate the white player's FIDE Elo rating. This is user-editable, is displayed at the top of the chessboard, and throughput to the export logs.

BlackElo 4

An optional PGN tag to indicate the black player's FIDE Elo rating. This is user-editable, is displayed at the top of the chessboard, and throughput to the export logs.

WhiteNationality ra

A proprietary extension to the PGN standard, this tag indicates the white player's nationality, using ISO-3166 country codes. A list of these codes can be found in the _program/_flags folder in plain text and Excel spreadsheet format. Not all countries have flag icons bundled with the program - those which do are indicated in the spreadsheet. This is user-editable, shown with a flag icon at the top of the chessboard, and the country code is throughput to the export logs.

BlackNationality ev

A proprietary extension to the PGN standard, this tag indicates the black player's nationality, using ISO-3166 country codes. A list of these codes can be found in the _program/_flags folder in plain text and Excel spreadsheet format. Not all countries have flag icons bundled with the program - those which do are indicated in the spreadsheet. This is user-editable This is user-editable, shown with a flag icon at the top of the chessboard, and the country code is throughput to the export logs.


top | query string game variables | query string style variables | page variables | query string examples | performance



Query string style variables

These variables are used to send color information for the board and control panel, and to define aspects of its behaviour and layout.

Many of the layout and style variables can be both predefined in the source code of chessboard.html and sent as named pairs in the query string. The query string will always take precedent, while the predefined values are defaults, so those values you never intend to change need never be sent in the query.

Some of the variable names are the same in the source code as they are if defined in the query, but not all. Query-string syntax is used here, but the source-defined name is also given, for example:

where size is the query string pair name and squareSIZE is the source code variable name. In all cases, the syntax used to define the actual values in the query string is subtly different, in a couple of important ways:
  1. do not use quotes to differentiate string values from numbers; values must never include quotes, or script errors will occur.
  2. don't use the # symbol when defining hex color values; including them will also cause errors.

Some query string examples are given later in this document

view w

Specify whether to default to white w or black b point of view. This can be user controlled, using a button in the player control panel.

size [squareSIZE] 35

The board square size. A range between 20-50 pixels is useable. This value is also the width and height of the piece images, so used in combination with the pieces variable, you could, for example, define large squares with high-resolution images.

pieces [pieceFOLDER] standard

Specify the name of the folder used for chess piece images, which must live in the root directory of the chess player script package.

showLegal [showLegal] true

Whether to show a marker for legal moves. This is a useful tutoring mode, but more experienced players may find it distracting. Enabling it also makes a small difference to the processing time required for each manual piece move. This mode is user-controlled, using a checkbox in the player control panel.

blockIllegal [blockIllegal] true

Whether to disallow illegal moves. This also makes a small difference to the processing time required for each manual piece move, but you can improve this by using it in the background, without the accompanying showLegal indicators. This mode, which can be used in combination with or independently of showLegal, is also user-controlled.

panels true,true,true,true,true

This defines which of the five control panel groups are expanded or contract by default. Specify the five panels in order - where the top-right panel is the first value, and the bottom-left FEN display is the last one - using comma delimited boolean values for open (true) or contracted (false). The panel layout is user-controlled.

lightCOLOR [lightCOLOR] eacda5

The main body background color, the background color of light form elements, and the text color in dark form elements; specify a hex color value or color name.

darkCOLOR [darkCOLOR]

9d7752

The control panel background color, including all buttons and dark form elements; specify a hex color value or color name.

borderCOLOR [borderCOLOR]

613825

The color of the thin double-border around the edge of the chessboard, and the text color in light form elements; specify a hex color value or color name.

boardBACKING [boardBACKING]

dabd95

The background color of the area around the chessboard; specify a hex color value or color name.

whiteSQUARES [whiteSQUARES]

f4d8b0

The color of white board squares; specify a hex color value, color name, or a GIF or JPG image.

blackSQUARES [blackSQUARES]

9d7752

The color of black board squares; specify a hex color value, color name, or a GIF or JPG image.

shadowCOLOR [shadowCOLOR]

5a5a5a

For ie5.5 and ie6 only, the dropshadow color underneath a piece when it's picked up. It's possible to disable the dropshadow effect altogether, by defining it in the source code of chessboard.html as shadowCOLOR = "";


top | query string game variables | query string style variables | page variables | query string examples | performance



Page variables

These values can only be set in the source code of chessboard.html

pageName

"chessboard.html"

The filename of the chessboard page. You will need to alter this value if you rename the file.

pagePath

"http://www.mydomain.com/ChessPlayer/"

Define the absolute path used in the player-format export to generate game urls. Whatever you specify here is appended to the filename given in pageName, to create the url, eg:

    http://www.mydomain.com/ChessPlayer/chessboard.html?game= ...etc

If you leave it as pagePath = "" then the script will generate absolute links to itself.

playbackSpeed

2000

The speed of automatic play-through, in milliseconds per move.

showSquareInfo

""

The board squares are normally blank, but you can use this variable to label each square, with:

  • "numbers" - where 0 is the top left and 63 is the bottom right,
  • "names" - from a8 to h1, or
  • "both"
outputToNotepad

false

Export logs are normally written as HTML pages, however ChessPlayer can export plain text documents, in the form of .tmp files which are saved onto your desktop.

I wanted to try this just to see if it could be done, planning eventually to do it in PHP. But it seemed a shame to remove it. It uses an ActiveX control to access the file system, so you will get a security warning if you turn it on, and it will not work on the internet at all.

enablePgnImport

true

Optionally disable the pgn import facility by setting this variable to false. You should do this if:

  • you don't want pgn import capabilities, or
  • your server doesn't support PHP and you don't have the time or inclination to port it to another scripting language.
pgnProcess

"pgnImport.php"

The script package comes with two versions of the pgn import module, which can be found in _program/_import. All use the same js archive to do the actual conversion, but have different interfaces and functionality.

Used locally, the script will always open pgnImport.html, which is a simple file-input for selecting .pgn archives from your computer.

When used on a web server (specifically, through HTTP) the script will call pgnImport.php, or whatever you specify with pgnProcess.

pgnImport.php creates a list of the files in the _pgn directory, and handles writing their contents into a textfield for the javascript to read. Before using this you must set a variable in its source code - $the_path - which defines the path to the _import directory from the server root.


top | query string game variables | query string style variables | page variables | query string examples | performance



Query string examples

The following examples give an idea of what kinds of data can be combined. The golden rule is that anything you define in the source code of chessboard.html is used as default, and doesn't need to be in the query string if those settings are okay.

The script sometimes needs to reload itself, for example when resizing the board, and in these cases it adds all the query string variables necessary to reproduce the current layout and appearance - thus maintaining any settings the user has changed themselves. There's no need to be concerned about this, but it's worth knowing.

Anyway, here's a few examples.



You can also open games using a javascript: url to call a window-opening function. Something like this, which must be in the <body> section: 

<script language="javascript1.2">

function chessWindow(chessUrl) {

	if(typeof document.all!="undefined" && typeof window.opera=="undefined") {
		var winSize = [676,474];
		var winPos = [0,0];
		var scrDim = new Array(screen.width,screen.height);
		if(scrDim[0]>800) {
			winPos = [(scrDim[0]-winSize[0])/2,((scrDim[1]-winSize[1])/2)-32];
			}
		var chessWin = window.open("ChessPlayer/chessboard.html?"+chessUrl,"chessWin","left="+winPos[0]+",top="+winPos[1]+",width="+winSize[0]+",height="+winSize[1]+",status=yes,menubar=no,toolbar=no,scrollbars=no,resizable=no");
		chessWin.focus();
		}

	}

</script>

This opens a window with minimal decorations; I've left the status bar so that users can see the document's status. The window is self-resizing, which means you can use it with impunity, safe in the knowledge that boards of any size and layout will fit perfectly. But note that if this is to work you should use the above function exactly as it is (unmodified) - since the resizing code relies on its values.

Call the function like this: 

<a href="javascript:chessWindow('game=e2e4,e7e5,g1f3,g8f6,f3e5,d7d6,e5f3,f6e4,d2d4,d6d5,f1d3,f8e7,e1g1,b8c6,f1e1,c8g4,c2c3,f7f5,d1b3,e8g8,b1d2,g8h8,b3b7,f8f6,b7b3,f6g6,d3f1&last=d3f1')">open chess game</a>

Where the entire query (without the ? delimitor) is sent as a string value to the function.


top | query string game variables | query string style variables | page variables | query string examples | performance



Performance

You'll probably have noticed that the script is quite large. The style and layout code in chessboard.html is 31K, while the main chess.js script is 98K.

The presence of query string data means that chessboard.html will almost never be called from cache, since its url is usually different each time. However chess.js will cache, because it's an external file, so you will notice a significant improvement in loading speed after the first time.

The chess piece images, and the images necessary for the panel layout, amount to 4K, while the pgn import module is 33K for the page and conversion script. These latter two files are not called until you open the import window, and will also cache.