Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ornicar/pgn4web

Git mirror of http://code.google.com/p/pgn4web/
https://github.com/ornicar/pgn4web

Last synced: 9 days ago
JSON representation

Git mirror of http://code.google.com/p/pgn4web/

Awesome Lists containing this project

README 

        
#

#  pgn4web javascript chessboard

#  copyright (C) 2009, 2010 Paolo Casaschi

#  see README file and http://pgn4web.casaschi.net

#  for credits, license and more details

#



PGN4WEB

display chess games on web pages using javascript



ABOUT



PGN4WEB is a javascript tool showing chess PGN games as a graphical

chessboard in websites and blogs. 



It comes as software package you can to your website or blogsite, but also

provides a very simple board generator web tool helping you adding chess 

games to your website or blog without any html/javascript coding from your 

side.

 

It has been designed to make it easier adding chess games to your web 

pages and blogs, without the need of much knowledge of HTML or any 

other technicality. It also has been integrated with many popular web

software platforms and services.



***

*** THIS README FILE IS A SUMMARY OF THE PGN4WEB DOCUMENTATION

*** MORE EXTENSIVE AND UPDATED DOCUMENTATION IS AVAILABLE

*** FROM THE PGN4WEB SUPPORT WIKI REACHABLE FROM http://pgn4web.casaschi.net

*** PLEASE RELY ON THE SUPPORT WIKI RATHER THAN THIS README ONLY

***



Project homepage: http://pgn4web.casaschi.net (including downloads and wiki)

Contact email: [email protected]



Features:

- display chess games form a PGN file on a dynamic chessboard on your

  webpage or blog

- shortcut keys for navigating through the game, for selecting the

  game from the file and much more; also uses chessboard squares as 

  input buttons (hit escape for help)

- fully customizable display. Each item (board, button bar, game

  selection menu, PGN header info, game text, game comment and more)

  can be displayed (or hidden) at pleasure in your html file

- support different chess bitmaps (even custom bitmaps) and different

  chessboard sizes

