November 30, 2008

How to publish a chess game on your blog


What's the problem?

Blogging is already one of the most popular ways of Web publishing for a good reason. The concept of simple to operate environment where authors can quickly publish their articles (i.e. postings) is ap­pealing to everyone, especially those who tried our hands on Web publishing the old-fashioned way (with little or no automation). Authors of chess related content have always had one extra wish - to be able to post a chess game/position so that to illustrate their ideas on a chessboard (e.g. this nice wish-list Publishing of chess games). Sure, pictures could be used but anybody who ventured to gener­ate, store on disk, upload and afterwards modify chess diagrams will tell you that not only is it time consuming, but it isn't much fun either. Moreover, chess diagrams are too static to meet the expecta­tions of today's Web where dynamic content (e.g. animation) is regarded as an essential element of modern design.

Over the years, applying the whole range of Web technologies, several solutions were developed but the problem was solved only to a certain extent. A complete, reliable and truly user-friendly solution remained to be seen. Here are a few of the key contenders:

  • Some solutions require a piece of software (an applet) to be installed on the server which may not always be possible, desirable or practical (very common situation in blog's environments). If you’re not a Webmaster and you don’t want to spend much time on maintenance or software upgrades, you might be disappointed by the amount of extra work;
  • Other solutions would transform our initial chess data into some proprietary internal format (usually based on HTML) which appears cryptic, illegible and only loosely related to chess. After a while, you may realize that (re)inventing new formats is more destructive than it appears at first sight. In most cases the final representation would be very difficult to modify after publishing (if at all possible);
  • Yet, other solutions introduce a whole new system for storing (and retrieving) user's chess data. To do that we are expected to trust our chess data to an external (third-party) repository. Among many drawbacks of such approach is the whole new set of skills that need to be learnt.

On the other hand, we all know how easy it is nowadays to publish rich text, photos and even videos. I kept asking myself: “Why should publishing of chess data be more difficult?”

My solution focuses on usability and leaves chess authors with only one concern: the chess data. All of the underlying implementation details are secondary and designed to stay behind the scenes. Users are expected to follow just a few steps that are easy to understand and carry out. The defining goal of my approach is to meet the best spirit of blogging: Authors should only worry about content.

Step One: Plugging in the extension.

Frankly, this is the installation step. It only needs to be done once and it literally takes a minute. Part of my project is a module called "deployChessViewer.js" which needs to be included in your blog's layout. Not a big task but, if you haven't modified your layout before, some extra caution is well justified. Login to your blog as usual, open the "Layout" tab and click on the "Edit HTML" link. Scroll down the template, which is inside the "Edit Template" box, until you find the </head> tag (there should be only one). On my original layout it was located two pages up from the very bottom. Here is a snapshot of the section of my layout just before the </head> tag.

body#layout #footer-wrap1 {
  padding-top: 0;

Carefully, without changing anything else, you need to insert the three highlighted lines from the box below into your template just before the </head> tag. The easiest, of course, is to select and copy the lines, then switch back to your layout editor and paste them into the template. When finished, click the "Save Template" button and you're done. Take your time if you're not comfortable editing the layout and consider making a backup before you start (just in case).

body#layout #footer-wrap1 {
  padding-top: 0;

<!-- Chess Viewer stub -->
<script src=''


Step Two: Formatting the chess data.

First of all, to get started you need to have your chess data in PGN format. Most likely that's already the case since PGN is the most popular format. Your initial PGN data (the source) needs to go through one extra step of preparation in order to be ready for publishing. I refer to it as data formatting (or wrapping) because it resembles various other formatting we do to improve the layout of our posts. This method of chess publishing stores your chess data in the most natural place - inside your post's body. Exactly like the rest of your article the chess data can be later modified as you wish. Such flexibility brings a lot of good news and accounts for some major advantages. Let's name a few:

  • Your chess data will be stored in its original source format exactly the way you submitted it in first place;
  • Modifying the source PGN later is not only possible but very straightforward and, best of all, you won't need anything special to do it (no new tools or skills);
  • You truly own your chess data and the integrity of your post is by design. This means that your chess data will always be available along with the rest of your post;
  • The backup policy that is already in place for your blog will automatically take care and backup your chess data as well (since it is an integral part of your posts).

During the formatting step you may also include some extra instructions to fine-tune the final presentation. Instead of going into lengthy explanations how to do it manually I developed a Web application that does the formatting for you: HTML Code Generator for Blogs. Explore the form and you will quickly have an idea of what this is about. For easy access you can find the same link under the Project's Resources section in the sidebar.

In a nutshell, the chess data is formatted into a ChessViewer (CV) section which consists of three segments nested within each other: the outermost HTML tags, a JavaScript wrapper and the PGN data. The innermost segment is the largest one and is also the easiest to recognize as it contains the original PGN source with its original formatting preserved. You can't do any harm playing with the form so feel free to submit your own PGN and see if you can identify the three segments in the CV section.

Step Three: Publishing of your post.

The result of the previous step should be a CV section (or a block, if you prefer) which is ready to be inserted into the body of your posting. To do so you need to select the "Edit HTML" mode of the post editor, go to the right location in your post and paste the CV section. Once published, the CV section will always be part of your post unless you decide to remove it.

That's all there is to it. At this point, you must realize that you're running out of excuses not to share your games and puzzles with us. Please, tell all your friends and neighbors about the easiest and most powerful method of chess publishing you just came across.

Editing the CV section

When you feel like editing a CV section after publishing (eg fixing or improving it) you’d need to use the "Edit HTML" mode of the post editor. If you're familiar with that mode you already know that your post won't appear the way readers normally see it on their screens. Instead, all of the otherwise invisible tag elements will be shown and that will make editing somewhat trickier. The biggest advantage of "Edit HTML" mode is that it gives you full control over every aspect of your post’s layout and content.

Most of the time you will be modifying the original PGN data (ie the PGN segment). Whether you're fixing an illegal move or introducing a new variation or annotation you can use the full power of the editor. A complex game with complete analyses will have pretty large PGN so you might want to make it friendlier by using line breaks and extra white space. All of your formatting will be preserved making future editing easier.

After a while you might be tempted to tweak some of the parameters in the JavaScript segment. Good example would be if you changed up your mind about a custom color. That won't be a problem if you have (at least) some minimal JavaScript language experience. If not, you might inadvertently break the syntax causing some kind of runtime error when the page is getting loaded by the browser. Of course, you should try to avoid that scenario and be ready to revert back your changes. The next two paragraphs only concern those of us who're brave enough to play with the JavaScript code. Non-technical users are encouraged to skip ahead.

There is this peculiar detail, I should warn you about, which is especially relevant to users of Google's software. In your blog's "Formatting" preferences under "Settings" tab you will find the "Convert line breaks" option with Yes/No possible values (also known as "Gratuitous Line Breaks", see sidebar for more info). Regardless of that parameter current setting, your CV section will be published successfully and displayed just as expected. The warning only applies to future editing of the CV section and only if you have the parameter "Convert line breaks" set to "Yes". In such case you should be extra careful modifying the JavaScript segment. For example, inserting new lines will very likely destroy the formatting and cause runtime errors. If you find yourself in such troubles you can always extract the PGN segment and reformat the entire CV section from scratch using the form (above).

In fact, the side effects of that parameter setting are well known in other situations (unrelated to chess) and every blogger gets some experience with them. I can only wish that blogging software providers could find a better, less painful solution. Allow me to say that formatting documents by pressing the "Enter" key was a common practice in the era of typewriters. It still has a limited usage in plain text documents (like PGN ones) but in the on-line world of HTML you should definitely know better. If so, you could completely avoid the possibility of nasty side effects by keeping the parame­ter "Convert line breaks" set to "No". In that case the post editor will be more forgiving to your editing style and you will be more flexible in your choices.


The author makes no representation about the suitability of this solution for any particular purpose. The software is provided "as is" without any express or implied warranty.


The following pages make use of the above method:

Using the Chess Viewer Applet
Six Must-Have Features of a user-friendly Chess Viewer (a guide to essential functionality)
Susan Polgar in Austin as posted by Susan on her Blog A very exciting game!
The Pope's Puzzle (along with a curious offshoot puzzle)

Related documents and readings:

Handling illegal moves

The Pope's Puzzle

The following is one of Karol Wojtyla's puzzles: White to play and mate in 2

The position is so rich on tactics that I couldn’t help modifying it just out of curiosity.

This next puzzle is also very interesting: White to play and mate in 2

Susan Polgar in Austin

In Susan's own words "one of my toughest simuls ever!". White to play and win

Chess Viewer Deluxe



Chess Viewer Deluxe (CVD) is a full featured Java applet, designed to present chess games on the Web. Its main purpose is to let users enjoy the games in an intuitive, user-friendly environ­ment. The presentation is complete, with support for recursive variations, annotations and glyphs. The games are being stored in their native PGN format which makes Web publishing simple and easy, free from any clumsy steps. In addition, many advanced features are included to provide robust chess-related functionality. Special effort is made to keep the applet's size small realizing that users can still be concerned about download speed.

This software was originally inspired by the well-known chess viewer MyChessViewer (by Michael Keating). I was impressed how elegant and efficient Mike's solution was and how he managed to implement it in such a small package. His viewer remains one of the most reliable chess viewers and is still very popular. I liked it a lot and I turned it into my personal stand-alone viewer.

After a while I felt the need and decided to introduce some new functionality. Going through Mike's code was fun and I could quickly identify the areas which I wanted to improve. Then, as I kept including more and more features, modifications affected whole modules and soon a complete re-design was inevitable. I made a lot of enhancements to the original GUI design but tried to preserve the main ideas. Also, the browser's program interface to the applet is quite compatible with the original.

Compliance with PGN Standard

One of the most important aspects of any publishing is sharing our ideas with others. The most valuable way of sharing chess information, no doubt, is by providing a notation that complies with the PGN format. By mean of such, well documented and widely spread, standard others are able to fully reproduce our ideas. In other words, PGN is for chess enthusiasts what sheet music is for musicians.

Thorough interpretation of every part of the PGN Specification is among CVD's best features. That expertise can be seen in several areas. Take for example the PGN file that is about to be loaded by the viewer. Being a text file makes it prone to errors and it often contains incorrect syntax or invalid chess moves. While parsing the PGN file a great effort is made to handle all possible situations. If a move is found to be "invalid" and cannot be played according to the rules it will be shown as "illegal" (drawn in red). A common bad practice, seen even in commercial parsers, is to turn such moves into annotations (as if by magic). Doing the right thing helps users get a better idea of what's wrong. Meaningful error handling also affects the rest of the game and improves the overall quality. If you want to learn more about PGN parsing in general and how CVD takes care of it feel free to visit this page.

Many examples can be found in the PGN Specification and Implementation Guide. Section 8 deals with PGN parsing and suggests ways of implementing it. A good parser should strictly comply in order to be taken seriously. Even better, attention should be paid to extra guidelines (eg 8.2.3) -- non-canonical SAN, applying transformations, etc. For instance, a check/checkmate indicator ('+', '#') must only appear on moves that are true check/checkmate and has to be removed from those that are not. That feature, alone, isn't as obvious or trivial as it may seem at first sight. On the contrary, many software titles don't bother implementing it. Once again, CVD won't disappoint and your source PGN will be improved wherever possible.

Another part of PGN Specification has to do with Date representation. To avoid the confusion of various international standards for representing dates, PGN defined date format to be "YYYY.MM.DD". This is the format used by CVD for on-screen and internal representation of Date fields (e.g. "Date", "EventDate").

Keyboard support

Wasting time with the mouse can be very annoying at times. Keyboard control allows you to stay focused on the chessboard (the only important thing). Shortcuts are provided for faster game navigation and for most common GUI functions.
Note: If the applet doesn't get the initial focus you may need to click inside it once and use the keyboard onwards.

Copy/Paste support

Copy/Paste is clearly a must-have feature of any software. The ability to quickly share data between applications has always been part of modern GUI design. In chess terms it means much easier transfer of position/game data for the purpose of analyses. I thought, for my own sake, how wonderful it would be to have this feature in a Web based chess viewer. That's why I put it on my high priority list when I started the CVD project. In the latest version, there are four types of commands in this category - "Copy/Paste Game" of PGN data which applies to the current game; "Copy Position" which applies to the current position and "Paste Moves Sequence" which insert a sequence of moves just after the current move.

Be aware that a security concern exists about whether to allow access to the clipboard from the content of a Web page loaded in the browser. If you are in habit of placing sensitive information in the clipboard you might be in danger. The question is big and some people consider it important. For example, Flash player's designers allowed only write (and no read) access to the clipboard. There are people who even consider that not safe enough. Java designers went further in JVM and completely disabled clipboard access from inside applets. Other people, not so paranoid about security, will explain that clipboard data is stored along with its data type (plain-text, image, spreadsheet etc.). Since only plain-text clipboard data has ever been accessible from a Web page content all our spreadsheets (and other proprietary formats) are pretty safe and not likely to be stolen by a malicious script reading the clipboard.

To implement copy/paste functionality CVD depends on copy/paste availability through the browser application. For example, IE6 always allows access and the functionality is available; IE7 gives us an option to allow/disallow it (so that we can decide) and Firefox always disallows it. In other words, if the browser of your choice doesn't allow so copy/paste functionality of CVD will not work for you.

Context menus

All powerful GUI applications provide this feature to their users. Context menus enhance the experience by simplifying the interface. They are a very efficient way of getting the right function at the right time. Taking the shortcut allows us to get the job done as fast as possible. Such a convenience often makes us forget about the alternatives.

The Chess Viewer Deluxe is no exception. There are three different contexts -- Chessboard, Scoresheet and Toolbar. A pop-up menu will appear when right-clicking on the corresponding area of the GUI. (I'm told that people in Mac world call it "apple-click") A list of options, relevant to the current context, will be presented. Every implemented command can be found and executed from these menus. Simply put, everything is exactly the way we're used to from the real applications.

Making chess moves

In addition to viewing our favorite games very often we feel like trying some lines of our own. In this kind of computer-assisted analyses we do the thinking and the computer just helps us organize the process by keeping track of the moves. I think of it as an improved version of a real chessboard and a notepad. With Chess Viewer Deluxe this process is very straightforward. New variations and branching points will be created automatically if necessary. At any time you will be able to delete or promote the current variation using a keystroke or a menu command.

In a complex game, things can get really messy when you branch several levels deep inside several variations. Well, they won't if you are using Chess Viewer Deluxe. You will always have a clear idea of the exact game path and an easy way to navigate back to any branching point. I don't know about professional players but for a casual/average player (like me) this is a great help.


The client Web browser must support Java 1.1 (or above). Older machines are likely to have MS Java (e.g. preinstalled with Windows 2000) which will work just fine. On newer machines you will have to install Java in order to use the applet.


You only need to install the CVD on your Web server if you 1) are a Webmaster; 2) have the technical background and 3) are interested in having full control of your installation. In most cases, a much faster result can be achieved by following How to publish a chess game on your blog. Think of it as an alternative way of installing (so called cloud-version), which is not only simpler but also functionally identical.

