How-to: Chess Game Viewer

What is a Chess Game Viewer?

A Chess Game Viewer is a software application that converts a chess or chess960 game formatted as a PGN (Portable Game Notation) text file into an easily viewable interface with which you can play through the moves using a graphical chess board and pieces.

What can I use it for?

If you have a chess or chess960 game formatted as a PGN text file, you can import that game into the viewer and then easily and quickly play through the moves.

Our intrepid chess warrior, AgentSmith, has been losing a lot lately. For inspiration he has decided to review some famous chess games. After rummaging around the Internet for a while, he tracked down PGN file containing the "Immortal Game":
[Event "Immortal game"]
[Site "London"]
[Date "1851.??.??"]
[Round "?"]
[White "Anderssen,A"]
[Black "Kieseritzky,L"]
[Result "1-0"] 

1.e4 e5 2.f4 exf4 3.Bc4 Qh4+ 4.Kf1 b5 5.Bxb5 Nf6 6.Nf3 Qh6 7.d3 Nh5 8.Nh4 Qg5 9.Nf5 c6 10.g4 Nf6
11.Rg1 cxb5 12.h4 Qg6 13.h5 Qg5 14.Qf3 Ng8 15.Bxf4 Qf6 16.Nc3 Bc5 17.Nd5 Qxb2 18.Bd6 Qxa1+
19.Ke2 Bxg1 20.e5 Na6 21.Nxg7+ Kd8 22.Qf6+ Nxf6 23.Be7# 1-0
This presentation of the game is certainly informative, but not very inspirational. AgentSmith wants to see the moves in action. Oh wait, doesn't Caissa's Web have a Chess Game Viewer...

How does the Chess Game Viewer provided by Caissa's Web work?

The Chess Game Viewer basically works in two modes: a game is already entered and viewable (View Mode), or the viewer can import any PGN file you like for viewing (Import Mode).

View Mode

Chess Viewer View Mode

In "View Mode," the Viewer has a game "pre-installed" and ready for viewing. In this case, you can use the playback buttons to move forward and back through the moves.

You can see a list of moves and any evaluation symbols in the move list to the right of the board. You can click on a move in the list to go directly to that move. The title bar across the top of the viewer interface includes the event, location, and date of the game.

You can view the underlying PGN file by clicking the "View PGN" button.

A text box below the board will update with any commentary associated with a move.

Import Mode

Chess Viewer Import Mode

In "Import Mode," the Game Viewer is ready for you to feed it a tasty PGN file for viewing (note that a default game may still be pre-installed).

Click the "Import PGN" button to the right of the board. You will be presented with a form into which you can copy-and-paste the text of the PGN file. If a game was previously entered, you will see its PGN file already entered. Choose the "Clear" button to delete that game and then paste in your PGN text. Choose "Import" and you will be taken back to the main viewer screen with your imported game ready to view (see "View Mode" above for viewing options).

Additionally, after you import a game and it is viewable, you will be given the Embed Code for the viewer and game you just imported. You can copy-and-paste the Embed Code into any web-enabled document so that others may view the game just as it is presented to you.

In most cases the default Embed Code will work fine. However we do offer two configuration options to customize the embedded Game Viewer to your specific situation. These options appears above the text box with the embed code and are check boxes labeled Small and Popup.

Small viewer option. If the width of the main content area of your blog or website is limited, you can choose this option so the Game Viewer will fit properly. Specifically, this option generates a viewer that is 460px wide by 296px high (the default viewer size is 590px by 420px).

Popup viewer option. This option will translate your PGN file into a hypertext link that when clicked will popup a new browser window with the Game Viewer in it. This is useful if you have a long list of games that you want to be viewed. It is particularly useful if you have a crosstable for a tournament and you want each game to be viewable via a hypertext link.

Example cont'd:

AgentSmith is feeling the chess love. He knows that if he can just get his eyeballs on this Immortal Game, he will be inspired to go out and kick some chess you-know-what. So he navigates to the Caissa's Web Chess Game Viewer, clicks the "Import PGN" button, and pastes in the game. Behold the Immortal Game:

Play Online Chess

After viewing the game, AgentSmith goes on to win 18 straight chess games and increases his rating by over 100 points. That's inspiration!

Here's a sample of the "Small" embed option:

Play Online Chess


And finally here are samples of the "Popup" embed options:

Anderssen,A-Kieseritzky,L  (Default size)
Anderssen,A-Kieseritzky,L  (Small size)

Tips & Tricks

Warning! The tips & tricks listed here are suggested for advanced users only. Although you (probably) can't break anything, you could end up with a funkily formatted Chess Game Viewer. You've been warned! (Contact us if you are having trouble).

Chess Viewer Embed Code

