The bridge plugin

Building a plugin and application to record and practice bridge hands

I learned to play bridge about a year ago. To help the practicing of my bidding and playing I have written a plugin and a wiki application. This post talks about the decisions I made along the way. I hope it will help others to create and publish applications.

Introduction

I learned to play bridge about a year ago. It's an interesting game with a mix of strategy, statistics, planning and execution that keeps me entertained. It's also social, because one plays as a partnership. And that brings an element of conversation and cooperation that goes well beyond the aim to win in other card games. There are two distinct parts in each game, the auction and the play. In the auction the partnership bids for a contract: How many tricks will we take. In the execution one player of the pair that wins the auction gets to play the cards to actually take the tricks.

Both the auction and the play improve considerably with practice and as I progress I often think: "Ooohh, I would like to play that hand again" At the same time, there are many books and websites that offer practice. The bidding practice is very nice, but without playing the hand I find it hard to assess whether the contract can actually be made. To help me out I developed the BridgeApp.

The application started simple. I needed a place to store interesting hands. I have used Foswiki for some time and the structured nature lends itself well to storing the information. There are a few notations in common use to describe bridge hands. The Portable Bridge Notation (PBN) is common as an interchange format. Bridge Base On-line uses the LIN notation, which is not documented. I chose Richards Bridge Notation (RBN), mostly because of his passionate defence and because it's easy to parse.

Once the data structure was available, I could consider display options. I started with the hands displayed in a tabular format. Easy to do, but with all the books and web sites displaying the hands around a table, I found it a real mind bender to keep track of the players and suits. So I added an option to display the hands around a table. Next came the auction. It's relatively simple to display the auction in a table. The Bakerbridge site gave a nice idea on how to display the bidding progressively and I added that to the display as an option.

With these two tools implemented I could practice the auction, but I could not play. There is a well established algorithm to play bridge: the Double Dummy Solver by Bo Haglund. There is C++ source for Linux available on GitHub, but I could not find a perl wrapper. Instead I selected a ready to play interface that I could provide with the selected data for the hands. I picked the on-line version of Bridge solver and integrated that into the page.

There is lots to improve on this. It would be nice to have a player program that did not show the opponents hands, but that is for the future. For now I will use this blog to describe the implementation of this application in the following posts:

• The establishment of the web site and the implementation of the data structure
• The creation of the BRIDGEHANDS and BRIDGEAUCTION macros.
• The integration with the Bridge solver web site.

It will take a little while and I am cleaning up the code as I write this. The BridgeApp will be released when I complete this blog.

Establishing the data structure

Applications in Foswiki are best developed through the Wiki Workbench, supported by the WikiWorkbenchContrib extension. If you have not used this extension before, the text below will help you to get started. The WikiWorkbenchContrib installs the Applications web.

For a new application, you click the New WikiApplication button, enter the name of the application (BridgeApp) and a description and press Submit. After the Submit there is a new sub web to the Applications web called BridgeApp. And BridgeApp.WebHome shows the tools to build a wiki application.

To define the data structure for the BridgeApp, we need to define a data form. Click DataForm in the Data model column and New on the next page. Provide the Title (BridgeAppForm), a description and click Submit. You get a new wiki page with the top four rows of the data form definition completed. For the time being I have completed the definition as follows:

| *Name:*| *Type:* | *Size:* | *Values:* | *Description:* | *Attributes:* | *Default:* |
| TopicType | label | 1 | BridgeHand, WikiTopic | topic type  | | |
| TopicTitle | text | 75 | | title | | |
| Summary | text | 75 | | short description or tagline | | |
| Board | text | 75 | |B: The board number | | |
| Hands | text | 75 | |H: Description of the hands | | |
| Auction | text | 75 | |A: Description of the auction | | |
| ContractAndDeclarer | text | 75 | |C: Contract and Declarer | | |
| Dealer | text | 10 | |Dealer if known. Duplicatets auction dealer | | |
| Declarer | text | 10 | |Declarer if known. Duplicates auction declarer | | |
| Contract | text | 10 | |Contract. Duplicates auction contract | | |
| OpeningBid | text | 10 | |Opening bid. Duplicates auction opening bid | | |

You may notice that I added some duplicate data. That will be useful later when it comes to seaching for particular hands. One can search without these duplicates, using appropriate regular expressions. But I find it easier to add the additional data.

I have also defined the TopicType as BridgeHand. That will help keeping the actual hands separate from the general topics.

Creating a new BridgeHand topic

With the data structure defined, we need to look for a way to create topics with that data structure attached. The workbench provides a standard mechanism to do that for the chosen TopicType. Like for the data form, you click TopicType and New, provide a title and description and click Submit. You are presented with a edit page that you can modify to create the required button.

The page supports more than just the creation of the button. You are encouraged to document the feature at the top, and define the data form at the bottom. I already defined the form, so I will delete that. In good programmer fashion I will skip the documentation as well. That comes later :-).

The section under the heading Topics of type 'BridgeHand' defines both the button and a list of all topic types. We don't want the list so that goes as well. What remains defines the button:

%STARTINCLUDE%
%DBCALL{"Applications.RenderSimpleTopicCreator"
  LABEL="%MAKETEXT{"Title"}%"
  BUTTONTEXT="%MAKETEXT{"New"}%"
  TEXT="%MAKETEXT{"Create a new [_1]" args="%TOPIC%"}%"
  VALUE=""
}%

<del>%DBCALL{"Applications.RenderTopicsOfType"}%</del>
%STOPINCLUDE%

As you can see, the button rendering is defined in Applications.RenderSimpleTopicCreator and the documentation of of this feature is presented there. The important parameter to add is the FORM parameter, specifying the BridgeAppForm we created before. The FORM parameter, like many parameters in the wiki applications takes the form of web.topic. So we specify:

%DBCALL{"Applications.RenderSimpleTopicCreator"
  FORM=%WEB%.BridgeAppForm
  ...

When the New button is clicked, we are asked for a Topic title. After entering the topic title we Submit and the new topic will show in edit for as a blank topic. The BridgeHandForm is associated with the topic and the fields will show as empty. Clicking Save will save the new topic in the Applications/BridgeApp web.

Uuuuuhhh, that does not seem like a good idea: Mixing the data with the code. We can do better than that. Create a new web and let's call it PracticeHands. We can do that from the SYSTEM.ManagingWebs page. Use the _default web as a starting point. Add the following on the PracticeHands.WebHome page:

%DBCALL{Applications/BridgeApp.BridgeHand}%

And save. The button we defined appears on the PracticeHands.WebHome page. Click the button and the dialogue to create a BridgeHand page appears. Once created, the form is attached to the new topic and we can edit and save it.

That's enough for now. Next time we'll implement some useful display features, once the hand data is entered.