If you're already using MyChessViewer on your Web site you will be able to install Chess Viewer Deluxe with no (OK, a tiny) effort.
Here is the short list of steps to follow:

  1. Download the viewer's code Viewer-Deluxe.jar. It is compressed for fastest loading, packed for convenience and you don't need to unpack it. Just save it to any folder of the Web space on your server.
  2. Take a look at the HTML source of Games Samples to get an idea how to use the applet on a page. Here is the essential part.
    <APPLET archive="Viewer-Deluxe.jar" code="ChessBoard.class"
      codebase="/bin" width="631" height="560" mayscript="true">
      <PARAM name=PgnGameFile value="/games/Samples.Pgn">
      <PARAM name=LightSquares value=F3DCC2>
      <PARAM name=DarkSquares value=DDA37B>
      <PARAM name=Background value=CCCCCC>
      <PARAM name=ImagesFolder value=images>
      <PARAM name=PuzzleMode value="off">
      Your browser is completely ignoring the &lt;APPLET&gt; tag!
    The meaning of various parameters and their usage is listed below:
    • MayScript is an important attribute. The value of "true" means "enabled" and is highly recommended. This way the applet is granted the same access to JavaScript as the rest of the Web page already has. Several extended functions (e.g. copy/paste) rely on that in order to work properly. The default value is "false".
    • PgnGameFile specifies the actual GameFile relative to the Web page home folder. It could reside is any folder (accessible, of course) and have any extension. This parameter is mandatory.
    • Use LightSquares, DarkSquares and Background to specify RGB custom colors to replace system defaults. These parameters are optional.
    • ImagesFolder specifies a folder inside the JAR file that contains the images. It allows for alternative sets of chess pieces. Unless you have modified the JAR file to include an extra folder there is no need to modify the value. This parameter is mandatory.
    • PuzzleMode is an optional parameter. The default value is "off". When turned "on" the viewer will start in puzzle mode -- showing the problem but hiding the answer.
  3. It is a good idea for your Web page to include code to verify if the client's browser supports Java first. This will make it more pleasant for users who load the page and need further instructions. The following piece of JavaScript code does the job.
    <SCRIPT LANGUAGE="JavaScript">
      // make sure this browser supports Java 1.1
      if ((navigator.appName == "Microsoft Internet Explorer" &&
           parseFloat(navigator.appVersion) < 4)    ||
          (navigator.appName == "Netscape"                    &&
           parseFloat(navigator.appVersion) < 4.06) ||
    Please refer to Games Samples's HTML source for an example how to include the code on the page.
  4. To make the previous step work you need to provide an "UpgradeBrowser.htm" file.
    Easiest is to use the one here but feel free to modify or replace it to your taste.

Now you are ready to present the Chess Viewer Deluxe to your site's visitors.

Version history

Read the change log document.


This software is free for anybody to use. The meaning of "free" is exactly the same as in "free beer" - you don't have to pay for using it. You may like it or even enjoy it but no promises of any kind are made. The beer recipe is not included and there's no point asking for it. There are no special clauses and no freedom of yours is taken away from you. I mean no harm with my offering and my ultimate goal (or rather a dream) is to make this software bugs-free. (Note: For the very same reason I also like my beer to be bugs-free.)


Chess Viewer Deluxe quickstart guide
How to View Games Using Chess Viewer Deluxe
The Chess Nut Blog: 5 Steps to Chess Viewer Deluxe

Any suggestions or feedback can be sent to pilafov ‹at› hotmail ‹dot› com and will be appreciated.

Nikolai Pilafov