Extension:ChessBrowser/Proposal front end

This proposal is related to this schema proposal.

Working prototype of front-end script: User:קיפודנחש/chess-animator.js

Overview

Front end looks for a div element with specific class (current code uses pgnviewer).

inside of it, it looks for a div element with class pgn-board-img , and populates it with pieces.

each piece is a div element with several classes:

a class identifying it as a chess piece: current implementation uses pgn-chessPiece
a class for the specific piece. current implementation uses pgn-ptype-color-XX, where XX stands for the piece itself, so black queen will be pgn-ptype-color-qd, and white pawn is pgn-ptype-color-pl
two classes for the file and row: pgn-prow-X and pgn-pfile-X. the X is a digit between 0 and 7, so a piece on square b3, will have classes pgn-pfile-1 pgn-prow-2
(when the piece is not on the board, i.e. captured or promoted pawn): pgn-piece-hidden the

The CSS takes care of the rest, i.e., actually show the correct pieces in their correct location.

The back-end pre-populates the board with the pieces in the desired position of the game - by default the last one, but can be any, so, in the absence of javascript, this board is displayed to the reader. In current implementation, the pieces (i.e., "divs") placed in the board div by the back-end, are cleared by the front end script, and replaced with those it creates itself.

Switching to any specific position in the game is implemented by turning the "hidden" class on or off, and changing the "row" and "file" classes of each piece to their correct value for this position. CSS takes care of the rest, such as correct location, correct image, and smooth animation.

inputs

Front end looks for a "data" attribute in the main div (the one with pgnviewer class), and looks for a "chess" data attribute in it (i.e., and attribute that looks like so: data-chess = '{ ... json object }'. The JSON object should contain the following:

fen: string, contains the FEN of the opening board.
plys: array of plys. the syntax of a single ply is described below
display: numerical, between 0 and #plys - 1. optional. if present, signal which ply to show initially, before any user interaction

Plys

each ply in the array represents one "ply" of the game, which affects one or two pieces. For this representation, the squares of the board are numbered: a1 is 0, a8 is 7, b1 is 8, and h8 is 63. There are 4 different types of "plys" in the array, representing 5 different moves. we will use S1, S2 etc. to denote different squares, so they represent numbers between 0 and 63:

simple move/simple capture: [S1,S2]. The piece on S1 moves to S2. if S2 was previously occupied, this is a capture
en passant: [S1,S2,S3]: The pawn on S1 moves to S2, capturing the pawn on S3
promotion: [S1,S2,"P"]. pawn on S2 "disappears", and instead, a new piece, as indicated by P, is born on S2. P uses the same encoding as FEN: r, n, b, and q denote black rook, knight, bishop, and queen (can't promote to pawn or king...), and R, N, B, Q denote their white counterparts.
castling: [ [S1,S2], [S3,S4] ]: piece on S1 moves to S2, piece on S3 moves to S4.

Legends and Notations

The back-end can create, in addition to the board, a an element containing the notations.

When a notation has a data attribute of the form data-ply = X, such that X is a number, this notation will become a "control", such that clicking on it will display (or, "go to") the corresponding position.

In addition, when "going to" any specific ply, the front-end will try to scroll the notation of this ply (if it finds such a notation), into view, if the notations are contained in a vertically-scrollable element.

Legends are placed by the front-end, and should use the same "pgn-row-X" or "pgn-file-X" CSS for positioning - this way, when a "flip" class is introduced to show the board from black POV. The front-end does not interact with the legends otherwise.

Controls

In addition to "notations as controls" discussed above, i.e., clicking a notation will instruct the front-end to display the appropriate position, there are several buttons which control the game:

"move to opening position", move to final position"
, "advance" and "retreat" to move to next or previous position
"start/stop autoplay"
"faster" and "slower" affect the autoplay rate
"flip board" (turn board 180, to show black POV)
"show/hide comments", presumably interleaved with notations

The front end does not place the controls (notations and buttons). It finds the controls placed by the back-end, through their classes, and hook them to the appropriate actions.

TBD

Game variations: This will require, e.g., defining a bit more elaborate definition of the way plys are denoted: e.g., "ply #3 in variation #4" can be denoted as "3/5"/ this is required for the value of the "data-ply" attribute of the notation of this variation. Straight game plys can remain unchanged
Show multiple games on a single browser (a' la' standalone)

Current state, limitations

Current code is tested and works, using the output generated by lua-based prototype (Module:ChessBowserPrototype).

This prototype has some limitations, so some of the functionality is not tested, or may have to change with the move to "real" (php-based) extension.

Specifically, the prototype does not support pgn-comments of any kind. Specifically, no game variations, and no show/hide comments button.

Validation is done server side by the PGN parser. As such, the front-end does no input validation, and will happily do silly things, such as "promote" the white king on b3 to a black queen on f6, "castle" black pawn on g2 with white knight on a3, "move" empty squares, etc. if you tell it to.