HTMLTTChess Reference Information
Creating your own page
With the font installed, you're now ready to view pages generated by HTMLTTChess, and to create new pages yourself. To do so first have a look further on this page. You will find detailed instructions on how to use HTMLTTChess. 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 page.
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 page, you'll also need a copy of the script and of the stylesheet, as indicated in the quick start procedure below:
- Copy the files
template.html,html_tt_chess.js,html_tt_chess.cssin a separate directory. - Edit the template page accordingly (use this page for more inspiration)
- Optionally, you may also customize further the style of generated chessboards.
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 replace their content by the equivalent 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 must not specify the complete FEN, but only the first part corresponding to the position of pieces on the board. 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.
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 asrnbqkbnr/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> |
|
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 |
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:
<c:chess border="double a5" mode="color">k3/2N1/1KN1/4</c:chess> |
|
<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:
|
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:chesstag. 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:chesstags that doesn't specify explicitly a color mode, and this until the end of the file, or until it is again changed by another emptyc:chesstag.
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
cstyleattribute. - Pass class style information using the
cclassattribute. - 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. 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
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.
