PgnViewerJS is a simple JavaScript implementation to show PGN files (Portable Game Notation == Chess) in a web page. PgnViewerJS does not write everything anew, but it uses the following libraries:
- chess.js Base library to model chess in JavaScript
- Chessground The chessboard used by lichess.org
- pegjs Parser Generator implemented in Javascript.
See the section Acknowledgments for more supporting libraries.
See the working examples on my new GitHub Pages site PgnViewerJS, especially the Configuration Builder that demonstrates all parameters in a running example.
The easiest way to use it is to install it by using NPM: npm install @mliebelt/pgn-viewer. You will find there the diretory lib that contains everything. Copy that onto your webserver.
The following are example screenshots with the configuration set below, to show the rich possibilities of PgnViewerJS.
The screenshots show from left to right:
mode: board; theme: sportverlag; pieceStyle: uscfmode: edit; orientation: black; locale: dewith commentsmode: view; layout: 'left'with comments
Go to the github.io pages (documentation), where the current (and former) versions are available.
This implementation has the following features:
- Allows to show one chess game complete, with a lot of different styles, themes, tuning, ...
- Allows to play through the games forward and backward, including variations.
- Allows to play from a legal position only legal moves, and adds these moves to the notation (in a different style)
- Allows to play through by
- clicking on moves
- clicking on next and previous button
- clicking on play button
- using cursor left and right on the keyboard
- Allows to add moves to a game, when in the right 'mode'.
- Knows all PGN notation elements, and knows how to render them.
There are four different kind of usages:
PGNV.pgnViewrenders the whole game, and allows to play it through, jump to any position.PGNV.pgnEditis a superset of pgnView, that allows to additional add variations, change the order of main line and variations, and allows all other kind of interactions that are possible: adding comments, PGN notation elements, whatever.PGNV.pgnBoardwill just show a position without any interaction possible.PGNV.pgnPrintwill just show a whole chess game, without any interaction possible.
There is at the moment no way to save a game that was edited in pgnEdit mode. But you may at least copy the whole notation, and insert it again in the HTML code of your web page.
- Run
npm test. This runs the tests for the modulepgn-reader.
- Copy the files from directory
libinto a web server. - Create new HTML files with the corresponding head and body.
- Clone the repository.
- Run
npm installfrom the root, to ensure are tools are installed. - Run
npm buildto both modules (first pgn-reader, then pgn-viewer) build a distribution. - Copy the files from the directory
modules/pgn-viewer/lib. - Create new HTML files with the corresponding head and body.
To use the viewer in an HTML page, you have to do the following steps:
- Include the necessary library
pgnv.jsand the corresponding resourceslocalesandpgnv-assets. - Have Fontawesome referenced.
- Include the necessary div container for rendering of the board and the moves.
- Include JavaScript code inside your HTML page to call the viewer.
So a rough template will look like:
<!DOCTYPE html>
<head>
<script src="js/pgnv.js" type="text/javascript" ></script>
</head>
<body>
<div id="board"></div>
<script>
PGNV.pgnView('board',{ pgn: '1. e4 e5 2. Nf3 Nc6 3. Bb5', pieceStyle: 'merida' });
</script>
</body>
</html>import React, {useLayoutEffect} from 'react'
import Children from 'react-children-utilities'
import * as uuid from 'uuid'
import { pgnView } from '@mliebelt/pgn-viewer'
function PGNViewer(props) {
const gameDecription = Children.onlyText(props.children)
const id = 'board-' + uuid.v4()
useLayoutEffect(() => {
pgnView(id,
{
pgn: gameDecription,
timerTime: '1',
locale: 'pl',
startPlay: 1,
showResult: true,
boardSize: '340',
showFen: true,
pieceStyle: 'chesscom'
}
)
})
return (
<div id={id}></div>
)
}
// Usage
<PGNViewer>
[Event "F/S Return Match"]
[Site "Belgrade"]
[Date "1992.11.04"]
[Round "29"]
[White "Fischer, Robert J."]
[Black "Spassky, Boris V."]
[Result "1/2-1/2"]
1. e4 e5 2. Nf3 Nc6 3. Bb5 a6 4. Ba4 Nf6 5. O-O Be7 6. Re1 b5 7. Bb3 d6 8. c3 O-O 9. h3 Nb8 10. d4 Nbd7
11. c4 c6 12. cxb5 axb5 13. Nc3 Bb7 14. Bg5 b4 15. Nb1 h6 16. Bh4 c5 17. dxe5 Nxe4 18. Bxe7 Qxe7 19. exd6 Qf6
20. Nbd2 Nxd6 21. Nc4 Nxc4 22. Bxc4 Nb6 23. Ne5 Rae8 24. Bxf7+ Rxf7 25. Nxf7 Rxe1+ 26. Qxe1 Kxf7 27. Qe3 Qg5
28. Qxg5 hxg5 29. b3 Ke6 30. a3 Kd6 31. axb4 cxb4 32. Ra5 Nd5 33. f3 Bc8 34. Kf2 Bf5 35. Ra7 g6 36. Ra6+ Kc5
37. Ke1 Nf4 38. g3 Nxh3 39. Kd2 Kb5 40. Rd6 Kc5 41. Ra6 Nf2 42. g4 Bd3 43. Re6 1/2-1/2
</PGNViewer>If you find something strange (bug), expect some feature (feature) or just want to comment on anything, please file first a ticket in Github.
If you want to help in implementing something, clone the repository, change whatever you want to, and provide a pull request that I can look at.
We use SemVer for versioning. For the versions available, see the tags on this repository.
From the version 1.0.0 on, the whole package can be downloaded / installed by using NPM:
- Download:
npm pack @mliebelt/pgn-viewerResults in download of a filemliebelt-pgn-viewer-1.3.0.tgz, that contains in the directorypackage/liball resources needed. - Install:
npm install @mliebelt/pgn-vieweras part of some other application. You will find then the files in the directorynode_modules/@mliebelt/pgn-viewer/lib.
The older versions are available for download from the links below.
- Version 0.9.8: Start play parameter, allow arrows and circles from Chessground, color marker for player at move, option for result in PGN notation.
- Version 0.9.7: UI with Chessground, small improvements, promotion.
- Version 0.9.6: A lot of fixes, multi-line notation, stability.
- Version 0.9.5: Some more fixes, stability.
- Version 0.9.4: Finished edit mode, cleanup, some more fixes.
- Version 0.9.3: Allows special markup, some more bug fixes.
- Version 0.9.2: Some more bug fixes, examples to all issues at GitHub, added Changelog.md, started restructuring the sources.
- Version 0.9.1: Some bug fixes, examples to all issues at GitHub, some additional examples and a lot of fixes in the documentation.
- Version 0.9.0: Nearly feature complete, roughly documented, stable enough to play with it.
- Markus Liebelt - mliebelt
PgnViewerJS is licensed under the Apache license 2.0, see the LICENSE.md file for details.
We use the following libraries in the implementation:
- chess.js Base library to model chess in JavaScript
- Chessground The chessboard used by lichess.org
- pegjs Parser Generator implemented in Javascript.
- Mousetrap Binds keys to actions in the UI
- roddeh-i18n Internationalization (== i18n) library to translate chess into current 18 languages. Strings are inlined in the library.
- Timer.js Small timer for automatic moves
- FontAwesome: Nice icon font used for some buttons
- PGN Specification: PGN (Portable Game Notation) specification
- NAG Specification Definition of the NAGs (Numeric Annotation Glyphs)
Thank you a lot to all contributors of issues.
- PgnJS Plugin for Mediawiki that uses PgnViewerJS to display chess games.
- PgnViewerJS-WP Plugin for Wordpress to show games with the help of PgnViewerJS