Embed Code URL Parameters
If you choose to embed the Chess Game Viewer into your blog or website, either as a tool or as a stand-alone viewer, the embed code that we provide to you can be manually altered to suit your needs. Although we do not officially support altering the embed code, there is one part of the code that can be modified: the URL that is the source of the iframe containing the viewer.

Various parameters can be appended to the URL to change the presentation of the Viewer. To append the parameters, add a question mark (?) to the end of the base URL and then add the parameter. Here's an example, with parameters in bold:

To append more than one parameter, separate them with an ampersand (&):

A description of the parameters and their values is below.

The first parameter is "mode." It controls the default functionality of the viewer.

  • mode=v

    This represents "View mode." An embedded viewer set to this mode will allow a user to view the "pre-installed" game as well as the underlying PGN file, but not to import a new game. See the description of "View mode" above. This is the default mode, so leaving off this parameter entirely will have the same effect.

  • mode=g

    This represents "Game mode." It is the same as the "View mode" except without the "View PGN" button. In this mode, a user would only be able to view the game; they would not be able to see the underlying PGN file.

  • mode=i

    This represents "Import mode." An embedded viewer set to this mode will allow a user to import a PGN file and then view and output the game. See the description of "Import mode" above.

  • mode=p

    This represents "PGN mode." When a Viewer is set to this mode, the user will initially see the raw text of the PGN file. They can then choose to "View Game Board" and play through the moves.

The next parameter is "pieces." This refers to the style of chess game pieces that will used in the viewer.

  • pieces=[#]

    This can be any number 1 thru 4. Note that the default piece value is 3.

The next parameter is "theme." This refers to the color combination of the chess board — light squares, dark squares and border — that will used in the viewer.

  • theme=[xx]

    The pre-defined color schemes are: bb=blue/blue, gg=green/green, rr=red/red, oo=orange/orange, yy=yellow/yellow, pp=purple/purple, mm=gray/gray, nn=brown/brown, tt=ocean/ocean, bw=blue/white, gw=green/white, rw=red/white, ow=orange/white, yw=yellow/white, pw=purple/white, mw=gray/white, nw=brown/white, tw=ocean/white.

The next parameters are "lsqr," "dsqr," "bord." These are similar to the Theme parameter in that they allow even greater customization of the chess board by specifying individual colors for the light squares, dark squares and border around the board.

  • lsqr=[color in hexadecimal format]

    This is the color of the light squares.

  • dsqr=[color in hexadecimal format]

    This is the color of the dark squares.

  • bord=[color in hexadecimal format]

    This is the color of the border around the board.

The next parameter is "bg." This refers to the background color of the screen onto which the board and other functions have been placed.

  • bg=[color in hexadecimal format]

    The color must be in hexadecimal RGB format, e.g. "ff0000" would result in a red background.

The next parameter is "logo." This allows you to custom-brand the Viewer so that your blog or website logo is presented with the game and Viewer. Additionally, anyone who imports a PGN file using your Chess Game Viewer and then outputs and embeds that game at another location will carry your logo with them.

  • logo=[encoded URL of the graphics file]

    In order to custom brand your Viewer, you must first have a graphical logo. The file format can be any web-enabled graphics file (GIF, PNG, etc). The dimensions of the graphic should be 234x60 pixels. With regard to the size of the file, it is recommended you optimize it so that it is as small as possible. Once you have the file, you must host it somewhere. You can put it on an existing blog or website, or you could host it at a free image hosting service. Once hosted, you will be provided with a URL to the location of the file. Enter the encoded URL as the value for the logo parameter. Use standard URL encoding, e.g. "" becomes "". Contact us for help with URL encoding.

Example cont'd:

AgentSmith gets ambitious and decides to customize his viewer. Here is the iframe URL with parameters added (notice the encoded URL for the logo):

Play Online Chess

Notice that the Viewer is in "Game mode", the piece type value is "1", the board theme is "bw", the background is red, and a custom logo has been entered. Cool, huh?

And finally, the same game and parameters using the small Game Viewer option:

Play Online Chess

Pre-loading a Game
To pre-load a game, send a POST parameter with the name "data" and a value of the PGN text of the game. You can also send the other parameters (such as mode or bg) as POST parameters if you prefer. This can be useful if you'd like to use your own forms or scripts for game selection. Don't worry if this sounds confusing, the automatically generated embed codes will take care of it all for you.

That's about it. You know the next step...

Start using the Chess Game Viewer!

Share Caissa Share
 This Page
Facebook Bookmark Bookmark StumbleUpon Bookmark Google Bookmark
Sign Up for Free Online Chess
Click here for FREE Sign Up
About Caissa's Web
Who is Caissa? Contact Us Site Map Terms & Conditions Privacy Policy