Fork me on GitHub

pgn-viewer

Version 1.6.10

ML

API

The following documentation explains in detail how to use the pgn-viewer. It tries to be a reference that can be used to modify and adapt working examples. For some of the examples, see the examples section and use them as starting template.

The configuration builder allows to try out the whole API of the configuration at one place, and extract a resulting configuration from there.

Configuration

The configuration is used when calling one of the APIs of the pgn-viewer. Depending on the kind of API (see below), the configuration paramemter may have no effect.

All the configuration can be used to define a global default, that is then used for the page on which it is used. Be aware that this only works if the global default is loaded before the pgn-viewer library. See the example Global Defaults how that is done.

Property / Type Required Default Description Example
ID yes - ID of the container for board, moves, and buttons. Has to be unique on that HTML page. All examples
mode yes - This will be automatically set by using one of the (currently) 4 provided calls: pgnView, pgnBoard, pgnEdit, pgnPrint. The corresponding modes are: view, board, edit, print. Don't try to set that on your own!!. -
pgn no - The moves of the game. Only necessary, if a whole game should be shown. The moves are then shown in a container that may be additionally styled by the theme selected. Game Examples
pgnFile no - The moves of the game denoted by an URL. Reads the content depending on the URL. Game Examples
position

'start' or FEN string

no 'start' Defines the position of the board, or where the game starts. Position examples
theme no default The theme will be added to all classes of divs for the board, the moves, the buttons, ... It tries to reproduce typical designs used in chess books, online sites, you name it. And you may of course add your own themes. Current themese are: green, zeit, informator, sportverlag, beyer, falken, blue. The theme can be added to CSS (as class) or as parameter to the configuration: theme: 'beyer'.
Warning! Don't use both inline CSS and configuration parameter for setting the theme.
Theme and Style Examples.
pieceStyle

'wikipedia', 'alpha', 'uscf' (all from chessboardjs), 'case', 'condal', 'maya', 'merida' (my favorite), 'leipzig' (all from ChessTempoViewer), and 'beyer' (from German chess books).

no 'wikipedia' Defines the piece style to take. These are all PNG files, that are then scaled by the browser. The piece style can be added to CSS (as class) or as parameter to the configuration: pieceStyle: 'merida'.
Warning! Don't use both inline CSS and configuration parameter for setting the piece style.
Piece Style Examples
layout

Layout of the board and moves. Available are: left, right, top, bottom

no top Denotes the layout of the board relevant to the moves. top is board over moves, left is board on the left, and moves on the right ... Layout Examples (and following)
width

Width of the whole div.

no - Denotes the width of the div widget. Width of board
boardSize

Size of the board (in CSS terms like '300px')

no - Size of the board that is set on the DIV for the board. Size of boards
resizable

Allow to resize the board

no true Add a resize handle, that allows to resize the board after the rendering. Resizable board
movesWidth

Width of the moves div.

no - Set the width of the moves div. Is relevant depending on the layout, and the size the whole div takes. Moves width
movesHeight

Height of the moves div.

no - Set the height of the moves div. Automatic computed with layout left and right, only relevant for layout top and bottom. NOT THERE
notationLayout

The layout of the notation in the moves section.

no inline Select the layout of the moves section. Available are: inline, list. Default is inline. Notation layout: list
timerTime no 700 milliseconds Time in milliseconds, when a game is shown by autoplay. timerTime set
orientation

Possible values are 'white' and 'black'

no 'white' Defines if the board has 'white' at the bottom or 'black'. May be switched at any time, if the buttons are rendered, that include an orientation-switch button. Orientation black
notation

Possible values are 'short' and 'long'

no 'short' To show moves in short or long notation. Notation short and notation long
headers no false To show the tags if available. Default is false. Layout with headers
showCoords no true Defines if the columns and rows should be show the coordinates a to h (for the columns) and 1 to 8 (for the rows). If shown, it could be styled by CSS. showCoords: false
coordsInner

False, if coordinates of the ranks should be shown outside of the board.

no true Set to false, if coords should be shown on the outside. Default is true. coordsInner: false
coordsFactor

Factor by which the coords font size should be multiplied.

no 1.0 Factor by which the coords font size should be multiplied. Default is 1.0. CoordsFactor second example
coordsFontSize

The font size for the coordinates (in pixels).

no - The font size to set for coordinates. Overwrites the defaults, and coordsFactor. CoordsFontSize third example
showFen

If fen should be displayed.

no true in edit mode, else false If fen text widget should be shown. Writable in edit mode, else readable. ShowFen: true
colorMarker

Show a mark for the player that has the next move.

no - Color marker who has the next move. Available are: anything (will be square), circle, additional size: small, big (default is medium). 3 colorMarker
locale

Currently supported are cs, da, de, en, es, et, fi, fr, hu, is, it, nb, nl, pl, pt, ro, sv

no 'en' Locale used for rendering figure symbols, NAG notation, ... Locale Examples en (default), de and fr
startPlay

Move where the positions should be shown (only view and edit mode)

no none Move where the position should be shown. Possibilities are: FEN, move number (half move), or the move itself. Start Play (4 examples)
hideMovesBefore no false True, if move before startPlay should be hidden. Hide Moves Before
showResult

Denotes if the result should be shown.

no false True, if the result of the game should be shown at the end of the pgn notation. Default is false Show Result == true
timeAnnotation

Styles the time annotations.

no none {class: 'timeTiny', colorClass: 'blue'} to show tiny font with color 'blue'. Different timeAnnotation
manyGames

True, if more than one game should be displayed.

no false Set to true, if you want to read and display many games. Will show then a drop-down with a computed title for the games. Different timeAnnotation
figurine

Shows the pgn with figurine notation

no null Set to one of any value (== alpha), merida, berlin, noto, cachess, to select the font to use. Figurine examples
drawable

Shows the pgn with figurine notation

no true Define if on-board annotations (arrows, circles) should be shown. Default true.

Functions

The relevant functions are different ways to use the same base functionality.

Function Required parameters Optional parameters Description Example
pgnBoard ID, position theme, pieceStyle, orientation, showCoords, width, boardSize, coordsInner, coordsFactor Displays (only) a board, in the size given by the container. Board Examples
pgnPrint ID, pgn theme, pieceStyle, orientation, showCoords, width, boardSize Shows the whole game in a notation seen normally in magazines or books. Does not allow to play the game interactively. Print Example
pgnView ID, pgn position, theme, pieceStyle, ... Shows the whole game (including the moves with comments, variations, ...) so that the reader may replay the game. There are some key bindings, so by pressing LEFT or RIGHT, the moves are played forth and back. Viewer Example
pgnEdit ID pgn, ... Allows to replay the game, and try variations that are automatically recorded and shown. By pressing the PGN button, the reader gets a text script that may be later used. Edit Example
pgnPuzzle ID pgn, ... Shows in a starting position a puzzle, where the player is able to guess the next move. As long as the next move is the right one, the move is answered by an automatic reply. Puzzle Example