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.
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
|
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
|
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: |
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 |
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 |
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 |
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. |
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 |