HTMLTTChess reference

The HTMLTTChess package is a combination of a javascript, a css and an html file that allows the rendering of nice chessboards in HTML at any size or color, by using TrueType fonts and without the need of extra images. Chess game diagrams can be rendered in both color or B&W mode, and figurine movements or square of interests can be indicated as well. Diagrams rendered in B&W mode can also be copy-pasted into e.g. an office application.

Supported features

Here a summary of supported features:

Notation:
- Forsyth-Edwards compatible notation.
- Extra symbols for eg. piece movement (. or x).
- Highlighting of squares of interest.
Rendering:
- Truetype font based rendering, using either local or web font.
- Color mode.
- Printer-friendly black&white mode.
- Default mode specification / inline mode specification.
Size:
- Fixed size.
- Variable size (eg. multiple of browser default font size).
Style:
- Stylesheet-based.
- Default style.
- Inline style.
- Class style.
Export:
- Black&white board can be copy-pasted in external applications.

Downloading the latest version of HTMLTTChess

The latest version of HTMLTTChess is available on GitHub or here.

Viewing pages generated by HTMLTTChess

To view pages containing chessboards generated by HTMLTTChess, all you need is to use a CSS3-compatible browser and to enable javascript in your browser. If you don't have the Chess Merida Unicode font installed on your computer, your browser will download it from the server as a web font.

See the compatibility section or the Chess Merida Unicode page for more information.

Quickstart — creating your own pages with HTMLTTChess

On this page you will find detailed instructions on how to use HTMLTTChess to create your own web pages with nice chess diagrams. These instructions are also illustrated by several examples on the sample page. Once you feel familiar enough with the possibilities, you may start creating your own pages.

To facilitate this step, this package contains a template page with the minimum HTML code that your page should have to work properly. Besides this template, you'll also need a copy of the script and of the stylesheet, as indicated in the quick start procedure below:

Copy the HTMLTTChess files in a separate directory:
- The Chess Merida Unicode font chess_merida_unicode.ttf,
- The java script file html_tt_chess.js,
- The CSS file html_tt_chess.css,
- The minimum template page template.html.
Optionally, install the Chess Merida Unicode font on your system. If you don't install the font, it will be downloaded from the server and used as a web font.
The CSS file assumes that the font file is located in the same directory. If this is not the case on your server, edit @font-face tag.
Edit the template page as you which, following examples in the sample page, or the reference instructions given below.
You can customize further the output following instructions given here.

Note that in the template page, the script and stylesheet are referred to as external files. This is usually the best option if you have several html pages to provide, as would be the case on a chess-dedicated website for instance. However it is also possible to include the stylesheet and the script within the HTML page itself, which is more convenient if you have only one page to distribute (eg. as an attachment to a mail).

Here's the content of the template page:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional Chess//EN"
"http://mip.noekeon.org/HTMLTTChess/xhtml1-transitional-chess.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xmlns:c="http://mip.noekeon.org/HTMLTTChess">
<head>
	<title>HTMLTTChess template</title>
	<script type="text/javascript" src="html_tt_chess.js"></script>
	<link rel="stylesheet" type="text/css" href="html_tt_chess.css" />
</head>
<body onload="parseChess()">
<c:chess border="a1">rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR</c:chess>
</body>
</html>

The `<c:chess>` tag

The chess positions to render must be written in a (slightly modified) Forsyth-Edwards Notation (FEN). FEN is a very simple and intuitive notation that makes it very easy to read chess positions even prior rendering. Moreover it is supported by almost all mainstream chess game softwares, and hence it is very easy to import a given game position for rendering in HTML using the HTMLTTChess script.

The FEN text must be enclosed in a <c:chess> tag in order to be processed by the script. The script will scan all such tags when the html page is loaded, and will translate their content into HTML code.

The syntax of this tag is

<c:chess [border="border-attr-list"]
	[mode="color-mode"]
	[cstyle="inline-style"]
	[cclass="class-style"]>
	position-in-FEN
</c:chess>

Output of the renderer can be customized by specifying attributes to the <c:chess> tag. The possible values for each attribute and their effects are given further on this page.

