Handviewer documentation

Introduction

The Handviewer program, developed by Bridge Base Online, can be used to create various types of attractive bridge presentations on web pages. Any web site is welcome to use this program for any non-commercial use. We believe this program works well but your mileage may vary. We warrant nothing.

You may not use this program for commercial purposes without written permission from Bridge Base Online.

You do not have permission to modify this program or to place copies of it on your own server.

The Handviewer program can be run in any browser that supports Javascript (and on which Javascript has been enabled). This includes the browsers that come installed on, for example, the iPhone and G1 mobile phones (as well as any modern browser on any modern computer, of course.)

What sort of bridge presentations can the Handviewer display?

Single hands
Pairs of hands for any 2 directions (North+South, East+West, West+North, etc.)
Bidding diagrams
Single hands (or pairs of hands) with bidding diagrams
All four hands
A “bridge movie” (all 4 hands in which the cards can be played out)

Embedding the Handviewer program in a web page

For most web publishing purposes, it will make sense to embed the Handviewer application within a web page. The easiest way to do this is by using an iframe. The HTML for doing so should look something like this:which will produce something like this:

Web publishers can specify the amount of space that a given instance of the Handviewer will occupy by setting the height and width of the iframe (350 pixels and 200 pixels respectively in the above example). The Handviewer program will resize itself so that it will fit in the space that you provide for it.

Individual web pages can contain multiple iframes, each using an instance of the Handviewer program.

Invoking the Handviewer program

The Handviewer program resides at this URL:

https://www.bridgebase.com/tools/handviewer.html

In order for the Handviewer to display anything useful, you must pass it at least one parameter. The specific parameters you use will determine which of the 6 types of presentations listed above will be displayed.

Parameters are specified by appending a question mark character (?) to the end of the above URL, followed by a list of parameter names and values in this form:

https://www.bridgebase.com/tools/handviewer.html?parameter=value1

Multiple parameter value combinations must be separated by an ampersand character (&).

For example: https://www.bridgebase.com/tools/handviewer.html?parameter1=value1&parameter2=value2

The order in which multiple parameters are specified does not matter. If multiple instances of the same parameter are specified, the first such instance will be used and subsequent instances will be ignored.

Parameters for specifying hands

In order to display single hands, pairs of hands, or all 4 hands using the Handviewer program, use some combination of the n, s, e, and w parameters to specify the hands for the North, South, East, and/or West players. Here are some examples:

Some notes about specifying hands:

the n, s, e, w parameters (along with most others) are not case sensitive
use T (or t) to specify a 10
you can use X (or x) to include x’s in hand diagrams (but not in conjunction with the p parameter described below)
if you specify 3 13-card hands, the Handviewer will fill in the 4th hand for you (as long as there are no x’s)
the Handviewer will not allow you to specify a hand with more than 13 cards or to give the same card to 2 different players
the Handviewer does allow you to specify hands with less than 13 cards (useful for end positions or suit combinations)

Parameters for specifying the names of the players

The nn, sn, en, and wn parameters are used to specify the names of North, South, East, and West respectively. For example:

If you do not specify the name for a given player whose hand has been specified, the direction of that player is displayed instead.

Parameters for specifying the dealer, vulnerability, and board number

The d parameter specifies the dealer. It takes values of n, s, e, or w. If you do not specify a dealer, the Handviewer will assume that North is the dealer.

The v parameter specifies the vulnerability. It takes values of n, e, b, and – (for North-South vul, East-West vul, both vul, and none vul respectively). If you do not specify the vulnerability, the Handviewer will assume that nobody is vulnerable.

The b parameter specifies the board number (which is assumed to be a positive integer). The Handviewer does not do any checks to make sure that the board number is consistent with the dealer or the vulnerability according the to standard progression of board numbers.

Here is an example of all three of these parameters in use:

https://www.bridgebase.com/tools/handviewer.html?d=e&v=n&b=2

This will set the dealer to East, the vulnerability to North-South, and the board number to 2.

Parameter for specifying the auction

Specify the auction using the a parameter. The value of this parameter consists of every call in the auction concatenated into a single string containing no spaces or dashes. For example:

Some notes about specifying calls in the auction:

use N, not NT, for notrump bids
use D or X for double
use R for redouble

Sometimes there is a need to create a presentation whereby either the contract or the player on lead and the trump suit is specified, but it is not appropriate to display an auction. This can be accomplished by setting the first character of the a parameter to a minus sign (-) and using the next few characters as follows:

To set the contract, use the next three characters to specify the level, the trump suit, and the declarer. For example: a=-4se sets the contract to 4 spades by East.
For end position diagrams, use the next two characters to specify the player on lead and the trump suit. For example: a=-sc will put South on lead with clubs as trump.

You can add explanations to specific calls in the auction by including an appropriate explanation between parentheses – “(” and “)”, immediately after the call in question appears. For example:

