HowTo

Applications notes: HowTo

"Always use the latest release of pgn4web; when using pgn4web for official events and for live broadcasts, read this first and don't hesitate contacting the pgn4web project for support!"
the pgn4web project

debugging

pgn4web logs errors alert messages (such as failure to load PGN data, incorrect PGN games or incorrect FEN strings) and signals those by flashing unintrusively the chessboard at regular intervals. Please refer to the debugging page for more information and for an example.

enabling pgn4web in your HTML file

To enable pgn4web, add a script instance at the top of your HTML file:

  <script src="pgn4web.js" type="text/javascript"></script>

The PGN input can be specified either as URL within another script instance with at least the call to

  SetPgnUrl("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 id=pgnText:

  <!-- paste your PGN below and make sure you dont specify an external source with SetPgnUrl() -->
  <form style="display: none;"><textarea style="display: none;" id="pgnText">

  ... your PGN text ...

  </textarea></form>
  <!-- paste your PGN above and make sure you dont specify an external source with SetPgnUrl() -->

Example:

  <script type="text/javascript">
    "use strict";

    SetPgnUrl("yourpath/yourfile.pgn");
    SetImagePath("images");
    SetImageType("png");
    SetHighlightOption(true); // true or false
    SetGameSelectorOptions(null, false, 0, 0, 0, 15, 15, 0, 10); // (head, num, chEvent, chSite, chRound, chWhite, chBlack, chResult, chDate);
    SetCommentsIntoMoveText(false);
    SetCommentsOnSeparateLines(false);
    SetAutoplayDelay(1000); // milliseconds
    SetAutostartAutoplay(false);
    SetAutoplayNextGame(false); // if set, move to the next game at the end of the current game during autoplay
    SetInitialGame(1); // number of game to be shown at load, from 1 (default); values (keep the quotes) of "first", "last", "random" are accepted; other string values assumed as PGN search string
    SetInitialVariation(0); // number for the variation to be shown at load, 0 (default) for main variation
    SetInitialHalfmove(0,false); // halfmove number to be shown at load, 0 (default) for start position; values (keep the quotes) of "start", "end", "random", "comment" (go to first comment or variation), "variation" (go to the first variation) are also accepted. Second parameter if true applies the setting to every selected game instead of startup only (default)
    SetShortcutKeysEnabled(false);

    SetLiveBroadcast(1, false, false, false, false); // set live broadcast; parameters are delay (refresh delay in minutes, 0 means no broadcast, default 0) alertFlag (if true, displays debug error messages, default false) demoFlag (if true starts broadcast demo mode, default false) stepFlag (if true, autoplays updates in steps, default false) endlessFlag (if true, keeps polling for new moves even after all games are finished)

  </script>

Then the script will automagically add content into your HTML file to any div or span containers with the following id values:

  <div id="GameSelector"></div>
  <div id="GameSearch"></div>
  <div id="GameLastMove"></div>
  <div id="GameLastVariations"></div>
  <div id="GameNextMove"></div>
  <div id="GameNextVariations"></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="GameLiveLastRefreshed"></div>
  <div id="GameLiveLastReceived"></div>
  <div id="GameLiveLastModifiedServer"></div>

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

For better chessboard display, it is recommended to explicitly enforce chessboard and square size using the .boardTable, .whiteSquare and .blackSquare CSS classes, such as:

  .boardTable { width:326px; height:326px; border-width:3px; } /* account for chessboard and squares border here, if any */ 
  .whiteSquare, .blackSquare { width:40px; height:40px; }

See template.html file for a general example.

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

The pgn4web scripts and pages are optimized for the HTML5 doctype declaration:

<!DOCTYPE HTML>

chess figurine display of moves

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

• 'pgn4web ChessSansAlpha'
• 'pgn4web ChessSansMerida'
• 'pgn4web ChessSansPiratf'
• 'pgn4web ChessSansUscf'
• 'pgn4web ChessSansUsual'

These fonts are based on the Liberation Sans font, see the credits section for more details, that is provided as well for overall consistent display of moves, text and headers.

To enable figurine display of chess moves text, make sure you include the corresponding fonts/pgn4web-font-ChessSansPiratf.css file toghether with the font/pgn4web-font-LiberationSans.css file into your HTML file:

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

or into your CSS file:

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

Then set the font-family for the .move, .variation and .commentMove classes to the chess font of your choice and the rest of the page to the Liberation Sans font. For example in your CSS file:

  body {
    font-family: 'pgn4web Liberation Sans', sans-serif;
  }
  .move, .variation, .commentMove {
    font-family: 'pgn4web ChessSansPiratf', 'pgn4web Liberation Sans', sans-serif;
  }

When using chess figurine fonts it's strongly recommended to activate the smooth fonts display feature of the client operating system (active by default on most current systems).

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

chess informant symbols

pgn4web allows for showing chess informant style symbols when the corresponding PGN NAGs (Numeric Annotation Glyphs) are found in the PGN comments. This feature is disabled by default; in order to enable it in your HTML page, please include the script below immediately after the main pgn4web script:

  <script src="pgn4web.js" type="text/javascript"></script>
  <script src="fonts/chess-informant-NAG-symbols.js" type="text/javascript"></script>

Warning: unlike with figurine fonts, if the user's web browser does not fully support web fonts, there's not elegant textual fallback and the game comments will appear garbled or incorrect.

See the chess-informant-template.html and collection-example.thml (chess informant sample) files for an example.

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
• customFunctionOnCheckLiveBroadcastStatus(): when a live broadcast is checked

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.

The function customPgnHeaderTag(customTagString, htmlElementIdString, gameNumber) is available for use in customFunctionOnPgnGameLoad() to parse custom PGN header tags and automatically assign their value to the given HTML elements. The function returns the custom tag value and the gameNumber parameter, if unassigned, defaults to the current game. For example, this allows showing the information from the PGN header tag ECO: first add to the page the HTML element <div id="myECO"></div>; then add to the customFunctionOnPgnGameLoad() function the statement customPgnHeaderTag("ECO", "myECO");

The function customPgnCommentTag(customTagString, htmlElementIdString, plyNumber) is available for use in customFunctionOnMove() to parse custom PGN comment tags like { [%pgn4web info] } and automatically assign their value to the given HTML elements. The function returns the custom tag value and the plyNumber parameter, if unassigned, defaults to the current ply.

See twic944.html or live.html for examples with the custom functions.

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 wiki page Example_PGN_Form and the underlying inputform.html HTML file.

examples and links

See the examples and templates wiki page.

See the live broadcast wiki page for more info about broadcasting live games.

See the user sites gallery wiki page for example of pgn4web usage.

See the user notes wiki page for feedback and tips from other pgn4web users.

[Anonymous]

Originally posted by: pa...@casaschi.net

custom font display and Internet Explorer 9 issue

Current version of Internet Explorer 9 (9.0.8112.16421 at the moment of writing) seem to have an issue with applying a custom font to the body element as suggested in the notes above. As a result the proposed .body statement might not work as expected with Internet Explorer 9.

A possible fix is to manually assign the custom font to every relevant element, with a statement like the following:

  div, span, table, tr, td {
    font-family: 'pgn4web Liberation Sans', sans-serif; /* fixes IE9 body css issue */
  }