`position-in-FEN` - The modified Forsyth-Edwards Notation

To render a specific chessboard position within an html page, you simply have to write it in FEN notation, and enclose the result in a <c:chess> tag.

In this case however, you do not have to specify the complete FEN, but only the first part corresponding to the position of pieces on the board (the extra fields can be given but are ignored by the parser as long as they match the FEN specification). For instance, the FEN of the starting position is given by

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

To render such position, you must only enclose the first part of the notation in the <c:chess> tag, and discard the parts corresponding to active color, castling, etc. In this case, we would write in HTML:

<c:chess>rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR</c:chess>

The position is parsed by the script, and the result is given below.

rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR

Besides this change,

Unoccupied squares - a dot (.) can be used to specify an unoccupied square. Replacing all figures in the notation by an equivalent amount of dots makes it more easy to read in HTML. So the above position can be equivalently written as rnbqkbnr/pppppppp/......../......../......../......../PPPPPPPP/RNBQKBNR
White spaces - White spaces, tabs, newlines can be inserted within the notation to improve further the readability in HTML.
Extra symbols - a plus sign (+) or x character (x) can be used to indicate squares of interest on the chessboard.
Highlighting squares - One or several squares can be enclosed within brackets ((... )) to have them highlighted in a different color.

So taking all these remarks into account, the following example would be a perfectly valid position for the script to parse, giving as result the board on the right:

<c:chess>
	r n b q k b n r/
	p p p p p p p p/
	. . . . . . . ./
	. . . . . . . ./
	. . . .(+). . ./
	. . . .(.). . ./
	P P P P(P)P P P/
	R N B Q K B N R
</c:chess>

r n b q k b n r/ p p p p p p p p/ . . . . . . . ./ . . . . . . . ./ . . . .(+). . ./ . . . .(.). . ./ P P P P(P)P P P/ R N B Q K B N R

See the sample page for more examples.

`border-attr-list` — Specifying the border style

The border attribute allows you to specify the style of the border surrounding the chessboard. The available options are:

solid	(B&W mode) Show a solid border around the chessboard. If not specified, default corner style is round. (Color mode) Show a border according to the stylesheet.
double	(B&W mode) Show a double border around the chessboard. If not specified, default corner style is round. (Color mode) Show a border according to the stylesheet.
round	(B&W mode) Show a border with round corners around the chessboard. If not specified, default border style is solid. (Color mode) Show a border according to the stylesheet.
square	(B&W mode) Show a border with square corners around the chessboard. If not specified, default border style is solid. (Color mode) Show a border according to the stylesheet.
`origin`	Specify the origin of the leftmost bottom square (eg. `a1`, `e5`, ...), and also show coordinates around the chessboard. In case where the position only shows a section of the complete chessboard, borders and coordinates for a given board side are shown only if outer squares for that side are visible in the selected section.
[n][s][e][o]	Select which border must be shown. If board origin is specified, it controls visibility of board coordinates, but visibility of borders still depends on the visibility of outer squares.
pad	Use `pad` to force renderer to print blanks for sides where coordinates are not shown. This way the chessboard is always surrounded by either a blank or a coordinate character, and hence it is easier to control alignment of the chessboard.

Please see the sample page for an illustration of these options.

`color-mode` — Color / B&W mode

The mode attribute controls whether HTMLTTChess generates colored chessboards or black&white chessboards. See for instance the two examples below:

k3/2N1/1KN1/4	`<c:chess border="double a5" mode="color">k3/2N1/1KN1/4</c:chess>`
k3/2N1/1KN1/4	`<c:chess border="double a5" mode="bw">k3/2N1/1KN1/4</c:chess>`

color-mode can have one of the following values:

color	Tell the renderer to use the color mode. Colored boards have a better look (although this can be a matter of taste), and have a rendering that is very close to the one found on eg. Wikipedia (note however that on Wikipedia, chessboards are actually made up of small images). The problem with colored boards however is that the rendering uses more advanced CSS layout techniques, and hence is more subject to be badly displayed by uncompliant browsers.
bw	Tell the renderer to use the black&white mode Besides your personal taste, there are 3 main reasons to use black & white rendering: Use it when your browser has some difficulty to render the colored version correctly. Use it if you want to easily copy & paste the rendered output to eg. an external office application (you might need to change the font of the pasted text in order for the board to appear correctly). Use it to generate printer-friendly version of your page.

