The bridge plugin - Part 3 - Foswiki Blog

In the previous posts I demonstrated:

How to set up the infrastructure for a data driven Bridge hand collection web site; and
How to create a plugin to support the expansion of macros creating the display

This post completes the application. It presents the development of the page that displays the hands, ready to practice and establishes a front page that supports the selection of hands with particular characteristics.

The first post created a New button and displayed that button on the front page (WebHome) of the BridgePractice web. Clicking the New button, presents an empty page and an empty form. First enter the data describing the hand in the fields associated with the form. For instance: Hands and Auction are set to:

H W:K84.KQT9852.K3.2::AJ62.J3.AQ85.A97
A EN:PP1NP4CP4NP6DA

The hand definition states that west is the first hand and the cards for west and east are defined. That is enough for bidding practice. The auction definition states that west is the dealer, north-south is vulnerable and the auction proceeded as pass, pass, 1NT (15-17), pass, 4 clubs (Gerber), pass, 4NT (3 aces), pass, 6 diamonds (slam by west), all pass.

Formatting the hands

After entering the macros %BRIDGEHANDS% and %BRIDGEAUCTION% on the canvas and saving you get the display shown on the right. This needs some serious formatting and styling. And you don't want to do that every time you create a new practice hand.

Topic templates can help here. They insert the text for the page on each page as it is created. In the Wiki Workbench: click TopicTemplate under Data Model in the BridgeApp. Create a topic: BridgeHandTopicTemplate. Insert the text for all bridge hand topics and save. The template is put to use by updating the BridgeHand topic type, adding TEMPLATE="%WEB%.BridgeHandTopicTemplate" as shown on the right.

The topic template inserts text when the topic is created. So when you change your mind, you will need to update all previously created topics. There is another way, using a view template. The view template is applied to the topic when the topic is viewed. It does not insert any text in the topic. The mechanics of view template are more complicated than the topic template, and to understand them completely you must read the documentation. For now, assume that it works and read on to see how a view template is implemented

%BRIDGEHANDS{ … }% %BRIDGEAUCTION{ … }%

BridgeHand topic type
referring BridgeHandTopicTemplate

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

Style in the view template

%TMPL:DEF{"templatestyle"}%
<style type="text/css">
.bridge {
  display: table;         
  width: 600px;         
  background-color: #eee;         
  border: 1px solid #666666;         
  border-spacing: 25px; /* cellspacing:poor IE support for  this */
}
.bridge-row {
  display: table-row;
  width: 1000px;
  clear: both;
}
.bridge-hands {
  float: left; /* fix for  buggy browsers */
  display: table-column;         
  width: auto;   
  background-color: #eee;  
}
.bridge-auction {
  float: right; /* fix for  buggy browsers */
  display: table-column;         
  width: auto;  
  background-color: #eee;  
}
</style>  %IF{"$raw='on'" then='%TMPL:P{"sig_textareabuttons"}%'}%%TMPL:END%

To create and use a view template is easy to do in the Wiki Workbench. To create a new view template, click TopicView under Control in the BridgeApp and create the BridgeHandsDataViewTemplate. Base the view on the default view and redefine the content definition to include the layout and macros as shown below. It is practical to define the styles for this view in the templatestyle definition shown on the left.

Content of the view template

%TMPL:DEF{"content"}%%TMPL:P{"simpleheader"}%
%TEXT% 
<div class="bridge">
  <div class="bridge-row">
     <div class="bridge-hands">
 %BRIDGEHANDS{ displayBoard="on" }%
     </div>
     <div class="bridge-auction">
%BRIDGEAUCTION%
     </div>
  </div>
</div> %TMPL:END%

With this naming convention, the AutoViewTemplatePlugin will apply the view template BridgeHandsDataViewTemplate to any topic of topic type BridgeHand. For details see the documentation.

Now I can record new bridge hands and then display them on a page that looks like:

Display the hand and practice the auction

Presenting the play

To play a hand, I decided to use the Bridge solver on line web site. The web site is made available through BRIDGEPLAY macro. The implementation is again standard text manipulation. But there was some additional complexity, since the rendering of the playing board occurs on the mirgo2.co.uk web site. In essence, we are displaying another web site on the wiki page. The other web page is displayed within an html iframe element.

