Introduction
The Handviewer program, developed by Bridge Base Online, Ltd., 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 permission from Bridge Base Online, Ltd.
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).
You can reach us at support@bridgebase.com
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:
<iframe src="http://www.bridgebase.com/tools/handviewer.html?s=sakqhakqdakqcakqj&d=w&a=3hpp" height="350px" width="200px"/>
which will produce something like this
If your web page uses SSL, you should change http: to https:, or you can leave out the protocol prefix entirely and
it will default to the same protocol as your page (but you can't do this if you're testing with a local file instead of a webserver, since
you can't access the BBO server using the file: protocol). We've shown it this way throughout the rest of this document.
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:
//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:
//www.bridgebase.com/tools/handviewer.html?parameter=value1
Multiple parameter value combinations must be separated by an ampersand character (&).
For example:
//www.bridgebase.com/tools/handviewer.html?parameter1=value1¶meter2=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:
//www.bridgebase.com/tools/handviewer.html?s=sakqhakqdakqcakqj
//www.bridgebase.com/tools/handviewer.html?s=sakqhakqdakqcakqj&n=s432h432d432c5432
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:
//www.bridgebase.com/tools/handviewer.html?s=sakqhakqdakqcakqj&sn=Fred
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 taks 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:
//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:
//www.bridgebase.com/tools/handviewer.html?a=1sp3ndrppp
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:
//www.bridgebase.com/tools/handviewer.html?1n(15-17)p3nppp
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:
//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.
Other parameters related to presentation
The c parameter can be used to specify the number of tricks claimed. If this parameter is included with, for example, a value of 10, a message "10 Tricks Claimed" will be displayed at the end of the play sequence.
The k (for kibitz) parameter, when used, instructs the Handviewer to show only one of the 4 hands (plus the dummy after the opening lead is made). The k parameter can take values of n, s, e, or w to specify kibitzing North, South, East, or West respectively. All 4 hands will be shown either if all 52 cards are played out or when claim is made before all 52 cards have been played out.
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 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:
//www.bridgebase.com/tools/handviewer.html?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|
;
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:
//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:
//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
tbt y/n. use "y" to have the NEXT button step by trick. "n" to step by card
v vulernability
w West
wn West's name