- provides a very simple board generator web tool helping you adding chess 

  games to your website or blog without any html/javascript coding (see 

  http://pgn4web-board-generator.casaschi.net

- integrated with popular blog platforms (such as blogger and wordpress), 

  portal platforms (such as joomla, drupal and wikimedia), forum platforms

  (such as phpBB, simplemachines and vbulletin) and hosting services (such 

  as google sites)

- allows for live broadcast of games



Limitations:

- variations are displayed as comment, it's not possible to display

  in the chessboard positions from variations

- only one chessboard for html file (use frames if you need to display

  more in the same view)



Bugs: 

- if square brackets are present in the comments (or the game text) in a

pattern similar to the PGN header pattern '[tag "value"]' then the game 

parsing might break. If your PGN file is not displayed properly, please 

check for characters "[" and "]" in the comments and try removing them. 

Please email me for review at [email protected] any PGN file that 

pgn4web fails parsing correctly.  



Enjoy!



DEBUGGING



Errors alert messages are logged by pgn4web, such as failure to load PGN

data, incorrect PGN games or incorrect FEN strings. 

When an error is encountered, the top left chessboard square will flash

to signal the exception. 

The error alert log can be reviewed clicking on the same top left 

chessboard square.



HOW TO USE pgn4we.js



add a SCRIPT instance at the top of your HTML file:



  



The PGN input can be specified either as URL within another SCRIPT instance 

with at least the call to 



  SetPgnUrl("http://yoursite/yourpath/yourfile.pgn")



and optionally any of the other calls listed below.  



Or the PGN file can be pasted in the body of the HTML file 

within a hidden FORM/TEXTAREA statement with the ID pgnText:



  

  



  ... your PGN text ...



  

  



Example:



  

 

Then the script will automagically add content into your HTML file 

to any <div> or <span> containers with the following IDs:



  <div id="GameSelector"></div>

  <div id="GameSearch"></div>

  <div id="GameLastMove"></div>

  <div id="GameNextMove"></div>

  <div id="GameSideToMove"></div>

  <div id="GameLastComment"></div>

  <div id="GameBoard"></div>

  <div id="GameButtons"></div>

  <div id="GameEvent"></div>

  <div id="GameRound"></div>

  <div id="GameSite"></div>

  <div id="GameDate"></div>

  <div id="GameWhite"></div>

  <div id="GameBlack"></div>

  <div id="GameResult"></div>

  <div id="GameText"></div>



  <div id="GameWhiteClock"></div>

  <div id="GameBlackClock"></div>

  <div id="GameLiveStatus"></div>

  <div id="GameLiveLastModified"></div>



The file template.css shows a list of customization style options.

For better chessboard display, it is recommended to explicitly enforce 

chessboard square sizes using the ".whiteSquare" and ".blackSquare" CSS 

classes, such as:

  .whiteSquare, .blackSquare { width:40px; height:40px; }



See template.html file for an example.

See *mini.html* for an example of embedding the PGN content into the HTML file.

See http://pgn4web-demo.casaschi.net usage example, including a live broadcast

demo.

See http://pgn4web-blog.casaschi for a usage example within a blog using the

iframe html tag. 



CHESS FIGURINE DISPLAY OF MOVES



pgn4web allows displaying chess moves text using the supplied figurine fonts: 

'pgn4web ChessSansAlpha', 'pgn4web ChessSansMerida', 'pgn4web ChessSansPiratf',

'pgn4web ChessSansUscf' and 'pgn4web ChessSansUsual'. These fonts are based on

the Liberation Sans font, see credits section for more details.

To enable figurine display of chess moves text, make sure you include the

fonts/pgn4web-fonts.css file into your HTML file:

  <link href="fonts/pgn4web-fonts.css" type="text/css" rel="stylesheet" /> 

or into your CSS file:

  @import url("fonts/pgn4web-fonts.css");

Then set the font-family for the .move class to the chess font of your choice.

For example in your CSS file:

  .move {

    font-family: 'pgn4web ChessSansPiratf', 'pgn4web Liberation Sans', sans-serif;

  }

See the template.html and template.css files for an example.



THE BOARD GENERATOR WEB TOOL



The board widget allows 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. 



Just go to the board widget generator site on 

  http://pgn4web-board-generator.casaschi.net

the enter your PGN games and configure the options. The tool will 

automatically generate some HTML code that you can cut and paste in your web 

page or your blog.



THE LIVE BROADCAST OF GAMES



By setting the SetLiveBroadcast(delay, alertFlag, demoFlag) option in the 

HTML file, pgn4web will periodically refresh the PGN file, showing the live 

progress of the games. PGN files produced by the DGT chessboards are supported.



SetLiveBroadcast(delay, alertFlag, demoFlag) parameters:

 - delay = refresh interval in minutes, decimals allowed (default 1)

 - alertFlag = if set true, shows alert debug messages (default false)

 - demoFlag = if set true, sets live demo mode (default false)



The bash shell script live-grab.sh, executed on your server allows for grabbing

the updated game source from anywhere on the Internet to your server.

The live broadcast stops refreshing once all games are ended.



If your live PGN contains clock info as comments after each game such as

{1:59:59}, the clock information is displayed in the following sections:



  <div id="GameWhiteClock"></div>

  <div id="GameBlackClock"></div>



Clock information provided by the DGT chessboards (like {[%clk 1:59:59]}) is

also supported.



The status of the live broadcast is displayed in the following sections: 



  <div id="GameLiveStatus"></div>

  <div id="GameLiveLastRefreshed"></div>

  <div id="GameLiveLastReceived"></div>

  <div id="GameLiveLastModifiedServer"></div>



Clicking on the H6 square will force a games refresh.

Clicking on the A6/B6 squares will pause/restart the automatic games refresh.



The file live-template.html shows a very basic example.



A demo facility is available to test the live broadcast functionality.

If the demo flag is set in SetLiveBroadcast() and a set of full games is 

provided, the tool will simulate a slow progress of the game. Set the

proper flag in live-template.html for an example. Please note, even during

a demo, the PGN file is actually refreshed from the server for a more

accurate testing.

Alternatively, for a more realistic simulation, the bash shell script 

live-simulation.sh slowly updates the live.pgn file, simulating a real event.



The easiest way to setup a live broadcast is to use the live-compact.html file.

The HTML file accepts these parameters:

 - pgnFile = PGN file to load (default live.pgn)

 - initialGame = initial game, a number or first, last, random (default 1)

 - refreshMinutes = refresh interval in minutes, decimals allowed (default 1)

 - demo = if set true, sets live demo mode (default false)

For instance, make sure that the file myGames.pgn on your server is periodically

refreshed with the live games, then add the following iframe to your page:

<iframe frameborder=0 width=480 height=360 

        src=live-compact.html?pgnFile=myGames.pgn>

</iframe>

Of course live-compact.html can be edited to customize colors, layout and every

detail.



http://pgn4web-live.casaschi.net will occasionally broadcast live major chess

events.



CUSTOMIZATION FUNCTIONS



The following functions, if defined in the HTML file after loading pgn4web.js,

allow for execution of custom commands at given points:

- customFunctionOnPgnTextLoad(): when loading a new PGN file

- customFunctionOnPgnGameLoad(): when loading a new game

- customFunctionOnMove(): when a  move is made

- customFunctionOnAlert(message_string): when an error alert is raised

Please note the order these functions are executed; for example, when loading 

a new PGN file at the end of the first game, first customFunctionOnMove() is 

executed, then (when the game has been loaded and the move positioning 

completed) customFunctionOnPgnGameLoad() is executed and finally (when the

selected game is fully loaded) customFunctionOnPgnTextLoad() is executed.



See twic765.html or live.html for examples.



The following functions, if defined in the HTML file after loading pgn4web.js,

allow for execution of custom commands when shift + a number key is pressed:

- customShortcutKey_Shift_0()

- customShortcutKey_Shift_1()

...

- customShortcutKey_Shift_9()



SHORTCUT KEYS AND TEXT FORMS



When the HTML page contains the following script command



  SetShortcutKeysEnabled(true);



then all keystrokes for that active page are captured and processed by pgn4web; 

this allows for instance to browse the game using the arrow keys. If no other 

precautions are taken, this has also the undesirable side effect of capturing 

keystrokes intended by the user for typing in text forms when present in the 

same page: this makes the text forms unusable.



In order to have fully functional text forms in pgn4web pages, the following 

"onFocus" and "onBlur" actions should be added to the textarea forms:



  <textarea onFocus="disableShortcutKeysAndStoreStatus();" 

  onBlur="restoreShortcutKeysStatus();"></textarea> 



See the inputform.html HTML file for an example.



TECHNICAL NOTES ABOUT WEB BROWSERS



pgn4web is developed and tested with recent versions of a variety of 

browsers (Arora, Blackberry browser, Chrome, Epiphany, Firefox, Internet 

Explorer, Opera, Safari) on a variety of personal computer platforms 

(Linux/Debian, MacOS, Windows) and some smartphone/pda platform (Android, 

Blackberry, Apple iOS for iPhone/iPad/iPod).

Not every browser version (please upgrade to a recent release) has been 

tested and not every combination of browser/platform has been validated. 

If you have any issue with using pgn4web on your platform, please email 

[email protected] 



Note about Google Chrome: you might experience problems when testing HTML

pages from your local computer while developing your site. This is a

security limitation of the browser with respect to loading local files. 

The limitation can be bypassed by starting Google Chrome with the command 

line switch '--allow-file-access-from-files'. Browsing pgn4web websites

with Google Chrome should work properly.



Note about Internet Explorer v7 and above: under some circumstances you might

experience problems when testing HTML pages from your local computer while 

developing your site. If this happens to you, read notes at 

http://code.google.com/p/pgn4web/issues/detail?id=23 



PGN STANDARD SUPPORT



pgn4web mostly supports the PGN standard for chess games notation (see 

http://www.tim-mann.org/Standard). Notable exceptions and limitations:



- variations are not parsed as such, but stored as comments; support for 

browsing variations is planned for a future release

- if square brackets are present in the comments (or the game text) in a

pattern similar to the PGN header pattern '[tag "value"]' then the game 

parsing might break. If your PGN file is not displayed properly, please

check for characters "[" and "]" in the comments and try removing them.

- only pieces initials in the English language are supported, the use of

alternative languages as specified by the PGN standard is not supported

(pgn4web can however display chess moves text using figurine notation, so

the language issue should not be much of a problem, just make sure your

chess software produces PGN data with English pieces initials).



pgn4web also follows a set of proposed extensions to the PGN standard

(see http://www.enpassant.dk/chess/palview/enhancedpgn.htm), more 

specifically:



- understands the [%clk 1:59:58] tag in the PGN comment section as the 

  clock time after each move

- understands the PGN tags [WhiteClock "2:00:00"] and 

  [BlackClock "2:00:00"] as the clock times at the beginning of the game

- defines the [%pgn4web internal comment] tag in the PGN comment section 

and stores the internal comment value for internal use. 



Please email me for review any PGN file that pgn4web fails parsing correctly. 



CHESS960 SUPPORT



pgn4web supports Chess960 (a.k.a. Fischer random chess) and understands both 

the X-FEN and the Shredder-FEN extensions to the FEN notation.



JAVASCRIPT CODING



As of pgn4web version 1.72, the pgn4web.js code is checked with the lint

tool (see online version at http://www.javascriptlint.com/online_lint.php).

Plase note that warnings "lint warning: increment (++) and decrement (--) 

operators used as part of greater statement" are ignored.

Lint validation should allow for easy compression of the javascript code,

for instance using http://javascriptcompressor.com/ 

Although a compression beyond 50% can be achieved, only the uncompressed

version is distributed, but if you want to use a compressed version on your

site, the pgn4web.js code should support it.



CREDITS AND LICENSE



javascript modifications of Paolo Casaschi ([email protected]) on code 

from the http://ficsgames.com database, in turn likely based on code from the 

LT PGN viewer at http://www.lutanho.net/pgn/pgnviewer.html



PNG images from http://ixian.com/chess/jin-piece-sets (creative commons 

attribution-share alike 3.0 unported license)



The figurine fonts are derived from the Liberation Sans font (released under

GNU General Public License, see https://fedorahosted.org/liberation-fonts/)

with the addition of chess pieces from freeware fonts: the alpha2 font (Peter

Strickland), the good companion font (David L. Brown), the merida font (Armando

H. Marroquin), the pirate font (Klaus Wolf) and the chess usual font (Armando

H. Marroquin). The original chess fonts and more details are available at 

http://www.enpassant.dk/chess/fonteng.htm

 

Some of the PGN files for the examples are coming from "The Week in Chess" at 

http://www.chesscenter.com/twic/twic.html (files wch08ak.pgn and twic765.pgn) 

and from the scid project at http://scid.sourceforge.net (file tactics.pgn).



The jscolor javascript code is  maintained by Honza Odvarko 

(http://odvarko.cz/) and released under the GNU Lesser General Public License 

(http://www.gnu.org/copyleft/lesser.html)

See http://jscolor.com/



The above items remains subject to their original licenses (if any).



Remaining pgn4web code is copyright (C) 2010 Paolo Casaschi



This program is free software; you can redistribute it and/or modify

it under the terms of the GNU General Public License as published by

the Free Software Foundation; either version 2 of the License, or

(at your option) any later version.



This program is distributed in the hope that it will be useful,

but WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

GNU General Public License for more details.



You should have received a copy of the GNU General Public License along

with this program; if not, write to the Free Software Foundation, Inc.,

51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.



See license-gpl-2.0.txt license file.



You are free to use pgn4web in your website or blog; you are not required to

acknowledge the pgn4web project, but if you want to do so the following line

might be used:

javascript chess viewer courtesy of <a href=http://pgn4web.casaschi.net>pgn4web</a>



You are also encouraged to notify [email protected] that you are using 

pgn4web.



END