Chess By Blog is a plugin for WordPress 2.0 that adds graphical chess functionality to your WordPress blog. It lets you do several things:

• PGN (Portable Game Notation) inserted into your post body will be displayed as a graphical board, inline in the browser. The client side code was written using the Google Web Toolkit, resulting in Javascript (no Java required) that has been tested in Internet Explorer 6 and 7, Mozilla/Firefox, and Safari. The graphical look of the chessboard is controlled by a single cascading style sheet, allowing for easy customization.
• The board supports interactive play directly in the browser, in a mode which does not update the post body. All rules of chess are supported, include en passant, castling, and pawn promotion. This can be used to present chess problems for readers to work through.
• Chess By Blog also supports a persistent game played between two players, hence the name of the plugin. Readers that have edit permissions on a post can take turns moving pieces, with the state of the board saving to the WordPress database between moves. The plugin uses WordPress and PHP security features to ensure that only moves that come from the client chessboard code can update the database.

You can see the plugin in action on the examples page.

License

Chess By Blog is free software, distributed under the Expat license. (Note that there is also a set of third party icons distributed with the software, which are under GNU GPL).

Download

The current version is 1.0.3, and can be downloaded from the 1.0.3 release post.

Installation

Chess By Blog has been tested on WordPress 2.0.2 to 2.3; it is not supported for earlier versions.

Before installing, you should back up your WordPress blog, particularly if you intend to use the persistent game feature; this will make changes directly to your database. The changes should only be limited to the body of the post which contains the chess board, and I’m not aware of any issues with the code - but better safe than sorry.

The top level contents of the zip folder look like this:

/ChessByBlog

+--chess-by-blog.php

+--ChessByBlog-compile

+--ChessByBlog-shell

+--/chess-by-blog

+--/src

chess-by-blog.php and the entire chess-by-blog directory should be copied to your WordPress wp-content/plugins directory. Unless you are building the client side code yourself, you can ignore the src directory and the ChessByBlog-compile and ChessByBlog-shell files.

You should now be able to active the plugin from the WordPress Plugins administration panel.

Building the client side code

This step is optional, but if you need to make fundamental changes to the code that can’t covered by changes to CSS, you’ll need to edit the Java sourcefiles.

The client side code is Javascript, translated from Java using the Google Web Toolkit. To build this yourself, you will need to have the Google Web Toolkit installed, after which the entire src directory can be copied into your Google Web Toolkit folder. It is then recommended that you run

applicationCreator -ignore org.levork.gwt.client.ChessByBlog

This will create the ChessByBlog-shell and ChessByBlog-compile scripts necessary to compile. Running ChessByBlog-compile will compile the project into the subdirectory www/org.levork.gwt.ChessByBlog. The files with cache in their name are the Javascript files; these go in wp-content/plugins/chess-by-blog (and the old ones should be deleted, most of them will have different names).

Usage

The plugin adds a “Chess By Blog” button to the Quicktag panel that appears when you edit or write a new post. (Unfortunately, at this time there is no corresponding button in the visual editor.) Clicking the button will pop open a new window which allows you to create a new chess board. The fields of this board correspond almost directly to the seven required tags of Portable Game Notation. For the purposes of the plugin, all fields are optional; accepting the defaults will result in code inserted into your post which will create an empty, closed board. There are three types of boards that can be set up:

Static, non playable board

A static, non playable board can be created by leaving the “Wordpress ID” fields blank and by inserting algebraic move notation in the Movelist field. Note that for speed reasons, the input (particularly pawn moves) isn’t fully error checked by the client code.

Single player, non-persistent board

An interactive, non-persistent board can be created by typing in “*” for the “WordPress ID” fields (both sides). Algebraic move notation can be inserted to set up the board. Note that when the board is played interactively, full validation is performed.

Two player, persistent board

An interactive and persistent board can be created by typing in names in the “WordPress ID” fields. These should correspond to the usernames of users of your blog. These users must have at least Subscriber Roles.

Alternately, you can forego the usage of the Quicktags button and insert PGN directly, enclosed in <div class=”CBB-board”></div> tags. The client code will treat standard PGN as a static, non playable board. Playable boards can be created by inserting [CBBWhiteId] and [CBBBlackId] PGN tags with values as described above.

Chess variant support

Chess By Blog fully supports FEN (Forsythe-Edwards Notation) via the “FEN” tag in PGN. This allows specification of the initial board layout. It also allows for handling of some chess variants.

Fischer Random Chess (or Chess960) is directly supported. The layout of the ranks must be specified via a FEN tag. Castling is supported correctly.

Capablanca chess is directly supported. The layout of the board must be specified via a FEN tag, using “A” or “a” for the Archbishop and “C” or “c” for the Chancellor; a 8×10 piece layout must be specified as well.

There is limited support for arbitrary board sizes. Castling is handled by always moving the King to the ‘c’ file if castling on the a side, or the file to the left of the rightmost file if castling on the
other side; the Rook is always moved to the inner square. This supports Fischer Random Chess and Capablanca Random Chess, but does not support other variants. In addition, en passant always assumes the pawns start on the 3rd rank.

Customization

The look of the client side code is controlled almost entirely by the style sheet chess-by-blog/ChessByBlog.css, which in turn makes references to graphics in the chess-by-blog/images folder. The default look uses icons from Wikimedia Commons (in turn inspired by Xboard and the fselch Metafont). If the icons are replaced with ones of different size, it is important to edit the CBB-square class and ensure that all three attributes are updated to match the size of the icon. (The three attributes are there to solve cross-browser compatibility issues.)

Known issues

• Switching from the code to visual editor may wreak havoc on the <div> tags, despite the tags being protected by <pre> tags. This is an issue with the visual editor.