BoardWidget_instructions

Board widget instructions

The HTML file board.html implements the basic board widget for showing games and positions in web pages and blogs, without any html coding for each game, where the chessboard widget is created using a given HTML code within the web page or blog.

The games and display options are assigned from the following URL parameters (the latest parameter list is also available browsing to board.html?help=true):

• pgnText = PGN games to display
• pgnEncoded = encoded PGN games to display (used only by web scripts like the board generator tool, see below for more details)
• fenString = FEN position to display, superceded by pgnText if set
• pgnId = id of the parent's textarea containing the PGN games (parent page/frame MUST be in the same domain)
• pgnData = URL of the file containing the PGN games (file MUST be in the same domain)
• refreshMinutes = live broadcast delay (default 0 = live broadcast disabled)
• refreshDemo = if set true sets live demo mode (default false)
• initialGame = first | last | random | a number | a search expression (default first)
• initialVariation = a number (default 0)
• initialHalfmove = start | end | random | comment | variation | a number (default start)
• autoplayMode = game (autoplay first game once) | loop (loops through games continuously) | none (default game)
• delay = autoplay delay in ms (default 1000)
• squareSize = size of square (default 28)
• pieceSize = size of pieces | default (default selects piece size based on square size)
• pieceFont = alpha | merida | uscf | random | default (default selects piece font based on piece size)
• highlightMode = border | square | none (default square)
• lightColorHex = light square color hex code, like FF0000 (default EFF4EC)
• darkColorHex = dark square color hex code, like FF0000 (default C6CEC3)
• highlightColorHex = highlight color hex code, like FF0000 (default DAF4D7)
• boardBorderColorHex = board border color hex code, like FF0000 (default 000000)
• boardShadowColorHex = board shadow color hex code, like FF0000, 'transparent' for no shadow, 'border' for same color as board border (default transparent)
• buttonsDisplay = hidden | standard (use browser's standard buttons) | custom (use custom color buttons) (default hidden)
• controlBackgroundColorHex = control buttons background color hex code, like FF0000 (default reverts to standard buttons)
• controlTextColorHex = control buttons text color hex code, like FF0000 (default 000000)
• headerDisplay = justified | centered | hidden | live | variations (default hidden)
• movesDisplay = figurine | text | puzzle | hidden (default hidden)
• textHeight = set height of the textual section, header and/or moves text, might be ignored if frameHeight is set (default 100%)
• textWidth = set width of the textual section, header and/or moves text, might be ignored if frameWidth is set (default 100%)
• textMargin = set left/right margin width of the textual section, header and/or moves text (default 0)
• commentsDisplay = hidden | inline (same line as moves) | newline (new lines) (default inline)
• fontHeaderColorHex = header color hex code, like FF0000 (default 000000)
• fontMovesColorHex = moves color hex code, like FF0000 (default 000000)
• fontCommentsColorHex = commentss color hex code, like FF0000 (default 808080)
• fontVariationsColorHex = variations color hex code, like FF0000; if set as 'comments' fontCommentsColorHex is copied (default comments)
• highlightMoveColorHex = background color hex code to highlight current move, like FF0000, 'background' for no highlight (default DAF4D7)
• fontHeaderSize = header font size (default 16)
• fontMovesSize = moves font size (default 16)
• fontCommentsSize = comments font size; if set as 'moves' fontMovesSize is copied (default moves)
• fontVariationsSize = variations font size; if set as 'comments' fontCommentsSize is copied (default comments)
• backgroundColorHex = page background color hex code, like FF0000, 'transparent' to use the parent's background color (default FFFFFF)
• horizontalLayout = if set true, shows header/moves text at the right of the board, below otherwise (default false)
• frameHeight = set height of the overall frame, as a number, as 'board' or as 'page', overriding textHeight (default not set)
• frameWidth = set width of the overall frame, as a number, as 'board' or as 'page', overriding textWidth (default not set)
• framePadding = padding within the frame (default 0)
• showHeightWidth = if set true, calculates optimal iframe dimensions (default false)
• help = true

URL parameters can be shortened: for example squareSize => sq, autoplayMode => am, highlightMoveColorHex => hmch

Also supplied textual values can be shortened: true => t, false => f

Every color parameter can by assigned also by name (like 'red') or using a proprietary encoding in base 64. For instance, the light square color, besides using the lightColorHex parameter can be also assigned using the lightColorName or the lightColorSex parameter. The latter is proprietary and used by the board generator tool.

Caveats:

• please note that web browser and servers have a limitation for the number of characters in the URL, so URL longer than 2000 chars might be rejected by some browsers or servers
• some characters are not allowed into URLs and might create problems if included in the pgnText parameter, such as: # % & ?. Those characters, if present in the PGN text should be replaced with their escape sequence: # => %23, % => %25, & => %26 and ? => %3F. See here for more details on URL characters. Even better to use the board generator tool to fully encode the PGN data and avoid this issue entirely.

Integration with third party software:

• the board widget can be integrated in third party software, like blog and forum platforms, to allow easier posting of chessboard. See the platforms integration wiki page for more details.
• the files pgn-encoder.js and pgn-encoder.php contains javascript and php code to generate the encodedPgn parameter form the PGN input. Using the encodedPgn parameter rather than the pgnText parameter for the board widget URL improves robustness and compatibility with web servers and browsers.

Below is a well known Spassky-Fischer game from the 1972 world championship, you can use the <iframe> HTML tag to show it in your web page or blog.

Click here for an example.

Below you have the (very long) link to add this chessboard to your web page using an <iframe> HTML tag (make sure you have everything on the same line). In order to help you sizing the iframe, adding the showHeightWidth=true parameter to the URL will prompt with the board dimensions.

When entering the iframe code in your website or blog, please make sure you are using the HTML editing option, otherwise the enhanced editor might alter the code you enter.

<iframe

height='720' width='600' frameborder='0' scrolling='no' marginheight='0' marginwidth='0'

src='http://pgn4web-board.casaschi.net/?
delay=1000&amp;
pieceFont=uscf&amp;
pieceSize=40&amp;
squareSize=50&amp;
lightColorHex=E5E1C6&amp;
darkColorHex=CCCBAC&amp;
highlightMode=border&amp;
highlightColorHex=FFFF00&amp;
highlightMoveColorHex=F5F587&amp;
headerDisplay=centered&amp;
movesDisplay=figurine&amp;
fontHeaderSize=80pct&amp;
fontMovesSize=80pct&amp;
fontCommentsSize=80pct&amp;
frameHeight=700&amp;
frameWidth=600&amp;
pgnText=[White "Spassky, Boris"] [Black "Fischer, Robert"] [Result "0-1"] 
[Date "1972"] [Event "World Championship"] [Site "Reykjavik"] [Round "13"] 
1. e4 Nf6 2.e5 Nd5 3. d4 d6 4. Nf3 g6 5. Bc4 Nb6 6. Bb3 Bg7  7. Nbd2 O-O 
8. h3 a5 9. a4 dxe5 10. dxe5 Na6 11. O-O Nc5 12. Qe2 Qe8  13. Ne4 Nbxa4 
14. Bxa4 Nxa4 15. Re1 Nb6 16. Bd2 a4 17. Bg5 h6 18. Bh4 Bf5  19. g4 Be6 
20. Nd4 Bc4 21. Qd2 Qd7 22. Rad1 Rfe8 23. f4 Bd5 24. Nc5 Qc8  25. Qc3 e6 
26. Kh2 Nd7 27. Nd3 c5 28. Nb5 Qc6 29. Nd6 Qxd6 30. exd6 Bxc3  31. bxc3 f6 
32. g5 hxg5 33. fxg5 f5 34. Bg3 Kf7 35. Ne5+ Nxe5 36. Bxe5 b5  37. Rf1 Rh8 
38. Bf6 a3 39. Rf4 a2 40. c4 Bxc4 41. d7 Bd5 42. Kg3 Ra3+  43. c3 Rha8 
44. Rh4 e5 45. Rh7+ Ke6 46. Re7+ Kd6 47. Rxe5 Rxc3+ 48. Kf2 Rc2+ 
49. Ke1 Kxd7 50. Rexd5+ Kc6 51. Rd6+ Kb7 52. Rd7+ Ka6 53. R7d2 Rxd2 
54. Kxd2 b4 55. h4 Kb5 56. h5 c4 57. Ra1 gxh5 58. g6 h4 59. g7 h3 60. Be7 Rg8 
61. Bf8 h2 62. Kc2 Kc6 63. Rd1 b3+ 64. Kc3 h1Q 65. Rxh1 Kd5 66. Kb2 f4 
67. Rd1+ Ke4 68. Rc1 Kd3 69. Rd1+ Ke2 70. Rc1 f3 71. Bc5 Rxg7 72. Rxc4 Rd7 
73. Re4+ Kf1 74. Bd4 f2 0-1'
>

your web browser and/or your host do not support iframes as required to display the chessboard

</iframe>

Service availability disclaimer

Before using this online service please read the service availability disclaimer note.

[Anonymous]

Originally posted by: paolocas...@gmail.com

When using the board widget for an iFrame as in the example above, the character ' is used to delimit the url property of the iFrame, therefore any ' character within the pgnText parameter will be misinterpreted as the end of the iFrame url property and the chessboard won't be displayed as intended.

In this case, please avoid ' characters within the pgnText parameter, or replace them with the escape sequence %27.