color

Tell the renderer to use the color mode.

Colored boards have a better look (although this can be a matter of taste), and have a rendering that is very close to the one found on eg. Wikipedia (note however that on Wikipedia, chessboards are actually made up of small images). The problem with colored boards however is that the rendering uses more advanced CSS layout techniques, and hence is more subject to be badly displayed by uncompliant browsers.

Tell the renderer to use the black&white mode

Besides your personal taste, there are 3 main reasons to use black & white rendering:

Use it when your browser has some difficulty to render the colored version correctly.
Use it if you want to easily copy & paste the rendered output to eg. an external office application (you might need to change the font of the pasted text in order for the board to appear correctly).
Use it to generate printer-friendly version of your page.

There are two ways to specify to HTMLTTChess which mode to use when generating chessboards:

The first way is by specifying explicitly the mode to use for a given position. For instance, to specify color mode:
```
...
<c:chess mode="color">rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR</c:chess>
...
```
The second way is when no mode is explicitly specified. In this case the current default mode is used. The default mode can be changed as above but with an empty c:chess tag. For instance, to change the current default mode to black&white:
```
...
<c:chess mode="bw"></c:chess>
...
```
In this case, the specified color mode will be applied to all subsequent c:chess tags that doesn't specify explicitly a color mode, and this until the end of the file, or until it is again changed by another empty c:chess tag.

`inline-style` — Passing inline style information

Use the cstyle attribute to pass inline style information to the board table element.

Please see the sample page for an illustration of this attribute, or below for further instructions.

`class-style` — Passing class style information

Use the cclass attribute to pass class style information to the board table element. You can use this attribute to define additional custom chessboard styles in the stylesheet to use on the same page.

Please see the sample page for an illustration of this attribute, or below for further instructions.

Customizing the HTMLTTChess style

There are basically four ways to customize the style of chessboards generated by HTMLTTChess:

Edit the chess stylesheet.
Pass inline style information using the cstyle attribute.
Pass class style information using the cclass attribute.
Define new styles based on the class of the containing parent.

Editing the stylesheet

The default styles used for color-mode and B&W-mode output are defined in the CSS file html_tt_chess.css. This file is split in two parts: a base stylesheet and a custom stylesheet. The base stylesheet contains definition that shouldn't be changed or overridden. Doing so may break the rendering of chessboards. The custom stylesheet however can be freely edited to for instance change the size of the font, the color of squares, etc.

You can adapt the definitions of the custom stylesheet either by editing this file directly, or by overriding the definitions with another external stylesheet or with an internal stylesheet. Each style element that can be changed is clearly commented in the file.

Specifying inline style

You can specify inline style to be applied to a single chessboard using the cstyle attribute. Note however that this method is quite limited since it can only change the styles attached to the root <table> element of generated chessboards. Without going to far into gory technical details, this means that you can only change (cfr. CSS file html_tt_chess.css):

The size of the font.
The background color of the board (b&w mode), or the background color of coordinates (color mode).
The foreground color of the board (b&w mode), or the foreground color of coordinates (color mode).

If you need more flexibility, you must then use the cclass attribute instead.

See the source code of the sample page for an example of this method.

Specifying class style

This method allows you to change all custom styles attached to a group of chessboards, ie. including color of squares and color of highlighted squares. This is a very convenient method to use different rendering styles in a same HTML page. For instance, you can define a style for the starting position of a game you want to study, and define another style for showing intermediate positions.

To do so, you simply define a new class-style name, and define the styles to apply to chessboards you have attached this class to through the cclass attribute. You can define these styles either in an external stylesheet or in an internal stylesheet. The syntax to follow is identical to the one of the custom stylesheet in the CSS file html_tt_chess.css. To avoid lengthy explanation though, the best is that you refer to the complete example in the sample page.

Relying on the containing parent class style