The 1NT bid in the auction diagram will be highlighted. If the user clicks a highlighted call, the explanation of that call will be displayed. In this case the explanation is: 15-17. Once an explanation is displayed, the user can remove it from the screen by clicking the call in question again.

If the a parameter is included but none of the n, s, e, or w parameters are included, then only the auction will be displayed.

If the a parameter is included and at least one of the n, s, e, and w parameters are also included, both the auction and the specified hand(s) will be displayed.

Parameter for specifying the play sequence

The play sequence is specified using the p parameter. The value of this parameter should consist of a series of cards. Each card consists of 2 characters. The first character is the suit of the card (S, H, D, or C) and the second character is the rank of the card (2, 3, 4, 5, 6, 7, 8, 9, T, J, Q, K, or A). For example:

https://www.bridgebase.com/tools/handviewer.html?p=sjsqsksadac2d4d3

This defines a play sequence in which the Jack of spades is the opening lead and the rest of the first trick consists (in order) of the Queen, King, and Ace of spades. The Ace of diamonds is led to the second trick. The next hand discards the 2 of clubs and the remaining players follow suit with the 4 of diamonds and the 3 of diamonds.

Adding annotations to the bidding and play sequence

The Handviewer program supports functionality for displaying annotations that are associated with particular places in the bidding and play sequence in the area below the deal diagram. Annotations can be inserted in the appropriate places of the a and p parameters by enclosing them in brace brackets – “{” and “}”.

For example, if the a parameter has this value:

a={This is a very interesting bridge deal!}1sp3ndr{I would not have redoubled}ppp

The annotation “This is a very interesting bridge deal!” will appear when the Handviewer is first launched. When the user clicks the “Next” button, the bidding will advance to the point to the next annotation (after the redouble) and the associated annotation, “I would not have redoubled”, will then be displayed.

Similarly, if the p parameter has this value:

p=sj{Excellent opening lead!}sqsksa{All the high spades are gone}dac2d4d3

The annotation “Excellent opening lead!” will appear after the Jack is spades is led to the first trick. The annotation “All the high spades are gone” will appear at the end of the first trick.

Some additional notes about annotations:

If the first character of an annotation is a plus sign (+) whatever annotation is currently being displayed will be augmented with the rest of the annotation in question.
To clear the annotation area use: {}
Spade, heart, diamond, and club symbols can be included in an annotation with !S, !H, !D, and !C.
Annotations can contain HTML tags.

Displaying a bridge movie that is defined using the language of .lin files

The Handviewer program understands a subset of the language that is used in .lin files. Most likely this subset will grow over time. For now only .lin commands that are used in the bridge movie files produced by the Bridge Base Online (BBO) Windows client program are supported. The Handviewer can be instructed to display a bridge movie represented by a string of .lin commands using the lin parameter. For example:

Displaying a bridge movie via a reference to the /myhands web site

The movies of bridge deals that were played recently on BBO can be accessed through www.bridgebase.com/myhands. Each bridge movie in the /myhands database contains a unique identifier. The Handviewer program can be instructed to display a bridge movie from /myhands by passing it the identifier for movie in question using the myhand parameter. For example:

https://www.bridgebase.com/tools/handviewer.html?myhand=M-103428497-1223755219

Loading an external .lin file through a parameter

The Handviewer program can be used to display a simple .lin file (for example, the type of file you get when you click the Save button in the Movie window in Bridge Base Online). In order to achieve this effect, it is necessary to create an XML file that acts as a “wrapper” for the .lin file. For example:

<lin>
md|1S2389JHTD3JC237KA,S7TH4QKD678TC4569,S456KAH25D25KACJQ,|rh||ah|Board 7|sv|b|mb|p|mb|p|mb|1S|mb|2H|mb|3S|mb|p|mb|4D|mb|p|mb|4S|mb|p|mb|p|mb|p|pg||pc|SQ|pc|S2|pc|S7|pc|SA|pg||pc|SK|pc|H3|pc|S8|pc|ST|pg||pc|CQ|pc|C8|pc|C2|pc|C4|pg||pc|CJ|pc|CT|pc|C3|pc|C5|pg||mc|13|
</lin>

Save this file on your server with the file extension of xml (for example, you could name the file hand1.xml) and then invoke the Handviewer using the linurl parameter with a value of the appropriate URL. For example:

https://www.bridgebase.com/tools/handviewer.html?linurl=http://www.mywebsite.com/hands/hand1.xml

If the linurl parameter is present all other parameters will be ignored.

List of all parameters:

a	auction
b	board number
c	number of tricks claimed
d	dealer
e	East hand
en	East's name
k	kibitz
lin	Contents of actual .lin file to display
linurl	URL of external .lin file in XML wrapper
myhand	Identifier of deal stored in myhands
n	North
nn	North's name
p	play sequence
s	South
sn	South's name 
v	vulernability
w	West
wn	West's name

For comments, bug reports, other issues contact us at support@bridgebase.com