Adding the BRIDGEPLAY macro to the view defined in the previous post created a very busy page. The presentation is improved by using the TAB macro to create a more attractive page. The BridgeHandsViewTemplate easily accommodated the change. The revised view template is shown on the right. The tabbed display becomes:

Revised view template

%TMPL:DEF{"content"}%%TMPL:P{"simpleheader"}%
%TEXT% 
%TABPANE%
 %TAB{ "The cards" }%
  %BRIDGEHANDS{ displayBoard="on" }%
 %ENDTAB%
 %TAB{ "Practice the auction"}%
<div class="bridge">
  <div class="bridge-row">
     <div class="bridge-hands">
 %BRIDGEHANDS{ displayBoard="on" }%
     </div>
     <div class="bridge-auction">
%BRIDGEAUCTION%      </div>
  </div>
</div> 
%ENDTAB%
%TAB{"Play this hand}%
%BRIDGEPLAY{ deal="partial" zoom="0.7" }%
%ENDTAB%
%ENDTABPANE%
%TMPL:END%

The tabbed display to play the hand

Setting up the home page of the BridgePractice web.

We now have a way to create new hands and to display hands. In addition we need a mechanism to locate previously entered hands and possibly select a hand based on some criteria. The home page of the BridgePractice web is the place to display this. Implementing the functionality on the home page mixes the functionality of the display with the storage of the data. Instead we can use a Wiki Workbench BridgeApp TopicFunction to implement the appearance of the home page.

The JQDataTablesPlugin provides a simple way to locate topics and select topics by data provided in a form. The Wiki Workbench uses it for just that purpose. I will use it here as a convenient starting point. To create a topic function you click TopicFunction under Control in the BridgApp Wiki Workbench. Click New, enter a name (Render bridge practice web home page) and a summary for the function and click Submit. We are now presented with a template for a topic function. We saw a completed topic function (RenderSimpleTopicCreator) in the first post in this series. The instructions to render a home page need to be placed between the %STARTINCLUDE% and %STOPINCLUDE% markers. Lets put the button to create a bridge practice hand there and call the Render bridge practice web home page function from BridgePractice.WebHome:

Render bridge practice web home page

%STARTINCLUDE%
%DBCALL{ "Applications/BridgeApp.BridgeHand" }%
%STOPINCLUDE%

BridgePractice.WebHome

%DBCALL{ "Applications/BridgeApp.RenderBridgePracticeWebHomePage" }%
-- BramVanOosterhout

Displays ...

Now add the %DATATABLE{ … }% macro. The DATATABLE macro has a lot of parameters, but for this blog most defaults suffice. The implemented definition is shown on the right.

There is some trickery here with respect to the definition of the webs where the components are located.

WEB is always replaced by the web containing the topic. In my implementation it will be Applications/BridgeApp.
BASEWEB is always replaced by the web that includes this topic. When RenderBridgePracticeWebHomePage is included in BridgePractice.WebHome, BASEWEB will be BridgePractice.
theWEB is an include parameter. If the parameter is not provided with the INCLUDE, the value is replaced by BASEWEB. Otherwise the value provided is used.

The full definition

%STARTINCLUDE%
%DBCALL{ "Applications/BridgeApp.BridgeHand" }%

This web contains a collection of bridge hands played at various clubs. Each hand is displayed on its own page. New hands can be created one by one, using the New button. 

%DATATABLE{ 
   connector="dbcache"
   web="%theWEB{ default="%BASEWEB%" }%"
   form="%WEB%.BridgeHandsDataForm"
   columns="index,TopicTitle,Dealer,OpeningBid,Declarer,Contract"
   paging="on"
   rows="5"
   searching="on"
}%
%STOPINCLUDE%

With the definition of the Render bridge practice web home page function, we can implement the BridgePractice home page with a single statment:

%DBCALL{ "Applications/BridgeApp.RenderBridgePracticeWebHomePage" }%

And the result is: The rendered bridge practice home page

There are many improvements needed and possible. But for the purpose of this blog I will leave the implementation of the user interface here. The important message is that the Wiki Workbench helps to implement wiki applications that separate the user interface from the data.

In the next post I will complete the story by presenting the packaging of the plugin and the application for distribution to other Foswiki users.