This method simply relies on standard features of the cascading style sheet, namely that you can change the style of a child element based on the class of the containing parent. Have a look on the sample page for an illustration of this method.

Font-based method vs. image-based method

The usual method to render chessboards in HTML is to combine several small images together to form the complete chessboard. The server stores several small images corresponding to each combination of Black & White figurines on light & dark squares, and the HTML page simply pick the right image for each square on the board to render a given chess position. See for instance the Wikipedia page on Chess for an example of this method.

The method followed here by HTMLTTChess is quite different. Instead of using fixed-size images, it uses characters (glyphs) stored in a chess TrueType font to print a given chessboard. The font contains all necessary glyphs to render either black&white chessboards or colored chessboards. Black&White chessboards are very similar to those seen in chess books, and colored chessboards are very close to those rendered on eg. Wikipedia. This method brings several advantages:

Since font glyphs are actually vector-based graphics, chessboards can be rendered at any size without loss of quality.
A same web page can contain chessboards of different sizes, and so web masters can use this feature to improve the layout of their pages, adapting the size to each context (start position, intermediate moves...).
Sizes of chessboards are specified by the attached stylesheet. By using the em CSS unit, chessboard size automatically adapts to the size of the surrounding text.
Also, visitors may also change the size of chessboards by increasing the default font size in their browser, or by defining their own user stylesheet.
It is easy to convert color chessboard in a given HTML page to their black&white equivalent to obtain a high-quality printer-friendly version of that page.
Chessboard rendered in black&white can be easily exported to an office-like application through copy&paste.

There are some minor drawbacks though:

The rendering requires a specific font on the client. If the client does not have that font installed locally, the font is downloaded from the server as a web font (via CSS3). This might slightly increase the page rendering time; also the rendering might vary from one browser to another.
Color mode is a bit tricky, and uses CSS and tables to layout the chessboards correctly. So some uncompliant browsers may render the pages incorrectly. In these cases, black&white mode can be used instead since it is easier to render correctly. However large efforts have been done to make the script compatible with available OS/browsers. See the next section for more information.
The quality of the rendering largely depends on the font rendering engine of your platform. But ClearType (WinXP/Vista) or font anti-aliasing (Linux) give excellent results, even at low pixel per em. See the screenshots page to compare the rendering of your platform to others.

Browser/OS compatibility

Here we come in the nice world of standardization. HTMLTTChess uses a mix of tables, Unicode, Javascript and Cascade Style Sheets to layout the chess boards correctly. All pages are valid XHTML 1.0 Transitional Chess (a custom DTD identical to XHTML 1.0 Transitional but with addition of the custom tag <c:chess>). Also all pages validate as CSS. So hopefully you should be able to see these pages correctly using any Unicode-, Javascript- and CSS-compliant browser. If you have issues with chessboard rendering in color mode, you may want to give a try with B&W mode, which is much simpler to render and makes almost no use of stylesheets.

The sample page shows how it is possible to display a button on the page to switch between both modes. You may reuse this code in your own web pages so that to let the visitor chooses which mode he prefers to use. A nice extension would be to also store this preference in a web cookie so that the preferred mode is automatically restored at the next visit.

The table below contains the pairs of browser/OS that I personally tested with this script, all giving excellent results in both color and black&white modes:

Linux	The script has been successfully tested under OpenSUSE 10.2 with the following browsers: Firefox 2.0.0.x Opera 9.2x
WinXP SP2	The script has been successfully tested under Windows XP SP2 with the following browsers: Firefox 2.0.0.x IE 6, IE 7 Opera 9.2x
Win2K	The script has been successfully tested under Windows 2000 SP3 with the following browsers: Firefox 2.0.0.x IE 5 Opera 9.2x
Android	The script has been successfully tested under Android 4.4 and 5.0 with the following browser: Chrome 47 Firefox 43 Internet 2.1 Opera 34
Mac OS	Not tested. Please email me if you did.
iOS	Not tested. Please email me if you did.

Last modified on

License

HTMLTTChess comes with ABSOLUTELY NO WARRANTY. This is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

See file COPYING for more details.

Content

Download