Integrating chessboards in your Blazor app

I enjoy playing chess even though I am not a good chess player at all. As a hobby chess player I tried a lot of times to integrate chessboards into Angular applications for instance. That’s probably why I was thinking about creating a Blazor chessboard component for some time but didn’t had the time to start working on it. Until four weeks ago. The result is CWK.Blazorcomponents.Chessboard, a Nuget package that makes it easy to integrate chessboards in your Blazor applications. The goal of this article is to describe the chessboard functionalities and also reveal how this Blazor component works under the hood.

Functionalities

There is a getting started guide on the Cwk.Blazorcomponents.Chessboard repository, so I won’t cover that in this article. But once everything is set up, integrating the chessboard in your application should be easy and straight forward:


1
2
3
4
&lt;CwkChessboard Width="700px"

               Orientation="black"

               FenHasChanged="@SetFen"

               Fen="r1bqkbnr/pppp1ppp/2n5/1B2p3/4P3/5N2/PPPP1PPP/RNBQK2R b KQkq - 0 3"&gt;&lt;/CwkChessboard&gt;

As you can see, the component has some parameters that you can use to provide information about the chessboard. The component will use this information to take care of moves, update positions an so on. The first useful thing that you can provide is the chessboard width and the component will obey to your desires by rendering the chessboard according to this width. By doing this it’s up to you if you want to use several smaller chessboards at one time or if you want to use only one.

Orientation

The orientation parameter can be used to provide the desired orientation of the chessboard. Possible values are “white” or “black“. If you use “white” then the white pieces will be displayed on the lower side of the board. If you choose “black” then the black pieces will be displayed at the lower side of the board.

This can be very useful if you want to build something like a tactics trainer application. If you have tactics that are played from black’s perspective, then it might be useful for the users to have the black pieces on the lower side of the board.

This parameter is not mandatory so you can skip it entirely. However, note that the default value will be “white”, so if you don’t specify anything the white pieces will be rendered on the lower side.

FEN

FEN is a standard notation for describing a particular board position of a chess game. The purpose of FEN is to provide all the necessary information to restart a game from a particular position. This means that you can create a chessboard with the desired starting position by providing a valid FEN string.

Using FENs can prove important if you want to integrate a chessboard in your Blazor app. Let’s assume for instance that you create a tactics trainer application. You’ll provide the FEN for the starting position for a specific tactic. Then the user can move. The chessboard Blazor component will notify you about the new position by providing you an updated FEN (see below). You can then check if the updated FEN coming from the chessboard component is the same with the FEN you would expect as part of your tactic. If the FENs don’t match it means that the performed move was not the correct one.

This parameter is also not mandatory, so you can skip it. However be aware that if you don’t provide a valid FEN string, CwkChessboard will use the FEN for the default starting position.

FenHasChanged

The CWKChessboard component pushes the new FEN after each move through an

1	EventCallback<string>

by exposing it via the FenHasChanged property. This means that you can attach a callback method to this property in which you can perform whatever action you would like with the updated FEN.

In this example we have a basic method in the Index.razor file that is attached to the event callback. It always takes the new value and updates the correspondent property, which is used in the heading.


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
&lt;h4&gt;Position: @Fen&lt;/h4&gt;



&lt;CwkChessboard Width="700px"

               Orientation="black"

               FenHasChanged="@SetFen"

               Fen="r1bqkbnr/pppp1ppp/2n5/1B2p3/4P3/5N2/PPPP1PPP/RNBQK2R b KQkq - 0 3"&gt;&lt;/CwkChessboard&gt;



@functions {



    protected string Fen { get; set; }

    protected void SetFen(string fen)

    {

        Fen = fen;

    }



}

Back and forward

The CwkChessboard component also comes with “Back” and “Forward” buttons. This way you can go back move by move till the starting position is reached and then replay the move, or perform new moves if you want. It should be noted that CwkChessboard doesn’t support variations, so if you perform a new move at a certain point when replaying it will automatically become your main line.

CwkChessboard under the hood

The main goal of this component is to provide a very easy way to integrate chessboards in your Blazor app without writing any Javascript. However, the component itself relies on several very important Javascript libraries like chess.js and chessboard.js. Therefore, the CwkChessboard component is basically a wrapper around these libraries.

When you use the component in your application, the component itself will use the chessboar.js library to render the visual part of the chessboard and the chess.js library to implement the chess rules. That’s why you can’t randomly move pieces on the board. Each move needs to be a valid chess move.

Due to the fact that under the hood the component is using a lot of Javascript and seen that in order to pass information about the current chess game back to the parent components, there’s a lot of Javascript interop used. This means that the component calls Javascript methods from C# methods and also Javascript functions call C# methods to notify about important aspects of the game.

Limitations

For now, CwkChessboard has some limitations. The first and most important one is that it is designed as a component for the client-side hosting model. The component should also work when hosted server side but in that case one would need to add all the needed JS files to the wwwroot folder and reference them in the markup. You can find the Javascript files HERE. If you already use bootstrap in your application, then the only files you need to manually copy are blazorchess.js, chess.js and chessboard-0.3.0.js.

Another limitation is that for the moment you can only promote a pawn to a queen. So, you can’t really choose to promote a pawn to a knight, bishop or rook.

Feedback

I am a very bad product manager and therefore I heavily rely on you feedback regarding this Blazor component. What features would you need from a chessboard component? How do you plan to use this component? Any type of feedback would be really appreciated. You can write your feedback either as a comment on this blog post or open a new issue in the repository.

If at a certain point you have some working samples of applications using this component, don’t be shy and write about your app in a comment on this blog post.

I really count on you! Cheers!